@vibesnipe/code Review Mcp

@vibesnipe/code-review-mcp

版本：1.0.0

一个 MCP（Model Context Protocol）服务，提供强大的工具，使用各种大模型（LLM）进行代码审查。此服务旨在无缝集成到 Anthropic 的 Claude Code、Cursor、Windsurf 等 AI 编码助手，或其他兼容 MCP 的客户端中。

注意： 此工具最初为 Claude Code 创建，后来扩展支持其他 AI IDE 和 Claude Desktop。请参阅 Claude Code、Cursor 和 Windsurf 的集成指南。

它会分析暂存的更改、与 HEAD 的差异或分支间差异的 git diff 输出，并根据任务描述和项目详情提供结合上下文的审查结果。

功能

• 审查 git diff（暂存的更改、当前 HEAD、分支差异）。
• 通过 Vercel AI SDK 集成 Google Gemini、OpenAI 和 Anthropic 模型。
• 支持指定任务描述、审查重点和整体项目背景，以提供定制化审查。
• 以清晰、可执行的 Markdown 格式输出审查结果。
• 可从你希望分析的任何 Git 仓库根目录运行。
• 可通过 npx 轻松安装和运行，即刻使用。

兼容性

• Node.js：需要 18 或更高版本。
• 操作系统：支持 Windows、macOS 和 Linux。
• Git：建议使用 2.20.0 或更高版本。

先决条件

• Node.js：需要 18 或更高版本。
• Git：必须已安装，并可通过系统的 PATH 访问。该服务会执行 git 命令。
• 大模型 API 密钥：你需要为计划使用的大模型提供商准备 API 密钥，并将其设为环境变量：
  • GOOGLE_API_KEY 用于 Google 模型。
  • OPENAI_API_KEY 用于 OpenAI 模型。
  • ANTHROPIC_API_KEY 用于 Anthropic 模型。 可以在环境中全局设置这些变量，也可以方便地将其写入 .env 文件，并放在当前正在审查的项目根目录中。服务会自动尝试加载该文件。

安装与使用

使用此服务的主要方式是通过 npx，这样无需全局安装即可始终使用最新版本。

推荐：使用 npx

1. 进入你的项目： 打开终端，切换到你要审查的 Git 仓库根目录。

   cd /path/to/your-git-project
   

2. 运行 MCP 服务： 执行以下命令：

   npx -y @vibesnipe/code-review-mcp
   

   此命令将下载（如果尚未缓存）并运行 @vibesnipe/code-review-mcp 服务。你应该会在终端中看到类似以下内容： [MCP Server] Code Reviewer MCP Server is running via stdio and connected to transport. 服务现已运行，并等待 MCP 客户端（如 Claude Code、Cursor 或 Windsurf）连接。

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 code-review-mcp：

npx -y @smithery/cli install @praneybehl/code-review-mcp --client claude

与 Claude Code 集成

启动 claude-code-review-mcp 服务后（最好在项目根目录中通过 npx 启动）：

1. 在 Claude Code 中添加为 MCP 服务： 在运行（或即将运行）Claude Code 的另一个终端中，将其配置为使用此 MCP 服务。 Claude Code 用于启动服务的命令可以是 code-review-mcp（如果已全局安装且位于 PATH 中），也可以是 npx ... 命令（如果你希望 Claude Code 每次都获取该服务）。

   将其添加到 Claude Code：

   claude mcp add code-reviewer -s <user|local> -e GOOGLE_API_KEY="key" -- code-review-mcp 
   

   如果希望 Claude Code 使用 npx（如果不进行全局安装，这是确保版本一致性的好做法）：

   claude mcp add code-reviewer -s <user|local> -e GOOGLE_API_KEY="key" -- npx -y @vibesnipe/code-review-mcp
   

   这会告知 Claude Code，在请求“code-reviewer”工具集时如何启动 MCP 服务。此配置可以针对项目（保存在项目的 .claude/.mcp.json 中），也可以针对用户（保存在 Claude Code 的全局设置中）。

2. 在 Claude Code 中使用智能斜杠命令： 在项目的 .claude/commands/ 目录中创建自定义斜杠命令文件，以便轻松调用审查工具。此软件包在 examples/claude-commands/ 目录中提供了多个示例命令，可复制到你的项目中。

   这些改进后的斜杠命令无需你手动指定任务描述或项目上下文——它们会利用 Claude Code 对项目以及当前任务的已有了解。

   在 Claude Code 中使用斜杠命令的示例：

   claude > /project:review-staged-claude
   

   无需其他参数！Claude 会了解你当前正在处理的内容，并将其用作审查上下文。

   对于需要参数的命令（例如使用自定义分支名称的 review-branch-custom-gemini.md），你可以直接在命令后传入参数：

   claude > /project:review-branch-custom-gemini main
   

   这会将“main”作为 $ARGUMENTS_BASE_BRANCH 参数传入。

