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 .