codereviewbuddy

![ci](https://github.com/detailobsessed/codereviewbuddy/actions?query=workflow%3Aci) ![release](https://github.com/detailobsessed/codereviewbuddy/releases) ![documentation](https://detailobsessed.github.io/codereviewbuddy/) ![Python 3.14+](https://www.python.org/downloads/) ![FastMCP v3](https://github.com/jlowin/fastmcp)

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:

Prefer uvx codereviewbuddy@latest in MCP client config.
For local source checkouts, launch with uv run --directory /path/to/codereviewbuddy codereviewbuddy.
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 .

codereviewbuddy