pr-review-mcp

Unified MCP control plane for AI pull request reviews on GitHub.

Modern pull requests often attract multiple AI reviewers, but their comments arrive in different formats, different places, and different timelines. pr-review-mcp turns that noise into one MCP-native workflow: it normalizes review output from seven agent sources, exposes 19 focused tools, and adds orchestration primitives for parallel review handling.

If you use Claude Code, Claude Desktop, or another MCP client to process GitHub reviews, this server gives you one place to list findings, inspect details, invoke agents, wait for them server-side, and coordinate worker agents without building your own review pipeline.

What's New in v0.3.0

pr_await_reviews adds a server-side wait loop for AI reviews, so clients no longer need to poll GitHub manually while agents finish posting.
pr_invoke now returns since, invokedAgentIds, and awaitHint, making the handoff into pr_await_reviews explicit and reliable.
Claude Code integration is stronger with skills/review/SKILL.md, a dedicated skill that wraps /pr:review into an autonomous review workflow.
CI now runs build, tests, and coverage on Node 20 and 22 through GitHub Actions.
Coverage reporting is part of the release baseline with @vitest/coverage-v8; v0.3.0 records 225 Vitest test cases and a 51.7% statement coverage baseline.
Qodo completion tracking is more accurate because persistent issue comments are detected via updated_at, not only created_at.
Agent status polling was simplified by extracting shared logic into fetchAgentStatusForAgents, removing duplicated code paths.
Ten dependency vulnerabilities were resolved as part of the release hardening work.

Features

Automates multi-agent PR review workflows with 19 MCP tools, 3 prompts, and 1 dynamic PR resource.
Eliminates review-source fragmentation by normalizing comments from CodeRabbit, Gemini, Copilot, Sourcery, Qodo, Codex, and Greptile.
Prevents polling loops in clients with pr_await_reviews, a server-side monitor for agent completion.
Coordinates parallel workers safely with file-level partition claiming, progress reporting, and orchestration status checks.
Surfaces machine-readable review data through structured outputs on key tools such as pr_summary, pr_list, pr_get, pr_get_work_status, and pr_progress_check.
Supports local and shared deployments through stdio by default and StreamableHTTP with pr-review-mcp --http or pr-review-mcp --http 8080.
Protects operational workflows with confirmation flows for destructive actions such as merge and coordination reset.
Ships with Claude Code assets including .claude-plugin/plugin.json, .mcp.json, and the review skill for slash-command driven orchestration.

Architecture

graph TD
    Client["MCP Client<br/>Claude Code / Claude Desktop / Inspector"]

    Client -->|stdio| Server
    Client -->|StreamableHTTP| Server

    subgraph Server["pr-review-mcp v0.3.0"]
        subgraph Interface["MCP Interface"]
            Resource["Resource<br/>pr://{owner}/{repo}/{pr}"]
            PromptReview["Prompt<br/>review"]
            PromptReviewBg["Prompt<br/>review-background"]
            PromptSetup["Prompt<br/>setup"]
        end

        subgraph Analysis["Analysis Tools (7)"]
            T1["pr_summary"]
            T2["pr_list_prs"]
            T3["pr_list"]
            T4["pr_get"]
            T5["pr_changes"]
            T6["pr_poll_updates"]
            T7["pr_await_reviews"]
        end

        subgraph Action["Action Tools (6)"]
            T8["pr_invoke"]
            T9["pr_resolve"]
            T10["pr_labels"]
            T11["pr_reviewers"]
            T12["pr_create"]
            T13["pr_merge"]
        end

        subgraph Orchestration["Orchestration Tools (6)"]
            T14["pr_claim_work"]
            T15["pr_report_progress"]
            T16["pr_get_work_status"]
            T17["pr_reset_coordination"]
            T18["pr_progress_update"]
            T19["pr_progress_check"]
        end

        Monitor["ReviewMonitor<br/>server-side wait + backoff"]
        Extractors["Extractors<br/>severity / prompt / nitpick / multi-issue"]
        Adapters["Adapters<br/>Qodo / Greptile"]
        State["Coordination State<br/>partitions / progress / phases"]
    end

    PromptReview --> T8
    PromptReview --> T14
    PromptReview --> T18
    PromptReviewBg --> T18
    PromptSetup --> T8
    Resource --> T1
    Analysis --> Monitor
    Analysis --> Extractors
    Action --> Adapters
    Orchestration --> State
    Monitor --> State

    Server --> GitHub["GitHub GraphQL + REST API"]
    State --> Workers["Parallel Worker Agents"]

Tools

Analysis

Tool	Description
`pr_summary`	Return PR review totals, resolution counts, severity breakdowns, file hotspots, and nitpick stats.
`pr_list_prs`	List open pull requests in a repository with review activity and change stats.
`pr_list`	Enumerate review comments with filters for resolution state, file, source, and severity.
`pr_get`	Fetch full detail for a single review thread, including the original body and extracted prompt data.
`pr_changes`	Return incremental review updates since a cursor for lightweight refresh workflows.
`pr_poll_updates`	Poll for comments, commits, and agent status changes when you need a non-blocking refresh loop.
`pr_await_reviews`	Block server-side until selected review agents post updates or a timeout is reached.

