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 文件（如果存在）。