Codereviewbuddy

🚀 codereviewbuddy

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

🚀 快速开始

在使用 codereviewbuddy 之前，你需要完成以下准备工作：

• 安装并认证 GitHub CLI (gh)，执行命令 gh auth login。
• 安装 Python 3.14 及以上版本。

安装方式有两种，你可以直接运行：

uvx codereviewbuddy

或者进行永久安装：

uv tool install codereviewbuddy

✨ 主要特性

审查评论管理

• 列出审查评论 — 可列出内联线程、PR 级别的审查以及机器人评论（如 codecov、netlify、vercel 等），同时识别审查者并检测评论的时效性。
• 支持堆叠 PR — list_stack_review_comments 可在一次调用中获取整个 PR 堆栈的评论。
• 回复任意评论 — 内联审查线程（PRRT_）、PR 级别的审查（PRR_）和机器人问题评论（IC_）都能被正确路由到 GitHub API 进行回复。

分类与 CI 诊断

• 对审查评论进行分类 — triage_review_comments 可过滤出可操作的线程，预先分类严重程度，建议修复/回复/创建问题的操作，并包含每个评论的直接 GitHub URL。
• 诊断 CI 失败 — diagnose_ci 可将 3 - 5 个连续的 gh 命令合并为一次调用，找到失败的运行、识别失败的作业/步骤，并提取可操作的错误行。
• 堆栈活动提要 — stack_activity 可显示整个 PR 堆栈中推送、审查、标签、合并的时间线，并带有 settled 标志，用于决定何时继续操作。
• 扫描已合并的 PR — list_recent_unresolved 可捕获已合并 PR 上的延迟审查评论。

问题跟踪

• 从审查评论创建问题 — 可将有用的 AI 建议转化为 GitHub 问题，包含标签、PR 反向链接、文件/行位置和引用的评论文本。

代理体验

• 恢复引导错误处理 — 每个工具处理程序都会对错误进行分类（认证、速率限制、未找到、工作区、GraphQL、配置），并返回可操作的恢复提示，以便代理能够自我纠正，而不是盲目重试。
• 下一步操作提示 — 工具响应包含 next_steps 建议，指导代理进行正确的后续工具调用。
• 空结果消息 — 当结果为空时，响应会解释原因并建议下一步尝试的操作。
• GUI URL — 分类项包含 comment_url，以便代理可以直接将用户链接到 GitHub 上的评论。
• 工具分类标签 — 工具被标记为 query、command 或 discovery，支持过滤的 MCP 客户端可使用。

服务器特性（FastMCP v3）

• 类型化输出模式 — 所有工具都返回带有 JSON Schema 的 Pydantic 模型，为 MCP 客户端提供结构化数据而非原始字符串。
• 进度报告 — 长时间运行的操作通过 FastMCP 上下文报告进度（在支持的 MCP 客户端中可见）。
• 生产中间件 — ErrorHandling（将异常转换为带有回溯的清晰 MCP 错误）、Timing（记录每个工具调用的执行时间）和 Logging（用于调试的请求/响应有效负载）。
• 更新检查 — check_for_updates 可将运行版本与 PyPI 进行比较，并建议升级命令。
• 零配置认证 — 使用 gh CLI，无需 PAT 令牌或 .env 文件。

CLI 测试（FastMCP v3 免费提供）

FastMCP v3 允许你在终端中测试服务器，无需额外代码：

# 列出所有工具及其签名
fastmcp list codereviewbuddy.server:mcp

# 直接从终端调用工具
fastmcp call codereviewbuddy.server:mcp list_review_comments pr_number=42

# 检查服务器元数据
fastmcp inspect codereviewbuddy.server:mcp

# 使用 MCP Inspector 进行交互式调试
fastmcp dev codereviewbuddy.server:mcp

📦 安装指南

此项目使用 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 \
  --env CRB_SELF_IMPROVEMENT__REPO=your-org/codereviewbuddy

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

uvx codereviewbuddy install mcp-json          # 输出到标准输出
uvx codereviewbuddy install mcp-json --copy   # 复制到剪贴板

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

手动配置

