codereviewbuddy

codereviewbuddy

GitHub の PR レビュー基盤を利用するあらゆる AI レビュアーからの PR レビューコメントを、AI コーディングエージェントが管理できるよう支援する MCP サーバーです。

機能

レビューコメントの管理

• レビューコメントのトリアージ — triage_review_comments は、対応可能なインラインスレッドのみを抽出し、各コメントの GitHub 直接 URL を含めます
• スレッドの詳細を取得 — get_thread は、ノード ID を指定してスレッドの会話履歴全体を取得します
• あらゆるコメントに返信 — インラインレビュースレッド（PRRT_）、PR レベルのレビュー（PRR_）、ボットの Issue コメント（IC_）を、それぞれ適切な GitHub API に振り分けます

CI とスタックの診断

• CI の失敗を診断 — diagnose_ci は、連続する 3～5 個の gh コマンドを 1 回の呼び出しにまとめます。失敗した実行を見つけ、失敗したジョブ／ステップを特定し、対応可能なエラー行を抽出します
• スタックアクティビティフィード — stack_activity は、スタック内のすべての PR におけるプッシュ、レビュー、ラベル、マージを時系列で表示し、次に進むタイミングを判断するための settled フラグも示します
• マージ済み PR をスキャン — list_recent_unresolved は、すでにマージ済みの PR に後から追加されたレビューコメントを検出します

エージェントの使いやすさ

• 復旧方法を示すエラー — すべてのツールハンドラーがエラー（認証、レート制限、見つからない場合、ワークスペース、GraphQL、設定）を分類し、エージェントがむやみに再試行せず自ら修正できるよう、具体的な復旧方法を返します
• 次のアクションのヒント — ツールの応答には、エージェントが適切な次のツール呼び出しを行うための next_steps の提案が含まれます
• 結果が空の場合のメッセージ — 結果が空の場合、その理由と次に試すことを応答で説明します
• GUI URL — トリアージ項目には comment_url が含まれ、エージェントが GitHub のコメントにユーザーを直接誘導できます
• ツール分類タグ — フィルタリングに対応する MCP クライアント向けに、ツールには query、command、discovery のタグが付けられます

サーバー機能（FastMCP v3）

• 型付き出力スキーマ — すべてのツールが JSON Schema を備えた Pydantic モデルを返すため、MCP クライアントは生の文字列ではなく構造化データを受け取れます
• 進捗状況の報告 — 時間のかかる処理は FastMCP コンテキストを通じて進捗状況を報告します（対応する MCP クライアントで確認できます）
• 本番環境向けミドルウェア — ErrorHandling（例外をトレースバック付きの簡潔な MCP エラーに変換）、Timing（すべてのツール呼び出しの実行時間を記録）、Logging（デバッグ用にリクエスト／レスポンスのペイロードを記録）
• 設定不要の認証 — gh CLI を使用するため、PAT トークンや .env ファイルは不要です

CLI テスト（FastMCP v3 では無料）

FastMCP v3 では、追加のコードなしでサーバーをターミナルからテストできます。

# List all tools with their signatures
fastmcp list codereviewbuddy.server:mcp

# Call a tool directly from the terminal
fastmcp call codereviewbuddy.server:mcp triage_review_comments pr_numbers='[42]'

# Inspect server metadata
fastmcp inspect codereviewbuddy.server:mcp

# Run with MCP Inspector for interactive debugging
fastmcp dev codereviewbuddy.server:mcp

前提条件

• GitHub CLI（gh） がインストールされ、認証済みであること（gh auth login）
• Python 3.14+

インストール

このプロジェクトでは uv を使用します。インストールは不要で、そのまま実行できます。

uvx codereviewbuddy

または、恒久的にインストールします。

uv tool install codereviewbuddy

MCP クライアントの設定

クイックセットアップ（推奨）

1 つのコマンドで MCP クライアントを設定できます。JSON を手動で編集する必要はありません。

uvx codereviewbuddy install claude-desktop
uvx codereviewbuddy install claude-code
uvx codereviewbuddy install cursor
uvx codereviewbuddy install windsurf
uvx codereviewbuddy install windsurf-next

環境変数を指定する場合：

uvx codereviewbuddy install windsurf \
  --env CRB_SELF_IMPROVEMENT__ENABLED=true

その他のクライアントでは、JSON 設定を生成します。

uvx codereviewbuddy install mcp-json          # print to stdout
uvx codereviewbuddy install mcp-json --copy   # copy to clipboard

インストール後に MCP クライアントを再起動してください。すべてのオプションについては、uvx codereviewbuddy install --help を参照してください。

手動設定

手動でセットアップする場合は、以下を MCP クライアントの設定 JSON に追加してください。

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uvx",
      "args": ["codereviewbuddy@latest"],
      "env": {
        // All CRB_* env vars are optional — zero-config works out of the box.
        // See Configuration section below for the full list.
      }
    }
  }
}

すべてのオプションを有効にする場合：

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uvx",
      "args": ["codereviewbuddy@latest"],
      "env": {
        // GitHub logins considered "ours" for triage filtering (comma-separated)
        "CRB_OWNER_LOGINS": "alice,bob",
        // Enable PR description quality checks
        "CRB_PR_DESCRIPTIONS__ENABLED": "true",
        // Agents suggest Linear issues when they hit server gaps
        "CRB_SELF_IMPROVEMENT__ENABLED": "true"
      }
    }
  }
}

サーバーは、クライアントからウィンドウごとに送信される MCP ルートからプロジェクトを自動検出します。異なるプロジェクトを開いた複数のウィンドウがある場合も正しく動作するため、環境変数は必要ありません。

