使用说明

代码审阅器MCP服务器

一个MCP（模型上下文协议）服务器，根据可定制的审阅者角色执行自动代码审阅。与Cursor IDE和其他MCP兼容工具无缝集成。

概述

此服务器通过根据可配置的审查标准分析git差异来提供自动代码审查功能。它支持自定义审阅者角色，使执行特定于团队的代码质量标准变得容易。

特性

服务器公开了7个工具：

工具	说明
`get_branch_diff`	获取当前分支和基础分支之间的git diff
`get_changed_files`	使用统计信息列出当前分支上更改的文件
`review_diff`	与评审背景和角色标准有所不同
`review_file`	根据标准审查特定文件
`get_persona`	查看活跃审阅者角色
`get_review_checklist`	获取完整的审核清单
`generate_review_report`	生成降价审查报告文件

自定义角色支持

所有审核工具都接受 persona_file 使用自定义审阅者角色的参数：

persona_file: "personas/example_persona.md"

默认位置 （按顺序检查）：

personas/example_persona.md 在MCP服务器目录中
notebooks/code_reviewer_persona.md 在项目根目录中（为了向后兼容性）
嵌入式默认角色（如果找不到文件）

角色示例： 看 personas/example_persona.md 查看评论者角色的完整示例。

安装

先决条件

Python 3.10+
紫外线（推荐）或pip

设置

安装依赖项：

cd code-reviewer-mcp
uv sync  # or: pip install -r requirements.txt

设置光标规则 （可选但推荐）：

将模板规则复制到项目的 .cursor/rules/ 目录：
```
mkdir -p .cursor/rules
cp tools/code-reviewer-mcp/.cursor/rules/code-review.mdc.template .cursor/rules/code-review.mdc
```
然后根据项目的审查标准对其进行自定义。

在游标中配置 通过添加到 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "code-reviewer": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/code-reviewer-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

或者如果使用pip：

{
  "mcpServers": {
    "code-reviewer": {
      "command": "python",
      "args": [
        "/path/to/code-reviewer-mcp/server.py"
      ]
    }
  }
}

建筑

代码审查员由两部分组成：

