{ "markdown": "# ReviewGuard MCP\n\n[![CI](https://github.com/eclipsesource/review-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/eclipsesource/review-guard/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/%40eclipsesource%2Freview-guard-mcp)](https://www.npmjs.com/package/@eclipsesource/review-guard-mcp)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nMCP server (`review-guard-mcp`) that lets AI agents work on GitHub PR reviews behind a safety boundary. The server holds the write-enabled GitHub token and exposes only review operations, so the agent never sees the token. What those operations are allowed to do is fixed at server start, not negotiable by the agent.\n\n## Why\n\nA write-enabled GitHub token is needed to create review comments, but giving that token directly to an agent risks accidental or prompt-injected actions: submitting approvals, requesting changes, closing other people's review threads, or touching unrelated repositories. This server sits in between and narrows the token down to exactly the review capabilities you opt into.\n\n## Modes\n\nThe server supports two modes of use:\n\n### Pending mode (default)\n\nThe agent reads PR discussion context and builds a **pending (draft) review**. Nothing it writes is visible to anyone else until a human opens the PR, inspects the draft comments, and submits the review themselves. Submission is structurally unreachable: the `submit` tool is not even registered, and the underlying client refuses every submit action.\n\nUse this when an agent assists a human reviewer, for example in IDE setups (Claude Code, Codex, Theia) where the agent drafts inline comments and the human stays the reviewer of record.\n\n### Submit mode (opt-in, `--allow-submit`)\n\nStarted with `--allow-submit`, the server additionally registers a `submit` tool so the agent can post the review itself. Guardrails stay in place:\n\n- The allowed review actions are restricted to the set you list (for example comment-only, with no approvals).\n- Every submitted review starts with a fixed, server-configured disclaimer the agent cannot change or remove.\n- Optionally, `--allow-resolve` lets the agent resolve **its own** review threads (never anyone else's), and `--repo`/`--pr` pin the server to a single pull request.\n\nUse this for unattended, autonomous review bots, for example a watcher that reviews every PR where a review is requested from the bot account and posts a real (comment-only) review.\n\n## Installation\n\nRequires Node.js >= 22.\n\nInstall globally (makes `review-guard-mcp` available in PATH):\n\n```sh\nnpm install -g @eclipsesource/review-guard-mcp\n```\n\nOr pin to a specific version:\n\n```sh\nnpm install -g @eclipsesource/review-guard-mcp@\n```\n\nThe server is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io)\nas `com.eclipsesource/review-guard`, so clients that browse the registry can find\nand install it from there. The entry is metadata only, there is no hosted instance\nto connect to: it describes the npm package above, which your client installs and\nruns locally in the default pending mode.\n\n### From source\n\nRequires npm >= 12 and a Node version supported by it (see [CONTRIBUTING.md](CONTRIBUTING.md)):\n\n```sh\ngit clone https://github.com/eclipsesource/review-guard.git\ncd review-guard\nnpm ci\nnpm run build\nnpm link # creates a global symlink to the binary\n```\n\n## Tools\n\n| Tool | Availability | Description |\n| ----------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `get_pr_review_context` | always | Get PR author/message, submitted review summaries, inline review threads with resolved state, reactions and permalinks, and general PR comments |\n| `list_pending_review` | always | List the authenticated user's pending draft review, including all current pending review comments and their permalinks |\n| `add_review_comments` | always | Add one or more comments to the authenticated user's pending review, creating the pending review if needed |\n| `modify_review_comment` | always | Update or delete one comment from the authenticated user's pending review |\n| `delete_pending_review` | always | Delete the authenticated user's pending review and all its comments |\n| `submit` | `--allow-submit` | Submit the pending review as a real, posted review. The `action` is limited to the allowed set and the review summary always starts with the fixed, server-configured disclaimer |\n| `resolve_review_thread` | `--allow-resolve` | Resolve one of the authenticated user's **own** review threads (e.g. a prior finding the latest push fixed). Refuses threads started by anyone else |\n\n## Submit mode flags\n\nBy default the server cannot submit reviews. To allow it, start the server with `--allow-submit` listing one or more of `approve`, `comment`, `reject`:\n\n```bash\nreview-guard-mcp --port 4000 \\\n --allow-submit approve,comment \\\n --submit-body \"This is an autonomous, AI-based review and may contain mistakes.\"\n```\n\n- `--allow-submit ` enables the `submit` tool and restricts its `action` enum to exactly these values. `approve` maps to APPROVE, `comment` to COMMENT, and `reject` to REQUEST_CHANGES. Invalid actions abort startup.\n- `--submit-body ` sets the fixed review summary prefix posted with every submission. The agent cannot change or remove it and may only append its own summary below it. If omitted while `--allow-submit` is set, a built-in default disclaimer is used. Its wording adapts to the allowed actions (when `approve` is not allowed it states the review is not an approval, rather than caveating one). Requires `--allow-submit` and must not be empty.\n- `--allow-resolve` registers the `resolve_review_thread` tool. The client resolves only threads whose first comment was authored by the authenticated user, so a bot can tidy up its own now-fixed findings on a re-review but never close another reviewer's conversation.\n\nWithout `--allow-submit`, the `submit` tool is not registered and the `submitReview` client method refuses every action, so submission is structurally unreachable.\n\n## Scoping to a single PR (opt-in)\n\nStart the server with `--repo --pr ` to pin it to one pull\nrequest:\n\n```bash\nreview-guard-mcp --port 4000 --repo eclipsesource/some-repo --pr 123\n```\n\nWhen scoped, every tool drops its `owner`/`repo`/`pull_number` arguments and\nacts on that PR only. `resolve_review_thread` additionally checks that the\nthread belongs to it. The client (`github.ts`) enforces this independently of\nthe tool schemas, so a caller cannot reach a different PR or repo the token can\notherwise write to. Use this whenever the server backs an automated review of a\nknown PR (typically together with submit mode), so a prompt-injected agent\ncannot post to or resolve threads on unrelated PRs. Both flags are required\ntogether. Omitting them leaves the server unscoped (the caller supplies the PR\nper call).\n\n## MCP Client Configuration\n\n### Stdio mode (recommended for IDEs)\n\nThe server runs as a child process managed by the IDE. No port configuration needed.\n\nFor MCP clients that use the common JSON config shape (Claude Code, VS Code,\nTheia):\n\n```json\n{\n \"mcpServers\": {\n \"review-guard\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@eclipsesource/review-guard-mcp\", \"--stdio\"]\n }\n }\n}\n```\n\nFor Codex, add the server to `~/.codex/config.toml` or a trusted project-local\n`.codex/config.toml`:\n\n```toml\n[mcp_servers.review-guard]\ncommand = \"npx\"\nargs = [\"-y\", \"@eclipsesource/review-guard-mcp\", \"--stdio\"]\n```\n\nOr pin to a specific version:\n\n```json\n{\n \"mcpServers\": {\n \"review-guard\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@eclipsesource/review-guard-mcp@\", \"--stdio\"]\n }\n }\n}\n```\n\n### Remote HTTP mode\n\nThe server runs standalone and exposes a Streamable HTTP endpoint.\n\nStart the server:\n\n```bash\nreview-guard-mcp --port 4000 # bind to 127.0.0.1 (localhost only)\nreview-guard-mcp --port 4000 --host 172.17.0.1 # bind to a specific address instead\n```\n\nThen point your MCP client at the printed URL (e.g. `http://127.0.0.1:4000/mcp`). Each POST is an independent stateless request.\n\nCodex HTTP configuration uses the same TOML shape:\n\n```toml\n[mcp_servers.review-guard]\nurl = \"http://127.0.0.1:4000/mcp\"\n```\n\n#### `--host` flag\n\nBy default the HTTP server binds to `127.0.0.1`, which makes it unreachable from containers and other machines. Pass `--host
` to bind one specific address instead. Because the endpoint is unauthenticated, the unspecified addresses (`0.0.0.0`, `::`) are rejected at startup.\n\nThe main use case is a reviewing agent that runs inside a container (e.g. a sandboxed agent runtime) and needs to reach the MCP server on the host. On Linux, bind the container network's gateway IP, e.g. for Docker's default bridge (typically `172.17.0.1`):\n\n```bash\nreview-guard-mcp --port 4000 \\\n --host \"$(docker network inspect bridge --format '{{(index .IPAM.Config 0).Gateway}}')\"\n```\n\nThe host firewall must also allow traffic on the MCP port from the container subnet, e.g. with ufw:\n\n```bash\nsudo ufw allow from 172.17.0.0/16 to any port 4000 proto tcp\n```\n\nFrom inside the container you can point the client at whichever local name reaches the host: the gateway IP itself, `host.docker.internal` (Docker) or `host.containers.internal` (Podman), or a `localhost`/`127.0.0.1` alias that your runtime maps to the host. With a non-loopback `--host` the server accepts the `Host` header for any of these while still rejecting unknown hosts, so DNS-rebinding protection stays on.\n\n## Authentication\n\nIf the [GitHub CLI](https://cli.github.com/) is installed and authenticated (`gh auth login`), **no token configuration is needed**. The server automatically retrieves the token via `gh auth token`.\n\nIf `gh` is not available, provide a token explicitly via the MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"review-guard\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@eclipsesource/review-guard-mcp\", \"--stdio\"],\n \"env\": { \"GITHUB_TOKEN\": \"ghp_...\" }\n }\n }\n}\n```\n\nThe full resolution order is:\n\n1. **`GITHUB_TOKEN`** environment variable\n2. **`GH_TOKEN`** environment variable\n3. **`gh auth token`**, which reads the token from the GitHub CLI\n\nA [fine-grained personal access token](https://github.com/settings/tokens?type=beta) scoped to the repositories you review is recommended.\n\n## Security considerations\n\n- **The agent never sees the token.** The server holds it and only exposes the\n tool set configured at startup.\n- **HTTP mode binds to `127.0.0.1` by default** and validates the `Host` header\n against the bound address (DNS rebinding protection), so a malicious website\n cannot reach the server through a victim's browser.\n- **The `/mcp` endpoint itself is unauthenticated.** Anyone who can reach the\n port can use the configured capabilities. Keep it on localhost, or with a\n non-loopback `--host` restrict the port to the intended subnet via firewall,\n because every machine or container on that network can otherwise reach it.\n Unspecified bind addresses (`0.0.0.0`, `::`) are refused at startup.\n- **Prefer a fine-grained token** scoped to only the repositories under review,\n and add `--repo`/`--pr` scoping for automated setups.\n\nPlease report vulnerabilities privately, as described in [SECURITY.md](SECURITY.md).\n\n## Safety Invariants\n\nThe `src/github.ts` module is the only file that talks to GitHub. By default it cannot submit. Every capability beyond pending-review writes is gated at construction time. It enforces:\n\n1. **No `event` field on comment/thread mutations.** Draft comments always leave the review `PENDING` because `event` is omitted entirely.\n2. **Submission is opt-in and gated.** The `submitPullRequestReview` mutation is called only inside `submitReview`, which refuses any action not in the `allowSubmit` set passed at construction. A client built without `--allow-submit` (the default) can never submit. `DISMISS` is never supported.\n3. **Fixed submission body.** Submitted reviews always start with the server-configured `--submit-body`. Callers can only append below it, never replace or remove it.\n4. **Thread resolution is opt-in and own-threads-only.** `resolveReviewThread` runs only when `--allow-resolve` is set and refuses threads not started by the authenticated user.\n5. **No REST submit/dismiss endpoints** are ever called.\n6. **Own-review writes.** Write tools only affect the authenticated user's own review.\n7. **PR scoping.** When started with `--repo`/`--pr`, every operation targeting a different PR or repository is refused inside the client, independent of the tool schemas.\n8. **Auditable.** Grep `src/github.ts` for `submitPullRequestReview`, `dismiss`, `APPROVE`, `REQUEST_CHANGES`. The mutation and events appear only inside `submitReview`. The gates are covered by unit tests in `test/github.test.ts`.\n9. **Post-mutation tripwire (defense in depth).** After creating a review, the response state is verified to be `PENDING`. Unlike the gates above this detects rather than prevents: on a violation the tool call fails with an MCP error that tells the agent to stop and alert the human, because many MCP clients do not show tool errors to the user on their own.\n\n## Development\n\nDevelopment requires npm >= 12 and a Node version supported by it. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.\n\n```bash\nnpm ci # install dependencies\nnpm run build # compile TypeScript to dist/\nnpm run dev # tsx watch mode\nnpm run typecheck # type-check sources, tests, and configs\nnpm run lint # ESLint\nnpm run format:check # Prettier\nnpm test # vitest suite\nnpm run test:integration # manual suite against a real repo (see CONTRIBUTING.md)\n```\n\n## Architecture\n\n```\nsrc/\n├── index.ts # Entry point: token resolution, mode dispatch (--stdio / HTTP)\n├── args.ts # CLI parsing: every flag in one place, unknown flags abort startup\n├── server.ts # MCP server factory with tool schemas (shared by both transports)\n├── stdio.ts # Stdio transport (for IDE-managed lifetime)\n├── http.ts # HTTP transport (node:http, Streamable HTTP)\n└── github.ts # Safety boundary: GraphQL mutations + REST reads\ntest/ # vitest suite: CLI parsing, safety gates, tool registration\n```\n\n- **GraphQL** for resolved review-thread context and mutations (`addPullRequestReview`, `addPullRequestReviewThread`, `updatePullRequestReviewComment`, `deletePullRequestReviewComment`, `deletePullRequestReview`, and, behind their opt-in gates, `submitPullRequestReview` and `resolveReviewThread`).\n- **REST** for well-paginated PR review summaries and general PR conversation comments.\n- HTTP mode binds to `127.0.0.1` only (or the specific address given with `--host`).\n\n## Contributing\n\nContributions are welcome, see [CONTRIBUTING.md](CONTRIBUTING.md). Contributors\nare required to sign a CLA, which is checked automatically on pull requests.\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 15914, "sha": "12edb74d9ba15ff320ef52d422eca47eaa0d4de704a203507fc5fb7f45511ca2", "repo_slug": "eclipsesource/review-guard", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_com_eclipsesource_review_guard_1a79978f/readme" }