For everything not covered here, the human-facing docs are authoritative: see
`README.md` for modes, tools, flags, and usage, and `CONTRIBUTING.md` for the
development setup, the script list, and the release process.

## Project overview

ReviewGuard MCP (npm package `@eclipsesource/review-guard-mcp`, binary
`review-guard-mcp`, MCP server name `review-guard`) is a TypeScript MCP server
that lets AI agents work on GitHub PR reviews behind a safety boundary. In the
default **pending mode** agents read PR discussion context and create draft
(pending) reviews but cannot submit them. In the opt-in **submit mode**
(`--allow-submit`) an agent may also submit the review, restricted to an allowed
action set and always prefixed with a fixed disclaimer. Two transports: stdio
(for IDE-managed lifetime) and HTTP (remote server).

## Architecture

- **`src/github.ts`**: `GitHubReviewClient` class. The ONLY file that touches GitHub APIs. Uses GraphQL for resolved review-thread context and mutations, and REST for review summaries and general PR comments. Review-thread comments (GraphQL `reactionGroups`) and conversation comments (REST `reactions`) expose a normalized `reactions` map (content -> count, e.g. `THUMBS_DOWN`) so agents can see downvotes. Thread `isResolved`/`resolvedBy` are also returned. Review comments, review summaries and conversation comments all carry their GitHub permalink as `url`, so an agent can link an earlier discussion (a thread's permalink is its first comment's `url`). The field is named `url` everywhere even though it comes from GraphQL `url` for review comments and REST `html_url` for the REST-sourced ones, since the output shape should be more consistent than the GitHub API is. A pending review comment already carries its final permalink, which starts resolving when the review is submitted, so an agent can cross-link its own findings while drafting. The `ReviewComment.url` doc comment and the pending tool descriptions say so, and the integration suite asserts that a comment's permalink survives submission unchanged. Safety boundary: comment/thread mutations exclude the `event` field, a post-creation tripwire verifies `PENDING` state (its error message tells the agent to stop and alert the human, since many MCP clients do not surface tool errors), and write operations are limited to the authenticated user's review. Submission is gated: `submitReview` (the only place `submitPullRequestReview` is called) refuses any action not in the `allowSubmit` set passed to the constructor, and always prefixes the review body with the fixed `submitBody` (an optional caller `additionalBody` is appended below it, never replacing it). Replies (`replyToReviewThreads`) are deliberately not limited to the authenticated user's own threads, since a reply is just another draft comment in the user's pending review. They always pass that pending review's id, every target thread is verified to belong to the PR the call names before anything is written, and each created reply goes through the PENDING tripwire, which also checks that the reply landed in that pending review. Thread resolution is gated too: `resolveReviewThread` runs only when `allowResolve` is set AND the thread's first comment is authored by the authenticated user (it refuses others' threads), so a bot can tidy up its own now-fixed findings but not close anyone else's conversations. PR scoping is enforced here too: when the client is constructed with a `scope` (owner/repo/PR), every public method calls `assertInScope` and refuses input targeting a different PR/repo, and `resolveReviewThread` verifies the thread's PR matches the scope. This is the authoritative boundary. The server-side schema change is convenience on top of it.
- **`src/server.ts`**: `createMcpServer(client)` factory. Registers `get_pr_review_context`, `list_pending_review`, `add_review_comments`, `reply_to_review_threads`, `modify_review_comment`, and `delete_pending_review` with Zod schemas. Additionally registers `submit` **only when** `client.allowedSubmitActions` is non-empty (its `action` enum is restricted to that set), and `resolve_review_thread` **only when** `client.resolveEnabled` (started with `--allow-resolve`). When `client.scopedPullRequest` is set, the PR tools omit their `owner`/`repo`/`pull_number` arguments and act on the scoped PR implicitly. Shared by both transports.
- **`src/stdio.ts`**: Stdio transport entry point. Connects the MCP server to stdin/stdout for IDE-managed lifetime (Theia, VS Code).
- **`src/http.ts`**: HTTP transport. A plain `node:http` server exposing stateless Streamable HTTP at `/mcp` (POST only, GET/DELETE return 405, other paths 404). No web framework: the MCP transport parses the request body and enforces the Host header itself. Receives `{ port, host }` from the entry point and binds that address (default `127.0.0.1`). Validates the Host header of incoming requests (DNS rebinding protection): loopback aliases only for a loopback bind, plus the bind address and the container-runtime host names (`host.docker.internal`, `host.containers.internal`) for a non-loopback bind.
- **`src/index.ts`**: Thin dispatcher. Parses the CLI via `parseCliOptions`, resolves the GitHub token, applies the default submit disclaimer, creates the client, then delegates to `--stdio` or HTTP mode.
- **`src/args.ts`**: `parseCliOptions`, the single place that knows every CLI flag. Accepts `--flag value` and `--flag=value`. Throws `CliUsageError` on unknown flags, missing values, or duplicates (the entry point prints it and exits non-zero), so a typo'd hardening flag (e.g. the `--repo`/`--pr` scope) can never be silently ignored.
- **`test/`**: vitest suite. `args.test.ts` covers CLI validation. `github.test.ts` covers the safety gates (submit refusal, fixed-body prefixing, scope assertion, own-thread resolve, reply thread checks, PENDING tripwire) with mocked `gql`/`octokit` internals. `server.test.ts` covers tool registration and dispatch over an in-memory MCP transport. `server-json.test.ts` covers the MCP Registry entry (see Key conventions). Changes to the safety boundary must keep this coverage. `test/integration/review-guard.itest.ts` is a manual end-to-end suite (`npm run test:integration`, own config in `vitest.integration.config.ts`) that drives every tool against a real GitHub repository with two accounts and verifies the results through direct API reads. It is excluded from `npm test` and CI, setup is documented in CONTRIBUTING.md.

## Key conventions

- **`server.json`**: the MCP Registry entry, published by the release workflow as `com.eclipsesource/review-guard`. Metadata only, so nothing is hosted for users and the `remotes` field stays unused: the entry describes the npm package and `--stdio`, which the client runs locally. It deliberately declares no `--allow-submit` or `--allow-resolve` argument, so the registry install path is the safe pending mode. Its `name` must stay equal to `mcpName` in `package.json` (how the registry verifies package ownership) and both of its versions must match the published npm version. `test/server-json.test.ts` enforces all of this and validates the file against the schema pinned in its `$schema` field (vendored verbatim under `test/fixtures/`, so validation stays offline), since otherwise it would only fail mid-release. The publishing job pins and checksums the `mcp-publisher` binary and refuses to run when the tag's `server.json` does not declare the version being listed
- ESM (`"type": "module"` in package.json), NodeNext module resolution
- Strict TypeScript. ESLint (type-checked) and Prettier are enforced in CI, so run `npm run lint` and `npm run format` before committing
- No em dashes and no semicolons in prose. This applies to docs, code comments, and user-facing strings. Write plain sentences instead
- Tool errors returned as `{ isError: true }` content, not thrown
- Server binds to `127.0.0.1` by default, or the one specific address given with `--host`. Unspecified addresses (`0.0.0.0`, `::`) are refused at CLI parsing. The HTTP transport validates the Host header (DNS rebinding protection)
- `submitPullRequestReview` lives ONLY in `submitReview` and runs ONLY when `allowSubmit` is non-empty and the requested action is in it. Do not add submission anywhere else, do not bypass the `allowSubmit` gate. The `submitBody` prefix stays server-controlled: a caller may pass `summary` (the `submit` tool) which is APPENDED below the prefix, but the prefix is always present and can never be replaced or removed.