与现代 AI IDE 集成

Cursor 集成

Cursor 是一款基于 VS Code、广受欢迎且由 AI 驱动的 IDE，支持 MCP 服务。以下介绍如何将代码审查 MCP 服务集成到 Cursor 中：

1. 配置 Cursor 的代码审查规则：

   在项目中创建或打开 .cursor/rules/project.mdc 文件，并添加以下部分：

   ## Slash Commands
   
   /review-staged: Use the perform_code_review tool from the code-reviewer MCP server to review staged changes. Use anthropic provider with claude-3-7-sonnet-20250219 model. Base the task description on our current conversation context and focus on code quality and best practices.
   
   /review-head: Use the perform_code_review tool from the code-reviewer MCP server to review all uncommitted changes (HEAD). Use openai provider with o3 model. Base the task description on our current conversation context and focus on code quality and best practices.
   
   /review-security: Use the perform_code_review tool from the code-reviewer MCP server to review staged changes. Use anthropic provider with claude-3-5-sonnet-20241022 model. Base the task description on our current conversation context and specifically focus on security vulnerabilities, input validation, and secure coding practices.
   

2. 在 Cursor 中添加 MCP 服务：

   • 打开 Cursor 设置
   • 导航到 MCP 服务部分
   • 使用以下 JSON 配置添加新的 MCP 服务：

   "code-reviewer": {
     "command": "npx",
     "args": ["-y", "@vibesnipe/code-review-mcp"],
     "env": {
       "GOOGLE_API_KEY": "your-google-api-key",
       "OPENAI_API_KEY": "your-openai-api-key",
       "ANTHROPIC_API_KEY": "your-anthropic-api-key"
     }
   }
   

3. 使用命令：

   在 Cursor 的 AI 聊天界面中，现在只需输入：

   /review-staged
   

   Cursor 就会使用 claude-code-review-mcp 服务审查已暂存的更改。

Windsurf 集成

Windsurf（前称 Codeium）是另一个支持通过斜杠命令使用自定义工作流的高级 AI IDE。以下是将其与 Windsurf 集成的方法：

1. 在 Windsurf 中配置 MCP 服务：

   • 打开 Windsurf
   • 点击 Cascade 右上角的 Customizations 图标
   • 前往 MCP Servers 面板
   • 使用以下 JSON 配置添加新的 MCP 服务：

   "code-reviewer": {
     "command": "npx",
     "args": ["-y", "@vibesnipe/code-review-mcp"],
     "env": {
       "GOOGLE_API_KEY": "your-google-api-key",
       "OPENAI_API_KEY": "your-openai-api-key",
       "ANTHROPIC_API_KEY": "your-anthropic-api-key"
     }
   }
   

2. 创建代码审查工作流：

   Windsurf 支持通过斜杠命令调用工作流。创建文件 .windsurf/workflows/review-staged.md：

   # Review Staged Changes
   
   Perform a code review on the currently staged changes in the repository.
   
   ## Step 1
   
   Use the perform_code_review tool from the code-reviewer MCP server with the following parameters:
   

   { "target": "staged", "llmProvider": "anthropic", "modelName": "claude-3-7-sonnet-20250219", "taskDescription": "The task I am currently working on in this codebase", "reviewFocus": "General code quality, security best practices, and performance considerations", "projectContext": "This project is being developed in Windsurf. Please review the code carefully for any issues." }

   同样，按需为其他审查类型创建工作流。

3. 使用工作流：

   在 Windsurf 的 Cascade 界面中，你可以通过以下方式调用这些工作流：

   /review-staged
   

   随后，Windsurf 将执行该工作流，并使用 claude-code-review-mcp 服务进行代码审查。

此 MCP 服务提供的工具

perform_code_review

描述： 使用指定的大模型审查当前 Git 仓库中的 Git 变更。此工具必须在待审查仓库的根目录中运行。

输入架构（参数）：

此工具接受符合 CodeReviewToolParamsSchema 的参数：

• target（枚举：'staged'、'HEAD'、'branch_diff'）： 指定要审查的变更集。

  • 'staged'：仅审查当前已暂存、准备提交的变更。
  • 'HEAD'：根据上次提交审查未提交的变更（包括已暂存和未暂存的变更）。
  • 'branch_diff'：审查指定的基准分支/提交与当前 HEAD 之间的变更。需要 diffBase 参数。

