io.github.uditk2/review-assist-mcp (MCP)

The io.github.uditk2/review-assist-mcp Model Context Protocol (MCP) server turns an AI coding agent session into a reviewable Intent Document, and validates that document against the code diff. Its goal is to connect agent outputs to a review-ready artifact grounded in the proposed changes.

🛠️ Key Features

Converts an AI coding agent session into an Intent Document
Validates the Intent Document against the diff

🚀 Use Cases

Producing reviewable documentation from agent-driven coding sessions
Checking that stated intent aligns with the diff

⚡ Developer Benefits

Creates a review artifact derived from agent activity
Supports diff-based validation for consistency checks

⚠️ Limitations

Source data only specifies Intent Document generation and diff validation; no additional capabilities are described

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.

The coding agent spawns two role-locked subagents. The Author holds the session transcript and has no submission tools. The Intent Reviewer never sees the transcript and is the only role that can submit. The Reviewer asks questions, the Author answers from transcript evidence, and submit_document gates the write behind repository consent, interview attestation, and five local checks.

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.

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.

bash

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 — 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/<branch>.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.

Tools

Author role:

Tool	Purpose
`get_generation_guide`	Schema plus the authoring protocol. Call first.
`list_transcripts`	Find this session's transcript, ranked by how much it touches the changed files.
`search_transcript`	Retrieve only the passages bearing on one question.
`read_transcript`	Page through a transcript to hydrate a fresh context.
`compute_diff`	Deterministic `base...head` diff plus resolved SHAs.

Reviewer role:

Tool	Purpose
`get_generation_guide`	Schema plus the authoring protocol.
`get_role_definitions`	Author and reviewer subagent definitions for your client.
`compute_diff`	The change, as a reviewer first meets it.
`record_interview_round`	One question, the author's answer, whether it resolved. The server stamps `meta.interview` from these, so the interview is attested rather than self-reported.
`submit_document`	The gate. Validates, then writes `.intent/<branch>.json`.
`set_consent` / `manage_consent`	Per-repository opt in and out.

The first submit_document in a repository returns consent_required instead of writing, with a prompt for the user to answer: always, once, or never. Nothing is written until they choose.

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.

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