PR Viewer MCP Server

MCP server for PR review workflows. Launches a diff visualizer against a git repo and returns "accepted" or "rejected" when the user is done.

Setup

uv sync --group dev

Tools

Tool	Description
health_check	Confirms the server is reachable.
open_review	Starts the configured visualizer and blocks until the user accepts or rejects.

open_review parameters:

Parameter	Default	Description
repo_path	—	Absolute path to a git repo.
base_ref	main	The base git ref (e.g. main, origin/main).
head_ref	HEAD	The head ref to diff against base (branch name, commit SHA, etc.).

Returns "accepted" or "rejected" as a string.

Wiring in a visualizer

Create a shell script that receives the repo context via env vars and writes the review decision to $RESULT_PATH when the user is done:

#!/usr/bin/env bash
# Env vars provided by the server:
#   REPO_PATH   – absolute path to the git repo
#   BASE_REF    – base ref (e.g. main)
#   HEAD_REF    – head ref (e.g. feature/add-greet)
#   RESULT_PATH – path this script must write "accepted" or "rejected" to

# launch your visualizer here, then write the result
echo "accepted" > "$RESULT_PATH"

The default visualizer (scripts/launch-octorus.sh) opens octorus in a new Terminal.app window and prompts accept/reject after the user quits.

Connecting Claude Code

Add to ~/.claude/mcp.json (global, available in every repo):

{
  "mcpServers": {
    "pr-viewer": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pr-viewer", "pr-viewer-mcp"]
    }
  }
}

Or scope it to one repo by placing the same block in .mcp.json at the project root.

Because open_review blocks until you finish reviewing, Claude can act on the result in the same turn. Useful prompts:

Open a review of feature/add-greet in /path/to/repo against main.
If it's accepted, merge it with `gh pr merge --merge`.
If it's rejected, post a comment explaining what needs to change.

Review the diff between main and HEAD in the current repo.
Summarize what changed and wait for my decision before doing anything.

Manual end-to-end test with a toy repo

1. Create the toy repo

./scripts/setup-toy-repo.sh

Creates ./toy-repo/ with a main branch and a feature/add-greet branch. To remove it when done:

./scripts/teardown-toy-repo.sh

2. Start the MCP inspector

uv run mcp dev src/pr_viewer_mcp/server.py

Open the inspector URL printed in the terminal (default: http://localhost:5173).

3. Call open_review

In the MCP inspector, select the open_review tool and fill in:

{
  "repo_path": "<absolute-path-to-project>/toy-repo",
  "base_ref": "main",
  "head_ref": "feature/add-greet"
}

The tool blocks — the inspector shows a spinner until the result file is written.

4. Complete the review

Either review in octorus (a Terminal.app window opens) and answer the accept/reject prompt, or write the result directly from another terminal:

# find the path in the server logs, then:
echo "accepted" > /tmp/tmp<hash>.review_result

The tool returns "accepted" or "rejected" and the inspector shows the result.

Programmatic use

For pipelines that don't use Claude, open_review is still a regular blocking MCP tool call:

import asyncio
from mcp.client.stdio import stdio_client, StdioServerParameters
from mcp.client.session import ClientSession

async def main() -> None:
    server = StdioServerParameters(
        command="uv",
        args=["run", "--directory", "/path/to/pr-viewer", "pr-viewer-mcp"],
    )
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("open_review", {
                "repo_path": "/path/to/repo",
                "base_ref": "main",
                "head_ref": "feature/my-branch",
            })
            decision = result.content[0].text  # "accepted" or "rejected"
            print(decision)

asyncio.run(main())

Tests

uv run pytest

The integration tests (tests/test_integration.py) run the server in-process via mcp.shared.memory with a FakeVisualizer that writes the result immediately, confirming that open_review returns the correct string.