Code Review MCP

🚀 代碼審查MCP — 以Cursor為先的PR審查工具

代碼審查MCP是一個端到端的解決方案，它利用你本地的工具鏈和Cursor的AI來審查GitHub上的拉取請求（PR）。它可以獲取PR的差異，加載項目文檔，運行靜態分析、安全檢查和測試，在允許的情況下發布內聯評論，並生成Markdown報告。

🚀 快速開始

代碼審查MCP藉助本地工具鏈和Cursor的AI，實現對GitHub拉取請求的端到端審查。它能獲取PR差異、加載項目文檔、執行各類檢查與測試、發佈評論並生成報告。

✨ 主要特性

• 自動化審查：自動拉取PR差異，結合項目文檔進行綜合審查。
• 多工具集成：支持ESLint、Prettier、TypeScript、Semgrep和Playwright等工具。
• 環境靈活配置：可通過.env.mcp文件或命令行指定環境變量。
• 報告生成：生成Markdown格式的詳細審查報告。

📦 安裝指南

1. 克隆此倉庫（或者將tools/mcp-code-review.mjs和.mcp/code-review/複製到你的項目倉庫中）。
2. 在倉庫中安裝Node依賴：npm ci（或者npm i）。
3. 確保.cursor/mcp.json指向tools/mcp-code-review.mjs的絕對路徑。

示例.cursor/mcp.json文件：

{
  "mcpServers": {
    "code-review": {
      "command": "node",
      "args": ["/absolute/path/to/tools/mcp-code-review.mjs"]
    }
  }
}

💻 使用示例

基礎用法

在目標倉庫的Cursor聊天框中，你可以使用以下命令觸發審查：

• @code-review 123（自動從git origin檢測倉庫）
• @code-review owner/repo#123
• @code-review https://github.com/owner/repo/pull/123
• @code-review latest

高級用法

你可以使用以下標誌來定製審查過程：

• --env-file=/abs/path/to/.env.mcp（覆蓋默認的環境文件）
• --dry-run（跳過發佈評論，仍然生成報告）
• --commit-report（在允許的情況下將報告提交到PR分支）
• --auto-fix 或 --auto-fix=force（應用ESLint/Prettier修復，提交併推送）
• --skip-static --skip-security --skip-tests --skip-figma
• --semgrep-rules-dir=/path/to/rules（覆蓋Semgrep規則）
• --max-diff-chars=20000 --max-file-hunks=10 --verbose

📚 詳細文檔

環境配置（認證）

• MCP默認只加載.env.mcp（倉庫根目錄），或者使用--env-file=/path/to/env指定其他文件。
• 必需配置：
  • GITHUB_TOKEN=...（必須有權限訪問目標倉庫；如果組織強制要求SSO，則需要經過SSO授權）
• 可選配置：
  • JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_KEY
  • FIGMA_TOKEN
  • SEMGREP_RULES_DIR=.mcp/code-review/semgrep-rules

自動檢測的項目文件

• 倉庫文檔（AI上下文）：
  • 倉庫根目錄下的codebase_structure.md和watchouts.md
  • .mcp/code-review/下的所有.md文件（例如your-rules.md）
• 代碼檢查/格式化/類型檢查：
  • 使用項目配置從本地node_modules/.bin運行ESLint/Prettier。
  • 如果存在tsconfig.json，則運行TypeScript檢查。
• 安全檢查：
  • 如果存在.mcp/code-review/semgrep-rules/，則使用其中的Semgrep規則；否則使用p/ci規則。
• 測試：
  • 如果倉庫根目錄存在playwright.config.ts/js，則運行Playwright測試。

輸出信息

• 日誌：mcp-logs/（每次運行的日誌文件）
• 工件：mcp-artifacts/<owner>-<repo>-PR<#>-<ts>/
• 報告：mcp-reports/code-review-<owner>-<repo>-PR<#>-<ts>.md

注意事項

• 如果認證用戶是PR的作者，GitHub可能會拒絕發佈審查評論；MCP將跳過評論，但仍然會生成報告（請查看報告中的管道狀態）。
• 舊的日誌/報告（超過1天）將被清理，每個PR只保留最新的報告。

子工具（高級用法）

你可以直接調用以下子工具：

• @github.resolve_pr { prId: "owner/repo#123" }
• @github.fetch_files { owner: "owner", repo: "repo", pull_number: 123 }
• @jira.fetch { prMeta: { title: "...", body: "...", branch: "..." } }
• @analysis.run_static { files: ["src/..."], runTsc: true }
• @security.run_semgrep {}
• @tests.run_playwright {}
• @report.generate {...}
• @cleanup.prune { owner:"owner", repo:"repo", pull_number:123 }

CI建議

為了保證一致性，建議在CI中運行相同的工具：

• ESLint: npx eslint . --max-warnings=0
• Prettier: npx prettier --check .
• Semgrep: pipx install semgrep && semgrep --config .mcp/code-review/semgrep-rules --error -- .
• Playwright: npx playwright install --with-deps && npx playwright test --reporter=line

故障排除

• 憑證問題：確保.env.mcp文件存在，並且日誌顯示Auth loaded from .env.mcp:...。驗證PAT：curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user → 響應狀態碼必須為200。
• Jira跳過：確保PR分支/標題/正文中包含Jira關鍵字，並且JIRA_*環境變量已設置。
• Semgrep跳過：安裝Semgrep CLI或設置規則目錄。
• Playwright跳過：添加playwright.config.*文件並安裝瀏覽器。

有關特定平臺（macOS/Windows）的設置，請參閱docs/Platform-Setup.md。

🔧 技術細節

代碼審查MCP基於Node.js 18+構建，通過調用各種工具和API實現對GitHub PR的審查。它利用Cursor的AI能力，結合項目文檔和規則，提供全面的審查報告。在運行過程中，它會自動檢測項目中的各種配置文件和工具，根據環境變量進行認證和配置。通過調用子工具，可以實現更細粒度的操作。

📄 許可證

文檔中未提及相關許可證信息。