gh-review-queue-mcp

一个 MCP 服务器，只回答一个问题：我接下来应该审什么？

它只暴露一个工具：get_review_queue，它返回你的 GitHub 拉取请求审查队列的一个排名、去重后的视图——请求你审的、请求你团队审的，以及你自己的、正等着别人审的拉取请求。

只提供一个工具是一个刻意为之的约束。一个必须在 list_prs、search_prs、get_pr_status 之间选择的助手，会把第一轮时间花在选择上；而一个只有这一个工具、能直接返回已排序列表的助手，可以直接回答。

它实际做什么

当这个工具被调用时，会按顺序发生四件事。

1. 识别你和你的团队

服务器发出一个 GraphQL 查询，获取 viewer { login } 以及你所属的团队（organizations.teams(role: MEMBER)）。团队 slug 很关键，因为 GitHub 的搜索 API 没有“请求我的任意一个团队”这种限定词——你必须明确地列出每个团队。这是 token 需要 read:org 权限的唯一原因。

2. 扇出为一个批量搜索

GitHub 没有能够一次返回“所有需要我关注的内容”的查询，所以服务器会跑多个搜索再合并。全部都在同一个 GraphQL 文档里，通过别名发出，因此无论你有多少团队，都只需要一次 HTTP 往返：

搜索字符串以 GraphQL 变量的形式传入，绝不会被插进查询文档里，所以一个团队 slug 不可能改写查询。

同一个查询也会请求 rateLimit { remaining resetAt }，因此每次响应报剩余额度额度，都不用再打一次 call。

关于响应形态，有两点说明。GitHub 的 search(type: ISSUE) 除拉取请求外还会返回 issue；由于选择集是 PullRequest 上的内联片段，issue 会返回为空节点并在解析时被丢弃。而 statusCheckRollup 是从 commits(last: 1) 读的——即 head 提交，而不是整条分支历史。

3. 合并、去重、过滤、排名

同一个拉取请求常常会来自多个搜索——一个你被直接点名审查、同时团队也被请求的 PR，会出现在两个桶里。它们按 GraphQL node id 去重，reason 会累积到同一条记录，所以响应会表示“这个 PR 在这里有两个原因”，而不是重复列出两次。

然后应用你的过滤条件，剩下的内容会评分并排序。

4. 序列化

排好序的列表以结构化输出返回——工具声明了完整的 JSON 输出 schema，所以客户端拿到的是有类型的字段，而不是需要解析的文本。

Related MCP server: github-ops-mcp

排序是怎么工作的

排序是**阶梯式（tiered）的，不是调权重。每个拉取请求必定落在恰好一个层级里，而层与层之间的距离，远大于层内能累积的一切东西：

在同一层内，还有两个更小的信号：

• 年龄 —— 离 PR open 多少天就加几分，满 20 分。这样旧请求会往上浮，但一个六个月前的 PR 不会永远霸榜。

• 小型 diff —— diff 在 100 行以内直接加 8 分。理由是：一个你很快能看完的小审查，胜过你会拖着的大审查。

封顶是关键。一层次内最大可累积的地方是 20 + 8 = 28，远低于 100 的一个层次差距，因此层次优势在结构上就是成立：新提交的直接请求永远排在资历已久的团队请求之前，未来调任何权重也不会悄然改变这一点。如果你想提供打分信号，就要让层内总分上限在 100 以下，否则这个保证就没了。

同分时按最近活动（updateAt 开即 updatedAt）来排，所以同分时，正在讨论的 PR 会排在一个僵住的 PR 前面。

每个条目都会带 priority_reasons —— 像 ["my PR, CI failing", "3 days old"] 这样人类可读的字符串——让这个排序能够向你解释原因，而不是给你一个不明不白的数字。

安装

需要 Python 3.11+ 和 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 —— 读取你的团队成员，用于 team-review?requested 搜索

一个经典 PAT 是最简单的。只要授权“Pull requests: read”外加组织成员级别只读，fine-grained 令牌也能用。在 https://github.com/settings/tokens 申请。

GITHUB_API_URL 也可以覆盖 GitHub Enterprise Server 的端点。

令牌是每次工具调用时读读取，而不是在启动时读——服务器在没有 token 的情况下也能正常启动，实际被调用时才返回一个可执行的错误，而不是在 MCP hand喊中途死掉（那样客户端只会看到一条 broken pipe）。

运行它

uv run gh-review-queue-mcp

它通过 stdio 说 MCP 协议，期望另一端有个客户端；直接运行的话它只是等着。

With MCP Inspector

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

打开打印出来的 URL，连接，这个工具就出现在 Tools 下面，带有它生成的输入 Schema。

with 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 不会从你的 shell 去启动服务器，所以它没有工作目录、没有能继承的环境变量。改完重启 Claude Desktop。然后问它“我今天该审什么？”

