codereviewbuddy

An MCP server that helps your AI coding agent manage PR review comments from any AI reviewer that uses GitHub's PR review infrastructure.

Features

Review comment management

• Triage review comments — triage_review_comments filters to only actionable inline threads and includes direct GitHub URLs for each comment
• Get thread details — get_thread fetches full conversation history for any thread by node ID
• Reply to anything — inline review threads (PRRT_), PR-level reviews (PRR_), and bot issue comments (IC_) all routed to the correct GitHub API

CI & stack diagnosis

• Diagnose CI failures — diagnose_ci collapses 3-5 sequential gh commands into one call: finds the failed run, identifies failed jobs/steps, and extracts actionable error lines
• Stack activity feed — stack_activity shows a chronological timeline of pushes, reviews, labels, merges across all PRs in a stack with a settled flag for deciding when to proceed
• Scan merged PRs — list_recent_unresolved catches late review comments on already-merged PRs

Agent experience

• Recovery-guided errors — every tool handler classifies errors (auth, rate limit, not found, workspace, GraphQL, config) and returns actionable recovery hints so agents self-correct instead of retrying blindly
• Next-action hints — tool responses include next_steps suggestions guiding agents to the right follow-up tool call
• Empty result messages — when results are empty, responses explain why and suggest what to try next
• GUI URLs — triage items include comment_url so agents can link users directly to the comment on GitHub
• Tool classification tags — tools are tagged query, command, or discovery for MCP clients that support filtering

Server features (FastMCP v3)

• Typed output schemas — all tools return Pydantic models with JSON Schema, giving MCP clients structured data instead of raw strings
• Progress reporting — long-running operations report progress via FastMCP context (visible in MCP clients that support it)
• Production middleware — ErrorHandling (transforms exceptions to clean MCP errors with tracebacks), Timing (logs execution duration for every tool call), and Logging (request/response payloads for debugging)
• Zero config auth — uses gh CLI, no PAT tokens or .env files

CLI testing (free with FastMCP v3)

FastMCP v3 gives you terminal testing of the server with no extra code:

# List all tools with their signatures
fastmcp list codereviewbuddy.server:mcp

# Call a tool directly from the terminal
fastmcp call codereviewbuddy.server:mcp triage_review_comments pr_numbers='[42]'

# Inspect server metadata
fastmcp inspect codereviewbuddy.server:mcp

# Run with MCP Inspector for interactive debugging
fastmcp dev codereviewbuddy.server:mcp

Prerequisites

• GitHub CLI (gh) installed and authenticated (gh auth login)
• Python 3.14+

Installation

This project uses uv. No install needed — run directly:

uvx codereviewbuddy

Or install permanently:

uv tool install codereviewbuddy

MCP Client Configuration

Quick setup (recommended)

One command configures your MCP client — no manual JSON editing:

uvx codereviewbuddy install claude-desktop
uvx codereviewbuddy install claude-code
uvx codereviewbuddy install cursor
uvx codereviewbuddy install windsurf
uvx codereviewbuddy install windsurf-next

With optional environment variables:

uvx codereviewbuddy install windsurf \
  --env CRB_SELF_IMPROVEMENT__ENABLED=true

For any other client, generate the JSON config:

uvx codereviewbuddy install mcp-json          # print to stdout
uvx codereviewbuddy install mcp-json --copy   # copy to clipboard

Restart your MCP client after installing. See uvx codereviewbuddy install --help for all options.

Manual configuration

If you prefer manual setup, add the following to your MCP client's config JSON:

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uvx",
      "args": ["codereviewbuddy@latest"],
      "env": {
        // All CRB_* env vars are optional — zero-config works out of the box.
        // See Configuration section below for the full list.
      }
    }
  }
}

All options enabled:

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uvx",
      "args": ["codereviewbuddy@latest"],
      "env": {
        // GitHub logins considered "ours" for triage filtering (comma-separated)
        "CRB_OWNER_LOGINS": "alice,bob",
        // Enable PR description quality checks
        "CRB_PR_DESCRIPTIONS__ENABLED": "true",
        // Agents suggest Linear issues when they hit server gaps
        "CRB_SELF_IMPROVEMENT__ENABLED": "true"
      }
    }
  }
}

The server auto-detects your project from MCP roots (sent per-window by your client). This works correctly with multiple windows open on different projects — no env vars needed.

Why @latest? Without it, uvx caches the first resolved version and never upgrades automatically.

