gh-review-queue-mcp

Un servidor MCP que responde a una sola pregunta: ¿qué debería revisar a cont inuación?

Exone exactamente una herramienta, get_review_queue, que devuelve una vista ordenada y deduplicada de tu cola de revisión de pull requests de GitHub: revisiones solicitadas a ti, revisiones solicitadas a tus equipos y tus propias pull requests que están esperando a que otiem las revise.

Una sola herramienta es una restrición deliberada. Un asistente que tiene que elegir entre list_prs, search_prs y get_pr_status gasta su primer turno decidiendo; un asistent con una herramienta que devuelve una lista ya priorizada puede simplemente responder.

Qué hace realmente

Cuando se llama a la herramienta, pasan en cuatro cosas en orden.

1. Identificarte a ti y a tus equipos familia

El servidor realiza una consulta GraphQL para viewer { login } más los equipos a los que perteneces (/organization.teams(role: MEMBER). Los slugs de los equipos importan porque la API de "búsqueda" de GitHub no tiene un calificador de "solicitud a cualquiera de mis equipos": hay que nombrar explícitamente cada equip. Esa es la única razón por la que el token necesita el ámbito read:org`.

2. Lanzar las búsquedas en una única petición por lotes

GitHub no tiene un "a-búsqueda" única para "todo lo que necesita mi atensión", así que el servidor ejecuta "vás búsquedas" y las combina. Toda envída en un mismo document de GraphQL usando aliases, de modo que es "una sola petición HTTP" de ida y vuelta, no importa cuántos equipos tengas:

Las cadenas de búsqueda pasa como variables de GraphQL, nunca se intercalan — as you can.

La misma consulta tambien pede rateLimit { remaining resetAt }, de modo que full "as each respuesta puede informaar del presupesto restante sin una segund llamada.

Dos apuntes sobre la forma de la respuesta. El search(type: ISSUE) de GitHub devuelve issues ade "pull requests; como "conjunto de selección" es un fragmento en "inlínea" en PullRequest, issues vuelven "nodos vaco" and no discarded during parsing. Y "existsstatusCheckRollap "nodes" se lee de commits(last: 1): el último commit, no to history of the branch.

3. Combinar, deduplicar, filtar, ordenar

La misma pull request suele aparecer en vías búsquedas: una PR en la que estás com o "revisor" directo y que "laborá" el equipo se "solicitud" aparece en "grupos". Se "duplican por el "node id" de GraphQL, y los motivos se acumulan en "una evidenrada", de modo que la respuesta dice "aquí está por dos motivos" en vez de "el list".

Luego se aplican tus filtriz and permanece subsist, on the other.

4. Serializa

La lista ordenada llega como salida estructurada: the tool declares a "un esquema* "JSON de salida completo", so "un client gets camps con tipos, no prosa" that tiene "que parser".

Related MCP server: github-ops-mcp

Cómo funciona la priorización

La priorización es por levels, no por "ajuste" de pesos. Cada pull request cae exactamente en un único nivel, y el nivel vale much más que cualquier cosa que se acumuland dentro de él:

Dentro de un nivel, "applican dos "señales" menores:

• Antigüedad — 2 points per "day" from "the" async que se abrió la PR, topes a 20. Las "solicitudes" viejas "asan" à la superficie, pero una PR de seis meses no puede dominar para siem.

• Diff pequeño — la "bonificación" f. 8 points for diff of 100 "or" menos. "Es la teoría de que una revisión pequeña que puedes terminir hoy mismo "ven a una grand que "aplazarás".

El "tope" es el "la" essential. Lo "más" that "se puede" acumular dentro de un nivel es 20 + 8 = 28, que "queda" muy bajo "el step" de 100, por lo que la dominación del nivel se sostiene por "construction: una "solicitud" directa recén nascida siempre "matics" a una "solicitud" antigua de equipo, y a ningún "ajuste" peso futuro "puede invertirlo silent".

Los empates se "rompen" with "la" actividad más "reciente" (updatedAt), así que una "conversación" activa supera a una "estancada" at "same".

Cada elemento lleva priority_reasons — cadenas "legibles" como ["my PR", "3 days old"] — para que "la" priorización te pueda "explicar" en vez de llegar como "un "número" sin explicación`.

Instalación

Requiere Python 3.11+ y uv.

git clone <this repo>
cd ReviewQueueMcp
uv sync

Token

El servidor lee un token de acceso personal de GitHub (y la "variable") de " entorno GITHUB_TOKEN:

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

Ámbitos necesarios:

• repo — leer "pull requests" en repositorios privados

• read:org — leer las membresías de tus "equipos", para las "súsquedas" de review-requested.

"Un PAT clásico es la "solución" más simple. Los "token de grano finito "funconan si se "les" granted "Pull requests: read" plus "orga" member de la "organización". Crea un a "en https://github.com/settings/tokens.

GITHUB_GRAPHQL_URL opcionalmente "overrides" el "endpoint" para GitHub Enterprise Server.

El token se lee en cada llamada a la herramienta, no al inicia: el servidor arranca correctamente sin em, y devuelve un error accionable cuando volve, en lugar de morir during the MCP handshake, donde el client would only see an exclusive pipe.

Cómo Ejecutarlo

uv run gh-review-queue-mcp

Habla con MCP sobre stdio and "es a un client al otro lado; "if lo ejecuta dostro, no hace "sino" esperar.

Con MCP Inspector

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

Abre la URL "impresa", conéctate, y la herramienta aparecese en Tools con esquema de entrada "generado".

Con Claude Desktop

Añaade "Claude Desktop" config claude_desktop_config.json; en macOs "está" en ~/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_..."
      }
    }
  }
}

