{
  "markdown": "<!-- mcp-name: io.github.detailobsessed/codereviewbuddy -->\n# codereviewbuddy\n\n[![ci](https://github.com/detailobsessed/codereviewbuddy/workflows/ci/badge.svg)](https://github.com/detailobsessed/codereviewbuddy/actions?query=workflow%3Aci)\n[![release](https://img.shields.io/github/v/release/detailobsessed/codereviewbuddy)](https://github.com/detailobsessed/codereviewbuddy/releases)\n[![documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://detailobsessed.github.io/codereviewbuddy/)\n[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)\n[![FastMCP v3](https://img.shields.io/badge/FastMCP-v3-blue.svg)](https://github.com/jlowin/fastmcp)\n\nAn MCP server that helps your AI coding agent manage PR review comments from any AI reviewer that uses GitHub's PR review infrastructure.\n\n## Features\n\n### Review comment management\n\n- **Triage review comments** — `triage_review_comments` filters to only actionable inline threads and includes direct GitHub URLs for each comment\n- **Get thread details** — `get_thread` fetches full conversation history for any thread by node ID\n- **Reply to anything** — inline review threads (`PRRT_`), PR-level reviews (`PRR_`), and bot issue comments (`IC_`) all routed to the correct GitHub API\n\n### CI & stack diagnosis\n\n- **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\n- **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\n- **Scan merged PRs** — `list_recent_unresolved` catches late review comments on already-merged PRs\n\n### Agent experience\n\n- **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\n- **Next-action hints** — tool responses include `next_steps` suggestions guiding agents to the right follow-up tool call\n- **Empty result messages** — when results are empty, responses explain why and suggest what to try next\n- **GUI URLs** — triage items include `comment_url` so agents can link users directly to the comment on GitHub\n- **Tool classification tags** — tools are tagged `query`, `command`, or `discovery` for MCP clients that support filtering\n\n### Server features (FastMCP v3)\n\n- **Typed output schemas** — all tools return Pydantic models with JSON Schema, giving MCP clients structured data instead of raw strings\n- **Progress reporting** — long-running operations report progress via FastMCP context (visible in MCP clients that support it)\n- **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)\n- **Zero config auth** — uses `gh` CLI, no PAT tokens or `.env` files\n\n### CLI testing (free with FastMCP v3)\n\nFastMCP v3 gives you terminal testing of the server with no extra code:\n\n```bash\n# List all tools with their signatures\nfastmcp list codereviewbuddy.server:mcp\n\n# Call a tool directly from the terminal\nfastmcp call codereviewbuddy.server:mcp triage_review_comments pr_numbers='[42]'\n\n# Inspect server metadata\nfastmcp inspect codereviewbuddy.server:mcp\n\n# Run with MCP Inspector for interactive debugging\nfastmcp dev codereviewbuddy.server:mcp\n```\n\n## Prerequisites\n\n- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated (`gh auth login`)\n- Python 3.14+\n\n## Installation\n\nThis project uses [`uv`](https://docs.astral.sh/uv/). No install needed — run directly:\n\n```bash\nuvx codereviewbuddy\n```\n\nOr install permanently:\n\n```bash\nuv tool install codereviewbuddy\n```\n\n## MCP Client Configuration\n\n### Quick setup (recommended)\n\nOne command configures your MCP client — no manual JSON editing:\n\n```bash\nuvx codereviewbuddy install claude-desktop\nuvx codereviewbuddy install claude-code\nuvx codereviewbuddy install cursor\nuvx codereviewbuddy install windsurf\nuvx codereviewbuddy install windsurf-next\n```\n\nWith optional environment variables:\n\n```bash\nuvx codereviewbuddy install windsurf \\\n  --env CRB_SELF_IMPROVEMENT__ENABLED=true\n```\n\nFor any other client, generate the JSON config:\n\n```bash\nuvx codereviewbuddy install mcp-json          # print to stdout\nuvx codereviewbuddy install mcp-json --copy   # copy to clipboard\n```\n\nRestart your MCP client after installing. See `uvx codereviewbuddy install --help` for all options.\n\n### Manual configuration\n\nIf you prefer manual setup, add the following to your MCP client's config JSON:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"codereviewbuddy\": {\n      \"command\": \"uvx\",\n      \"args\": [\"codereviewbuddy@latest\"],\n      \"env\": {\n        // All CRB_* env vars are optional — zero-config works out of the box.\n        // See Configuration section below for the full list.\n      }\n    }\n  }\n}\n```\n\nAll options enabled:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"codereviewbuddy\": {\n      \"command\": \"uvx\",\n      \"args\": [\"codereviewbuddy@latest\"],\n      \"env\": {\n        // GitHub logins considered \"ours\" for triage filtering (comma-separated)\n        \"CRB_OWNER_LOGINS\": \"alice,bob\",\n        // Enable PR description quality checks\n        \"CRB_PR_DESCRIPTIONS__ENABLED\": \"true\",\n        // Agents suggest Linear issues when they hit server gaps\n        \"CRB_SELF_IMPROVEMENT__ENABLED\": \"true\"\n      }\n    }\n  }\n}\n```\n\nThe 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.\n\n> **Why `@latest`?** Without it, `uvx` caches the first resolved version and never upgrades automatically.\n\n### From source (development)\n\nFor 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.\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"codereviewbuddy\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/codereviewbuddy\", \"codereviewbuddy\"],\n      \"env\": {\n        // Same CRB_* env vars as above, plus dev-specific settings:\n        \"CRB_SELF_IMPROVEMENT__ENABLED\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Troubleshooting\n\nIf your MCP client reports `No module named 'fastmcp.server.tasks.routing'`, the runtime has an incompatible FastMCP. Fixes:\n\n1. Prefer `uvx codereviewbuddy@latest` in MCP client config.\n2. For local source checkouts, launch with `uv run --directory /path/to/codereviewbuddy codereviewbuddy`.\n3. Reinstall to refresh cached deps: `uv tool install --reinstall codereviewbuddy`.\n\n## MCP Tools\n\n| Tool | Tags | Description |\n| ---- | ---- | ----------- |\n| `summarize_review_status` | query, discovery | Lightweight stack-wide overview — start here |\n| `triage_review_comments` | query | Only actionable inline threads needing attention |\n| `get_thread` | query | Full thread details by node ID — use after triage for conversation history |\n| `reply_to_comment` | command | Reply to inline threads (`PRRT_`), PR-level reviews (`PRR_`), or bot comments (`IC_`) |\n| `diagnose_ci` | query | Diagnose CI failures — finds the failed run, jobs, steps, and error lines in one call |\n| `check_ci_status` | query | Lightweight CI pass/fail/pending check for a PR — use before merging |\n| `stack_activity` | query | Chronological activity feed across a PR stack with a `settled` flag |\n| `list_recent_unresolved` | query | Scan recently merged PRs for unresolved review threads |\n| `review_pr_descriptions` | query | Analyze PR descriptions for quality issues (empty body, boilerplate, missing linked issues) |\n| `show_config` | discovery | Show active configuration with human-readable explanation |\n\n## MCP Resources\n\n| Resource | Description |\n| -------- | ----------- |\n| `pr://{owner}/{repo}/{pr_number}/reviews` | Read-only review summary for a single PR |\n\n## MCP Prompts\n\n| Prompt | Description |\n| ------ | ----------- |\n| `review_stack` | Full review pass workflow — summarize, triage, fix, reply, verify |\n| `pr_review_checklist` | Pre-merge quality checklist (review threads, PR hygiene, CI, tests) |\n| `ship_stack` | Pre-merge sanity check workflow before merging a PR stack |\n\n## Configuration\n\ncodereviewbuddy 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](#from-source-development) above for a fully-commented example.\n\n### All settings\n\n| Env var | Type | Default | Description |\n| ------- | ---- | ------- | ----------- |\n| `CRB_PR_DESCRIPTIONS__ENABLED` | bool | `true` | Whether `review_pr_descriptions` tool is available |\n| `CRB_SELF_IMPROVEMENT__ENABLED` | bool | `false` | Agents suggest Linear issues when they encounter server gaps |\n| `CRB_OWNER_LOGINS` | comma-separated | `[]` | GitHub usernames considered \"ours\" for triage filtering (e.g. `alice,bob`) |\n\n## Typical workflow\n\n```\n1. summarize_review_status()                     # Stack-wide overview — start here\n2. triage_review_comments(pr_numbers=[42, 43])   # Only actionable threads needing attention\n3. # Fix bugs flagged by triage, then:\n4. reply_to_comment(42, thread_id, \"Fixed in ...\")  # Reply explaining the fix\n5. diagnose_ci(pr_number=42)                     # If CI fails, diagnose in one call\n```\n\nEach 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.\n\n## Development\n\n```bash\ngit clone https://github.com/detailobsessed/codereviewbuddy.git\ncd codereviewbuddy\nuv sync\n```\n\n### Testing\n\n```bash\npoe test          # Run tests (excludes slow)\npoe test-cov      # Run with coverage report\npoe test-all      # Run all tests including slow\n```\n\n### Quality checks\n\n```bash\npoe lint          # ruff check\npoe typecheck     # ty check\npoe check         # lint + typecheck\npoe prek          # run all pre-commit hooks\n```\n\n### Architecture\n\nThe server is built on [FastMCP v3](https://github.com/jlowin/fastmcp) with a clean separation:\n\n- **`server.py`** — FastMCP server with tool registration, middleware, instructions, and recovery-guided error handling\n- **`config.py`** — Configuration (`CRB_*` env vars via pydantic-settings)\n- **`tools/`** — Tool implementations (`comments.py`, `stack.py`, `ci.py`, `descriptions.py`)\n- **`gh.py`** — Thin wrapper around the `gh` CLI for GraphQL and REST calls\n- **`models.py`** — Pydantic models for typed tool outputs with `next_steps` and `message` fields for agent guidance\n\nAll blocking `gh` CLI calls are wrapped with `call_sync_fn_in_threadpool` to avoid blocking the async event loop.\n\n## Template Updates\n\nThis project was generated with [copier-uv-bleeding](https://github.com/detailobsessed/copier-uv-bleeding). To pull the latest template changes:\n\n```bash\ncopier update --trust .\n```\n",
  "bytes": 11217,
  "sha": "dcb40ff34b748b30152a6e4b1ac3f35cdc9761444db236f669cff4309ab27341",
  "repo_slug": "detailobsessed/codereviewbuddy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_detailobsessed_codereviewbuddy_2c36d839/readme"
}