From source (development)

For local development, use uv run --directory to run the server from your checkout instead of the PyPI-published version. Changes to the source take effect immediately — just restart the MCP server in your client.

{
  "mcpServers": {
    "codereviewbuddy": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codereviewbuddy", "codereviewbuddy"],
      "env": {
        // Same CRB_* env vars as above, plus dev-specific settings:
        "CRB_SELF_IMPROVEMENT__ENABLED": "true"
      }
    }
  }
}

Troubleshooting

If your MCP client reports No module named 'fastmcp.server.tasks.routing', the runtime has an incompatible FastMCP. Fixes:

1. Prefer uvx codereviewbuddy@latest in MCP client config.
2. For local source checkouts, launch with uv run --directory /path/to/codereviewbuddy codereviewbuddy.
3. Reinstall to refresh cached deps: uv tool install --reinstall codereviewbuddy.

MCP Tools

Tool	Tags	Description
summarize_review_status	query, discovery	Lightweight stack-wide overview — start here
triage_review_comments	query	Only actionable inline threads needing attention
get_thread	query	Full thread details by node ID — use after triage for conversation history
reply_to_comment	command	Reply to inline threads (PRRT_), PR-level reviews (PRR_), or bot comments (IC_)
diagnose_ci	query	Diagnose CI failures — finds the failed run, jobs, steps, and error lines in one call
check_ci_status	query	Lightweight CI pass/fail/pending check for a PR — use before merging
stack_activity	query	Chronological activity feed across a PR stack with a settled flag
list_recent_unresolved	query	Scan recently merged PRs for unresolved review threads
review_pr_descriptions	query	Analyze PR descriptions for quality issues (empty body, boilerplate, missing linked issues)
show_config	discovery	Show active configuration with human-readable explanation

MCP Resources

Resource	Description
pr://{owner}/{repo}/{pr_number}/reviews	Read-only review summary for a single PR

MCP Prompts

Prompt	Description
review_stack	Full review pass workflow — summarize, triage, fix, reply, verify
pr_review_checklist	Pre-merge quality checklist (review threads, PR hygiene, CI, tests)
ship_stack	Pre-merge sanity check workflow before merging a PR stack

Configuration

codereviewbuddy works zero-config with sensible defaults. All configuration is via CRB_* environment variables in the "env" block of your MCP client config — no config files needed. Nested settings use __ (double underscore) as a delimiter. See the dev setup above for a fully-commented example.

All settings

Env var	Type	Default	Description
CRB_PR_DESCRIPTIONS__ENABLED	bool	true	Whether review_pr_descriptions tool is available
CRB_SELF_IMPROVEMENT__ENABLED	bool	false	Agents suggest Linear issues when they encounter server gaps
CRB_OWNER_LOGINS	comma-separated	[]	GitHub usernames considered "ours" for triage filtering (e.g. alice,bob)

Typical workflow

1. summarize_review_status()                     # Stack-wide overview — start here
2. triage_review_comments(pr_numbers=[42, 43])   # Only actionable threads needing attention
3. # Fix bugs flagged by triage, then:
4. reply_to_comment(42, thread_id, "Fixed in ...")  # Reply explaining the fix
5. diagnose_ci(pr_number=42)                     # If CI fails, diagnose in one call

Each tool response includes next_steps hints guiding the agent to the right follow-up call. For stacked PRs, all query tools auto-discover the stack when pr_numbers is omitted.

Development

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

Testing

poe test          # Run tests (excludes slow)
poe test-cov      # Run with coverage report
poe test-all      # Run all tests including slow

Quality checks

poe lint          # ruff check
poe typecheck     # ty check
poe check         # lint + typecheck
poe prek          # run all pre-commit hooks

Architecture

The server is built on FastMCP v3 with a clean separation:

• server.py — FastMCP server with tool registration, middleware, instructions, and recovery-guided error handling
• config.py — Configuration (CRB_* env vars via pydantic-settings)
• tools/ — Tool implementations (comments.py, stack.py, ci.py, descriptions.py)
• gh.py — Thin wrapper around the gh CLI for GraphQL and REST calls
• models.py — Pydantic models for typed tool outputs with next_steps and message fields for agent guidance

All blocking gh CLI calls are wrapped with call_sync_fn_in_threadpool to avoid blocking the async event loop.

Template Updates

This project was generated with copier-uv-bleeding. To pull the latest template changes:

copier update --trust .