gh-review-queue-mcp

次に何をレビューすべきか。この問いに答えるための MCP サーバーです。

このサーバーが公開するツールは、ちょうど1つだけ、get_review_queue です。これは、あなたの GitHub プルリクエストのレビューキューを、ランキング済み・重複除去済みのビューとして返します。あなたに直接依頼されたレビュー、あなたのチームに依頼されたレビュー、そして誰かの対応を待っているあなた自身のプルリクエストです。

ツールを1つだけにするのは、意図的な制約です。list_prs、search_prs、get_pr_status のどれを使うか選ばなければならないアシスタントは、最初のターンを「選ぶこと」に費やします。しかし、すでに優先順位付けされたリストを返す1つのツールを持つアシスタントは、ただ答を返すだけです。

実際の動作

ツールが呼び出されると、次の4つのことが順番に起こります。

1. あなたとあなたのチームを特定する

サーバーは GraphQL クエリで viewer { login } に加えて、あなたが属するチーム（organizations.teams(role: MEMBER)）を取得します。チームの slug が重要なのは、GitHub の検索 API には「自分のチームのどれかに依頼された」という検索句がないため、各チームを明示的に指定する必要がからです。read:org スコープがトークンに必要となる理由は、これだけです。

2. 複数検索を1つのバッチにまとめる

GitHub には「対応が必要なすべて」を一度に検索するクエリはありません。そこでサーバーは複数の検索を実行し、結果を結合します。これらの検索はエイアスを使って 1つの GraphQL ドキュメント にまとめて送られるため、属しているチームの数に関係なくHTTP の往復は1回だけです。

検索文字列は GraphQL の 変数 として渡され、クエリ本文に文字列補間されることはありません。そのため、チームの slug がクエリの形を変えることはできません。

同じクエリは rateLimit { remaining resetAt } も要求します。これにより、2回目の呼び出しなしで毎回のレスポンスに残り利用可能枠を報告できます。

レスポンスの形について2点注意があります。GitHub の search(type: ISSUE) はプルリクエストだけでなくイシューも返しますが、選択セットが PullRequest 上の中間フラグメントであるため、イシューは空のノードとして返ってきて、パースの際に捨てられます。また、statusCheckRollup は commits(last: 1) から取得されます。つまり、ブランチ全体の履歴ではなく、先頭コミットの CI 状況です。

3. 結合、重複除去、フィルタ、順位付け

同じプルリクエストは、複数の検索結果に出てくることがよくあります。あなたが直接レビューして、かつチームにも依頼されている PR は、2つのカテゴリに現れます。これらは GraphQL ノードID で重複排除され、理由は1つのエントリに蓄積されるため、レスポンスは同じ項目を2回列挙するのではなく「この項目は2つの理由にあたります」と示します。

その後、あなたのフィルタが適用され、残った項目がスコアリングされて順序付けされます。

4. シリアライズ

ランク付きのリストは構造化された出力として返されます。ツールは完全な JSON 出力スキーマを宣言するため、クライアントは解析が必要な文章ではなく、型付けのされたフィールドを受け取ります。

Related MCP server: github-ops-mcp

ランキングの仕組み

ランキングは、重みの自動調整ではなく階層制です。各プルリクエストはちょうど1つの階層に入り、その階層の基点数は、階層内で蓄積されるどの要素よりもはるかに大きい値です。

階層性内では、2つの小さなシグナルが適用されます。

• 年齢 — プルリクエストが開かれてからの日数に応じて1日あたり2点、上限は20点です。古いレビュー依頼も表に出てきますが、6ヶ月前のPRがずっと上位を占め続けることはありません。

• 小さな差分 — 100行以下の差分には8点一律のボーナス。今終わる割ができる小さなレビューが、後で延ばす大きなレビューより勝つという考え方です。

上限こそがポイントです。階層内で蓄積される最大値は20 + 8 = 28で、階層の刻み幅100よりはるかに小さい。したがって、階層の優先位は構造上で保証されます。新しい直接依頼が過去のチーム依頼を常に優先し、将来の重み調整がこの保証を静かに覆すことはありません。スコアリングのシグナルを追加する際はは、階層内の合計を100未満に保ってください。でないとその保証は壊れます。

同点の場合は、もっとも最近の活動地（updatedAt）で決定されます。そのため、同じスコアの場合は停止しき会話より活発な会話が上回ります。