工具参考

get_review_queue

所有参数都可选。

响应：

{
  "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"
    }
  ]
}

returned 与 total_matching 区分“这里返回了 25 条”和“实际上总数很多”——如果没有它，限流后的响应和完整响应无法区分。

warnings 承载 GraphQL 部分失败。GitHub 有可能在报错的同时仍然返回可用数据（例如某个 org 读不了、某个搜索挂掉）；这骨汇总不整体抛掉整个队列，而是把它们降级为代表不明的警告，剩下的结果照常回来。

架构

Four modules under src/gh_review_queue/, and the boundaries are load-bearing.

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，不再有别的，因此每一种排序规则都能用纯数据来测试，不需要 mock、不需要网络、也不需要改变系统的时钟。这就是把这个拆开的原因，也正是 httpx 永远不能到到 queue.py 的原因。

降级而不是失败

GitHub 来的未知枚举 value —— 一个新 reviewDecision、一个新 CI rollup 状态——映射为 None，而不是抛异常。反而，GitHub 那边加的状态，不应该会影响你整个队列。同样的思路贯穿了解析层：缺失的作者名会变成 ghost（GitHub 自己用于被删除账号的约定），非 PR 的搜索结果会被丢弃，时间戳缺失是唯一真正无法恢复、会 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 中的 [tool.mypy] files 读取目标，所以如果传一个路径，要检查的东西反而变少了。

测试方法

测试基于 tests/fixtures/queue_response.json，那是一份捕获的 GraphQL 响应，特意包含这样几类难点：一个 PR 出现在两个桶里、一份草稿、一个很旧的 PR、viewer 自己的 CI 失败 PR，又 null 的状态 rollup。

test_rank_orders_the_fixture_the_way_a_reviewer_would_read_it 在固定时钟下断言精确的得分。这是评分变更的金丝雀测试——如果它挂掉了，先判断新顺序是不是确实更好，然后再改这些数值。

状态

阶段 3 已经过端到端（真实 MCP stdio 握手、tool discovery、一次 tool call），但 tests/test_server.py 仍然是一个占位符。客户端错误路径（401、403、部分 GraphQL 失败、连接的主机不可达）代码写了，但还没有自动化测试覆盖。

许可证

This project is licensed under the Apache License 2.0。细节请见 LICENSE 文件。# gh-review-queue-mcp

一个 MCP 服务器，只回答一个问题：我接下来应该审什么？

它只暴露一个工具：get_review_queue，它返回一个排序、去重后的 GitHub 拉取请求审查队列视图——请求你审的、请求你团队审的，以及你自己的、正在等待别人审的拉取请求。

只提供一种工具是刻意的约束。一个必须在 list_prs、search_prs、get_pr_status 之间做选择的助手，会把第一轮花在选择上；一个只有一个工具，且这个工具会返回一份已按优先级排好序的列表的助手，可以直接回答问题。

它到底做了什么

当工具被调用时，会有四件事按顺序发生。

1. 识别你和你的团队

服务器发出一个 GraphQL 查询，获取 viewer { login } 以及你所属的团队（organizations.teams(role: MEMBER)）。团队 slug 很重要，因为 GitHub 的搜索 API 没有“发给我的任一团队”这样的限定词——你只能显式列出每个团队。这是 token 需要 read:org 权限的唯一原因。

2. 扇出一个批量搜索

GitHub 没有一个能表达“所有需要我注意的东西”的单一查询，所以服务器会跑若干搜索然后把结果合并起来。所有输出都在同一个 GraphQL 文档中，借助别名发出——所以，无论你在多少个团队中，都是一次 HTTP 往返：

搜索字符串都是以 GraphQL 变量 传的，绝不会被插进查询文档里，因此一个团队 slug 也不能影响整个查询。

同一个查询还请求了 rateLimit { remaining resetAt }，所以每次响应都可以报告剩余配额，而不需要额外调用一次。

关于响应形态，有两点说明。GitHub 的 search(type: ISSUE) 返回的不只有拉取请求，还有 issue；因为选择集是直接写在 PullRequest 上的一个内联片段，issue 会作为空节点返回，并在解析时被丢弃。另外 statusCheckRollup 是从 commits(last: 1) 读取的——即 head commit 的 CI 状态，而不是整条分支历史。

3. 合并、去重、过滤、排名

同一个拉取请求经常在多个搜索结果里出现——

一个你被直接点名审的 PR，如果同时团队也被请求了，就会出现在两个桶里。它们会按 GraphQL node id 去重，原因会累积到同一条上，所以响应里说是“这里有两条原因”，而不是分别列出两次。

然后，你的过滤条件会被应用，幸存下来的内容再算分、排序。

4. 序列化

排序后的列表作为结构化数据返回——工具声明了完整的 JSON 输出 schema，所以到客户端手里是类型化字段，而不是需要再解析的散文。

