review-assist-mcp

review-assist-mcp

AI コーディングエージェントのセッションを、レビュー可能な意図ドキュメントに変換します。実際に解決しようとしていた問題、置かれた前提、採用しなかったアプローチ、すべての変更をたどれるガイドをまとめ、書き込む前に差分と照合します。

このサーバーがモデルを呼び出すことはありません。生成は呼び出し元のエージェントが担当し、サーバーはグラウンドトゥルース（差分とトランスクリプト）を提供し、役割分担を徹底し、結果を管理します。

0.3.0 での破壊的変更 — compute_diff は差分テキストを返さなくなりました。代わりに、実行ハンドル、番号付きのハンクインデックス、SHA を返します。変更内容は、ページごとに取得する read_diff から得られるようになりました。以前はこれらが一緒に返されていましたが、205,826 バイトの変更ではレスポンスが 234,337 文字に達し、クライアントのツール結果上限を超えていました。そのため、レスポンス全体がファイルに書き出され、12 文字の run_id も一緒に失われました。その結果、設計上ファイルにアクセスできない Reviewer は、ラウンドの記録も提出もできなくなっていました。変更のサイズに応じて大きくなるレスポンスは、もうありません。サーバーをアップグレードし、役割定義を再インストールしてください。意図ドキュメントの内容に変更はありません。

Review Assist は 2 つのインストールで構成されています

このパッケージはその半分です。これだけをインストールした場合、Intent Document をローカルで作成して検証できます。それだけです。

1. この MCP サーバー — エージェントがドキュメントを作成できるようにします。

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 は TTY がないと何も表示せずに失敗する .cmd ラッパーです。いずれの場合も、エラーが表示されないままサーバーは not connected と表示されます。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 を起動し、シェルの PATH を引き継がせてください。そうすれば npx が動作します。これは設定ではなく習慣として行う必要があります。Dock からエディターを開くと、接続がひそかに停止します。

これはこのサーバー固有の問題ではなく、クライアント側の問題です。npx ベースの MCP サーバーはすべて同じ影響を受けます (claude-code#25044)。

2. GitHub App — ドキュメントをプルリクエスト上のガイド付きレビューにします。

選択したリポジトリで、ワンクリックで設定できます。カバレッジチェック、サマリーコメント、「Open guided review」リンクが追加されます。追加するワークフローファイルも、ランナーの実行時間も不要です — これは GitHub App であり、Action ではありません。

これがない場合も、ドキュメントは .intent/<branch>.json にコミットされます。ただし、PR 上で確認できる人はいません。

2 つの役割の分担

ドキュメントは、互いのツールにアクセスできない 2 つのエージェントによって作成されます。

• Author はセッションのトランスクリプトを保持し、送信できません。
• Intent Reviewer はトランスクリプトを一切見ず、送信できる唯一の役割です。

Reviewer がインテントについて知っていることは、すべて自ら質問して得た情報です。これは推奨ではなく、強制される仕組みです。REVIEW_ASSIST_ROLE により、サーバーはもう一方の役割のツールの登録を拒否するため、Author インスタンスには submit_document がなく、Reviewer インスタンスには read_transcript がありません。get_role_definitions を呼び出して、クライアントに両方をサブエージェントとして登録してください。このツールは manage_consent や import_session と同様、どちらの役割にも属しません。これは 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 は書き込み前に同意を再確認します。

許可された場合、ローカルで5つの決定論的なチェック（スキーマ、網羅性（実質的な差分のすべてのハンクに説明があること）、古さ、相互参照、秘密情報のマスキング）に加え、インタビューの証明が実行されます。その後にのみドキュメントが書き込まれ、応答にはすぐに使える PR の説明が含まれます。

補足

.intent/ への書き込みを除き、git に対する読み取り専用です。トランスクリプトがマシンの外に出ることはなく、外部に出るのは要約されたドキュメントだけです。サーバーが複数のリポジトリに対応する場合は、REVIEW_ASSIST_REPO を設定するか、呼び出しごとに repo を渡してください。

レビュー担当者が回答を待っている間、get_answers はサーバー上で各呼び出しを最大50秒保留し、回答が届くとすぐに返します。そのため、レビュー担当者はおよそ1分ごとにポーリングします。保留時間は REVIEW_ASSIST_ANSWER_WAIT_MS で変更できます（0 にすると無効になります）。この値はサーバー起動時に読み込まれるため、変更後はクライアントを再起動してください。また、クライアントが50秒未満でツール呼び出しを打ち切る場合は値を小さくしてください。そうしないと、保留中の呼び出しはすべて回答を返さずタイムアウトします。

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