如果你更喜欢手动设置，可以在 MCP 客户端的配置 JSON 中添加以下内容：

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uvx",
      "args": ["codereviewbuddy@latest"],
      "env": {
        // 所有 CRB_* 环境变量都是可选的 — 零配置开箱即用。
        // 请参阅下面的配置部分以获取完整列表。

        // 自我改进：当代理遇到服务器缺陷时会创建问题
        // "CRB_SELF_IMPROVEMENT__ENABLED": "true",
        // "CRB_SELF_IMPROVEMENT__REPO": "your-org/codereviewbuddy",

        // 诊断（默认关闭）
        // "CRB_DIAGNOSTICS__IO_TAP": "true",
        // "CRB_DIAGNOSTICS__TOOL_CALL_HEARTBEAT": "true"
      }
    }
  }
}

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

为什么使用 @latest？ 不使用它时，uvx 会缓存第一个解析的版本，并且不会自动升级。

从源代码安装（开发用途）

对于本地开发，可以使用 uv run --directory 从你的代码库运行服务器，而不是使用 PyPI 发布的版本。对源代码的更改会立即生效，只需在客户端中重启 MCP 服务器即可。

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codereviewbuddy", "codereviewbuddy"],
      "env": {
        // 与上述相同的 CRB_* 环境变量，以及开发特定的设置：
        "CRB_SELF_IMPROVEMENT__ENABLED": "true",
        "CRB_SELF_IMPROVEMENT__REPO": "detailobsessed/codereviewbuddy",
        "CRB_DIAGNOSTICS__IO_TAP": "true",
        "CRB_DIAGNOSTICS__TOOL_CALL_HEARTBEAT": "true",
        "CRB_DIAGNOSTICS__HEARTBEAT_INTERVAL_MS": "5000",
        "CRB_DIAGNOSTICS__INCLUDE_ARGS_FINGERPRINT": "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 工具

配置

codereviewbuddy 支持零配置运行，具有合理的默认值。所有配置都通过 MCP 客户端配置的 "env" 块中的 CRB_* 环境变量进行，无需配置文件。嵌套设置使用 __（双下划线）作为分隔符。请参考上面的 开发设置 以获取完整注释的示例。

所有设置

严重程度级别

严重程度根据评论正文中的表情符号标记进行分类：

典型工作流程

1. summarize_review_status()                     # 堆栈级概述 — 从此处开始
2. triage_review_comments(pr_numbers=[42, 43])   # 仅列出可操作的线程并建议操作
3. # 修复分类标记的错误，然后：
4. reply_to_comment(42, thread_id, "Fixed in ...")  # 回复解释修复情况
5. create_issue_from_comment(thread_id, "Improve X")  # 将后续跟进事项作为问题跟踪
6. diagnose_ci(pr_number=42)                     # 如果 CI 失败，一次调用进行诊断

每个工具响应都包含 next_steps 提示，指导代理进行正确的后续调用。对于堆叠 PR，当省略 pr_numbers 时，所有查询工具都会自动发现堆栈。

开发

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

测试

poe test          # 运行测试（排除慢速测试）
poe test-cov      # 运行测试并生成覆盖率报告
poe test-all      # 运行所有测试，包括慢速测试

质量检查

poe lint          # ruff 检查
poe typecheck     # ty 类型检查
poe check         # 代码检查 + 类型检查
poe prek          # 运行所有预提交钩子

架构

服务器基于 FastMCP v3 构建，结构清晰：

• server.py — FastMCP 服务器，包含工具注册、中间件、指令和恢复引导的错误处理。
• config.py — 配置文件（通过 pydantic-settings 处理 CRB_* 环境变量）。
• tools/ — 工具实现（comments.py、stack.py、ci.py、descriptions.py、issues.py）。
• gh.py — 围绕 gh CLI 的轻量级包装器，用于 GraphQL 和 REST 调用。
• models.py — Pydantic 模型，用于类型化工具输出，包含 next_steps 和 message 字段以指导代理。

所有阻塞的 gh CLI 调用都使用 call_sync_fn_in_threadpool 进行包装，以避免阻塞异步事件循环。

模板更新

此项目使用 copier-uv-bleeding 生成。要拉取最新的模板更改，请执行以下命令：

copier update --trust .