MCP服务器 (server.py)：提供工具(get_branch_diff, review_diff等等）
光标规则 (.cursor/rules/code-review.mdc)：提供工作流程说明和审查标准

MCP服务器是 可重复使用的 跨项目-它提供通用的代码审查工具。
光标规则为 特定项目 -它定义了团队的审查标准和工作流程。

当您要求进行代码审查时，游标规则会指示AI：

调用哪些MCP工具以及调用顺序
要检查哪些标准
如何格式化输出

游标中的用法

快速开始

重新启动游标 安装后加载新的MCP服务器
让Claude检查你的代码：
- “查看我当前的分支”
- “根据发展情况审查此PR”
- “检查此文件是否存在问题”

示例命令

基本用法（使用默认角色）：

"Review the changes on my branch"
"Get the diff against development"
"Review src/my_module/file.py"
"Generate a code review report"

使用自定义角色（使用@reference）：

"Review my code using @personas/example_persona.md"
"Review this file using the persona at @path/to/strict_reviewer.md"
"Generate a review report with @personas/example_persona.md"

这 @file Cursor中的语法扩展了文件引用，使为不同的审阅风格选择不同的审阅者角色。

使用光标规则

光标规则位于 .cursor/rules/code-review.mdc 自动触发当你说“审查”、“代码审查”或“PR审查”时，审查者。

规则的作用：

提供使用MCP工具的分步工作流程说明
定义审查标准和检查表（类型安全、文件等）
指定评论的输出格式
通过以下方式处理角色文件选择 @ 语法

对于本项目： 该规则位于 .cursor/rules/code-review.mdc 在repo根目录中。

对于其他项目： 模板规则文件包含在 tools/code-reviewer-mcp/.cursor/rules/code-review.mdc.template。将其复制到项目的 .cursor/rules/ 目录，并根据团队的标准对其进行自定义。

该规则规定：

工作流程说明：关于如何使用MCP工具的分步指南
审查标准：检查内容清单（可根据项目定制）
输出格式：审查意见结构
集成指导：如何与Bitbucket MCP结合进行PR评论

Persona文件

人物角色选择是如何工作的

显式选择：通行证 persona_file 带有路径的参数
默认位置 （按顺序检查）：
- personas/example_persona.md 在MCP服务器目录中
- notebooks/code_reviewer_persona.md 在项目根目录中（为了向后兼容性）
嵌入式回退：如果找不到文件，则使用内置角色

角色示例： 看 personas/example_persona.md 基于真实代码审查模式的完整示例。

创建自定义角色

根据您的审核标准创建一个标记文件。示例结构：

# Code Reviewer Persona: [Name]

## Review Philosophy
[Your approach to code review]

## Key Standards
### Type Safety
- [Your type checking rules]

### Documentation
- [Your documentation requirements]

### Code Style
- [Your style preferences]

## Common Callouts
- "Missing type hint" → Add type annotations
- "No tests" → Add test coverage

切换角色

您可以为不同的上下文创建多个角色文件。将它们存储在 personas/ 目录：

personas/example_persona.md -示例角色（包含在此仓库中）
personas/strict_reviewer.md -用于生产代码（创建自己的代码）
personas/junior_friendly.md -教育，更具解释性（创建自己的）
personas/security_focused.md -强调安全模式（创建自己的模式）

从开始 personas/example_persona.md 并根据团队的需求进行定制。

默认审核标准

嵌入式默认角色检查以下内容：

类型安全

所有函数的完整类型提示
现代语法(str | None 超过 Optional)
不 Any 没有正当理由的类型

文档

具有版权的文件头
带参数/返回值的完整文档字符串

代码组织

仅绝对进口
幻数作为常数
已删除未使用的代码

错误处理

仅特定例外
处理边缘案件

建筑

保持分层
模板中的常见逻辑

公用事业

导出PR评论

这 utils/export_comments.py 该脚本有助于将您的Bitbucket PR评论导出到CSV进行分析或者为代码审查角色构建训练数据。

用途：

# Set environment variables (recommended)
export ATLASSIAN_EMAIL="your-email@example.com"
export BITBUCKET_API_TOKEN="your-api-token"
export BITBUCKET_WORKSPACE="your-workspace"
export BITBUCKET_REPO_SLUG="your-repo"
export BITBUCKET_ACCOUNT_ID="your-account-id"  # Optional: filter to your comments only

# Export comments (from the code-reviewer-mcp directory)
python utils/export_comments.py

# Export only your comments (with account ID filter)
python utils/export_comments.py --account-id your-account-id

# Export all comments (no filter)
python utils/export_comments.py --account-id ""

# Or pass everything as arguments
python utils/export_comments.py \
  --email your-email@example.com \
  --token your-token \
  --workspace your-workspace \
  --repo your-repo \
  --output my_comments.csv \
  --account-id your-account-id

备注：此实用程序需要 requests 图书馆。安装方式：

pip install requests
# or
uv add requests

输出： 该脚本生成一个包含列的CSV文件：

pr_id, pr_title, pr_url
comment_id, content
file_path, line （用于内联评论）
created_on, updated_on

发展

测试服务器

cd code-reviewer-mcp
uv run server.py

服务器通过stdio进行通信，因此您会看到它正在等待JSON-RPC消息。

修改人物角色

评论者角色嵌入 server.py 在 REVIEWER_PERSONA 常数。更新此内容以更改审核标准。

局限性

没有内联评论：游标没有可通过编程方式添加的API 对文件进行内联注释。服务器输出带有file:line引用的评论你可以导航到。
专注于Python：当前筛选器为 *.py 默认情况下为文件。这 file_filter 可以更改参数以包括其他文件类型。

故障排除

服务器未出现在游标中

检查 ~/.cursor/mcp.json 具有正确的路径
完全重新启动光标（macOS上的Cmd+Q）
检查MCP日志： ~/Library/Logs/Claude/mcp*.log

Git错误

使用diff相关工具时，请确保您位于git存储库中。服务器需要访问git命令。

可选：Bitbucket集成

对于使用Bitbucket的团队，您可以选择配置 @lexmata/bitbucket-mcp 服务器以实现程序化的PR评论创建。这允许您发布评论直接发送到Bitbucket拉取请求。

设置Bitbucket MCP

安装Bitbucket MCP服务器 （如果尚未安装）：
```
npm install -g @lexmata/bitbucket-mcp
```

在中配置 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "code-reviewer": {
      "command": "uv",
      "args": ["--directory", "/path/to/code-reviewer-mcp", "run", "server.py"]
    },
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@lexmata/bitbucket-mcp"],
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_REPO_SLUG": "your-repo",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

用法：配置后，您可以在代码审阅器旁边使用Bitbucket MCP工具：
- 以编程方式创建PR评论
- 获取PR详细信息
- 将评论反馈直接发布到Bitbucket
工作流程示例：
```
1. Use code-reviewer tools to generate review feedback
2. Use bitbucket-mcp tools to post comments to the PR
```
备注：此集成是可选的。代码审查员在没有它的情况下工作得很好，生成审核报告，您可以手动复制到PR评论中。