Action

Tool	Description
`pr_invoke`	Trigger one agent or all configured agents for a PR review run.
`pr_resolve`	Resolve a GitHub review thread after the issue is handled.
`pr_labels`	List, add, remove, or set pull request labels.
`pr_reviewers`	Request or remove human and team reviewers on a pull request.
`pr_create`	Create a new pull request from existing branches.
`pr_merge`	Merge a pull request with confirmation-aware safety checks.

Orchestration

Tool	Description
`pr_claim_work`	Claim the next pending file partition for a worker agent.
`pr_report_progress`	Report completion, failure, or skip status for a claimed partition.
`pr_get_work_status`	Inspect the current coordination run, partition counts, and reviewed or pending agents.
`pr_reset_coordination`	Clear the active coordination run after explicit confirmation.
`pr_progress_update`	Publish orchestrator phase transitions for background workflows.
`pr_progress_check`	Read orchestrator phase history and coordination progress in one call.

Prompts

Prompt	Slash Command	Description
`review`	`/pr:review`	Main autonomous PR review orchestrator for a PR number, URL, or `owner/repo#N`.
`review-background`	`/pr:review-background`	Fire-and-forget variant that keeps its own progress tracking without blocking the main chat thread.
`setup`	`/pr:setup`	Guided setup prompt for repository-level review configuration and agent defaults.

Resources

pr://{owner}/{repo}/{pr} is a dynamic MCP resource that returns pull request metadata and a current review summary in one JSON payload. Use it when a client needs a machine-readable snapshot without issuing multiple tool calls.

Example URI:

pr://thebtf/pr-review-mcp/2

Returned data includes PR metadata such as title, state, author, branch names, mergeability, review decision, timestamps, and the same summary dimensions exposed by pr_summary.

Quick Start

Install the server:
```
npm install -g pr-review-mcp
```

Add it to your MCP client:

