{"id":44338761,"url":"https://github.com/detailobsessed/codereviewbuddy","last_synced_at":"2026-04-05T02:04:56.777Z","repository":{"id":337453896,"uuid":"1151840071","full_name":"detailobsessed/codereviewbuddy","owner":"detailobsessed","description":"codereviewbuddy helps your AI agent interact with AI code review--smoothly.","archived":false,"fork":false,"pushed_at":"2026-02-24T16:43:45.000Z","size":894,"stargazers_count":0,"open_issues_count":24,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T17:44:06.196Z","etag":null,"topics":["ai","code-review","fastmcp","github","llm","mcp","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/detailobsessed.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"ichoosetoaccept"}},"created_at":"2026-02-07T00:59:07.000Z","updated_at":"2026-02-24T16:46:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/detailobsessed/codereviewbuddy","commit_stats":null,"previous_names":["detailobsessed/codereviewbuddy"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/detailobsessed/codereviewbuddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detailobsessed%2Fcodereviewbuddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detailobsessed%2Fcodereviewbuddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detailobsessed%2Fcodereviewbuddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detailobsessed%2Fcodereviewbuddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/detailobsessed","download_url":"https://codeload.github.com/detailobsessed/codereviewbuddy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detailobsessed%2Fcodereviewbuddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29917660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"ssl_error","status_checked_at":"2026-02-27T19:37:41.463Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","code-review","fastmcp","github","llm","mcp","python"],"created_at":"2026-02-11T12:18:19.508Z","updated_at":"2026-04-05T02:04:56.770Z","avatar_url":"https://github.com/detailobsessed.png","language":"Python","funding_links":["https://github.com/sponsors/ichoosetoaccept"],"categories":[],"sub_categories":[],"readme":"\u003c!-- mcp-name: io.github.detailobsessed/codereviewbuddy --\u003e\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, suggests fix/reply actions\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### Triage \u0026 CI diagnosis\n\n- **Triage review comments** — `triage_review_comments` filters to only actionable threads, suggests fix/reply actions, and includes direct GitHub URLs for each comment\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- **Update checker** — `check_for_updates` compares the running version against PyPI and suggests upgrade commands\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        // Self-improvement: 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\u003e **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 with suggested actions |\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## 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\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 with suggested actions\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetailobsessed%2Fcodereviewbuddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdetailobsessed%2Fcodereviewbuddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetailobsessed%2Fcodereviewbuddy/lists"}