Gerrit Review MCP Server

Gerrit Review MCP 服务

此 MCP 服务可与 Gerrit 代码评审系统集成，让 AI 助手通过简洁的界面评审代码更改及其详细信息。

功能

该服务提供一套精简的代码评审工具：

获取更改详情

fetch_gerrit_change(change_id: str, patchset_number: Optional[str] = None)

• 获取完整的更改信息，包括文件和补丁集
• 显示每个已修改文件的详细差异信息
• 显示文件更改、插入和删除内容
• 支持评审特定补丁集
• 返回全面的更改详情，包括：
  • 项目和分支信息
  • 作者和评审者详情
  • 评论和评审历史
  • 包含差异内容的文件修改信息
  • 当前补丁集信息

比较补丁集差异

fetch_patchset_diff(change_id: str, base_patchset: str, target_patchset: str, file_path: Optional[str] = None)

• 比较某个更改的两个补丁集之间的差异
• 查看特定文件的差异或所有已更改文件
• 分析不同补丁集版本之间的代码修改
• 跟踪各轮评审中的更改演进

提交评审反馈

submit_gerrit_review(
    change_id: str,
    message: Optional[str] = None,
    patchset_number: Optional[str] = None,
    labels: Optional[Dict[str, int]] = None,
    comments: Optional[List[Dict[str, Any]]] = None,
    notify: str = "OWNER",
)

• 发布总结反馈、投票标签（例如，{"Code-Review": 1}）以及行内／文件级评论
• 指定特定补丁集，或默认使用最新修订版本
• 控制 Gerrit 的通知行为（notify：NONE、OWNER、OWNER_REVIEWERS、ALL）
• 评论载荷接受包含 path、message 以及可选 Gerrit 评论字段（line、side、range 等）的字典

使用示例

评审完整的更改：

# Fetch latest patchset of change 23824
change = fetch_gerrit_change("23824")

提交包含投票和行内评论的评审反馈：

submit_gerrit_review(
    change_id="23824",
    message="Looks good overall",
    labels={"Code-Review": 1},
    comments=[{"path": "src/app.py", "line": 42, "message": "Nice refactor."}],
    patchset_number="2",           # optional: target a specific patchset
    notify="OWNER_REVIEWERS",      # optional: adjust notification scope
)

比较指定的补丁集：

# Compare differences between patchsets 1 and 2 for change 23824
diff = fetch_patchset_diff("23824", "1", "2")

查看特定文件的更改：

# Get diff for a specific file between patchsets
file_diff = fetch_patchset_diff("23824", "1", "2", "path/to/file.swift")

前提条件

• Python 3.10 或更高版本（推荐 Python 3.11）
• Gerrit HTTP 访问凭据
• 从 Gerrit 设置中生成的 HTTP 密码
• 访问 mcp[cli] 软件包仓库（私有软件包）

安装

通过 Smithery 安装

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

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

手动安装

1. 克隆此仓库：

git clone <repository-url>
cd gerrit-review-mcp

2. 创建并激活虚拟环境：

# For macOS/Linux:
python -m venv .venv
source .venv/bin/activate

# For Windows:
python -m venv .venv
.venv\Scripts\activate

3. 以可编辑模式安装此软件包及其依赖项：

pip install -e .

配置

1. 设置环境变量：

export GERRIT_HOST="gerrit.example.com"  # Your Gerrit server hostname (without https://)
export GERRIT_USER="your-username"       # Your Gerrit account username
export GERRIT_HTTP_PASSWORD="your-http-password"  # Generated HTTP password from Gerrit Settings > HTTP Credentials
export GERRIT_EXCLUDED_PATTERNS="\.pbxproj$,\.xcworkspace$,node_modules/"  # Optional: regex patterns for files to exclude from reviews
# Optional TLS configuration for custom or self-signed certificates
export GERRIT_SSL_VERIFY="true"              # Set to 'false' to skip TLS verification in constrained environments
export GERRIT_CA_BUNDLE="/path/to/ca.pem"    # Optional custom CA bundle path used when verification stays enabled
# Note: If both are set, GERRIT_CA_BUNDLE takes precedence and verification stays enabled using that bundle.

或者创建 .env 文件：

GERRIT_HOST=gerrit.example.com
GERRIT_USER=your-username
GERRIT_HTTP_PASSWORD=your-http-password
GERRIT_EXCLUDED_PATTERNS=\.pbxproj$,\.xcworkspace$,node_modules/
GERRIT_SSL_VERIFY=true
GERRIT_CA_BUNDLE=/path/to/ca.pem
# If both are set, the CA bundle wins.

2. 生成 HTTP 密码：

• 登录 Gerrit Web 界面
• 前往 Settings > HTTP Credentials
• 生成新密码
• 将密码复制到环境变量或 .env 文件中