• taskDescription（字符串）： 清晰简洁地描述导致代码变更的任务、功能或错误修复。这能为大模型审查者提供关键背景信息。（例如：“通过电子邮件 OTP 实现密码重置功能。”）

• llmProvider（枚举：'google'、'openai'、'anthropic'）： 用于审查的大模型提供商。

• modelName（字符串）： 所选提供商对应的具体模型名称。例如：

  • Google：'gemini-2.5-pro-preview-05-06'、'gemini-2.5-flash-preview-04-17' （参考：https://ai-sdk.dev/providers/ai-sdk-providers/google-generative-ai#model-capabilities）
  • OpenAI：'o4-mini'、'gpt-4.1'、'gpt-4.1-mini'、'o3' （参考：https://ai-sdk.dev/providers/ai-sdk-providers/openai#model-capabilities）
  • Anthropic：'claude-3-7-sonnet-20250219'、'claude-3-5-sonnet-20241022' （参考：https://ai-sdk.dev/providers/ai-sdk-providers/anthropic#model-capabilities） 请确保所选模型可通过 Vercel AI SDK 使用，且你的 API 密钥有权访问该模型。

  **注意：**提供商发布新版本时，模型名称通常会变化。请务必查看提供商的最新文档，并相应更新模型名称。

• reviewFocus（字符串，可选但建议提供）： 指定你希望大模型在审查期间重点关注的领域、问题或方面。（例如：“重点检查并发操作中的线程安全性。”“特别留意输入验证和清理。”“检查是否遵循我们针对 React 组件的内部风格指南。”）

• projectContext（字符串，可选但建议提供）： 提供项目的一般背景信息，例如项目架构、主要库、编码规范或其他有助于大模型提供更相关、更深入审查的背景。（例如：“这是一个使用 Rust 和 Actix 构建的高性能微服务。低延迟至关重要。”“项目遵循整洁架构原则。请确保新增代码与之保持一致。”）

• diffBase（字符串，可选）： 当 target 为 'branch_diff' 时必需。指定基准分支（例如：'main'、'develop'）或特定提交 SHA，以便与当前 HEAD 进行比较。

• maxTokens（数字，可选）： 大模型响应可使用的最大 token 数。若未指定，默认为 32000。使用此参数可优化响应速度和成本（较低的值），或获得更全面的审查（较高的值）。 注意：在 v0.11.0 中，默认值从 60000 降至 32000 个 token，以更好地平衡成本和质量。

输出：

• 成功时：返回一个 JSON 对象，其中 isError: false，且 content 数组包含一个文本项。text 字段包含大模型以 Markdown 格式生成的代码审查结果。
• 出错时：返回一个 JSON 对象，其中 isError: true，且包含一个 content 数组。text 字段将包含描述问题的错误消息。

环境变量

要让 LLM 集成正常工作，claude-code-review-mcp 服务（由 npx 或 claude-code-review-mcp 启动的进程）需要访问相应的 API 密钥。

请在 shell 环境中设置这些变量，或将它们放入你要审查的项目根目录中的 .env 文件：

• 对于 Google 模型： GOOGLE_API_KEY="your_google_api_key"

• 对于 OpenAI 模型： OPENAI_API_KEY="your_openai_api_key"

• 对于 Anthropic 模型： ANTHROPIC_API_KEY="your_anthropic_api_key"

服务会自动从当前工作目录（即项目根目录）中的 .env 文件加载变量；你也可以按照上方示例，在 MCP 服务配置中直接配置这些变量。

Claude Code 智能斜杠命令

此软件包在 examples/claude-commands/ 目录中提供了几个改进版斜杠命令，你可以将它们复制到项目的 .claude/commands/ 目录中。这些命令利用 Claude Code 对项目上下文和当前任务的理解，无需手动输入。

可用的斜杠命令

命令文件	描述
review-staged-claude.md	使用 Claude 3.5 Sonnet 审查已暂存的更改
review-staged-openai.md	使用 OpenAI GPT-4.1 审查已暂存的更改
review-staged-gemini.md	使用 Google Gemini 2.5 Pro 审查已暂存的更改
review-head-claude.md	使用 Claude 3.7 Sonnet 审查所有未提交的更改
review-head-openai.md	使用 OpenAI O3 审查所有未提交的更改
review-head-gemini.md	使用 Google Gemini 2.5 Pro 审查所有未提交的更改
review-branch-main-claude.md	使用 Claude 3.7 Sonnet 审查 main 分支中的更改
review-branch-develop-openai.md	使用 OpenAI O4-mini 审查 develop 分支中的更改
review-branch-custom-gemini.md	使用 Google Gemini 2.5 Flash 审查指定分支中的更改
review-staged-security-claude.md	使用 Claude 3.5 Sonnet 对已暂存的更改进行安全性审查
review-staged-performance-openai.md	使用 OpenAI O3 对已暂存的更改进行性能审查
review-staged-maintainability-gemini.md	使用 Google Gemini 2.5 Flash 对已暂存的更改进行可维护性审查