{
  "mcpServers": {
    "pr": {
      "command": "pr-review-mcp",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Verify the binary and version:
```
pr-review-mcp --version
```

Expected output:

pr-review-mcp v0.3.0

Installation

Prerequisites

Node.js >=20.0.0
A GitHub Personal Access Token with repo scope
An MCP client such as Claude Code, Claude Desktop, or MCP Inspector

Global npm install

npm install -g pr-review-mcp

Verify the install

pr-review-mcp --version

MCP client configuration

Use the globally installed binary in your client config:

{
  "mcpServers": {
    "pr": {
      "command": "pr-review-mcp",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Local clone alternative

git clone https://github.com/thebtf/pr-review-mcp.git
cd pr-review-mcp
npm install
npm run build

When running from a clone, point your client at the built entry point:

{
  "mcpServers": {
    "pr": {
      "command": "node",
      "args": ["D:/path/to/pr-review-mcp/dist/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

HTTP mode

Start a StreamableHTTP server on the default port:

pr-review-mcp --http

Or specify a port explicitly:

pr-review-mcp --http 8080

Upgrading

From v0.2.x to v0.3.0

Update the package:
```
npm install -g pr-review-mcp@0.3.0
```
If your client automation waits for agents, switch from manual polling loops to the new pattern:
1. Call pr_invoke
2. Read since and invokedAgentIds from its response
3. Pass those values into pr_await_reviews

If you copied older README examples, migrate repository config to the nested format actually consumed by pr_invoke:

{
  "version": 1,
  "invoke": {
    "agents": ["coderabbit", "gemini", "codex"],
    "defaults": {
      "focus": "best-practices",
      "incremental": true
    }
  }
}

Claude Code users can now rely on skills/review/SKILL.md for a richer /pr:review workflow.
CI now validates build, tests, and coverage on Node 20 and 22, so local compatibility checks should target the same matrix.

Configuration

Environment variables

Variable	Required	Default	Description
`GITHUB_PERSONAL_ACCESS_TOKEN`	Yes	None	GitHub Personal Access Token with `repo` scope. The server exits early if it is missing.
`PR_REVIEW_AGENTS`	No	`coderabbit`	Comma-separated agent IDs used when `pr_invoke` resolves `agent: "all"` without repository config.
`PR_REVIEW_MODE`	No	`sequential`	Review invocation mode: `sequential` or `parallel`.

Valid agent IDs are coderabbit, sourcery, qodo, gemini, codex, copilot, and greptile.

Repository config

Create .github/pr-review.json in the reviewed repository to define repository-specific defaults:

{
  "version": 1,
  "invoke": {
    "agents": ["coderabbit", "gemini", "codex"],
    "defaults": {
      "focus": "best-practices",
      "incremental": true
    }
  }
}

Config resolution order is:

.github/pr-review.json
PR_REVIEW_AGENTS and PR_REVIEW_MODE
Built-in defaults (coderabbit, sequential)

invoke.defaults maps directly to the options accepted by pr_invoke, so you can preconfigure values such as focus and incremental at the repository level.

Usage

Workflow 1: Inspect a single PR

Use the analysis tools to summarize and drill into the review state:

{
  "name": "pr_summary",
  "arguments": {
    "owner": "thebtf",
    "repo": "pr-review-mcp",
    "pr": 2
  }
}

Then list unresolved findings:

{
  "name": "pr_list",
  "arguments": {
    "owner": "thebtf",
    "repo": "pr-review-mcp",
    "pr": 2,
    "resolved": false
  }
}

Workflow 2: Invoke agents and wait server-side

Trigger one or more AI reviewers:

{
  "name": "pr_invoke",
  "arguments": {
    "owner": "thebtf",
    "repo": "pr-review-mcp",
    "pr": 2,
    "agent": "all"
  }
}

Use the returned since and invokedAgentIds in pr_await_reviews:

{
  "name": "pr_await_reviews",
  "arguments": {
    "owner": "thebtf",
    "repo": "pr-review-mcp",
    "pr": 2,
    "since": "2026-03-28T10:00:00.000Z",
    "agents": ["coderabbit", "gemini"],
    "timeoutMs": 600000,
    "pollIntervalMs": 30000
  }
}

Workflow 3: Run an orchestrated parallel review

In Claude Code, start the orchestrator:

/pr:review 2

Under the hood, the prompt uses orchestration tools such as pr_claim_work, pr_report_progress, pr_progress_update, and pr_progress_check to distribute unresolved comment partitions across worker agents and track progress until review handling is complete.

Claude Code Integration

The repository ships with Claude Code assets:

.claude-plugin/plugin.json declares the packaged plugin metadata and MCP server bootstrap.
.mcp.json provides an MCP server config that points at the built dist/index.js.
skills/review/SKILL.md defines the review skill used by /pr:review.

Available slash commands:

/pr:review
/pr:review-background
/pr:setup

Minimal Claude Code configuration with the global binary:

{
  "mcpServers": {
    "pr": {
      "command": "pr-review-mcp",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Agent Sources

Source	Bot Login Pattern	Comment Type	Notes
CodeRabbit	`coderabbitai[bot]`	Inline review threads	Supports focus, file filtering, and incremental review options.
Gemini	`gemini-code-assist[bot]`	Inline review threads	Invoked through mention-based review commands.
Copilot	`copilot-pull-request-reviewer[bot]`	Inline review threads	Parsed as a standard review-thread source.
Sourcery	`sourcery-ai[bot]`, `sourcery-ai-experiments[bot]`	Inline review threads	Detection accepts both production and experiments bot patterns.
Qodo	`qodo-code-review[bot]`	Issue comment	Persistent review comment updated per commit; readiness uses `updated_at`.
Codex	`chatgpt-codex-connector[bot]`	Inline review threads	Mention-based invocation, parsed as a regular review source.
Greptile	`greptile-apps[bot]`	Issue overview plus inline review threads	Posts an overview issue comment and may also add inline findings.

Qodo and Greptile are handled through dedicated adapters because they do not behave like simple inline review-only sources.

Troubleshooting

`GITHUB_PERSONAL_ACCESS_TOKEN` is missing

The server checks prerequisites on startup and exits early if the token is not configured. Add the token to the env block of your MCP server entry and restart the client.

`.github/pr-review.json` seems ignored

pr_invoke only reads the nested config under invoke.agents and invoke.defaults. Invalid JSON falls back to default agents, so validate the file shape before assuming repository config is active.

HTTP mode does not start

Use the packaged CLI entry point:

pr-review-mcp --http

Or:

pr-review-mcp --http 8080

If you run from a clone instead, build first and invoke node dist/index.js --http.

An agent does not appear to respond

Confirm the agent is enabled through .github/pr-review.json or PR_REVIEW_AGENTS.
Check whether the agent already reviewed the PR; pr_invoke skips reviewed agents unless force is set.
Use pr_await_reviews for a blocking wait or pr_poll_updates if your client needs periodic status refreshes.
For Qodo, remember that new activity may update one persistent issue comment rather than create fresh review threads.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for setup, validation, and PR submission guidance.

License

MIT. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
agents		agents
commands		commands
docs/plans		docs/plans
scripts		scripts
skills		skills
src		src
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.ru.md		README.ru.md
RELEASE_NOTES.md		RELEASE_NOTES.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

pr-review-mcp

What's New in v0.3.0

Features

Architecture

Tools

Analysis

Action

Orchestration

Prompts

Resources

Quick Start

Installation

Prerequisites

Global npm install

Verify the install

MCP client configuration

Local clone alternative

HTTP mode

Upgrading

From v0.2.x to v0.3.0

Configuration

Environment variables

Repository config

Usage

Workflow 1: Inspect a single PR

Workflow 2: Invoke agents and wait server-side

Workflow 3: Run an orchestrated parallel review

Claude Code Integration

Agent Sources

Troubleshooting

GITHUB_PERSONAL_ACCESS_TOKEN is missing

.github/pr-review.json seems ignored

HTTP mode does not start

An agent does not appear to respond

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`GITHUB_PERSONAL_ACCESS_TOKEN` is missing

`.github/pr-review.json` seems ignored

Packages