Batch Review

Batch Review

人間のレビュアーと AI エージェントをつなぐ、共同コード・Markdown レビューツールです。どちらも同じ UI からリアルタイムでファイルの閲覧、git 差分の確認、構造化コメントの投稿、最終レビューレポートの保存を行えます。

---

機能

機能	説明
3 パネルのレビュー UI	左側にファイルエクスプローラーと git の変更、中央にビューアー、右側にコメントスレッドを表示
Markdown のレンダリング	.md ファイルを完全にレンダリングします。KaTeX によるGitHub 形式の数式（インラインの $…$ と GitHub のドル記号・バッククォート形式、表示用の $$…$$ ブロック、フェンス付き math コードブロック）、Mermaid のフェンス付き図、WaveDrom のフェンス付き図（デジタルタイミング図、ビットフィールド／レジスター図、論理／回路図）に対応し、それぞれツールバーでレンダリング表示とソース表示を切り替えられます。任意の段落をハイライトしてコメントを追加できます
HTML のプレビュー	.html および .htm ファイルは、スクリプトを無効にしたサンドボックス内の中央パネルでレンダリングされます。レンダリングされた要素、テキスト、または視覚的な領域を選択して、ソースに紐づいたコメントを追加できます。領域コメントには保存済みの PNG 切り抜き画像も含まれます
PDF の表示	.pdf ファイルを中央パネルにレンダリングします。ページを考慮したテキストコメントや領域コメントを追加でき、再読み込みにも対応しています
DOCX/PPTX の表示	.docx および .pptx ファイルを docx-preview と @aiden0z/pptx-renderer を使用してブラウザー内でローカルにレンダリングします。文書のテキストまたは正規化されたページ／スライド領域を選択してコメントを追加できます。Office の領域選択はレビューの JSON／Markdown 出力の隣に PNG スクリーンショットとして保存されます。LibreOffice や Microsoft Office は不要です
Office 文書の安全性	Office パッケージはバイナリデータとして取得されます。git 差分モードでは、誤解を招く ZIP/XML テキストを表示せず、バイナリとして報告します
構文ハイライト	Monaco Editor による一般的なすべての言語への対応（Python、TypeScript、Go、Rust など）
インライン git 差分	変更されたファイルをクリックすると、ローカルの変更、過去のコミット／参照と HEAD の比較、または現在のチェックアウトと GitHub PR のヘッドの比較による、赤／緑のインライン統合差分を表示します
構造化コメント	各コメントには @filename:L10-15 形式の行参照が自動で記録され、必要に応じてレンダリング表示上のより詳細なアンカーも含まれます。Office のアンカーには、文書の種類、ページ／スライド、正規化された領域、選択したテキスト、レンダラーのフィンガープリントが含まれます
古くなったコメントの復旧	テキストコメントが古くなった場合、右側のパネルから現在のファイルを基に、保存済みのハイライトを更新できます
AI との共同作業	MCP サーバーは多数のツールを提供し、AI エージェントが人間と一緒にレビューできます。UI はリアルタイムで更新され、エージェントによるコメント変更は画面上に通知されます。コーディングエージェント向けのトークン効率に優れた CLI クライアントモード（batch-review <verb>）と、レビューのワークフロースキルを備えた Claude Code プラグインも付属しています
2 種類の出力	レビューを JSON（機械可読）と Markdown（人間可読）の両方で保存します
セッションの再開	起動時に {output-dir}/{output}.json がすでに存在する場合、コメントを自動的に読み込みます
クロスプラットフォーム	Windows と Linux で動作します
テーマ切り替え	左側パネル上部のバーから、Web UI を従来のダークテーマと暖かみのあるライトテーマの間で切り替えられます

GitHub 形式の数式の例

プレビューでは、数式の記述にある区切り文字のルールを使用します。インライン数式の $…$、GitHub のドル記号とバッククォートを使うインライン形式（解析前に $…$ に書き換え）、ディスプレイ数式の $$…$$、フェンス付きの math コードブロックに対応しています。GitHub の MathJax ではなく KaTeX でレンダリングするため、Markdown の構文が一致していても、一部のあまり一般的でないマクロの動作が異なる場合があります。

このアプリは Markdown プレビューに生の HTML を埋め込まないため、文章中のドル記号をそのまま表示するための GitHub の <span>$</span> 回避策は利用できません。数式内では、GitHub のドキュメントに従って $ を \$ のようにエスケープしてください。

例：

インライン：$\sqrt{3x-1}+(1+x)^2$

