Ndlovu Code Reviewer

🚀 代碼審查MCP服務器

這是一個由Gemini-CLI（目前）驅動的代碼審查助手，它作為模型上下文協議（MCP）服務器運行，旨在解決手動代碼審查耗時且難以結合靜態分析與上下文友好反饋的問題，為開發者提供高效、智能的代碼審查服務。

🚀 快速開始

本項目需要以下運行環境：

• Node.js 18 或更高版本（全程使用 ES 模塊和 AbortSignals）。
• npm（隨 Node.js 安裝）。
• Git（用於收集本地差異）。
• 已安裝並通過身份驗證的 Google Gemini CLI (gemini)。請參閱 Gemini 快速入門指南 進行設置。

安裝步驟

git clone https://github.com/<your-org>/ndlovu-code-reviewer.git
cd ndlovu-code-reviewer
npm install
npm run build

如果您計劃對 TypeScript 源代碼進行迭代開發，可以跳過 npm run build 步驟，依賴下面描述的開發腳本。

啟動 MCP 服務器

npm start

服務器通過標準輸入輸出進行通信，因此可以與任何兼容 MCP 的客戶端（如 IDE 集成或助手沙盒）進行註冊。連接成功後，調用 review-local-changes 工具即可觸發混合分析並接收 JSON 格式的審查結果。

✨ 主要特性

• 自動化審查：自動收集本地未提交更改的差異和 lint 結果，將上下文流式傳輸到 Gemini CLI，讓模型專注於提供可操作的見解。
• 多工具支持：採用“混合”審查工作流程，結合 git diff 輸出和多種代碼檢查工具（ESLint、JSHint 和 TypeScript），以最大程度覆蓋不同項目。
• 安全調用：安全調用 Gemini CLI，處理長提示和超時問題。
• 結構化輸出：返回結構化的 JSON 審查結果，方便與 MCP 兼容的客戶端集成。

📦 安裝指南

git clone https://github.com/<your-org>/ndlovu-code-reviewer.git
cd ndlovu-code-reviewer
npm install
npm run build

若要進行本地開發，可跳過 npm run build 步驟，使用以下命令啟動開發模式：

npm run dev

此命令使用 ts-node 啟動服務器，便於快速迭代。若要生成編譯後的 JavaScript 輸出，可運行：

npm run build

編譯後的文件將生成在 dist/ 目錄中。

💻 使用示例

基礎用法

啟動服務器後，使用兼容 MCP 的客戶端連接到服務器，調用 review-local-changes 工具對本地未提交的代碼更改進行全面分析。

調用 MCP 工具的前提條件

• 您的 Git 倉庫中必須有未提交的更改。
• 更改的文件應為 JavaScript、TypeScript 或 Vue 文件（.js, .ts, .tsx, .vue）。
• 已安裝並通過身份驗證的 Gemini CLI。

調用方式

與 Claude Code 配合使用

為了獲得最佳效果，建議在請求中明確使用代碼審查功能。以下是一些可靠的請求示例：

• "Use the code review tool to analyze my changes"（使用代碼審查工具分析我的更改）
• "Run code review on my local changes"（對我的本地更改進行代碼審查）
• "Perform a comprehensive code review of my uncommitted changes"（對我未提交的更改進行全面的代碼審查）
• "Analyze my code changes with static analysis"（使用靜態分析分析我的代碼更改）

自然語言請求可能有效，但可靠性較低：

• "Please review my local changes"（請審查我的本地更改）
• "Can you analyze the code changes I've made?"（你能分析我所做的代碼更改嗎？）

直接調用工具最為可靠：

• "Use the review-local-changes tool"（使用 review-local-changes 工具）
• "Call the review-local-changes tool to check my modifications"（調用 review-local-changes 工具檢查我的修改）

示例輸出格式

