ReviewQueueMcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

gh-review-queue-mcp is an MCP server that exposes exactly one tool, get_review_queue: a ranked, deduped view of the viewer's GitHub pull request review queue. Resisting the urge to add a second tool is a design constraint, not an oversight.

Commands

Dependencies are managed with uv against uv.lock. uv run syncs automatically, so there is no separate install step.

uv run pytest                                    # all tests
uv run pytest tests/test_queue.py::test_diff_size_sums_both_sides   # one test
uv run pytest -k "rank or score"                 # by name
uv run ruff check .                              # lint
uv run ruff format .                             # format
uv run mypy                                      # typecheck

mypy takes its targets from [tool.mypy] files in pyproject.toml, so run it bare — passing a path checks less than CI would. It runs strict, and tests/ is exempted only from disallow_untyped_defs. Ruff's ignore list drops ANN for tests/* and scripts/*. asyncio_mode = "auto", so async tests need no decorator.

Architecture

Four layers, and the boundaries are the point:

• models.py — frozen pydantic value objects (PullRequest, QueueItem, QueueSnapshot, Reason). No network types live here. PullRequest.from_node() is the only place GitHub's nested GraphQL shape gets flattened.
• queue.py — the entire ranking pipeline as pure functions: merge → apply_filters → rank/score, composed by build_queue. It takes a QueueSnapshot and a clock, nothing else, which is why its tests need no mocks. Never let an httpx import reach this module.
• github.py — the only module that touches the network. Builds the GraphQL, handles HTTP and GraphQL errors, returns domain objects. It must never rank or filter.
• server.py — a thin MCP adapter: parse arguments, call the client, hand off to the domain layer, serialize. Its own docstring sets a ~120-line budget; exceeding it means logic leaked into the wrong layer.