它是如何排序的

排序是分层的（tiered），不是调权重的。每个拉取请求都准确地落在某一层，而且层的权重要远大于只能在一层内累积的一切：

再往下一层，有两个更小的信号起效：

• Age —— 从 PR 打开日到今天天数 × 2 分，上限 20 分。这样旧审请能浮上来，但半年余的 PR 不会永远霸榜。

• Small diff —— 100 行以内的非空 diff 固定 +8 分，理由是：能马上做完的小审，近于等下再做的会一个更大的审。

封顶正是关键点。一层内最多能累积 20+8=28 分，远小于 100 分的层级步进，所以层级优越性在结构上成立：一个全新的直接请求，总是排在很久以前团队请求之前；之后再怎么调权，也无法悄悄把这个翻转。如果要加一个算分信号，保持层内总分小于 100，否则这个保证就不成立。

同分时按 `updatedAt** 最近活动时间**来打破：得同分的两个条目，最近更活跃的排在了上面。

每项都带有 priority_reasons——人可以读的字段，比如 ["my PR, CI failing"、“3 days old"]——于是排名可以解释给你，而不是一个光秃秃的数字。

安装

需要 Python 3.11+ 和 uv。

git clone <this repo>
cd ReviewQueueMcp
uv sync

Token

服务器从 GITHUB_TOKEN 读取 GitHub 个人访问令牌：

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

需要的 scopes：

• repo —— 读取私有仓库中拉取请求

• read:org —— 读取你所在团队，为了 team-rever 团队审查请求的搜索

class PAT 是最省事的。如果被授予“Pull requests: read”和 org 成员只读，git -使用细粒度 token指。在 https://github.com/settings/tokens 创建。

GITHUB_GRAPHQL_URL 可以可选方式覆盖 GitHub Enterprise Server 的 endpoint。

Token 是每次工具调用都读、不是启动时读——所以服务端能没有 token 先干净（正常）启动，真正被调用时才报一个可执行的错误，而不是在 MCP 握手阶段直接挂了，让客户端只会看到 pipe broken。

运行

uv run gh-review-queue-mcp

它用 stdio 讲 MCP，并期待一头面对某个客户端；直接跑它，它只是待着。

With MCP Inspector

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

打开打印速度 URL、连接，你就能在 Tools 下看到这个工具以及它生成的输入 schema。

用 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 不会从你的 shell 里启动服务器，所以它没有工作目录，也没有导出的环境变量继受。改完之后重启 Claude Desktop。然后你就可以叫它“你今天应该审什么？”

工具参考

get_review_queue

所有参数都可选。

响应：

{
  "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"
    }
  ]
}

returned 和 total_matching 的关系是区分“这里返回了 25 条”与“这不止 25 条”——如果没有它，限制数量后的响应和有完整结果的响应在区分不出来。

warnings 会带来 GraphQL 的部分失败。精细来说：GitHub 可能一边报错一边给出可用的结果（譬如某个 org 不给你读、某个搜索内容失败)；不把整个队列扔掉，而是把它们降为 warnings, 其余的照常返回。

架构

src/gh_review_queue/ 下四个模块, 边界是承重的：

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,其他什么也不需要, 所以每条优先级规则都能用纯数据测试—无 mock、无网络、无改 born。正是因此才切成那样，也正因为这里 queue.py 绝对不能 import httpx。

降级而不是挂掉

来自 Git hub 的未知枚举值——一个新的 reviewDecision、一个新的 CI rollup 状态——会映射为 None，不抛异常。GitHub 那边新增状态并不能坏了整个队列。这种思想贯穿解析层：

作者缺失变 ghost（GitHub 对已删除账号的惯例）；非 PR 搜索结果是丢弃；外部不存在的 timestamp 是唯一只能 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 里 [tool.mypy] files 拿目标，所以传个路径反而会少于它原本应该检查的范围。

使用测试策略

测试用的是 tests/fixtures/queue_response.json——一份真得的 GraphQL 回应，专为包含那些尴尬案例而构造：一个同时出现在两个 bucket 的 PR、一个 draft、一个远古 PR、一个 viewer 自己的失败 CI PR、以及一个 null 的 status rollup。

test_rank_orders_the_fixture_the_way_a_reviewer_would_read_it 用一个 fixed clock 精确断言最后得分。它是评分改动的金丝雀——如果 bug 到它挂，就要先考虑新的排序是否确实更好，然后再更新数字。

Status

阶段 3 已经做了端到端验证——真实的 MCP stdio 握手、工具发现、和一个工具调用；但 tests/test_server.py 仍然是个占位符。客户端错误的路径（401、403、部分 GraphQL 失败、主机主机不可达）已经写好了实现，但还没有自动化测试挡住。

License

本项目采用 Apache License 2.0 许可，详见 LICENSE。