Review Assist MCP

review-assist-mcp

Turn an AI coding agent's session into a reviewable Intent Document — the problem it was really solving, the assumptions it made, the approaches it rejected, and an anchored walkthrough of every change — validated against the diff before it is written.

This server never calls a model. Generation is the calling agent's job; the server supplies ground truth (the diff, the transcript), enforces the role split, and gatekeeps the result.

Breaking in 0.3.0 — compute_diff no longer returns the diff text. It returns the

run handle, the numbered hunk index and the SHAs; the change itself now comes from

read_diff, a page at a time. The two used to travel together, and on a 205,826-byte

change that response reached 234,337 characters — past the client's tool-result cap, so

it was spilled to a file whole and the twelve characters of run_id went with it,

leaving a reviewer (which has no file access by design) unable to record a round or

submit anything. No response grows with the size of the change any more. Upgrade the

server and reinstall the role definitions; nothing about the Intent Document changes.

Review Assist is two installs

This package is one half. Installed alone it will author and validate Intent Documents locally, and that is all.

1. This MCP server — so your agent can author the document.

claude mcp add -s user review-assist -- npx -y review-assist-mcp   # Claude Code

codex mcp add review-assist -- npx -y review-assist-mcp # Codex

Claude desktop app: download the .mcpb and open it. No terminal.

Using the VS Code extension, or a GUI-launched editor? Register it without

npx. GUI apps on macOS get only /usr/bin:/bin:/usr/sbin:/sbin, so a

Homebrew/nvm npx is not on the path, and on Windows npx is a .cmd wrapper

that fails silently without a TTY. Either way the server shows as *not connected*

with no error. Invoking node directly avoids both:

`bash

npm install -g review-assist-mcp

claude mcp add -s user review-assist -- "$(which node)" "$(npm root -g)/review-assist-mcp/dist/index.js"

`

Both $(...) expand on your machine, so this is correct for Homebrew, nvm, fnm,

Volta and Linux alike. If you use nvm and later switch Node versions, re-run it.

To avoid the global install, launch VS Code from a terminal with code . so it

inherits your shell's PATH; npx then works. That is a habit rather than a

setting — open the editor from the Dock and it silently stops connecting.

This is a client-side issue rather than something specific to this server — every

npx-based MCP server is affected the same way

(claude-code#25044).

2. [The GitHub App](https://github.com/apps/review-assist-guided-review) — so the document becomes a guided review on the pull request.

One click, on the repositories you choose. It adds the coverage check, the summary comment, and the "Open guided review" link. There is no workflow file to add and no runner minutes — it is a GitHub App, not an Action.

Without it, the document still gets committed to .intent/ .json; nobody just sees it on the PR.

The two-role split

The document is written by two agents that cannot reach each other's tools:

• Author holds the session transcript and cannot submit.
• Intent Reviewer never sees the transcript and is the only role that can submit.

Everything the Reviewer knows about intent, it had to ask for. This is enforced, not advised: REVIEW_ASSIST_ROLE makes the server refuse to register the other role's tools, so an author instance has no submit_document and a reviewer instance has no read_transcript. Call get_role_definitions to install both as subagents for your client — that tool, like manage_consent and import_session, belongs to neither role; it is the orchestrating agent's, not the Author's or Reviewer's.

Tools

Author role:

Reviewer role:

Consent and validation

Each repository is asked once, before anything about it is read: every tool that reads a coding session returns consent_required instead, with a prompt for the user to answer: always, once, or never. The one answer covers reading the repository's sessions and writing its document, and nothing is read or written until they choose. submit_document checks it again before writing.

On allow, five deterministic checks run locally — schema, coverage (every substantive diff hunk explained), staleness, cross-references, and secret redaction — plus the interview attestation. Only then is the document written, and the response includes a ready-made PR description.

Notes

Read-only against git apart from writing .intent/. Transcripts never leave the machine; only the distilled document does. Set REVIEW_ASSIST_REPO, or pass repo per call, when the server spans multiple repositories.

While the reviewer waits for answers, get_answers holds each call on the server for up to 50s and returns as soon as an answer lands, so the reviewer polls about once a minute. REVIEW_ASSIST_ANSWER_WAIT_MS changes the hold (0 turns it off). It is read when the server starts, so restart your client after changing it, and lower it if your client cuts tool calls off in less than 50s, or every held call will time out instead of answering.

Apache-2.0 · github.com/uditk2/review-assist