3. 配置文件排除项（可选）：

• 设置 GERRIT_EXCLUDED_PATTERNS，以从更改评审中排除特定文件类型
• 使用逗号分隔的正则表达式模式（例如，\.pbxproj$,\.xcworkspace$,node_modules/）
• 留空或不设置，以使用默认排除项
• 这有助于避免大型文件导致的无限循环

MCP 配置

若要将此 MCP 服务与 Cursor 或 RooCode 搭配使用，需要将其配置添加到 ~/.cursor/mcp.json 或 .roo/mcp.json 文件中。所需配置如下：

{
  "mcpServers": {
    "gerrit-review-mcp": {
      "command": "/path/to/your/workspace/gerrit-code-review-mcp/.venv/bin/python",
      "args": [
        "/path/to/your/workspace/gerrit-code-review-mcp/server.py",
        "--transport",
        "stdio"
      ],
      "cwd": "/path/to/your/workspace/gerrit-code-review-mcp",
      "env": {
        "PYTHONPATH": "/path/to/your/workspace/gerrit-code-review-mcp",
        "VIRTUAL_ENV": "/path/to/your/workspace/gerrit-code-review-mcp/.venv",
        "PATH": "/path/to/your/workspace/gerrit-code-review-mcp/.venv/bin:/usr/local/bin:/usr/bin:/bin"
      },
      "stdio": true
    }
  }
}

将 /path/to/your/workspace 替换为你的实际工作区路径。例如，如果你的项目位于 /Users/username/projects/gerrit-code-review-mcp，请使用该路径。

确保配置中的所有路径均指向：

• 虚拟环境中的 Python 解释器
• 项目的 server.py 文件
• 正确的工作目录
• PATH 中虚拟环境的 bin 目录

实现详情

此服务使用 Gerrit REST API 与 Gerrit 交互，提供：

• 快速可靠地获取更改信息
• 使用 HTTP 摘要认证进行安全身份验证
• 支持各种 Gerrit REST 端点
• 整洁且易于维护的代码库
• 使用 HTTPS 加密，确保通信安全

故障排除

如果遇到连接问题：

1. 确认已在 GERRIT_HTTP_PASSWORD 中正确设置 HTTP 密码
2. 检查 GERRIT_HOST 设置（仅填写主机名，不含 https://）
3. 确保 Gerrit 服务已启用 HTTPS 访问
4. 使用带有 /a/ 前缀的 curl 测试经过身份验证的 API 调用：

   curl -u "your-username:your-http-password" https://your-gerrit-server.com/a/changes/?q=status:open
   

5. 确认你的账号具有 Gerrit 访问权限

HTTP 凭据身份验证问题

如果身份验证遇到问题，请检查 Gerrit 配置中的 gitBasicAuthPolicy = HTTP（或 HTTP_LDAP）。

使用自签名证书

• 如果 Gerrit 使用内部颁发且缺少所需主题备用名称（SAN）条目的证书，GERRIT_SSL_VERIFY=false 会禁用 TLS 验证。
• 通过 GERRIT_CA_BUNDLE=/path/to/ca.pem 提供自定义证书包，以便在信任私有 CA 的同时保持验证启用。
• 应将禁用验证视为临时解决方法，直到为你访问的 Gerrit 主机名颁发匹配的 SAN 证书。

许可证

本项目采用 MIT 许可证授权。

测试

本项目包含全面的 Docker 集成测试，使用 testcontainers-python 实现可靠的跨平台测试。

运行测试

运行完整测试套件：

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run only integration tests
pytest -m integration

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=. --cov-report=html

测试环境变量

可使用以下环境变量配置测试行为：

• TEST_STARTUP_TIMEOUT：容器启动超时时间，单位为秒（默认值：30）
• TEST_LOGS_SETTLE_DELAY：检查日志前的延迟时间，单位为秒（默认值：0）
• DOCKER_HOST：远程 Docker 的 Docker 守护进程主机（可选）

示例：

# Run tests with custom timeouts
TEST_STARTUP_TIMEOUT=60 TEST_LOGS_SETTLE_DELAY=1 pytest tests/test_docker_integration.py -v

Docker 要求

Docker 集成测试需要：

• Docker 守护进程正在运行且可访问
• Docker 套接字位于 /var/run/docker.sock（Linux/macOS），或已设置 DOCKER_HOST
• 具备足够权限来构建和运行容器

如果 Docker 不可用，测试将自动跳过。

CI/CD 集成

对于 CI/CD 环境，请确保：

• 提供 Docker-in-Docker（DinD）服务
• 已挂载 Docker 套接字或已配置 DOCKER_HOST
• 为较慢的环境设置了足够的超时时间

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 运行测试套件，确保一切正常
5. 提交 pull request