使用这些命令：

1. 将所需命令文件从 examples/claude-commands/ 目录复制到项目的 .claude/commands/ 目录
2. 在 Claude Code 中使用 /project:command-name 调用命令（例如，/project:review-staged-claude）

这些命令会自动利用 Claude 对当前任务和项目上下文的了解，无需输入冗长的手动参数。

安全注意事项

• API 密钥处理：LLM 提供商的 API 密钥属于敏感凭据。此工具会从环境变量或 .env 文件中读取这些密钥，但不会存储或在必要的 API 调用之外传输它们。建议在生产环境中使用安全的环境变量管理器。

• Git 仓库分析：此工具会分析本地 Git 仓库内容。它会执行 Git 命令并读取差异输出，但不会将整个代码库传输给大模型，只会传输正在审查的具体更改。

• 代码隐私：向外部大模型提供商发送代码进行审查时，请注意：

  • 代码注释或字符串中的敏感信息
  • 专有算法或商业机密
  • 配置文件中的身份验证凭据或 API 密钥

• 分支名称清理：为防止命令注入，分支名称在用于 Git 命令前会经过清理。不过，仍建议避免在分支名称中使用特殊字符。

开发（针对 @vibesnipe/code-review-mcp 包本身）

如果你要为 @vibesnipe/code-review-mcp 包贡献代码或对其进行修改：

1. 克隆 Monorepo： 确保已克隆仓库。

2. 进入包目录：

   cd /path/to/claude-code-review-mcp
   

3. 安装依赖：

   pnpm install
   

4. 以开发模式运行： 这会使用 tsx 对 TypeScript 更改进行热重载。

   pnpm dev
   

   服务将启动，并将日志输出到 stderr。

5. 使用 Claude Code 进行测试（本地开发）： 你需要告知 Claude Code 本地开发服务脚本的位置：

   # 在你使用 Claude Code 的任意目录中运行
   claude mcp add local-code-reviewer "node /path/to/claude-code-review-mcp/src/index.ts" --interpreter=tsx
   

   现在，当 Claude Code 需要使用“local-code-reviewer”时，它会使用 tsx 执行源文件 index.ts。请记得将 /path/to/claude-code-review-mcp/ 替换为仓库的实际绝对路径。

构建以用于生产环境/发布

在包目录中运行：

pnpm build

这会将 TypeScript 编译为 JavaScript，并输出到 dist 目录。package.json 中的 prepublishOnly 脚本会确保在将包发布到 npm 之前自动运行此命令。

故障排除

• “当前目录不是 Git 仓库……”：确保你在有效 Git 项目的根目录中运行 npx @vibesnipe/code-review-mcp（或全局命令）。
• “未配置……的 API 密钥”：请确保在启动 MCP 服务的 shell 中，或在项目根目录下的 .env 文件中，设置了相关环境变量（例如 OPENAI_API_KEY）。
• “获取 git diff 失败。Git 错误：……”：这表示 git diff 命令出现问题。
  • 检查是否已安装 git，以及它是否位于 PATH 中。
  • 确认 target 和 diffBase（如适用）对你的仓库有效。
  • git 本身的错误消息应该能提供更多线索。
• 大模型 API 错误：大模型提供商返回的错误（例如速率限制、模型名称无效、身份验证问题）会直接传递。请查看错误消息，了解具体大模型 API 的详细信息。
• Claude Code MCP 问题：如果 Claude Code 找不到或无法启动服务，请仔细检查 claude mcp add ... 命令，并确保指定的 MCP 服务命令正确且可执行。使用 claude mcp list 进行验证。
• Cursor MCP 服务问题：如果 Cursor 无法识别 MCP 服务，请确保已在设置中使用正确的配置添加该服务。
• Windsurf 工作流错误：如果 Windsurf 工作流无法正确执行，请检查：
  • 工作流文件格式是否正确，以及是否位于 .windsurf/workflows/ 目录中
  • 是否已在 Windsurf 的 MCP Server 面板中正确配置 MCP 服务
  • 是否已在环境中设置所需的 API 密钥

许可证

MIT 许可证 - 版权所有 (c) Praney Behl