ドル記号とバッククォート（GitHub 互換）：$e^{i\pi} + 1 = 0$

$$ \nabla_\theta J(\theta) = \mathbb{E}{(s, a) \sim \pi\theta} \left[\nabla_\theta \log \pi_\theta(a \mid s), R(s, a)\right] $$

WaveDrom の例

フェンス付きの ```wavedrom ブロックは WaveJSON として解析され（JSON5 を使用するため、引用符なしまたはシングルクォートのキーも使用できます）、Mermaid と同じソース／レンダリング表示切り替えツールバー付きでインラインにレンダリングされます。図の種類は JSON の形状から自動的に選択され、次の 3 種類に対応しています。

デジタルタイミング図（signal）：

{signal: [
  {name: 'clk',  wave: 'p.....'},
  {name: 'data', wave: 'x.345x', data: ['head', 'body', 'tail']},
  {name: 'req',  wave: '0.1..0'},
  {name: 'ack',  wave: '1.....'}
]}

ビットフィールド／レジスター図（reg）：

{reg: [
  {bits: 7, name: 'opcode'},
  {bits: 5, name: 'rd'},
  {bits: 3, name: 'funct3'},
  {bits: 5, name: 'rs1'},
  {bits: 12, name: 'imm[11:0]'}
], config: {bits: 32}}

ロジック／回路図（assign）：

{assign: [["z", ["|", "a", ["&", "b", "c"]]]]}

---

アーキテクチャ

実行時、Batch Review は単一の Python アプリケーションとして、ブラウザー UI を提供し、その UI 向けの REST および WebSocket エンドポイントを公開します。また、オプションで同じレビューセッションを MCP クライアントにも公開します。

flowchart LR
    CLI["CLI entry point<br/>`uv run batch-review`"]
    Browser["Browser UI<br/>React + Zustand"]
    McpHost["MCP host<br/>Cursor / Claude Desktop / VS Code / other clients"]
    AgentCli["Coding agent<br/>Claude Code / Cursor CLI / Codex<br/>`batch-review <verb>`"]

    subgraph Backend["Batch Review backend process"]
        Server["FastAPI app<br/>static frontend `/`<br/>REST `/api/*`<br/>WebSocket `/ws`"]
        Mcp["FastMCP server<br/>stdio transport<br/>HTTP transport `/mcp`"]
        State["Shared AppState<br/>repo root, comments, MCP session,<br/>connected WebSocket clients"]
    end

    Repo["Git repository under review"]
    Output["Saved review output<br/>`review_comments.json`<br/>`review_comments.md`"]
    PortFile[".batch_review/server.json<br/>discovery file"]

    CLI --> Server
    CLI --> Mcp
    Server --> Browser
    Browser -->|"REST reads/writes"| Server
    Browser <-->|"live sync"| Server
    Server --> State
    Mcp --> State
    McpHost -->|"stdio or HTTP MCP"| Mcp
    AgentCli -->|"REST `/api/*`"| Server
    AgentCli -.->|"reads for discovery"| PortFile
    Server -.->|"writes on start"| PortFile
    State -->|"read files, diffs, existing review data"| Repo
    State -->|"save/load review reports"| Output
    State -.->|"broadcast UI events"| Browser

• ブラウザーは FastAPI サーバーから React アプリを読み込み、REST 経由でファイル／コメント／設定を取得し、/ws を通じて同期を維持します。
• MCP ツールと REST ルートはどちらも同じインメモリの AppState を操作するため、エージェントが作成したコメントはすぐに UI に表示されます。
• --mcp モードでは、HTTP サーバーが Web UI を利用可能な状態に保ちながら、FastMCP もエディターや CLI のホスト向けに stdio 経由で実行されます。
• CLI クライアントモードでは、コーディングエージェントが batch-review <verb>（例：add-comment、diff）を呼び出し、同じ REST エンドポイントを利用します。エージェントのコンテキストに MCP ツールのスキーマを読み込む必要はありません。サーバーは起動時に .batch_review/server.json を書き込み、CLI の動詞からサーバーを検出できるようにします。

---

配布

• PyPI — batch-review-mcp — pip／uv 向けに公開された wheel と sdist です。
• 公式 MCP Registry — io.github.hevangel/batch-review-mcp — 最新の公開サーバーメタデータです（JSON API。レジストリーサイトは現在もプレビュー版です）。

---

要件

• Python ≥ 3.13 と uv
• Node.js ≥ 22（フロントエンドの初回ビルド用。GitHub Actions と同じバージョンです）

---

インストール

git clone https://github.com/hevangel/batch-review-mcp.git
cd batch-review-mcp
uv sync

初回実行時に frontend/dist/ が存在しない場合、React フロントエンドが自動的にビルドされます（Node.js と npm が PATH 上にある必要があります）。

---

使い方

スタンドアロンモード（デフォルトでブラウザーが開きます）

# Review the current directory
uv run batch-review

# Review a specific git repository
uv run batch-review --root /path/to/your/repo

# Custom host / port
uv run batch-review --root /path/to/repo --host 0.0.0.0 --port 9100

# Specify output filenames
uv run batch-review --root /path/to/repo --output review --output-dir /tmp/reviews
# → saves /tmp/reviews/review.json and /tmp/reviews/review.md

デフォルトのポートがすでに使用中の場合、サーバーは 9000〜9999 の範囲で空いているポートを自動的に選択します。

MCP stdio モード（Claude Desktop／Cursor／任意の MCP クライアント。デフォルトでブラウザーが開きます）

uv run batch-review --mcp --root /path/to/repo

HTTP サーバーはバックグラウンドスレッドで起動するため、ブラウザー UI は引き続きアクセス可能です。デフォルトのブラウザーがアプリの URL を開きます（スタンドアロンモードと同じです。開かないようにするには --no-browser を使用してください）。MCP stdio トランスポートはメインスレッドで実行されます。

Claude Desktop の設定（claude_desktop_config.json）：

{
  "mcpServers": {
    "batch-review": {
      "command": "uv",
      "args": ["run", "batch-review", "--mcp", "--root", "/path/to/repo"]
    }
  }
}

CLI クライアントモード（トークン効率の高いエージェントインターフェース）

コーディングエージェント（Claude Code、Cursor CLI、Codex など）では、CLI クライアントモードのほうが、18 個の MCP ツールスキーマをコンテキストに読み込むよりもトークン効率に優れています。各動詞は 1 回のプロセス呼び出しで実行され、単一の JSON ドキュメントを stdout に出力します。CLI は REST 経由で実行中のサーバーと通信するため、コメントやハイライトはすべて、人間のレビュアーが使うブラウザー UI にもリアルタイムで表示されます。

# Start the server in the background (browser opens by default)
batch-review start --root .
# {"web_url": "http://127.0.0.1:9000", "pid": 12345, "port": 9000}

# List changed files
batch-review changes
# [{"path": "main.py", "status": "M", ...}, ...]

# Inspect a diff
batch-review diff main.py

# Add a comment anchored to a line range
batch-review add-comment main.py 10 15 "This null check is redundant."

# Save the review report (JSON + Markdown)
batch-review save

# Stop the server when done
batch-review stop

サーバーの検出 — 動詞は次の優先順位で実行中のサーバーを自動検出します。BATCH_REVIEW_WEB_URL 環境変数、次に <repo_root>/.batch_review/server.json（start が書き込みます）、最後にポート 9000～9999 のプローブです。

動詞リファレンス — すべての動詞で --root PATH を指定できます（デフォルト：cwd）。

動詞	引数	説明
start	[--port N] [--no-browser]	サーバーをバックグラウンドで起動します
stop	—	実行中のサーバーを停止します
config	—	サーバー設定（出力名、ディレクトリ、Web URL）
url	—	接続 URL（Web UI、WebSocket、MCP HTTP）
changes	[--mode local|commit|pr] [--base REF] [--pr N]	変更されたファイルの一覧を表示します
diff	<path> [--mode ...]	統合 diff と元の内容・変更後の内容
ls	[path] [--depth N]	ファイル／ディレクトリの一覧を表示します
file	<path>	ファイルの内容、行数、言語を読み込みます
add-comment	<path> <L1> <L2> [text] [--highlighted TEXT]	コメントを追加します
list-comments	—	すべてのコメントを一覧表示します
update-comment	<id> <text>	コメントのテキストを編集します
delete-comment	<id>	コメントを削除します
clear	—	すべてのコメントを削除します
delete-outdated	—	古いコメントを削除します
recompute-stale	—	古いコメントのフラグを再計算します
save	[--stem NAME] [--dir DIR]	JSON と Markdown に保存します
load	<stem>	保存済みのレビューを読み込みます
list-reviews	—	保存済みレビュー名の一覧を表示します
open	<path> [--mode view|diff]	ブラウザー UI でファイルを開きます
highlight	<path> <L1> <L2>	UI で行の範囲をハイライトします
jump	<comment-id>	UI でコメントの位置に移動します

出力仕様：JSON は stdout に、進行状況メッセージは stderr に出力し、エラー時はゼロ以外の終了コードを返します。start 動詞は後方互換性があり、すでにサーバーが実行中の場合は、重複して起動せず既存の URL を報告します。

Claude Code プラグイン

このリポジトリには Claude Code プラグインが含まれています（CLI 専用 — MCP サーバーエントリーはないため、エージェントはツールスキーマをコンテキストに読み込みません）。マーケットプレイスからインストールします。

/plugin marketplace add hevangel/batch-review-mcp
/plugin install batch-review@batch-review

このプラグインには次のものが含まれています。

• スキル（skills/batch-review/SKILL.md）— CLI 動詞を使ったレビューのワークフローをエージェントに教えます。
• コマンド（commands/batch-review.md）— スキルを起動する /batch-review スラッシュコマンドです。
• プラグインマニフェスト（.claude-plugin/plugin.json）＋ マーケットプレイス（.claude-plugin/marketplace.json）。

エージェントスキル（skills.sh）

レビューのワークフロースキルは、オープンな Agent Skills 標準に対応したあらゆるエージェント（Claude Code、Cursor、Codex、Gemini CLI、Copilot、ZCode など 60 以上）にも、npx skills CLI 経由でインストールできます。

# Install globally (available across all your projects)
npx skills add hevangel/batch-review-mcp --global --yes

# Or install into a specific agent only
npx skills add hevangel/batch-review-mcp --skill batch-review --agent claude-code --global

# List available skills without installing
npx skills add hevangel/batch-review-mcp --list

インストールすると、エージェントにコードのレビュー、diff の確認、レビューコメントの記入を依頼したときに、スキルが自動的に起動します。skills.sh での検出と一覧表示は、インストール時のテレメトリーによって自動的に行われます。手動で送信する必要はありません。

公式 MCP レジストリ

このプロジェクトには、Model Context Protocol registry（プレビュー）用のルートレベルの server.json が含まれています。エントリーでは registryType": "mcpb" を使用しています。ダウンロード URL は公開されている GitHub リリースアセットでなければならず、fileSha256 はそのバイト列と完全に一致する必要があります（Release ワークフローは Linux 上で .mcpb をビルドするため、Windows 上でパックしたものとは異なる場合があります）。

新しいバージョン（例：v0.4.3）で推奨される手順：

1. pyproject.toml、mcpb/manifest.json、および server.json の version を更新します（最上位の version と、packages[0].identifier の URL：.../releases/download/v0.4.3/batch-review-mcp-0.4.3.mcpb）。
2. リリース準備の変更をコミットし、main にプッシュします。
3. タグをプッシュします（例：git tag v0.4.3 && git push origin v0.4.3）。
4. Release ワークフローが Linux アーティファクトを再度ビルドし、scripts/update_server_json_mcpb_sha.py を実行してワークフローのワークスペース内にある server.json を Linux でビルドした .mcpb に合わせて修正し、scripts/verify_release_mcp_registry.py を実行してから、GitHub リリースを作成または更新し、GitHub Actions OIDC（mcp-publisher login github-oidc）経由で server.json を MCP Registry に公開します。また、PYPI_API_TOKEN が設定されていれば、wheel／sdist を PyPI に公開します。identifier またはバージョンがタグと一致しない場合、あるいは修正後の server.json が Linux でビルドした .mcpb と一致しない場合、ジョブは失敗するため、壊れたアセットがレジストリに公開されることはありません。

個別の MCP registry preflight (Linux MCPB hash) ワークフローは、現在は任意です。タグ付けの前に Linux でビルドしたバンドルのバイト列を確認したい場合や、レジストリとの不一致をデバッグする場合には引き続き役立ちますが、通常のリリースでは server.json に SHA を手動でコピーする必要はなくなりました。

両方の CI ワークフローでは、npm ci --legacy-peer-deps を使ってフロントエンドの依存関係をインストールします。フロントエンドでは react-pdf／pdfjs-dist を 4.8.69 に固定していますが、@aiden0z/pptx-renderer が宣言するオプションの PDF.js ピア依存関係は >=5 <7 を対象としています。GitHub Actions で使用される Node 22／npm 10 環境では、通常の npm ci はピア依存関係の解決に失敗します。Office の PDF フォールバックは無効になっているため、ロックされた依存関係ツリーを受け入れても、アプリケーションバンドルは変わりません。

タグがすでに存在していて、Release ワークフロー自体の修正だけが必要な場合は、Actions から workflow_dispatch を使って手動で再実行し、release_tag（例：v0.4.3）を指定できます。この手動の手順では、指定したタグをチェックアウトして main の現在のリリースメタデータを重ね合わせ、既存のタグ名を再利用するため、タグを移動したり、別のコードリビジョンからビルドしたりせずにリリースを復旧できます。この再実行では、main ブランチの現在のメタデータを使ってワークフローが server.json を再公開し、検証／公開の前に Linux の fileSha256 を再計算することで、MCP Registry への公開も修復します。

scripts/build_mcpb.py は mcpb pack の後にパック済みアーカイブを決定論的に書き換えるため、同じソースツリーであれば、preflight の Linux SHA は Release ワークフローで再度確認される Linux SHA と一致するはずです。

ローカルでの mcp-publisher login github は、単発の手動公開には引き続き便利ですが、通常のタグ付きリリースではワークステーションでのデバイスコード確認は不要になりました。

CLI フラグ

batch-review コマンドは最初の引数に応じて処理を切り替えます。既知の CLI 動詞（start、stop、changes、diff、add-comment など）の場合は、REST 経由で実行中のサーバーと通信する、トークン効率の高いクライアントとして動作します。それ以外の場合は、次のフラグを指定してサーバーとして動作します。

フラグ	デフォルト	説明
--root PATH	カレントディレクトリ	レビュー対象の Git リポジトリ
--host HOST	127.0.0.1	バインドアドレス
--port PORT	9000	優先ポート（使用中の場合は自動的に番号を増やします）
--output NAME	review_comments	保存する出力ファイルのベース名（拡張子なし）
--output-dir DIR	リポジトリのルート	出力ファイルを書き込むディレクトリ
--mcp	オフ	MCP stdio トランスポートを有効にします
--no-browser	false（省略）	通常の動作（フラグを省略）：スタンドアロン、--dev、--mcp でサーバーの準備完了から約 1.2 秒後にブラウザーが自動的に開きます。無効にするには --no-browser を指定します。
--skip-build	オフ	npm のビルド手順をスキップします

動詞の全リファレンスについては、上記の CLI クライアントモードを参照するか、batch-review --help を実行してください。

---

UI の概要

左パネル — 2 つのタブ

Files タブ — 遅延読み込みされるディレクトリツリーです。大規模なリポジトリでも応答性を保てるよう、最初のレンダリングでは最初の数階層のみを読み込みます。フォルダーを展開すると、その子がオンデマンドで読み込まれ、さらに深い階層はバックグラウンドで引き続き読み込まれます。ファイルをクリックすると中央パネルで開きます。

上部のバーには、再読み込みコントロールの横にテーマ切り替えボタンもあります。アプリはダークモードで起動し、ブラウザーで選択したライトモード／ダークモードを記憶します。

Git タブ — 選択中の比較モードに対して変更されたファイルを、ステータスバッジ付きで一覧表示します。

• 🟡 M 変更済み
• 🟢 A 追加済み
• 🔴 D 削除済み
• ⚪ U 未追跡

HEAD に対するワーキングツリー／インデックスの変更には Local、現在の HEAD に対する過去のコミット／参照には Commit、現在のチェックアウトに対する GitHub PR のヘッドには PR を使用します（PR 番号または URL を入力してください）。変更されたファイルをクリックすると、選択した左右の比較対象を示すラベル付きのインライン差分モードで開きます。

センターパネル

• ファイルが選択されていません — アプリ名と、「左側でファイルまたは差分を開き、コメントを追加してからレビューを保存してください」という簡単な案内を表示する、軽量なスタートガイドパネルです。
• Markdown ファイル — レンダリング済みのプレビューと Markdown ソースをツールバーで切り替えられます。相対パスの画像はインラインで表示され、GitHub 互換の数式構文（KaTeX）は、インラインの $…$、ドル記号とバッククォートを使ったインライン数式、ディスプレイ数式の $$…$$、フェンス付き数式ブロックに対応しています（GitHub のドキュメント）。Mermaid のフェンス付きブロックは、センターパネルのツールバーから図のレンダリング表示とソース表示を切り替えられます。WaveDrom のフェンス付きブロック（```wavedrom）はデジタルタイミング図をレンダリングします。ビットフィールド／レジスタ図（reg）と論理／回路図（assign）も、同じツールバーでソース表示とレンダリング表示を切り替えられます。リポジトリ内の別ファイルへのリンクはアプリ内で開き、other.md#heading のようなリンクは該当ファイルを開いて、センターパネルで見出しに移動します。
• HTML ファイル — スクリプトを無効にしたサンドボックスプレビューでレンダリングされ、ツールバーでソース表示に切り替えられます。レンダリングされた要素にマウスを重ねるかクリックするか、レンダリングされたテキストを選択すると、ソース HTML の行範囲と要素セレクター／フィンガープリントに紐づいたコメントを作成できます。視覚的なレイアウトの問題には 領域 モードを使用します。このモードでは、正規化されたレンダリングページ上の矩形を保存し、PNG の切り抜きをレビュー JSON の隣に保存します。リポジトリ内の CSS と画像アセットは、安全な生コンテンツエンドポイントを通じて読み込まれます。
• PDF ファイル — センターパネルにページごとに表示されます。テキスト選択によるコメントでは、そのページでハイライトしたテキストが記憶されるため、ツールバーの［追加］ボタンをクリックしても保持されます。領域コメントではページ上の矩形が保持され、PNG の切り抜きがレビュー JSON の隣に保存されます（Ctrl+Alt+C）。
• DOCX ファイル — ブラウザー内でローカルに、可能な範囲で Word ページとしてレンダリングされ、ページの比率を保ちながら、利用可能なセンターパネルのコンテンツ幅に収まるよう縮小されます。幅の広いコンテンツも縮小前に含めるため、フィット計算ではレンダリングされたページの子孫要素も考慮されます。テキストを選択するとページ情報を含むドキュメントアンカーを作成できます。または 領域 モードに切り替えて、ページ上の視覚的な領域にコメントできます。選択した領域は PNG としてキャプチャされ、レビュー JSON／Markdown 出力の隣に保存されます。docx-preview を使用します。複雑な Word のレイアウトやページ割り付けは Microsoft Word と異なる場合があり、ドキュメントアンカーは、バックエンドで検証された古いテキスト範囲ではなく、可能な範囲でフィンガープリントとして保持されます。
• PPTX ファイル — @aiden0z/pptx-renderer を使い、ブラウザー標準のスライドとしてローカルにレンダリングされます。ブラウザーレンダラーで表示できるテキストを選択するか、領域 モードでスライド上の矩形を指定できます。選択したスライド上の領域は PNG ファイルとしてキャプチャされ、レビュー JSON／Markdown 出力の隣に保存されます。既存の PDF.js 4.x 依存関係を変更しないよう、埋め込み EMF／PDF のフォールバックレンダリングは無効になっています。
• Office の差分 — DOCX／PPTX の変更は、生の ZIP／XML 差分ではなくバイナリパッケージとして報告されます。視覚的なレビューには現在のドキュメントビューアーを開いてください。意味に基づく新旧ドキュメントの差分表示には、まだ対応していません。
• コードファイル — 構文ハイライトに対応した Monaco Editor です。行を選択し、ツールバーの + コメントを追加 をクリックします。
• 差分ビュー — 選択した比較対象をインライン表示する Monaco DiffEditor です（赤＝削除、緑＝追加）。Git タブに戻るか、ファイルタブでファイルをクリックすると、通常表示に戻ります。

右パネル

各コメントには、次の項目があります。

• @filename:L10-15 参照 — クリックすると、中央パネルの該当箇所に移動します
• レビューのメモを入力するテキストエリア（フォーカスが外れると自動保存）
• 古くなったテキストコメントの場合、テキストボックス内の更新アイコンをクリックすると、その行範囲の現在のハイライトテキストを再取得し、古い状態を解除します
• 削除ボタン

💾 Save Review ボタンをクリックすると、すべてのコメントが次の場所に保存されます。

• {output-dir}/{output}.json — 機械可読な JSON 配列
• {output-dir}/{output}.md — ファイルごとにグループ化された、人が読みやすい Markdown レポート

レンダリングされた HTML、PDF、DOCX、PPTX の領域のスクリーンショットは、同じ出力ディレクトリに PNG ファイルとして保存され、対応する JSON コメントからファイル名で参照されます（カスタム出力パスの場合は、そのパスにもコピーされます）。

サーバーの起動時に JSON ファイルがすでに存在する場合は、セッションに読み込まれ、保存済みのレビューを続行できます（無効なファイルはログに警告を記録してスキップされます）。右パネルのフォルダーボタンから保存済みのレビューを読み込むと、フッターに表示されるアクティブなレビュー名も更新され、その後の保存では、読み込んだレビュー名がデフォルトで使用されます。

---

MCP ツール

AI エージェントは http://localhost:PORT/mcp（HTTP トランスポート）または stdio（--mcp フラグ）経由で接続します。

MCP の機能は意図的にレビュー優先にしています。Batch Review は、汎用的なリポジトリブラウザーやエディター API を目指すものではなく、次の操作を行う共有レビュー状態サーバーです。

• レビュー対象範囲の特定
• 差分と、必要最小限のファイルコンテキストの確認
• アンカー付きレビューコメントの追加または更新
• レビューセッションの保存または再開

エージェントの一般的なフローは次のとおりです。

1. get_git_changes() を呼び出します
2. レビューする価値のあるファイルについて、get_git_diff(path) を呼び出します
3. 差分以外のコンテキストが必要な場合に限り、get_file_content(path) を使用します
4. コメントを追加または更新します。必要に応じて、開く・ハイライト・移動の各ツールで共有 UI を操作します
5. レビューファイル用ツールでレビューセッションを保存または読み込みます

プロトコルの互換性

このサーバーでは、MCP Python SDK 2.x（mcp>=2.0.0,<3.0）とともに fastmcp 4.0.2 を使用するようになりました。FastMCP 4 は MCP プロトコルの両世代に対応しているため、既存のホストは接続ごとの従来の initialize ハンドシェイクを引き続き使用でき、最新のクライアントはステートレスなプロトコルパスを使用できます。

従来の世代では、プロトコルリビジョン 2025-11-25 と、ストリーム可能な HTTP 向けの Mcp-Session-Id によるセッション管理を使用します。MCP 仕様の最新リビジョン 2026-07-28 では、このハンドシェイクがリクエストごとの _meta.io.modelcontextprotocol/* フィールドに置き換えられ、ストリーム可能な HTTP に MCP-Protocol-Version／Mcp-Method／Mcp-Name ヘッダーが追加され、server/discover が必須になります。FastMCP と MCP SDK が、このネゴシエーションとトランスポートの動作を担います。Batch Review が競合するプロトコル互換レイヤーを追加することはありません。

FastMCP 4.0.2 では新しい世代の Starlette も必要となるため、FastMCP のアップグレードに合わせて、プロジェクトでは fastapi>=0.133.0 と uvicorn[standard]>=0.35.0 も宣言しています。再現可能なバージョンの正確な情報は uv.lock に記録されています。現在のバージョンは FastMCP 4.0.2 と MCP 2.1.1 です。

アクティブなプロトコルバージョンは、get_config MCP ツールと GET /api/config REST エンドポイントで、protocol キーの下に表示されます。

{
  "active_protocol_version": "2026-07-28",
  "supported_protocol_versions": ["2025-11-25", "2026-07-28"],
  "pending_protocol_versions": [],
  "modern_era_available": true
}

これらの値の唯一の信頼できる情報源は backend/mcp_compat.py です。

リポジトリ内の MCP ホスト設定

このリポジトリには、一般的なエージェントが Batch Review と Playwright を一緒に使用できるよう、チェックイン済みのデフォルト設定が含まれています。

製品	設定ファイル	形式
Cursor（エディターと agent CLI）	.cursor/mcp.json	"type": "stdio" を指定した mcpServers
VS Code / GitHub Copilot	.vscode/mcp.json	"type": "stdio" を指定した servers（リファレンス）
Claude Code	.mcp.json	プロジェクトの mcpServers（stdio）
OpenAI Codex CLI	.codex/config.toml	[mcp_servers.NAME] の stdio ブロック（信頼済みプロジェクトで読み込まれます）
Gemini CLI	.gemini/settings.json	最上位の mcpServers（ガイド）

すべての定義で uv run batch-review --mcp --root . --skip-build を実行するため、レビューのルートは、各ホストがサーバーの作業ディレクトリとして使用する ワークスペースディレクトリ になります。Cursor の agent CLI は、args 内の ${workspaceFolder} を常に展開するとは限らないため、これらの設定では --root に "." を使用しています（VS Code は引き続き .vscode/mcp.json で ${workspaceFolder} を使用できます。このホストでは展開されます）。

stdio MCP の検証

# Smoke test with the official Python MCP client
uv run python scripts/test_mcp_client.py

# Cursor Agent CLI (after install: https://cursor.com/docs/cli )
cd /path/to/batch_review_mcp
agent mcp enable batch-review
agent mcp list-tools batch-review
agent --approve-mcps -p "Your prompt that may call MCP tools"

ツール	説明
init_batch_review_session(coding_agent, model_name?, client_version?)	MCP 接続ごとに 最初に一度だけ呼び出してください。ホストとモデルを登録します。これが成功するまでは、ほかのツールはエラーを返します（ただし、get_config、get_review_web_url、およびリソース batch-review://server/urls は除きます）。
get_git_changes()	HEAD と比較して変更されたファイルの一覧を表示します
get_git_diff(path)	統合差分と変更前／変更後の内容を表示します
add_comment(...)	レビューコメントを追加します。ソースファイルへのコメントでは行範囲を使用し、DOCX／PPTX へのコメントでは document_kind、document_page、正規化された領域、document_anchor、document_fingerprint を使用できます。UI に短い通知を表示します
update_comment(comment_id, text)	コメント本文を編集します。UI に通知を表示します
delete_comment(id)	コメントを削除します。UI に通知を表示します
clear_all_comments()	メモリ内のすべてのコメントを一度に削除します。UI に通知を表示します
delete_outdated_comments()	outdated が true のコメントを削除します。UI に通知を表示します
list_comments()	メモリ内のすべてのコメントを一覧表示します
recompute_comment_stale()	ファイルを highlighted_text と照合して再スキャンし、各コメントの outdated フラグを設定します。UI に通知を表示します
list_review_files()	output_dir 内の *.json レビューのステムを一覧表示します
load_review_by_stem(stem)	{stem}.json のコメントで置き換えます。UI に通知を表示します
save_comments(output_stem?, output_dir?)	JSON と Markdown のレポートを保存し、パスを返します
get_file_content(path)	差分のコンテキストだけでは不十分な場合に、ファイルの内容を構造化データ（content、line_count、language、path）として読み込みます
list_directory(path)	レビューファイルツリーを表示したいホスト向けの、簡易的なリポジトリ移動用ヘルパーです
open_file_in_ui(path, mode)	ファイルを中央パネルで開きます（view または diff）。同じパスとモードを指定すると表示を更新します
highlight_in_ui(path, line_start?, line_end?, pdf_page?, region_x1?, …)	ソースファイル： line_start～line_end（1 始まり）。PDF： pdf_page と、そのページ上で 0～1 に正規化された region_*。画像： 元のピクセル単位の region_*。DOCX／PPTX： document_page と正規化された region_*（および任意の document_kind／アンカーフィールド）
jump_to_comment_in_ui(comment_id)	コメントの @file:L… リンクをクリックしたときと同様に、ファイルを開き、そのアンカーをハイライトします
get_config()	output_stem、output_dir、および（サーバーのバインド後は）web_ui_url を返します
get_review_web_url()	実行中のアプリの web_ui、websocket、mcp_http の各 URL を返します
(リソース)	MCP リソース URI batch-review://server/urls — get_review_web_url と同じ URL JSON（resources/read）。init_batch_review_session より前でも読み取り可能です

エージェントは接続後すぐに（Cursor や Claude Desktop など、空でない coding_agent を指定して）init_batch_review_session を呼び出してください。サーバーによってこれが強制されており、先にほかのツールを呼び出すと、明確な「init を呼び出してください」というエラーが返されます。

コメントの 追加、更新、削除、clear_all_comments、delete_outdated_comments、recompute_comment_stale、load_review_by_stem を実行すると、右パネルの下部にも、閉じることのできるトースト通知が表示されます（保存後にパスを示すヒントと同様のスタイルです）。

---

出力形式

JSON（review_comments.json）

[
  {
    "id": "4c66b5fc-...",
    "file_path": "src/auth.py",
    "line_start": 42,
    "line_end": 55,
    "reference": "@src/auth.py:L42-55",
    "text": "Token is never validated — add expiry check.",
    "highlighted_text": "…",
    "region_screenshot_file": null,
    "region_screenshot_width": null,
    "region_screenshot_height": null,
    "outdated": false,
    "created_at": "2026-04-15T10:00:00+00:00"
  }
]

Markdown（review_comments.md）

# Code Review

_Generated: 2026-04-15 10:00 UTC — 3 comment(s)_

---

## src/auth.py

### `@src/auth.py:L42-55`
> Token is never validated — add expiry check.

---

---

開発

# Backend only (no frontend build needed)
uv run batch-review --root . --skip-build --no-browser

# Frontend dev server (proxies API to port 9000)
cd frontend && npm run dev

# Full production build
cd frontend && npm run build

コントリビューター向けドキュメントでは、session_history/ 内のファイル名に、古い項目の日付を流用するのではなく、変更を作成した AI セッションの実際の日付を使用してください。

---

ライセンス

MIT