codereviewbuddy

codereviewbuddy

一个 MCP 服务，可帮助你的 AI 编码 Agent 管理来自任何使用 GitHub PR 审查基础设施的 AI 审查者的 PR 审查评论。

功能

审查评论管理

• 整理审查评论 — triage_review_comments 仅筛选出可采取行动的行内讨论串，并为每条评论提供直接的 GitHub URL
• 获取讨论串详情 — get_thread 根据节点 ID 获取任意讨论串的完整对话历史
• 回复任意评论 — 行内审查讨论串（PRRT_）、PR 级审查（PRR_）和机器人议题评论（IC_）都会路由到正确的 GitHub API

CI 和堆栈诊断

• 诊断 CI 故障 — diagnose_ci 将 3-5 条连续的 gh 命令合并为一次调用：查找失败的运行、识别失败的作业/步骤，并提取可采取行动的错误行
• 堆栈活动动态 — stack_activity 按时间顺序显示堆栈中所有 PR 的推送、审查、标签和合并情况，并提供 settled 标志，帮助判断何时继续操作
• 扫描已合并的 PR — list_recent_unresolved 可发现已合并 PR 上较晚出现的审查评论

Agent 体验

• 带恢复指引的错误 — 每个工具处理程序都会对错误进行分类（身份验证、速率限制、未找到、工作区、GraphQL、配置），并提供可采取行动的恢复提示，让 Agent 能自行纠正，而不是盲目重试
• 后续操作提示 — 工具响应包含 next_steps 建议，引导 Agent 调用合适的后续工具
• 空结果消息 — 结果为空时，响应会解释原因并建议接下来尝试的操作
• GUI URL — 整理结果包含 comment_url，方便 Agent 直接将用户链接到 GitHub 上的评论
• 工具分类标签 — 工具会标记为 query、command 或 discovery，供支持筛选的 MCP 客户端使用

服务功能（FastMCP v3）

• 类型化输出架构 — 所有工具都返回包含 JSON Schema 的 Pydantic 模型，为 MCP 客户端提供结构化数据，而非原始字符串
• 进度报告 — 长时间运行的操作通过 FastMCP 上下文报告进度（可在支持此功能的 MCP 客户端中查看）
• 生产级中间件 — ErrorHandling（将异常转换为简洁的 MCP 错误并附带回溯）、Timing（记录每次工具调用的执行时长）和 Logging（记录请求/响应负载，便于调试）
• 零配置身份验证 — 使用 gh CLI，无需 PAT 令牌或 .env 文件

CLI 测试（FastMCP v3 免费提供）

FastMCP v3 支持在终端中测试服务，无需编写额外代码：

# List all tools with their signatures
fastmcp list codereviewbuddy.server:mcp

# Call a tool directly from the terminal
fastmcp call codereviewbuddy.server:mcp triage_review_comments pr_numbers='[42]'

# Inspect server metadata
fastmcp inspect codereviewbuddy.server:mcp

# Run with MCP Inspector for interactive debugging
fastmcp dev codereviewbuddy.server:mcp

先决条件

• 已安装并完成身份验证的 GitHub CLI（gh）（gh auth login）
• Python 3.14+

安装

此项目使用 uv。无需安装，可直接运行：

uvx codereviewbuddy

或永久安装：

uv tool install codereviewbuddy

MCP 客户端配置

快速设置（推荐）

运行一条命令即可配置 MCP 客户端，无需手动编辑 JSON：

uvx codereviewbuddy install claude-desktop
uvx codereviewbuddy install claude-code
uvx codereviewbuddy install cursor
uvx codereviewbuddy install windsurf
uvx codereviewbuddy install windsurf-next

使用可选环境变量：

uvx codereviewbuddy install windsurf \
  --env CRB_SELF_IMPROVEMENT__ENABLED=true

对于其他客户端，可生成 JSON 配置：

uvx codereviewbuddy install mcp-json          # print to stdout
uvx codereviewbuddy install mcp-json --copy   # copy to clipboard

安装后重启 MCP 客户端。查看 uvx codereviewbuddy install --help 了解所有选项。

手动配置

如果你更倾向于手动设置，请将以下内容添加到 MCP 客户端的配置 JSON 中：

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uvx",
      "args": ["codereviewbuddy@latest"],
      "env": {
        // All CRB_* env vars are optional — zero-config works out of the box.
        // See Configuration section below for the full list.
      }
    }
  }
}

启用所有选项：

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uvx",
      "args": ["codereviewbuddy@latest"],
      "env": {
        // GitHub logins considered "ours" for triage filtering (comma-separated)
        "CRB_OWNER_LOGINS": "alice,bob",
        // Enable PR description quality checks
        "CRB_PR_DESCRIPTIONS__ENABLED": "true",
        // Agents suggest Linear issues when they hit server gaps
        "CRB_SELF_IMPROVEMENT__ENABLED": "true"
      }
    }
  }
}

服务会根据 MCP 根目录（由客户端按窗口发送）自动检测你的项目。即使同时打开多个窗口并处理不同项目，也能正常工作——无需设置环境变量。