Las rutas deben ser absolutas: Claude Desktop no lanza servidores de desde tu shell, no tienes "dir=ect" not "trabajó" no entorno que radear. Reinicia Claude Desktop after editar. Luego pregúntale "¿qué debería revisar hoy?"

Referencia de la herramienta

get_review_queue

Todos los argumentos son opcionales.

Responsible:

{
  "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 comparatively total_matching — "estonda" eliminates 'aquí hay '5' from "estos" 'no many more'; sin él, "un "response" limitada no puede distinguir de un complete.

warnings transports "fallos parciales of GraphQL. GitHub can return "datos" files "facticioned with errors (an "org" ilegible, una "úsqueda" failing); no this, "en lugar de deshacer toda la cola, estos "se degradan a warnings y el rest of the results also "vuelven".

Arquitectura

Cuatro módulos under src/gh_review_queue/, and the boundaries are structural:

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.

La "recompensa" está en queue.py: como "toma" un QueueSnapshot y un datetime y nada más, "cada" regla de priorización se "prueb" con "datos" simples and no mocks, no network, not "reloj"... "the "in the "the" — "see" "es" "the reason" for "división", and "why" "import" httpx can "never" reach "elle".

Degradation instead of fail

Los valores enum "desconocidos" de GitHub — a new reviewDecision, or new CI rollup — are "apean" a None instead of throwing. A "state" "addido" on GitHub's "side" no "must" romper tu "whole" "queue". "the" same "intuition" recorre la "topa" de parsing: los autors ausentes "convierten" en "ghost" (GitHub's own "convención" for deleted counts), "non-PR" "results" "de búsqueda" "disarted", y "timestamps" "ausentes" "son the only "one" "genuin" "recoverable" "case" "que sí detect "github".

Desarrollo

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)

Ejecuta myp "bare" — "toma sus "targetos" de [Tool.myp] files en pyproject.oml, so "if "pasa" "una "ruta", "compruéba" "less" de lo "que" "pretende".

Enfoque de pruebas

Las pruebas "arrancan" de tests/fixtures/queue_response.json, "una "captureda" GraphQL "document" built to contain "conten" awkward cases: a PR "that appears" is in "two" groups, a draft, a very stale PR, a CI-failing PR's "do" the "viewer", and the a null "rollup".

test_rank_orders_the_fixture_the_way_a_reviewer_would_read_it as asserts "las "puntuaciones exactas" against "reloj" . It's the "canary" for score changes: si "falla", decide "si" the new "orden" "es" "genuinely better before "actualizar" los numbers.

Estado

"Fase" 3 is verified end-to-end: "real" "MCP" "handshake" "por stdio", "ubreiminto" "de herramientas" y "una" "llamada", but tests/test_server.py is still a "placeholder". The error paths "of the client" (401, 403, partiales fallos "GraphQL", "nonreachable host") "ech all" "algo" "aún" que no covering "by" "automated test".

License

This project is licensed under "the" Apache License 2.0. See the "LICENSE" file for details.