AGENTS.md

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). 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, 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, 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.