全項目には priority_reasons が含まれます。これは「私のPR、CI失敗」「3日日経過」のような読み取れる文字列が入ります。これにより、順位付けの根拠が説明のない目数ではなく、あなたに分かる形で説明される形で渡されます。

インストール

Python 3.1+ と uv が必要です。

git clone <this repo>
cd ReviewQueueMcp
uv sync

トークン

サーバーは GITHUB_TOKEN から GitHub 個人的なアクセストークンを読読み込みます:

cp .env.example .env      # then edit it
export GITHUB_TOKEN=ghp_...

必要なスコープ:

• repo — プライベートのりポジトリ内のプルリクエストを読む取り

• read:org — 所属チームを読み取るための、チームレビュー依頼の検索に使用する

クラシック な PAT がもっとも簡単です。新細グレーンなトークンめる場合、「Pull requests: read」と組織メンバーの読み取り許可があれば機能ます。https://github.com/settings/tokens で作成できます。

GITHUB_GRAPHQL_URL はオプションで、GitHub Enterprise Server のエンドポイントを上書きします。

トークンは起点で起動時ではなく、ツール呼び出しのたびに読み込まれます。そのため、トークンがなくてもサーバーは正常に起動し、呼び出された時に実行できるエラーを返します。MCP のハンドシェク中にサーバーが死んで、クライアントに壊れたパイプしか見え、という結果にはりません。

実行方法

uv run gh-review-queue-mcp

stdio を経由した MCP を話し、そあたのクライが必要です。直接実行するば、ただ待ち続けるだけです。

MCP Designer を使用する

npx @modelcontextprotocol/inspector uv --directory /absolute/path/to/ReviewQueueMcp run gh-review-queue-mcp

印字されたURLを開いて接切すると、生成された入力スキーマとともにツールがToolsに表示されます。

Claude Desktop を使用する

claude_desktop_config.json に追加します。macOS では ~/Library/Application Support/Claude/claude_desktop_config.json です。