{
  "summary": "Overview of changes made",
  "assessment": "Overall code quality evaluation",
  "findings": [
    {
      "filePath": "src/example.js",
      "lineNumber": 42,
      "severity": "warning",
      "category": "style",
      "comment": "Detailed explanation of the issue",
      "suggestion": "Specific recommendation for improvement"
    }
  ]
}

注意：如果沒有相關文件被更改，工具將返回 "No relevant files changed" 消息，這屬於正常現象。

📚 詳細文檔

從 MCP 客戶端連接

在將服務器連接到任何客戶端之前，請確保已運行 npm run build 命令，以生成 dist/index.js 文件。以下命令假設您從倉庫根目錄執行客戶端，以便服務器可以讀取您的 Git 工作區。

Claude Code（VS Code 擴展）

1. 在 VS Code 中，打開命令面板（Cmd/Ctrl+Shift+P）並運行 Claude: Edit Config File。
2. 找到 mcpServers 部分（如果需要則創建），並添加如下條目：

{
  "mcpServers": {
    "ndlovu-code-reviewer": {
      "command": "node",
      "args": ["/absolute/path/to/ndlovu-code-reviewer/dist/index.js"],
      "cwd": "/absolute/path/to/ndlovu-code-reviewer"
    }
  }
}

3. 保存文件並運行 Claude: Restart Claude Code（或重新加載 VS Code），使服務器顯示在 工具 列表中。
4. 在對話中啟用該工具，Claude Code 將在側邊欄直接流式傳輸 review-local-changes 結果。

Gemini CLI

1. 從項目根目錄運行以下命令：

gemini mcp add ndlovu-code-reviewer node $(pwd)/dist/index.js

2. 使用 gemini mcp list 命令驗證註冊信息。
3. 從同一倉庫目錄啟動 gemini，並使用 review-local-changes 工具（例如，在 CLI 中運行 :tools 並選擇該工具）。CLI 將啟動服務器並將標準輸出作為審查 JSON 返回。

Roo Code

1. 打開 Roo Code，點擊 Roo 面板頂部的服務器圖標。
2. 選擇 Add MCP Server → STDIO 並填寫以下信息：
   • 名稱：ndlovu-code-reviewer
   • 命令：node
   • 參數：/absolute/path/to/ndlovu-code-reviewer/dist/index.js
   • 工作目錄：/absolute/path/to/ndlovu-code-reviewer
3. 保存配置併為您的工作區啟用服務器。Roo 將配置信息存儲在全局 mcp_settings.json 或項目 .roo/mcp.json 文件中。
4. 若要與團隊成員共享配置，可提交包含首選啟動命令的 .roo/mcp.json 文件，例如：

{
  "mcpServers": {
    "ndlovu-code-reviewer": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "."
    }
  }
}

Roo 會相對於項目根目錄解析工作目錄，因此 npm run start 腳本將基於倉庫自身的包腳本運行。

Codex CLI

1. 註冊服務器：

codex mcp add ndlovu-code-reviewer node $(pwd)/dist/index.js

2. 使用 codex mcp list 命令確認註冊信息，然後從倉庫根目錄啟動 Codex。CLI 將 review-local-changes 作為工具暴露，您可以在交互式運行中調用該工具。

🤝 貢獻指南

我們非常歡迎您的貢獻。如果您有關於新工具、更好的代碼檢查器或改進提示的想法，請按照以下步驟進行：

1. 打開一個問題或討論，以便我們就範圍達成一致。
2. 分叉倉庫並創建一個功能分支。
3. 在需要的地方添加或更新文檔/測試，以幫助未來的貢獻者。
4. 提交拉取請求，描述更改內容以及您是如何驗證的。

如果您不確定從哪裡開始，請隨時聯繫我們，該審查器還有很大的擴展空間，例如增加客戶端示例和優化提示等。

📄 許可證

本項目採用 ISC 許可證。有關詳細信息，請參閱 LICENSE 文件（如果存在）。