review-assist-mcp

review-assist-mcp

将 AI 编码 Agent 的会话转化为可供评审的 意图文档——它实际要解决的问题、做出的假设、拒绝的方案，以及对每项更改进行锚定式逐步说明——并在写入前根据差异进行验证。

此服务不会调用大模型。生成内容是调用方 Agent 的工作；服务端提供真实依据（差异和会话记录）、强制执行角色分离，并把关最终结果。

0.3.0 版的重大变更——compute_diff 不再返回差异文本，而是返回运行句柄、带编号的代码块索引和 SHA；现在需要通过 read_diff 分页获取变更内容。以前这两者会一并返回，而在 205,826 字节的变更中，响应长度达到 234,337 个字符——超过客户端的工具结果上限，因此整个响应被溢写到文件中，连同 run_id 的十二个字符也一并溢写，导致按设计无法访问文件的评审者既无法记录访谈轮次，也无法提交任何内容。现在响应大小不再随变更规模增长。升级服务端并重新安装角色定义；意图文档本身没有任何变化。

Review Assist 需要安装两部分

此软件包只是其中一部分。单独安装后，它只能在本地编写和验证 Intent Documents，仅此而已。

1. 此 MCP 服务——让你的 Agent 能够编写文档。

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 桌面应用： 下载 .mcpb 并打开。无需终端。

使用 VS Code 扩展或通过 GUI 启动的编辑器？ 无需使用 npx 即可注册。在 macOS 上，GUI 应用只能获取 /usr/bin:/bin:/usr/sbin:/sbin，因此 Homebrew/nvm 的 npx 不在路径中；在 Windows 上，npx 是一个 .cmd 包装程序， 没有 TTY 时会静默失败。无论哪种情况，服务都会显示为未连接，且没有错误提示。 直接调用 node 可以避开这两个问题：

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

两个 $(...) 都会在你的机器上展开，因此此方法适用于 Homebrew、nvm、fnm、 Volta 和 Linux。如果你使用 nvm，之后切换 Node 版本时，请重新运行此命令。

若要避免全局安装，请从终端运行 code . 启动 VS Code，使其继承 shell 的 PATH；这样就能使用 npx。这是一种使用习惯，而不是设置项——从 Dock 打开编辑器， 连接就会悄无声息地中断。

这是客户端问题，并非此服务独有——所有基于 npx 的 MCP 服务都会受到同样影响 （claude-code#25044）。

2. GitHub App——让文档 在拉取请求上成为引导式评审。

只需点击一次，即可应用到你选择的仓库。它会添加覆盖率检查、摘要评论和“Open guided review”链接。无需添加工作流文件，也不消耗运行器分钟数——它是 GitHub App，不是 Action。

如果没有它，文档仍会提交到 .intent/<branch>.json；只是没有人能在 PR 上看到它。

两种角色的划分

文档由两个无法访问对方工具的 Agent 编写：

• Author 持有会话记录，无法提交。
• Intent Reviewer 从未见过会话记录，是唯一可以提交的角色。

Reviewer 对意图的所有了解，都必须通过询问获得。这是强制执行的，而非建议：REVIEW_ASSIST_ROLE 会让服务拒绝注册另一角色的工具，因此 Author 实例没有 submit_document，Reviewer 实例没有 read_transcript。调用 get_role_definitions，即可为你的客户端安装这两个子 Agent——与 manage_consent 和 import_session 一样，该工具不属于任何一种角色；它属于协调 Agent，而非 Author 或 Reviewer。

工具

作者角色：

工具	用途
get_generation_guide	获取架构和编写协议。首先调用。
list_transcripts	查找本次会话的记录，并按涉及已更改文件的程度排序。
get_spine	获取会话的完整对话，分多页返回。跟随 next_cursor 直到末尾；不会为了适应页面而省略内容。
read_transcript	获取完整记录中指定 spine 索引附近的窗口，查看支撑某项说法的工具输出。
compute_diff	开始一次运行：返回句柄、带编号的差异块索引和解析后的 SHA。不包含差异文本。
read_diff	分页读取差异本身。跟随 next_cursor，或请求 hunks/paths。
get_questions	直接从运行记录中读取评审者的问题及其 q_id。
answer_questions	作者对各个 q_id 的回答。这是对访谈内容的唯一写入操作，也是服务器可以核实的部分。
set_consent	当会话工具请求同意时，记录开发者的回答，因为作者是读取会话的角色。

评审者角色：

工具	用途
get_generation_guide	获取架构和编写协议。
compute_diff	开始一次运行：返回句柄、带编号的差异块索引和解析后的 SHA。不包含差异文本。
read_diff	分页读取变更内容，这是评审者首次看到变更时的呈现方式。
record_interview_round	记录评审者的问题，再转交给作者。每个问题都会返回一个 q_id，作者按该 ID 回答，因此服务器能听到双方的陈述，而不是只听评审者代述双方。
get_answers	直接从运行记录中读取作者本人的回答。
submit_document	最终关卡。进行验证，然后写入 .intent/<branch>.json。
set_consent	按仓库选择加入或退出。

同意与验证

每个仓库在读取任何相关内容之前都会被询问一次：所有读取编码会话的工具都会改为返回 consent_required，并提示用户选择 always、once 或 never。该选择同时适用于读取仓库会话和写入文档；在用户选择之前，不会读取或写入任何内容。submit_document 会在写入前再次检查同意状态。

用户允许后，系统会在本地运行五项确定性检查——架构、覆盖范围（解释每个实质性差异块）、过时检查、交叉引用和机密信息脱敏——以及访谈证明。只有通过后才会写入文档，响应中还会附带一份可直接使用的 PR 描述。

说明

除写入 .intent/ 外，不会对 git 进行写入操作。记录不会离开本机；只有提炼后的文档会被传出。如果服务器连接多个仓库，请设置 REVIEW_ASSIST_REPO，或在每次调用时传入 repo。

评审者等待回答时，get_answers 会在服务器上保持每次调用最多 50s，并在收到回答后立即返回，因此评审者大约每分钟轮询一次。REVIEW_ASSIST_ANSWER_WAIT_MS 可更改等待时间（设为 0 可关闭等待）。该值在服务器启动时读取，因此更改后请重启客户端；如果客户端会在 50s 前中断工具调用，请调低此值，否则所有等待中的调用都会超时，而不是返回回答。

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