Codereviewbuddy

🚀 codereviewbuddy

GitHubのPRレビューインフラストラクチャを使用する任意のAIレビュアーからのPRレビューコメントを、AIコーディングエージェントが管理するのを支援するMCPサーバーです。

🚀 クイックスタート

このサーバーを使用するには、まず必要な前提条件を満たす必要があります。その後、インストールを行い、MCPクライアントを設定することで利用を開始できます。

✨ 主な機能

レビューコメント管理

• レビューコメントの一覧表示 — インラインスレッド、PRレベルのレビュー、ボットコメント（codecov、netlify、vercelなど）を、レビュアーの識別と古さの検出とともに表示します。
• スタックされたPRのサポート — list_stack_review_comments を使用すると、一度の呼び出しでPRスタック全体のコメントを取得できます。
• 任意のコメントに返信 — インラインレビュースレッド (PRRT_)、PRレベルのレビュー (PRR_)、ボットのissueコメント (IC_) すべてに対して、正しいGitHub APIにルーティングされます。

トリアージとCI診断

• レビューコメントのトリアージ — triage_review_comments は、実行可能なスレッドのみをフィルタリングし、深刻度を事前に分類し、修正/返信/issue作成のアクションを提案し、各コメントの直接のGitHub URLを含めます。
• CI失敗の診断 — diagnose_ci は、3 - 5の連続した gh コマンドを1回の呼び出しにまとめます。失敗した実行を見つけ、失敗したジョブ/ステップを特定し、実行可能なエラー行を抽出します。
• スタックアクティビティフィード — stack_activity は、スタック内のすべてのPRにわたるプッシュ、レビュー、ラベル、マージの時系列タイムラインを表示し、進行するタイミングを決定するための settled フラグを含みます。
• マージされたPRのスキャン — list_recent_unresolved は、すでにマージされたPRに対する遅いレビューコメントを検出します。

イシュー追跡

• レビューコメントからイシューを作成 — 有用なAI提案を、ラベル、PRのバックリンク、ファイル/行の位置、引用されたコメントテキストとともにGitHubのイシューに変換します。

エージェントエクスペリエンス

• 回復ガイド付きエラー — すべてのツールハンドラーはエラー（認証、レート制限、未検出、ワークスペース、GraphQL、設定）を分類し、実行可能な回復ヒントを返すため、エージェントは盲目に再試行するのではなく、自己修正できます。
• 次のアクションヒント — ツールの応答には next_steps の提案が含まれており、エージェントが適切なフォローアップツールの呼び出しに導かれます。
• 空の結果メッセージ — 結果が空の場合、応答は理由を説明し、次に試すべきことを提案します。
• GUI URL — トリアージ項目には comment_url が含まれており、エージェントはユーザーを直接GitHub上のコメントにリンクできます。
• ツール分類タグ — ツールは query、command、または discovery というタグが付けられており、フィルタリングをサポートするMCPクライアントに対応しています。

サーバー機能 (FastMCP v3)

• 型付き出力スキーマ — すべてのツールはJSONスキーマ付きのPydanticモデルを返し、MCPクライアントに生の文字列ではなく構造化されたデータを提供します。
• 進捗報告 — 長時間実行される操作はFastMCPコンテキストを介して進捗を報告します（これはサポートするMCPクライアントで表示可能）。
• 本番用ミドルウェア — ErrorHandling（例外をトレースバック付きのクリーンなMCPエラーに変換）、Timing（すべてのツール呼び出しの実行時間をログに記録）、およびLogging（デバッグ用のリクエスト/レスポンスペイロード）。
• 更新チェッカー — check_for_updates は実行中のバージョンをPyPIと比較し、アップグレードコマンドを提案します。
• ゼロコンフィグ認証 — gh CLIを使用し、PATトークンや .env ファイルは必要ありません。

📦 インストール

前提条件

• 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 \
  --env CRB_SELF_IMPROVEMENT__REPO=your-org/codereviewbuddy

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