为什么使用 @latest？ 如果不使用它，uvx 会缓存首次解析出的版本，并且永远不会自动升级。

从源代码运行（开发）

进行本地开发时，使用 uv run --directory 从你的代码检出目录运行服务，而不是运行已发布到 PyPI 的版本。对源代码的更改会立即生效——只需在客户端中重启 MCP 服务。

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codereviewbuddy", "codereviewbuddy"],
      "env": {
        // Same CRB_* env vars as above, plus dev-specific settings:
        "CRB_SELF_IMPROVEMENT__ENABLED": "true"
      }
    }
  }
}

故障排除

如果 MCP 客户端提示 No module named 'fastmcp.server.tasks.routing'，说明运行时使用了不兼容的 FastMCP。解决方法：

1. 优先在 MCP 客户端配置中使用 uvx codereviewbuddy@latest。
2. 对于本地源代码检出，请使用 uv run --directory /path/to/codereviewbuddy codereviewbuddy 启动。
3. 重新安装以刷新缓存的依赖项：uv tool install --reinstall codereviewbuddy。

MCP 工具

工具	标签	描述
summarize_review_status	query, discovery	轻量级的全栈概览——从这里开始
triage_review_comments	query	仅显示需要处理的内联讨论串
get_thread	query	根据节点 ID 获取完整讨论串详情——完成初步筛选后，用于查看对话历史
reply_to_comment	command	回复内联讨论串（PRRT_）、PR 级别的评审（PRR_）或机器人评论（IC_）
diagnose_ci	query	诊断 CI 故障——一次调用即可找到失败的运行、作业、步骤和错误行
check_ci_status	query	轻量级检查 PR 的 CI 通过、失败或待处理状态——合并前使用
stack_activity	query	按时间顺序显示 PR 堆栈中的活动，并附带 settled 标记
list_recent_unresolved	query	扫描最近合并的 PR，查找尚未解决的评审讨论串
review_pr_descriptions	query	分析 PR 描述中的质量问题（内容为空、套话、缺少关联议题）
show_config	discovery	显示当前配置，并提供便于阅读的说明

MCP 资源

资源	描述
pr://{owner}/{repo}/{pr_number}/reviews	单个 PR 的只读评审摘要

MCP 提示词

提示词	描述
review_stack	完整的评审工作流——汇总、筛选、修复、回复、验证
pr_review_checklist	合并前质量检查清单（评审讨论串、PR 规范、CI、测试）
ship_stack	合并 PR 堆栈前的合并前检查工作流

配置

codereviewbuddy 使用合理的默认值，无需配置即可运行。所有配置均通过 MCP 客户端配置中 "env" 块里的 CRB_* 环境变量进行——无需配置文件。嵌套设置使用 __（双下划线）作为分隔符。请参阅上文的开发环境设置，了解带有完整注释的示例。

所有设置

环境变量	类型	默认值	描述
CRB_PR_DESCRIPTIONS__ENABLED	bool	true	是否提供 review_pr_descriptions 工具
CRB_SELF_IMPROVEMENT__ENABLED	bool	false	Agent 遇到服务缺陷时是否建议创建 Linear 议题
CRB_OWNER_LOGINS	逗号分隔	[]	在筛选中被视为“我方”的 GitHub 用户名（例如 alice,bob）

典型工作流

1. summarize_review_status()                     # Stack-wide overview — start here
2. triage_review_comments(pr_numbers=[42, 43])   # Only actionable threads needing attention
3. # Fix bugs flagged by triage, then:
4. reply_to_comment(42, thread_id, "Fixed in ...")  # Reply explaining the fix
5. diagnose_ci(pr_number=42)                     # If CI fails, diagnose in one call

每个工具响应都包含 next_steps 提示，引导 Agent 执行合适的后续调用。对于堆叠式 PR，如果省略 pr_numbers，所有查询工具都会自动发现堆栈。

开发

git clone https://github.com/detailobsessed/codereviewbuddy.git
cd codereviewbuddy
uv sync

测试

poe test          # Run tests (excludes slow)
poe test-cov      # Run with coverage report
poe test-all      # Run all tests including slow

质量检查

poe lint          # ruff check
poe typecheck     # ty check
poe check         # lint + typecheck
poe prek          # run all pre-commit hooks

架构

此服务基于 FastMCP v3 构建，各部分职责清晰：

• server.py — FastMCP 服务，包含工具注册、中间件、说明以及恢复指导型错误处理
• config.py — 配置（通过 pydantic-settings 管理 CRB_* 环境变量）
• tools/ — 工具实现（comments.py、stack.py、ci.py、descriptions.py）
• gh.py — 用于 GraphQL 和 REST 调用的 gh 命令行轻量封装
• models.py — 用于类型化工具输出的 Pydantic 模型，包含为 Agent 提供指导的 next_steps 和 message 字段

所有会阻塞的 gh 命令行调用都通过 call_sync_fn_in_threadpool 封装，以避免阻塞异步事件循环。

模板更新

此项目由 copier-uv-bleeding 生成。若要拉取最新模板更改：

copier update --trust .