内容
# go-gerrit-mcp
MCP（模型上下文协议）服务器，暴露Gerrit代码审查操作作为能力分级的工具。它允许AI代理搜索和读取变更，发布评论，投票和驱动变更状态转换 —— 具有安全姿态，使每个写入能力成为明确的操作员选择。
- **传输方式:** 标准输入输出
- **目标平台:** Gerrit 3.13+，通过HTTP凭证认证
- **输出:** llmxml — 面向模型的可读语义标签文本（参见[输出格式](#输出格式)）
## 安全姿态
两个默认值编码了它：
- **零配置仅暴露`读取`组。** 除非通过`--groups`启用，否则写入能力永远不会出现。
- **默认启用仅限于自己的变更的限制。** 即使启用了写入组，留下痕迹的操作（评论，投票，状态更改，其他人类可见的操作）也拒绝在变更不是认证账户拥有的情况下，直到操作员明确传递`--own-changes-only=false`。
代理在同事的变更上留下不想要的痕迹是一种外部可见的失败；缺少能力是一种本地可发现的不便。根据这些，默认值被选择。故意扩大：
```sh
# 代理可以对任何人的变更发表评论和投票，但仅限于两个项目
go-gerrit-mcp --groups read,comment,transition --own-changes-only=false --projects core,infra
```
## 安装
**二进制发布** — 从 [GitHub Releases](https://github.com/GaijinEntertainment/go-gerrit-mcp/releases) 下载适用于您平台的二进制文件，使其可执行并将其放在您的 `PATH` 中：
```sh
# 苹果芯片的macOS；替换 <os>_<arch> 为：linux，darwin，windows x amd64，arm64
curl -Lo /usr/local/bin/go-gerrit-mcp \
https://github.com/GaijinEntertainment/go-gerrit-mcp/releases/latest/download/go-gerrit-mcp_darwin_arm64
chmod +x /usr/local/bin/go-gerrit-mcp
```
**Docker：**
```sh
docker pull ghcr.io/gaijinentertainment/go-gerrit-mcp:latest
```
**go install：**
```sh
go install dev.gaijin.team/go/go-gerrit-mcp/cmd/go-gerrit-mcp@latest
```
## 快速开始
服务器仅从环境变量中读取连接标识 — 凭证永远不会通过标志传递：
| 变量 | 含义 |
| --- | --- |
| `GERRIT_URL` | Gerrit实例的基本URL |
| `GERRIT_USERNAME` | HTTP基本认证的账户用户名 |
| `GERRIT_TOKEN` | 与用户名配对的HTTP凭证 |
在Gerrit的 **设置 → HTTP凭证** 下生成凭证（HTTP密码或实例提供的认证令牌）。所有三个变量都是必需的；服务器退出时，会报错指出缺少的变量。
### Claude 代码
```sh
claude mcp add gerrit \
--env GERRIT_URL=https://gerrit.example.com \
--env GERRIT_USERNAME=your-username \
--env GERRIT_TOKEN=your-http-credential \
-- go-gerrit-mcp
```
### 任意MCP客户端（JSON配置）
```json
{
"mcpServers": {
"gerrit": {
"command": "go-gerrit-mcp",
"args": ["--groups", "read"],
"env": {
"GERRIT_URL": "https://gerrit.example.com",
"GERRIT_USERNAME": "your-username",
"GERRIT_TOKEN": "your-http-credential"
}
}
}
}
```
### Docker
```json
{
"mcpServers": {
"gerrit": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "GERRIT_URL", "-e", "GERRIT_USERNAME", "-e", "GERRIT_TOKEN",
"ghcr.io/gaijinentertainment/go-gerrit-mcp:latest",
"--groups", "read"
],
"env": {
"GERRIT_URL": "https://gerrit.example.com",
"GERRIT_USERNAME": "your-username",
"GERRIT_TOKEN": "your-http-credential"
}
}
}
}
```
## 能力组
能力在启动时通过`--groups`以逗号分隔的列表选择。组是独立且可组合的 —— 没有阶梯；每个具有写入能力的组都捆绑了其正常运行所需的最小变更读取子集，并且启用的组是联合的。
| 组 | 工具 |
| --- | --- |
| `read` | `search_changes`, `get_change`, `list_change_files`, `get_file_diff`, `get_change_comments` |
| `comment` | `get_change`, `get_change_comments`, `post_comments` |
| `transition` | `get_change`, `set_vote`, `transition_change` |
### 工具
- `search_changes` — 使用Gerrit的变更查询语法查询变更，分页。
- `get_change` — 一个变更的评审相关细节：状态，所有者，带有投票的标签，当前修订，消息。
- `list_change_files` — 修订版触及的文件，带有每个文件的变更统计。
- `get_file_diff` — 修订版中一个文件的差异。
- `get_change_comments` — 变更的评论线程，带有解析状态和评论ID。
- `post_comments` — 发布评论：可选的顶级消息和内联，范围，文件级和回复评论；回复锚定到`get_change_comments`的评论ID；`resolved`切换线程状态。
- `set_vote` — 设置标签投票（例如`Code-Review`）并带有可选消息；值`0`清除自己的投票。
- `transition_change` — 移动变更状态：`submit`，`abandon`，`restore`，`wip`或`ready`，并带有可选消息（提交不接受消息）。Gerrit的拒绝 — 被阻止的提交，合并变更的恢复 — 被原样报告。
## 配置参考
行为通过CLI标志配置，每个标志都镜像一个环境变量，以便二进制和Docker调用的配置方式相同。优先级：**标志优先于其镜像，镜像优先于默认值。**
| 标志 | 镜像 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `--groups` | `GERRIT_MCP_GROUPS` | `read` | 以逗号分隔的能力组：`read`，`comment`，`transition` |
| `--projects` | `GERRIT_MCP_PROJECTS` | （空） | 项目允许列表，限制所有操作，包括读取 |
| `--own-changes-only` | `GERRIT_MCP_OWN_CHANGES_ONLY` | `true` | 拒绝对非认证账户拥有的变更的操作 |
| `--include-tools` | `GERRIT_MCP_INCLUDE_TOOLS` | （空） | 仅保留已列出的工具，来自组解析的集合 |
| `--exclude-tools` | `GERRIT_MCP_EXCLUDE_TOOLS` | （空） | 从组解析的集合中删除已列出的工具 |
注意：
- `--own-changes-only`需要一个明确的布尔值：`--own-changes-only=false`。没有值的裸标志是一个配置错误。
- **项目范围**（`--projects`）在服务器端强制执行：一个项目子句被注入每个变更查询中，无论代理如何组合，并且拒绝直接操作超出范围的变更。
- **工具过滤器**仅限缩小。`--exclude-tools`从组解析的集合中删除工具；`--include-tools`仅保留已列出的子集。组外工具永远无法通过过滤器激活，排除优先于包含。命名未知工具的过滤器条目启动失败，因此配置错误立即出现。
- 配置错误被聚合：服务器报告每个问题一次，然后退出非零。
## 输出格式
每个工具都以 **llmxml** 响应：一种LLM可读的XML子集 — 结构化的，语义标签的文本，面向模型读取。属性携带元数据，元素主体携带内容：
```
<changes query="status:open owner:self" start="0" count="1" more="false">
<change number="12345" project="core" branch="main" status="NEW" owner="Jane Doe (jdoe)" updated="2026-07-10T20:48:32Z">fix scanner initialization</change>
</changes>
```
没有XML声明，没有命名空间，也没有模式；没有任何东西可以解析它。如果您需要可机器读取的Gerrit数据，请直接使用Gerrit的REST API — 此格式适用于模型消费。
## 许可证
[MIT](LICENSE)
