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

MCP Resources

MCP Prompts

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

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 .