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

• List review comments — inline threads, PR-level reviews, and bot comments (codecov, netlify, vercel, etc.) with reviewer identification and staleness detection
• Stacked PR support — list_stack_review_comments fetches comments across an entire PR stack in one call
• Reply to anything — inline review threads (PRRT_), PR-level reviews (PRR_), and bot issue comments (IC_) all routed to the correct GitHub API

• Triage review comments — triage_review_comments filters to only actionable threads, pre-classifies severity, suggests fix/reply/create_issue actions, and includes direct GitHub URLs for each comment
• 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

• Create issues from review comments — turn useful AI suggestions into GitHub issues with labels, PR backlinks, file/line location, and quoted comment text

• 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

• 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)
• Update checker — check_for_updates compares the running version against PyPI and suggests upgrade commands
• Zero config auth — uses gh CLI, no PAT tokens or .env files

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 list_review_comments pr_number=42

# Inspect server metadata
fastmcp inspect codereviewbuddy.server:mcp

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

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

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

uvx codereviewbuddy

Or install permanently:

uv tool install codereviewbuddy

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 \
  --env CRB_SELF_IMPROVEMENT__REPO=your-org/codereviewbuddy

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.

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.

        // Self-improvement: agents file issues when they hit server gaps
        // "CRB_SELF_IMPROVEMENT__ENABLED": "true",
        // "CRB_SELF_IMPROVEMENT__REPO": "your-org/codereviewbuddy",

        // Diagnostics (off by default)
        // "CRB_DIAGNOSTICS__IO_TAP": "true",
        // "CRB_DIAGNOSTICS__TOOL_CALL_HEARTBEAT": "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.

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",
        "CRB_SELF_IMPROVEMENT__REPO": "detailobsessed/codereviewbuddy",
        "CRB_DIAGNOSTICS__IO_TAP": "true",
        "CRB_DIAGNOSTICS__TOOL_CALL_HEARTBEAT": "true",
        "CRB_DIAGNOSTICS__HEARTBEAT_INTERVAL_MS": "5000",
        "CRB_DIAGNOSTICS__INCLUDE_ARGS_FINGERPRINT": "true"
      }
    }
  }
}

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.

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.

Severity is classified from emoji markers in comment bodies:

1. summarize_review_status()                     # Stack-wide overview — start here
2. triage_review_comments(pr_numbers=[42, 43])   # Only actionable threads with suggested actions
3. # Fix bugs flagged by triage, then:
4. reply_to_comment(42, thread_id, "Fixed in ...")  # Reply explaining the fix
5. create_issue_from_comment(thread_id, "Improve X")  # Track followups as issues
6. 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.

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

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

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

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, issues.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.

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

copier update --trust .