{ "markdown": "# go-gerrit-mcp\n\nAn MCP (Model Context Protocol) server that exposes Gerrit code review operations as capability-gated tools. An AI\nagent can search and read changes, publish review comments, vote, and drive change-state transitions. Every write\ncapability is an explicit operator opt-in.\n\n- Transport: stdio\n- Target platform: Gerrit 3.13+, authenticated via HTTP credentials\n- Output: llmxml, semantically tagged text meant to be read by a model (see [Output format](#output-format))\n\n## Safety posture\n\nTwo defaults encode it:\n\n- Zero configuration exposes the `read` group only. Write capability never appears unless enabled via `--groups`.\n- The own-changes restriction is on by default. Even with write groups enabled, trail-leaving operations (comments,\n votes, state changes, anything other humans see) are refused on changes the authenticated account does not own,\n until the operator explicitly passes `--own-changes-only=false`.\n\nAn agent leaving unwanted trail on colleagues' changes is an externally visible failure; a missing capability is a\nlocally discoverable inconvenience. The defaults are chosen accordingly. Widen deliberately:\n\n```sh\n# agent may comment and vote on anyone's changes, but only within two projects\ngo-gerrit-mcp --groups read,comment,transition --own-changes-only=false --projects core,infra\n```\n\n## Install\n\nBinary release: download the binary for your platform from\n[GitHub Releases](https://github.com/GaijinEntertainment/go-gerrit-mcp/releases), make it executable, and put it on\nyour `PATH`:\n\n```sh\n# macOS on Apple silicon; substitute _ from: linux, darwin, windows x amd64, arm64\ncurl -Lo /usr/local/bin/go-gerrit-mcp \\\n https://github.com/GaijinEntertainment/go-gerrit-mcp/releases/latest/download/go-gerrit-mcp_darwin_arm64\nchmod +x /usr/local/bin/go-gerrit-mcp\n```\n\nDocker:\n\n```sh\ndocker pull ghcr.io/gaijinentertainment/go-gerrit-mcp:latest\n```\n\ngo install:\n\n```sh\ngo install dev.gaijin.team/go/go-gerrit-mcp/cmd/go-gerrit-mcp@latest\n```\n\n## Quick start\n\nThe server reads connection identity from environment variables only; credentials never travel through flags:\n\n| Variable | Meaning |\n| ----------------- | -------------------------------------------------- |\n| `GERRIT_URL` | Base URL of the Gerrit instance |\n| `GERRIT_USERNAME` | Account username for HTTP Basic authentication |\n| `GERRIT_TOKEN` | HTTP credential paired with the username |\n\nGenerate the credential in Gerrit under **Settings → HTTP Credentials** (an HTTP password, or an auth token on\ninstances that issue them). All three variables are required; the server exits with an error naming the missing ones.\n\n### Claude Code\n\n```sh\nclaude mcp add gerrit \\\n --env GERRIT_URL=https://gerrit.example.com \\\n --env GERRIT_USERNAME=your-username \\\n --env GERRIT_TOKEN=your-http-credential \\\n -- go-gerrit-mcp\n```\n\n### Any MCP client (JSON configuration)\n\n```json\n{\n \"mcpServers\": {\n \"gerrit\": {\n \"command\": \"go-gerrit-mcp\",\n \"args\": [\"--groups\", \"read\"],\n \"env\": {\n \"GERRIT_URL\": \"https://gerrit.example.com\",\n \"GERRIT_USERNAME\": \"your-username\",\n \"GERRIT_TOKEN\": \"your-http-credential\"\n }\n }\n }\n}\n```\n\n### Docker\n\n```json\n{\n \"mcpServers\": {\n \"gerrit\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"GERRIT_URL\", \"-e\", \"GERRIT_USERNAME\", \"-e\", \"GERRIT_TOKEN\",\n \"ghcr.io/gaijinentertainment/go-gerrit-mcp:latest\",\n \"--groups\", \"read\"\n ],\n \"env\": {\n \"GERRIT_URL\": \"https://gerrit.example.com\",\n \"GERRIT_USERNAME\": \"your-username\",\n \"GERRIT_TOKEN\": \"your-http-credential\"\n }\n }\n }\n}\n```\n\n## Per-project configuration in Claude Code\n\nEverything the server needs is read from the environment: the identity variables above plus a `GERRIT_MCP_*` mirror\nfor every flag (see [Configuration reference](#configuration-reference)). MCP server processes inherit the session\nenvironment, so in Claude Code one user-level registration turns into per-project configuration, down to different\nGerrit instances with different credentials per repository.\n\n`~/.claude.json` holds the registration, with no `env` block:\n\n```json\n{\n \"mcpServers\": {\n \"gerrit\": {\n \"command\": \"go-gerrit-mcp\"\n }\n }\n}\n```\n\n`/.claude/settings.local.json` carries the project's environment; every `env` entry reaches the server\nprocess:\n\n```json\n{\n \"env\": {\n \"GERRIT_URL\": \"https://gerrit.example.com\",\n \"GERRIT_USERNAME\": \"your-username\",\n \"GERRIT_TOKEN\": \"your-http-credential\",\n \"GERRIT_MCP_GROUPS\": \"read,comment\",\n \"GERRIT_MCP_PROJECTS\": \"core,infra\"\n }\n}\n```\n\nValues shared by most projects can sit one layer down in `~/.claude/settings.json`. Settings files merge, with\n`.claude/settings.local.json` over `.claude/settings.json` over `~/.claude/settings.json`, so a project declares only\nits deltas. Anything no layer sets falls back to the server's own defaults: read-only, own changes.\n\nThe registration's `env` block stays empty for a reason. A variable named there shadows every settings layer, and\nreferences are no workaround: `${VAR}` expands only from the shell environment that launched `claude`, never from\nsettings files, and anything unresolved reaches the server as a literal string.\n\nOther MCP clients inherit their launch environment the same way, so per-directory tooling such as\n[direnv](https://direnv.net/) achieves the identical split without client support.\n\n## Capability groups\n\nCapability is selected at startup via `--groups` as a comma-separated list. Groups are independent and combinable,\nwith no privilege ladder: each write-capable group bundles the minimal change-read subset it needs to work on its\nown, and enabled groups union.\n\n| Group | Tools |\n| ------------ | ---------------------------------------------------------------------------------------- |\n| `read` | `search_changes`, `get_change`, `list_change_files`, `get_file_diff`, `get_change_comments` |\n| `comment` | `get_change`, `get_change_comments`, `post_comments` |\n| `transition` | `get_change`, `set_vote`, `transition_change` |\n\n### Tools\n\n- `search_changes`: query changes with Gerrit's change query syntax, paginated.\n- `get_change`: one change in review-relevant detail: status, owner, labels with votes, current revision, messages.\n- `list_change_files`: files touched by a revision, with per-file change stats.\n- `get_file_diff`: the diff of one file in a revision.\n- `get_change_comments`: comment threads on a change, with resolution state and comment ids. Returns unresolved\n threads only by default; `status=all` fetches the full history, `status=resolved` the settled threads.\n- `post_comments`: publish a review in one call: optional top-level message plus inline, range, file-level, and\n reply comments. Replies anchor to comment ids from `get_change_comments`; `resolved` toggles the thread state.\n- `set_vote`: set a label vote (e.g. `Code-Review`) with an optional message; value `0` clears an own vote.\n- `transition_change`: move a change's state: `submit`, `abandon`, `restore`, `wip`, or `ready`, with an optional\n message (submit accepts none). Gerrit's refusal (a blocked submit, a restore of a merged change) is reported\n verbatim.\n\n## Review notifications\n\nAn opt-in push channel for review activity. The agent subscribes to a change with `subscribe_change`; from then on,\nnew change messages, votes, inline comment threads, and status transitions arrive in the session on their own as\n`review_activity` blocks. The payload uses the same llmxml vocabulary the read tools emit and carries the activity\nwhole, so nothing needs fetching afterwards. `unsubscribe_change` ends a subscription early. A merged or abandoned\nchange ends its own subscription with a final notification that says so, and a change that becomes unreadable\n(deleted, or no longer visible to the account) does the same, with the reason spelled out.\n\nSubscriptions are per-session and in-memory: they leave no trace on the Gerrit instance, end with the session, and\nafter a server restart the agent subscribes again. With the feature off (the default) the server is byte-identical\nto its pre-feature self, with no extra tools or capabilities and no background polling.\n\nEnabling takes both sides:\n\n1. Server side: pass `--review-notifications=true` (or its mirror). The server registers both subscription tools\n and polls Gerrit every `--review-notifications-poll-interval` (default `60s`): one batched query per tick over\n all subscribed changes, with detail fetches only for changes that actually moved.\n2. Client side: delivery uses the Claude Code channels contract (research preview, Claude Code 2.1.80 or newer).\n For a server registered plainly under `mcpServers`, launch with\n `claude --dangerously-load-development-channels server:`, where `` is the registration key; it\n becomes the `source` attribute of the injected `` blocks. Allowlisted channel plugins load with\n `claude --channels` instead.\n\nResearch-preview caveats: organization policy can disable channels entirely; the flag syntax may change between\nClaude Code releases; and a client without channel support silently drops the events, in which case the server\nbehaves exactly as if the feature were off, with no errors on either side.\n\nNoise control is operator configuration. The server applies no heuristics of its own and filters nothing by message\ntag, because a bot's verdict is often exactly the outcome the agent is waiting for:\n\n- the authenticated account's own activity is skipped by default (`--review-notifications-include-own` keeps it);\n- `--review-notifications-exclude-accounts` silences accounts by username or numeric ID;\n- `--review-notifications-exclude-patterns` drops events whose message or comment text matches a regular\n expression; an invalid pattern fails startup with an error naming it.\n\nEvery flag has a `GERRIT_MCP_*` mirror that follows the same settings layering as the rest of the configuration\n(see [Per-project configuration](#per-project-configuration-in-claude-code)), so a project can enable notifications\nand pick exclusions in its own settings file.\n\n## Configuration reference\n\nBehavior is configured by CLI flags, each mirrored by an environment variable so one configuration style works for\nbinary and Docker invocations alike. Precedence: the flag wins over its mirror, and the mirror wins over the default.\n\n| Flag | Mirror | Default | Meaning |\n| -------------------- | ----------------------------- | ------- | -------------------------------------------------------------- |\n| `--groups` | `GERRIT_MCP_GROUPS` | `read` | Comma-separated capability groups: `read`, `comment`, `transition` |\n| `--projects` | `GERRIT_MCP_PROJECTS` | (empty) | Project allowlist confining every operation, reads included |\n| `--own-changes-only` | `GERRIT_MCP_OWN_CHANGES_ONLY` | `true` | Refuse trail-leaving operations on changes not owned by the authenticated account |\n| `--include-tools` | `GERRIT_MCP_INCLUDE_TOOLS` | (empty) | Keep only the listed tools from the group-resolved set |\n| `--exclude-tools` | `GERRIT_MCP_EXCLUDE_TOOLS` | (empty) | Remove the listed tools from the group-resolved set |\n| `--review-notifications` | `GERRIT_MCP_REVIEW_NOTIFICATIONS` | `false` | Enable [review notifications](#review-notifications) |\n| `--review-notifications-poll-interval` | `GERRIT_MCP_REVIEW_NOTIFICATIONS_POLL_INTERVAL` | `60s` | Poll cadence for subscribed changes, as a Go duration |\n| `--review-notifications-include-own` | `GERRIT_MCP_REVIEW_NOTIFICATIONS_INCLUDE_OWN` | `false` | Keep the authenticated account's own activity in notifications |\n| `--review-notifications-exclude-accounts` | `GERRIT_MCP_REVIEW_NOTIFICATIONS_EXCLUDE_ACCOUNTS` | (empty) | Accounts (usernames or numeric IDs) whose activity never becomes a notification |\n| `--review-notifications-exclude-patterns` | `GERRIT_MCP_REVIEW_NOTIFICATIONS_EXCLUDE_PATTERNS` | (empty) | Comma-separated regular expressions; matching message or comment text never becomes a notification |\n\nNotes:\n\n- `--own-changes-only` takes an explicit boolean value: `--own-changes-only=false`. A bare flag without a value is a\n configuration error.\n- Project scoping (`--projects`) is enforced server-side: a project clause is injected into every change query\n regardless of what the agent composed, and direct operations on out-of-scope changes are refused.\n- Tool filters only narrow. `--exclude-tools` removes tools from what the groups resolved; `--include-tools` keeps\n only the listed subset of it. A tool outside the enabled groups can never be activated by a filter, and exclude\n wins over include. Filter entries naming no known tool fail startup, so misconfigurations surface immediately.\n- Configuration errors are aggregated: the server reports every problem at once, then exits non-zero.\n\n## Output format\n\nEvery tool responds in llmxml, an LLM-digestible subset of XML: line-structured, semantically tagged text meant to\nbe read by a model. Attributes carry metadata; element bodies carry content:\n\n```\n\nfix scanner initialization\n\n```\n\nThere is no XML declaration, no namespaces, and no schema; nothing parses it back. If you need machine-readable\nGerrit data, use Gerrit's REST API directly; this format is for model consumption.\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 13992, "sha": "bb536b36eb7cc56a252a6b1d09762926cee41fc65a5aa93e7eafb3adb31bbd7f", "repo_slug": "gaijinentertainment/go-gerrit-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_team_gaijin_go_gerrit_mcp_498c9092/readme" }