review-guard 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.