uvx codereviewbuddy install mcp-json          # 標準出力に表示
uvx codereviewbuddy install mcp-json --copy   # クリップボードにコピー

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

手動設定

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

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uvx",
      "args": ["codereviewbuddy@latest"],
      "env": {
        // すべてのCRB_* 環境変数はオプションです。ゼロコンフィグでも問題なく動作します。
        // 以下の設定セクションを参照して、全リストを確認してください。

        // 自己改善: エージェントがサーバーの不備に遭遇したときにイシューを作成します
        // "CRB_SELF_IMPROVEMENT__ENABLED": "true",
        // "CRB_SELF_IMPROVEMENT__REPO": "your-org/codereviewbuddy",

        // 診断（デフォルトではオフ）
        // "CRB_DIAGNOSTICS__IO_TAP": "true",
        // "CRB_DIAGNOSTICS__TOOL_CALL_HEARTBEAT": "true"
      }
    }
  }
}

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

なぜ @latest を使うのか？ これを指定しないと、uvx は最初に解決されたバージョンをキャッシュし、自動的にアップグレードされません。

ソースからのインストール（開発用）

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

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codereviewbuddy", "codereviewbuddy"],
      "env": {
        // 上記と同じCRB_* 環境変数に加えて、開発用の特定の設定:
        "CRB_SELF_IMPROVEMENT__ENABLED": "true",
        "CRB_SELF_IMPROVEMENT__REPO": "detailobsessed/codereviewbuddy",
        "CRB_DIAGNOSTICS__IO_TAP": "true",
        "CRB_DIAGNOSTICS__TOOL_CALL_HEARTBEAT": "true",
        "CRB_DIAGNOSTICS__HEARTBEAT_INTERVAL_MS": "5000",
        "CRB_DIAGNOSTICS__INCLUDE_ARGS_FINGERPRINT": "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ツール

設定

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

すべての設定

深刻度レベル

深刻度は、コメント本文の絵文字マーカーから分類されます。

典型的なワークフロー

1. summarize_review_status()                     # スタック全体の概要 — ここから始めましょう
2. triage_review_comments(pr_numbers=[42, 43])   # 提案されたアクション付きの実行可能なスレッドのみ
3. # トリアージでフラグが立てられたバグを修正した後:
4. reply_to_comment(42, thread_id, "Fixed in ...")  # 修正内容を説明する返信
5. create_issue_from_comment(thread_id, "Improve X")  # フォローアップをイシューとして追跡
6. diagnose_ci(pr_number=42)                     # CIが失敗した場合、一度の呼び出しで診断

各ツールの応答には next_steps のヒントが含まれており、エージェントを適切なフォローアップ呼び出しに導きます。スタックされたPRの場合、pr_numbers が省略されたときにすべてのクエリツールが自動的にスタックを検出します。

開発

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

テスト

poe test          # テストを実行（低速なテストを除く）
poe test-cov      # カバレッジレポート付きでテストを実行
poe test-all      # 低速なテストを含むすべてのテストを実行

品質チェック

poe lint          # ruff チェック
poe typecheck     # ty チェック
poe check         # lint + typecheck
poe prek          # すべてのpre-commitフックを実行

アーキテクチャ

サーバーは FastMCP v3 をベースに構築されており、明確な分離があります。

• server.py — ツールの登録、ミドルウェア、指示、および回復ガイド付きエラーハンドリングを備えたFastMCPサーバー
• config.py — 設定 (CRB_* 環境変数をpydantic-settingsを介して管理)
• tools/ — ツールの実装 (comments.py, stack.py, ci.py, descriptions.py, issues.py)
• gh.py — GraphQLおよびREST呼び出し用の gh CLIの薄いラッパー
• models.py — 型付きツール出力用のPydanticモデルで、エージェントガイダンス用の next_steps と message フィールドを持つ

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

テンプレートの更新

このプロジェクトは copier-uv-bleeding を使用して生成されました。最新のテンプレート変更を取得するには、以下のコマンドを実行します。

copier update --trust .