Codereviewbuddy

🚀 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

• 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 & CI diagnosis

• 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.

Issue tracking

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

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).
• 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.

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 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

📦 Installation

Prerequisites

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

Installation Steps

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

uvx codereviewbuddy

Or install permanently:

uv tool install codereviewbuddy

📚 Documentation

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 \
  --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.

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.

        // 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.

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",
        "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"
      }
    }
  }
}

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

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

Severity levels

Severity is classified from emoji markers in comment bodies:

Typical workflow

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.

🔧 Technical Details

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

Template Updates

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

copier update --trust .