@gyeonghokim/gerrit-cli 0.0.1 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +360 -324
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,324 +1,360 @@
|
|
|
1
|
-
# gerrit-mcp-server
|
|
2
|
-
|
|
3
|
-
[
|
|
4
|
-
|
|
5
|
-
[
|
|
4
|
+
|
|
5
|
+
[](https://github.com/GyeongHoKim/gerrit-mcp-server/actions/workflows/ci.yml)
|
|
6
|
+
[](https://www.npmjs.com/package/@gyeonghokim/gerrit-mcp-server)
|
|
7
|
+
[](https://go.dev)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
|
|
10
|
+
Connect your AI coding agent to Gerrit code review.
|
|
11
|
+
|
|
12
|
+
Ask your agent to find the changes waiting on you, read a diff, draft line comments, and publish a
|
|
13
|
+
review — without leaving the session and without pasting code review comments back and forth.
|
|
14
|
+
|
|
15
|
+
It ships as **two frontends over the same code**, so you can pick how much of your agent's context
|
|
16
|
+
you want to spend:
|
|
17
|
+
|
|
18
|
+
| | What it is | Context cost |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| **`gerrit-cli` + skill** | A command-line binary, plus an [agent skill](skills/gerrit-cli/SKILL.md) that teaches an agent to drive it | One line, until the skill triggers |
|
|
21
|
+
| **`gerrit-mcp-server`** | A [Model Context Protocol](https://modelcontextprotocol.io) server over **stdio** | 22 tool schemas, for the whole session |
|
|
22
|
+
|
|
23
|
+
The skill route is the lighter one and works with any agent that reads skills. The MCP server needs
|
|
24
|
+
no shell access and works with any MCP client: Claude Code, Codex, Cursor, Zed, Continue, or your
|
|
25
|
+
own.
|
|
26
|
+
|
|
27
|
+
Either way it is a single static binary with no runtime dependencies. You self-host it; nothing is
|
|
28
|
+
sent anywhere except to the Gerrit host you configure.
|
|
29
|
+
|
|
30
|
+
## Quick start
|
|
31
|
+
|
|
32
|
+
Both routes start the same way.
|
|
33
|
+
|
|
34
|
+
**Create a Gerrit auth token.** In Gerrit, go to *Settings → HTTP Credentials* and generate one.
|
|
35
|
+
See [Credentials](#credentials) below if your Gerrit is older.
|
|
36
|
+
|
|
37
|
+
Node is needed only so that `npm` or `npx` can fetch the right binary for your machine. The binaries
|
|
38
|
+
are Go and have no Node runtime dependency.
|
|
39
|
+
|
|
40
|
+
### Route A — `gerrit-cli` + agent skill
|
|
41
|
+
|
|
42
|
+
The lighter one. Nothing sits in your agent's context until it needs Gerrit.
|
|
43
|
+
|
|
44
|
+
**1. Install the binary.**
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm i -g @gyeonghokim/gerrit-cli
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**2. Install the skill.** This works for Claude Code, Codex, Cursor and many others.
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npx skills add GyeongHoKim/gerrit-mcp-server
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**3. Configure it.** Run this yourself in a terminal — it asks for your token on stdin, and will
|
|
57
|
+
refuse to run where nothing can type into it.
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
gerrit-cli init
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**4. Check it.** `gerrit-cli config` reports every setting and where it came from, naming anything
|
|
64
|
+
still missing. Then ask your agent: *"What’s the verified score for XXX Change Id’s review?"*
|
|
65
|
+
|
|
66
|
+
To allow the commands that modify Gerrit, set `GERRIT_ALLOW_WRITE=true` — see
|
|
67
|
+
[Available tools and commands](#available-tools-and-commands).
|
|
68
|
+
|
|
69
|
+
You can also use the CLI on its own, without an agent:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
gerrit-cli query-changes --query "is:open reviewer:self -owner:self"
|
|
73
|
+
gerrit-cli get-file-diff --change-id 12345 --file src/main.go
|
|
74
|
+
gerrit-cli help
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Route B — MCP server
|
|
78
|
+
|
|
79
|
+
No shell access needed, and it works with any MCP client.
|
|
80
|
+
|
|
81
|
+
**Add the server to your client.**
|
|
82
|
+
|
|
83
|
+
<details open>
|
|
84
|
+
<summary><b>Claude Code</b></summary>
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
claude mcp add gerrit \
|
|
88
|
+
--env GERRIT_URL=https://gerrit.example.com \
|
|
89
|
+
--env GERRIT_USER=your-username \
|
|
90
|
+
--env GERRIT_TOKEN=your-token \
|
|
91
|
+
-- npx -y @gyeonghokim/gerrit-mcp-server
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
</details>
|
|
95
|
+
|
|
96
|
+
<details>
|
|
97
|
+
<summary><b>Codex</b></summary>
|
|
98
|
+
|
|
99
|
+
Add this to `~/.codex/config.toml`, or to `.codex/config.toml` for a single trusted project:
|
|
100
|
+
|
|
101
|
+
```toml
|
|
102
|
+
[mcp_servers.gerrit]
|
|
103
|
+
command = "npx"
|
|
104
|
+
args = ["-y", "@gyeonghokim/gerrit-mcp-server"]
|
|
105
|
+
# npx downloads the binary on first run, which can exceed the 10s default.
|
|
106
|
+
startup_timeout_sec = 60
|
|
107
|
+
|
|
108
|
+
[mcp_servers.gerrit.env]
|
|
109
|
+
GERRIT_URL = "https://gerrit.example.com"
|
|
110
|
+
GERRIT_USER = "your-username"
|
|
111
|
+
GERRIT_TOKEN = "your-token"
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Or let the CLI write it for you:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
codex mcp add gerrit \
|
|
118
|
+
--env GERRIT_URL=https://gerrit.example.com \
|
|
119
|
+
--env GERRIT_USER=your-username \
|
|
120
|
+
--env GERRIT_TOKEN=your-token \
|
|
121
|
+
-- npx -y @gyeonghokim/gerrit-mcp-server
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
</details>
|
|
125
|
+
|
|
126
|
+
<details>
|
|
127
|
+
<summary><b>Cursor, Zed, and other clients</b></summary>
|
|
128
|
+
|
|
129
|
+
Add this to the client's MCP configuration file:
|
|
130
|
+
|
|
131
|
+
```jsonc
|
|
132
|
+
{
|
|
133
|
+
"mcpServers": {
|
|
134
|
+
"gerrit": {
|
|
135
|
+
"command": "npx",
|
|
136
|
+
"args": ["-y", "@gyeonghokim/gerrit-mcp-server"],
|
|
137
|
+
"env": {
|
|
138
|
+
"GERRIT_URL": "https://gerrit.example.com",
|
|
139
|
+
"GERRIT_USER": "your-username",
|
|
140
|
+
"GERRIT_TOKEN": "your-token"
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
</details>
|
|
148
|
+
|
|
149
|
+
**Ask for something.** "What changes am I reviewing?" or "Summarise the diff on change 12345."
|
|
150
|
+
|
|
151
|
+
## Credentials
|
|
152
|
+
|
|
153
|
+
Gerrit authenticates REST clients with HTTP Basic using a token from your account settings, and
|
|
154
|
+
expects authenticated requests to be prefixed with `/a/`. Both binaries handle the prefix for you.
|
|
155
|
+
|
|
156
|
+
Generate a token under *Settings → HTTP Credentials*. On Gerrit 3.13 and newer you can name the
|
|
157
|
+
token and give it a lifetime (`90 days`, `1 year`, and so on) — worth doing, so the credential this
|
|
158
|
+
holds is scoped and expires on its own. Older Gerrit versions call the same thing an *HTTP
|
|
159
|
+
password*; it still works, as that endpoint is now an alias that creates a token with the id
|
|
160
|
+
`legacy`.
|
|
161
|
+
|
|
162
|
+
**Where the token lives depends on which frontend you use.**
|
|
163
|
+
|
|
164
|
+
`gerrit-mcp-server` reads the environment and only the environment, so its credentials live in your
|
|
165
|
+
MCP client's config file and nowhere else. It never reads a file of its own.
|
|
166
|
+
|
|
167
|
+
`gerrit-cli` has no client config to inherit from, so `gerrit-cli init` writes one under the OS
|
|
168
|
+
configuration directory:
|
|
169
|
+
|
|
170
|
+
| OS | Path |
|
|
171
|
+
| --- | --- |
|
|
172
|
+
| Linux | `$XDG_CONFIG_HOME/gerrit-cli/config.json`, or `~/.config/gerrit-cli/config.json` |
|
|
173
|
+
| macOS | `~/Library/Application Support/gerrit-cli/config.json` |
|
|
174
|
+
| Windows | `%AppData%\gerrit-cli\config.json` |
|
|
175
|
+
|
|
176
|
+
Set `GERRIT_CONFIG` to put it somewhere else. Environment variables always take precedence over the
|
|
177
|
+
file, so a one-off `GERRIT_TOKEN=... gerrit-cli ...` works and CI never needs a file at all.
|
|
178
|
+
`gerrit-cli config` prints where each value actually came from.
|
|
179
|
+
|
|
180
|
+
What holds for both:
|
|
181
|
+
|
|
182
|
+
- **The token only ever travels in an `Authorization` header.** It is never passed as a process
|
|
183
|
+
argument, so it cannot be read out of `ps`, and it is never written to a log line or an error
|
|
184
|
+
message. `gerrit-cli init` has no `--token` flag for exactly this reason.
|
|
185
|
+
- **Nothing goes anywhere but your Gerrit host.**
|
|
186
|
+
|
|
187
|
+
What is worth knowing about the file:
|
|
188
|
+
|
|
189
|
+
- On Linux and macOS it is written `0600`, readable only by you. On Windows it inherits the ACL of
|
|
190
|
+
`%AppData%`, which is already restricted to your account plus SYSTEM and Administrators — setting
|
|
191
|
+
a tighter one needs a dependency this project does not take. If your `%AppData%` is redirected to
|
|
192
|
+
a network share, prefer keeping `GERRIT_TOKEN` in your environment instead.
|
|
193
|
+
- **`gerrit-cli init` echoes the token as you type it.** Hiding terminal input needs a dependency
|
|
194
|
+
this project does not take either. Pipe it in if that matters:
|
|
195
|
+
`printf 'https://gerrit.example.com
|
|
196
|
+
alice
|
|
197
|
+
%s
|
|
198
|
+
' "$TOKEN" | gerrit-cli init -non-interactive`
|
|
199
|
+
- **Do not commit it, and do not commit an MCP config either.** A project-level `.mcp.json` holding
|
|
200
|
+
`GERRIT_TOKEN` is a credential in your repository. Keep it in your user-level client config, or
|
|
201
|
+
gitignore it.
|
|
202
|
+
- **Use a dedicated token with a lifetime**, so it can be revoked without touching your other
|
|
203
|
+
credentials.
|
|
204
|
+
- Your Gerrit permissions still apply. Neither frontend can see or do anything your account cannot.
|
|
205
|
+
|
|
206
|
+
## Configuration
|
|
207
|
+
|
|
208
|
+
Both frontends read the same variables. For the MCP server they live in your client's config; for
|
|
209
|
+
the CLI they are optional, since `gerrit-cli init` writes the same settings to a file.
|
|
210
|
+
|
|
211
|
+
| Variable | Required | Default | Description |
|
|
212
|
+
| --- | --- | --- | --- |
|
|
213
|
+
| `GERRIT_URL` | yes | — | Base URL of the Gerrit host, for example `https://gerrit.example.com` |
|
|
214
|
+
| `GERRIT_USER` | yes | — | Your Gerrit username |
|
|
215
|
+
| `GERRIT_TOKEN` | yes | — | Auth token from *Settings → HTTP Credentials* |
|
|
216
|
+
| `GERRIT_ALLOW_WRITE` | no | `false` | Set to `true` to enable the tools and commands that modify Gerrit |
|
|
217
|
+
| `GERRIT_TIMEOUT` | no | `30s` | Per-request timeout |
|
|
218
|
+
| `GERRIT_LOG_LEVEL` | no | `info` | `debug`, `info`, `warn`, or `error`. Logs go to stderr |
|
|
219
|
+
| `GERRIT_CONFIG` | no | — | `gerrit-cli` only. Path to the configuration file, overriding the default |
|
|
220
|
+
|
|
221
|
+
## Available tools and commands
|
|
222
|
+
|
|
223
|
+
**The two frontends expose exactly the same set**, and a test in the repository holds them there.
|
|
224
|
+
A CLI command is its MCP tool name with the underscores written as dashes — `query_changes` becomes
|
|
225
|
+
`query-changes` — and `gerrit-cli` accepts either spelling.
|
|
226
|
+
|
|
227
|
+
Reads are always available. **Writes are off unless you set `GERRIT_ALLOW_WRITE=true`**, so an
|
|
228
|
+
agent cannot abandon a change or post a review by accident. The MCP server does not register the
|
|
229
|
+
write tools at all; `gerrit-cli` still lists them in its help, marked, but refuses to run one.
|
|
230
|
+
|
|
231
|
+
The same asymmetry applies to operations your Gerrit is too old for — see
|
|
232
|
+
[Supported Gerrit versions](#supported-gerrit-versions).
|
|
233
|
+
|
|
234
|
+
### Read
|
|
235
|
+
|
|
236
|
+
| Tool | Description |
|
|
237
|
+
| --- | --- |
|
|
238
|
+
| `query_changes` | Search changes with Gerrit query syntax (`status:open owner:self`) |
|
|
239
|
+
| `get_change_details` | Full summary of one change |
|
|
240
|
+
| `get_commit_message` | Commit message of the current patch set |
|
|
241
|
+
| `list_change_files` | Files touched by the latest patch set |
|
|
242
|
+
| `get_file_diff` | Diff for one file in a change |
|
|
243
|
+
| `list_change_comments` | Published comments on a change |
|
|
244
|
+
| `list_draft_comments` | Your unpublished draft comments |
|
|
245
|
+
| `changes_submitted_together` | Changes that would submit alongside this one |
|
|
246
|
+
| `suggest_reviewers` | Reviewer suggestions for a change |
|
|
247
|
+
| `get_bugs_from_cl` | Bug ids referenced in the commit message |
|
|
248
|
+
|
|
249
|
+
Every value is a flag; `gerrit-cli` has no positional arguments. Run `gerrit-cli help <command>`
|
|
250
|
+
for one command's flags — that is authoritative and cannot go stale.
|
|
251
|
+
|
|
252
|
+
`gerrit-cli` also has five commands of its own that no MCP tool corresponds to: `help`, `version`,
|
|
253
|
+
`config`, `init`, and `doctor`, which reports your host's Gerrit release and what that rules out.
|
|
254
|
+
|
|
255
|
+
There is deliberately **no `--json` output**. Everything passes through the same renderer that keeps
|
|
256
|
+
responses inside a sensible token budget, and handing an agent raw Gerrit JSON would undo that.
|
|
257
|
+
|
|
258
|
+
### Write — requires `GERRIT_ALLOW_WRITE=true`
|
|
259
|
+
|
|
260
|
+
| Tool | Description |
|
|
261
|
+
| --- | --- |
|
|
262
|
+
| `post_review_comment` | Add a draft comment on a line, or reply in a thread |
|
|
263
|
+
| `publish_drafts` | Publish your draft comments as a review |
|
|
264
|
+
| `delete_draft_comment` | Delete one draft comment |
|
|
265
|
+
| `delete_draft_comments` | Delete every draft on a change |
|
|
266
|
+
| `add_reviewer` | Add a reviewer or CC |
|
|
267
|
+
| `set_topic` | Set or clear the topic |
|
|
268
|
+
| `set_ready_for_review` | Take a change out of WIP (needs Gerrit 2.15+) |
|
|
269
|
+
| `set_work_in_progress` | Mark a change WIP (needs Gerrit 2.15+) |
|
|
270
|
+
| `create_change` | Create a change |
|
|
271
|
+
| `abandon_change` | Abandon a change |
|
|
272
|
+
| `revert_change` | Revert a change |
|
|
273
|
+
| `revert_submission` | Revert a whole submission (needs Gerrit 3.2+) |
|
|
274
|
+
|
|
275
|
+
## Exit codes
|
|
276
|
+
|
|
277
|
+
`gerrit-cli` reports what to do about a failure, not just that one happened. Rendered output goes to
|
|
278
|
+
stdout and everything else to stderr, so the answer is safe to pipe.
|
|
279
|
+
|
|
280
|
+
| Code | Meaning |
|
|
281
|
+
| --- | --- |
|
|
282
|
+
| 0 | Success |
|
|
283
|
+
| 1 | Something else failed; read stderr |
|
|
284
|
+
| 2 | Bad arguments |
|
|
285
|
+
| 3 | Not configured — run `gerrit-cli init` |
|
|
286
|
+
| 4 | Not permitted — the account, `GERRIT_ALLOW_WRITE`, or a Gerrit too old for this operation |
|
|
287
|
+
| 5 | No such change, file or comment |
|
|
288
|
+
| 6 | The change is not in a state that allows this |
|
|
289
|
+
|
|
290
|
+
## Supported Gerrit versions
|
|
291
|
+
|
|
292
|
+
Built and tested against the Gerrit **3.14** REST API. Supported down to **2.14**.
|
|
293
|
+
|
|
294
|
+
Almost everything works unchanged on an old host — including the draft comment endpoints, which
|
|
295
|
+
earlier versions of this document blamed. Three write operations genuinely do not exist:
|
|
296
|
+
|
|
297
|
+
| Operation | Needs |
|
|
298
|
+
| --- | --- |
|
|
299
|
+
| `set_work_in_progress` / `set-work-in-progress` | Gerrit 2.15+ |
|
|
300
|
+
| `set_ready_for_review` / `set-ready-for-review` | Gerrit 2.15+ |
|
|
301
|
+
| `revert_submission` / `revert-submission` | Gerrit 3.2+ |
|
|
302
|
+
|
|
303
|
+
The two frontends handle that the same way they handle write access. `gerrit-mcp-server` asks the
|
|
304
|
+
host which release it is as it starts, and never offers a tool it cannot serve, so the tool list
|
|
305
|
+
your client sees is right from the first time it asks. `gerrit-cli` lists the commands with the
|
|
306
|
+
release each needs and reports exit 4 if you run one anyway, naming both the release required and
|
|
307
|
+
the one your host reports.
|
|
308
|
+
|
|
309
|
+
**If the release cannot be determined, everything is offered.** A proxy that swallows the version
|
|
310
|
+
endpoint, or a patched internal fork that backported an endpoint, should not lose an operation that
|
|
311
|
+
works — so an unknown version hides nothing, and anything genuinely missing still fails with a
|
|
312
|
+
clear message.
|
|
313
|
+
|
|
314
|
+
One more difference worth knowing: Gerrit did not report comment counts before 3.0, so
|
|
315
|
+
`get_change_details` omits that line on an older host rather than claiming zero.
|
|
316
|
+
|
|
317
|
+
```bash
|
|
318
|
+
gerrit-cli doctor # which release your host runs, and what that rules out
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
## Other ways to install
|
|
322
|
+
|
|
323
|
+
`npm` is the easy path, but the binaries stand alone.
|
|
324
|
+
|
|
325
|
+
```bash
|
|
326
|
+
# Go toolchain
|
|
327
|
+
go install github.com/GyeongHoKim/gerrit-mcp-server/cmd/gerrit-mcp-server@latest
|
|
328
|
+
go install github.com/GyeongHoKim/gerrit-mcp-server/cmd/gerrit-cli@latest
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
Or download the archive for your platform from the
|
|
332
|
+
[releases page](https://github.com/GyeongHoKim/gerrit-mcp-server/releases). It contains both
|
|
333
|
+
binaries and the agent skill, and you can point your MCP client's `command` straight at
|
|
334
|
+
`gerrit-mcp-server`. No Node required.
|
|
335
|
+
|
|
336
|
+
## Development
|
|
337
|
+
|
|
338
|
+
```bash
|
|
339
|
+
mise install # toolchain, pinned in mise.toml
|
|
340
|
+
just setup # dependencies and git hooks
|
|
341
|
+
just ci # everything CI runs
|
|
342
|
+
just --list # all tasks
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
If you are AI Coding Agent(Codex, Claude Code, OpenCode, etc.), See [AGENTS.md](AGENTS.md) for architecture, conventions, and the Gerrit API details worth knowing
|
|
346
|
+
before you touch the client.
|
|
347
|
+
|
|
348
|
+
## License
|
|
349
|
+
|
|
350
|
+
[Elastic License 2.0](LICENSE).
|
|
351
|
+
|
|
352
|
+
> It is prohibited to deploy this MCP server as a commercial service.
|
|
353
|
+
|
|
354
|
+
**Using this at work is fine.** ELv2 places exactly three restrictions on you: you may not offer
|
|
355
|
+
this software to third parties as a hosted or managed service, you may not circumvent license key
|
|
356
|
+
functionality, and you may not strip the copyright notices. Running it, modifying it, forking it,
|
|
357
|
+
and deploying it across your engineering organisation are all expressly permitted.
|
|
358
|
+
|
|
359
|
+
Note that ELv2 is source-available rather than OSI-approved open source. If your organisation
|
|
360
|
+
screens dependencies by license, it may need to be allowlisted.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gyeonghokim/gerrit-cli",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"description": "Command-line client for Gerrit code review, and the binary behind the gerrit-cli agent skill.",
|
|
5
5
|
"license": "Elastic-2.0",
|
|
6
6
|
"author": "GyeongHoKim",
|
|
@@ -34,10 +34,10 @@
|
|
|
34
34
|
"node": ">=18"
|
|
35
35
|
},
|
|
36
36
|
"optionalDependencies": {
|
|
37
|
-
"@gyeonghokim/gerrit-mcp-server-linux-x64": "0.0
|
|
38
|
-
"@gyeonghokim/gerrit-mcp-server-linux-arm64": "0.0
|
|
39
|
-
"@gyeonghokim/gerrit-mcp-server-darwin-x64": "0.0
|
|
40
|
-
"@gyeonghokim/gerrit-mcp-server-darwin-arm64": "0.0
|
|
41
|
-
"@gyeonghokim/gerrit-mcp-server-win32-x64": "0.0
|
|
37
|
+
"@gyeonghokim/gerrit-mcp-server-linux-x64": "1.0.0",
|
|
38
|
+
"@gyeonghokim/gerrit-mcp-server-linux-arm64": "1.0.0",
|
|
39
|
+
"@gyeonghokim/gerrit-mcp-server-darwin-x64": "1.0.0",
|
|
40
|
+
"@gyeonghokim/gerrit-mcp-server-darwin-arm64": "1.0.0",
|
|
41
|
+
"@gyeonghokim/gerrit-mcp-server-win32-x64": "1.0.0"
|
|
42
42
|
}
|
|
43
43
|
}
|