{
  "mcpServers": {
    "gh-review-queue": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ReviewQueueMcp",
        "run",
        "gh-review-queue-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

パスは絶対パスで指定する必要があります。Claude Desktop はシェル経由でサーバーを起動しないため、作業デイレクトリの環境変数を受継ません。編集後、 Claude Desktop を再起動します。あとは「今日はどんなレビューをすればいい?」と聞いてると機能しません。

(原文"Then ask even"等" -> Need to reflect "対応able".

Let me finish the rest.

Hmm I see I wrote パス must be absolute - I should preserve "パスは絶対パスにする必要があります。 Claude Desktop はシェルから起動しないので、作業ディレクトリも環境変数もありません。編集後 Claude Desktop を再起動してください。その後「今日は何をレビューすればいい ?」と聞いてみてください。

The hmm I had "といった" mistake.

ツールリファーンス

get_review_queue

すべての引数はオプションです。

レスポンス:

It may be slightly mis-tying. OK.

{
  "viewer": "octocat",
  "generated_at": "2026-08-20T12:00:00Z",
  "returned": 5,
  "total_matching": 5,
  "rate_limit_remaining": 4712,
  "warnings": [],
  "items": [
    {
      "repository": "acme/payments-api",
      "number": 4830,
      "title": "Add idempotency keys",
      "url": "https://github.com/acme/payments-api/pull/4830",
      "author": "octocat",
      "reasons": ["my_pr_awaiting_review"],
      "priority_score": 306.0,
      "priority_reasons": ["my PR, CI failing", "3 days old"],
      "age_days": 3.0,
      "diff_size": 374,
      "changed_files": 12,
      "is_draft": false,
      "review_decision": "REVIEW_REQUIRED",
      "ci_status": "FAILURE"
    }
  ]
}

retured と total_matching を分けることで、「実際に25件です」と「全部25件あります」との区別ができます。この区別がないと、先頭に25件限定した表示と全部表示の区別ができなくなります。

warnings は、GraphQL の部分的な壊を運びます。GitHub は、エラーと共存して利用可能なデータを返すことがあります。（1つの組織の読取の壊れ、1つの検索が失敗する）キュー全体を捨てる代わりに、これらのエラーは warnings に何の込み:

不要。: hmm.

Let me re-translate clean: "warnings carries GraphQL partial failures. GitHub can return usable data alongside errors (one org unreadables, one search failing); rather than throwing away the whole queue, those degrade to warnings and the rest of the results still come back."

I'll write:

warnings には、GraphQL の部分失敗が格納されます。GitHub はエラーを伴いながらも利用可能なデータを返すことがあります（ある組織が読み取れない、ある検索が失敗する）。キュー全体を破棄する代わりに、それらはワーニングに格下げされ、残りの結果はただちに返されます。

Yes.

アーキテクチュア

src/gh_review_queue/ 配下に4つのジュールがあり、セスージュール間の境界が構造を支えています。

server.py    MCP wiring. Parse arguments -> call client -> domain layer -> serialize.
   |         Deliberately thin; its docstring sets a ~120-line budget.
   v
github.py    The only module that touches the network. Builds GraphQL, handles HTTP
   |         and GraphQL errors, returns domain objects. Never ranks or filters.
   v
queue.py     Pure functions: merge -> apply_filters -> rank/score, via build_queue.
   |         Input is a snapshot and a clock. Nothing else.
   v
models.py    Frozen pydantic value objects. The only place GitHub's nested GraphQL
             shape is flattened. No network types.

ここでの成果は queue.py です。これは QueueSnapshot と datetime だけを受け取り、それ以外の依存を持たないため、すべてのランキングルールをプレーンなデータと モックなし、ネットワークなし、クロック改造なし でテストできます。これが分割の理由であり、httpx のインポートが queue.py に到達してはけない理由でもあります。

失敗ではなくデグレード

GitHub から返る未知の enum 値（新しい reviewDecision、新しい CI ロールアップ状態）は、例外を起こす代わりに None に変換されます。GitHub 側で追加された状態が、自分のキュー全体を壊すべきではありません。率いて: The same instinct runs through the parsing layer: missing authors become ghost (GitHub's own convention for deleted account), non-PR search results are dropped, and absent timestamps are the only genuinely unrecoverable case which raises.

I'll write: この同じ考えは、パース層にも貫かれています。不明の著者は ghost（削除済みアカウントに関する GitHub の標準）に変換され、PR 以外の検索結果はすてられ、そ存在しないタイムスタンプだけは、もと純では復元できなケースであり、この例外が発生します。

Hmm "absent timestamps raise" ~ "不存在のタイムスタンプは、単一的に復旧が不可なため、エラーを発生します。"

開発

uv run pytest                       # all tests
uv run pytest tests/test_queue.py   # one file
uv run pytest -k "rank or score"    # by name
uv run ruff check .                 # lint
uv run ruff format .                # format
uv run mypy                         # typecheck (strict)

mypy はは、対象を pyproject.toml の [toole.mypy] files から取るため、パスを引数に渡してチェックすると、意図したよりも範囲が狭くなります。

(Mmm exact) Actually mypy bare: run it without argvs. I wrote enough.

テストの進め方

テストは tests/fixtures/queue_response.json を使います。このJSONは、本来GraphQL のレスポンスをキャプチャしたもので、面倒なケースをすべて含むように作られています:* 2つのバケット中に現れるPR、 1つの draft（下書）、 とても古いPR、 自分がアウトの CI 失敗 PR、 *ヌルの status rollup。

test_rank_orders_the_fixture_the_way_a_reviewer_would_read_it は、固定の時計に対して排他的な正確なスコアを検証します。これはスコアリング変更のカナリャです。失ルした場合は、数値を更新前に、新しい順序が本当に良くなっているのかを判断してください。

Wait the phrase: "fixed clock" -> 固定の時刻.

But I've printed random. Let me clean.

ステータス

Phase 3 is verified end-to-end – 実 MCP stdio のハンドシェク, ツール発見, ツール呼出し Optional – しか, tests/test_server.py まだ placeholder. The client error paths (401, 403, GraphQL 部分失敗, 接続先のホスト到達不能) are written but not yet covered by automated tests.

So:

フェーズ3は、エンドツーエンドとして検証されています。実物の MCP stdio のハンドシェク、ツールの発見、そして実ツールの呼び出しまで動いています。しかし tests/test_server.py はまだプレースホルダーのままです。クライアント側のエラー経路（401、403、GraphQL の部分失敗、ホスト到達不能）は作られていますが、自動テストのカバレッジは未作です。

ライセンス

このプロジェクトは Apache License 2.0 の下で提供されます。詳細は LICENSE` ファイルを参照。