@latest を使う理由：指定しない場合、uvx は最初に解決したバージョンをキャッシュし、自動では更新されません。

ソースから実行（開発）

ローカル開発では、PyPI で公開されているバージョンの代わりに、チェックアウトしたソースからサーバーを実行するため、uv run --directory を使用します。ソースへの変更はすぐに反映されます。クライアントで MCP サーバーを再起動するだけです。

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codereviewbuddy", "codereviewbuddy"],
      "env": {
        // Same CRB_* env vars as above, plus dev-specific settings:
        "CRB_SELF_IMPROVEMENT__ENABLED": "true"
      }
    }
  }
}

トラブルシューティング

MCP クライアントで No module named 'fastmcp.server.tasks.routing' と表示された場合、実行環境の FastMCP に互換性がありません。次の方法で解決してください。

1. MCP クライアントの設定で uvx codereviewbuddy@latest を優先してください。
2. ローカルのソースチェックアウトでは、uv run --directory /path/to/codereviewbuddy codereviewbuddy で起動してください。
3. キャッシュされた依存関係を更新するため、再インストールしてください：uv tool install --reinstall codereviewbuddy

MCP ツール

ツール	タグ	説明
summarize_review_status	query, discovery	スタック全体の概要を軽量に確認できます。ここから始めてください
triage_review_comments	query	対応が必要なインラインスレッドのみを確認します
get_thread	query	ノード ID を指定してスレッドの詳細を取得します。会話履歴を確認するには、トリアージの後に使用してください
reply_to_comment	command	インラインスレッド（PRRT_）、PR レベルのレビュー（PRR_）、またはボットコメント（IC_）に返信します
diagnose_ci	query	CI の失敗を診断します。失敗した実行、ジョブ、ステップ、エラー行を 1 回の呼び出しで特定します
check_ci_status	query	PR の CI が成功・失敗・保留中のいずれかを軽量に確認します。マージ前に使用してください
stack_activity	query	settled フラグ付きで、PR スタック全体のアクティビティを時系列で表示します
list_recent_unresolved	query	最近マージされた PR をスキャンし、未解決のレビューコメントスレッドを探します
review_pr_descriptions	query	PR の説明を分析し、品質上の問題（本文が空、定型文、関連する Issue の記載漏れ）を検出します
show_config	discovery	有効な設定を、人が読みやすい説明とともに表示します

MCP リソース

リソース	説明
pr://{owner}/{repo}/{pr_number}/reviews	単一の PR の読み取り専用レビュー概要

MCP プロンプト

プロンプト	説明
review_stack	レビュー全体のワークフロー。要約、トリアージ、修正、返信、確認を行います
pr_review_checklist	マージ前の品質チェックリスト（レビューコメントスレッド、PR の整備状況、CI、テスト）
ship_stack	PR スタックをマージする前の最終確認ワークフロー

設定

codereviewbuddy は、適切なデフォルト設定により設定不要で動作します。すべての設定は、MCP クライアント設定の "env" ブロックにある CRB_* 環境変数で行います。設定ファイルは必要ありません。ネストされた設定では、区切り文字として __（アンダースコア 2 つ）を使用します。コメント付きの設定例は、上記の開発用セットアップを参照してください。

すべての設定

環境変数	型	デフォルト	説明
CRB_PR_DESCRIPTIONS__ENABLED	bool	true	review_pr_descriptions ツールを利用可能にするかどうか
CRB_SELF_IMPROVEMENT__ENABLED	bool	false	サーバーの不足に気付いたエージェントが Linear Issue を提案するかどうか
CRB_OWNER_LOGINS	カンマ区切り	[]	トリアージのフィルタリングで「自分たちのもの」と見なす GitHub ユーザー名（例：alice,bob）

一般的なワークフロー

1. summarize_review_status()                     # Stack-wide overview — start here
2. triage_review_comments(pr_numbers=[42, 43])   # Only actionable threads needing attention
3. # Fix bugs flagged by triage, then:
4. reply_to_comment(42, thread_id, "Fixed in ...")  # Reply explaining the fix
5. diagnose_ci(pr_number=42)                     # If CI fails, diagnose in one call

各ツールの応答には、エージェントに適切な次の呼び出しを案内する next_steps のヒントが含まれます。スタックされた PR では、pr_numbers を省略すると、すべてのクエリツールがスタックを自動検出します。

開発

git clone https://github.com/detailobsessed/codereviewbuddy.git
cd codereviewbuddy
uv sync

テスト

poe test          # Run tests (excludes slow)
poe test-cov      # Run with coverage report
poe test-all      # Run all tests including slow

品質チェック

poe lint          # ruff check
poe typecheck     # ty check
poe check         # lint + typecheck
poe prek          # run all pre-commit hooks

アーキテクチャ

このサーバーは FastMCP v3 を基盤とし、役割を明確に分離しています。

• server.py — ツールの登録、ミドルウェア、指示、復旧方法を示すエラー処理を備えた FastMCP サーバー
• config.py — 設定（pydantic-settings を介した CRB_* 環境変数）
• tools/ — ツールの実装（comments.py、stack.py、ci.py、descriptions.py）
• gh.py — GraphQL および REST 呼び出し用の gh CLI ラッパー
• models.py — エージェントへの案内に使う next_steps フィールドと message フィールドを備えた、型付きツール出力用の Pydantic モデル

イベントループをブロックしないよう、ブロッキングを伴う gh CLI の呼び出しはすべて call_sync_fn_in_threadpool でラップされています。

テンプレートの更新

このプロジェクトは copier-uv-bleeding を使用して生成されました。最新のテンプレート変更を取り込むには、次を実行します。

copier update --trust .