pr-council-mcp

pr-council-mcp is a local MCP server for durable, multi-model pull-request reviews. Quality and security reviewers inspect a PR independently, deliberators filter their findings, and an aggregator prepares a single review for human approval before anything is published to GitHub.

It is also an experimental playground running on two related tracks:

• Infrastructure: using an MCP seam between the conversational client and a durable service, with LangGraph orchestration and recovery, constrained model tooling, macOS sandboxing, approval-gated side effects, and optional Langfuse telemetry.
• Product: exploring whether multi-model, multi-disposition reviews become more useful when independent quality and security findings go through deliberation, reconciliation, and aggregation before reaching a human.

Status: early development (alpha). The design, tool surface, and configuration are still changing and may break between versions. Expect rough edges, and expect the interfaces to evolve as both tracks are explored.

Quickstart

The server currently runs on macOS and requires Python 3.12+. Install uv, git, rg, and gh, then authenticate GitHub:

gh auth login
gh auth status

On first launch, the server creates ~/.config/localmcp/localmcp.toml (or the path beneath $XDG_CONFIG_HOME) with this base configuration if the file does not exist. The llm, secrets, and observability tables are owned by localmcplib; pr-council owns only its optional pr_review table:

schema_version = 1

[llm]
backend = "native"

[secrets.openai_api_key]
env_vars = ["OPENAI_API_KEY"]

[secrets.anthropic_api_key]
env_vars = ["ANTHROPIC_API_KEY"]

Set OPENAI_API_KEY and/or ANTHROPIC_API_KEY for the providers used by your selected models. Native secrets may instead be stored in the shared localmcp keyring service under the openai_api_key and anthropic_api_key accounts. The server starts without these keys and reports missing credentials when a review is requested.

Install the package on demand from public PyPI in your MCP client configuration.

Claude Code

Add .mcp.json:

{
  "mcpServers": {
    "pr-council-mcp": {
      "command": "uvx",
      "args": ["--from", "pr-council-mcp", "pr-council-mcp"]
    }
  }
}

opencode

Add opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pr-council-mcp": {
      "type": "local",
      "command": ["uvx", "--from", "pr-council-mcp", "pr-council-mcp"]
    }
  }
}

Example session

The client owns the conversation and handles the operation ID, polling, and preview details. A typical terminal session looks like this (output is illustrative):

$ claude
> Use pr-council-mcp to review https://github.com/acme/widgets/pull/123.
  Focus on authorization boundaries and regressions. Show me the review before publishing it.

The council review is ready. It found two issues:
1. High: a new update path does not enforce repository membership.
2. Medium: retries can create duplicate audit records.

I have the revision-bound publication preview. Nothing has been published.

> Publish that review.

Published the approved inline comments and COMMENT-only summary to PR #123.

How it works

Reviews are checkpointed operations rather than one long MCP request. The client starts a review, polls it, presents the exact revision-bound preview, and publishes only after explicit approval. Restarts can recover unfinished work, and publication revalidates the PR revision and approved payload before writing.

By default the server prepares an isolated managed worktree. Reviewer and deliberator models receive one bounded Bash tool inside a read-only macOS Seatbelt sandbox. They can inspect source and Git history with ordinary local tools, but cannot write files, access the network or credentials, or execute repository code. A local-checkout mode is also available when cloning a large repository is impractical.

The MCP surface intentionally stays small: start, status, preview, commit, and cancel. Published reviews contain inline comments plus a COMMENT-only summary; the server never approves or rejects a pull request.

Tools

Inspect the MCP server's tool schema for complete arguments and return models.

Basic configuration

Configuration lives at ~/.config/localmcp/localmcp.toml, or beneath $XDG_CONFIG_HOME when set. Shared root values are inherited by every local MCP server and [server.pr-council-mcp] overrides this server's application settings. Unknown application keys are rejected. The generated configuration uses the default reviewer matrix.

Secrets resolve from declared environment aliases first and the shared localmcp OS-keyring service second. The native backend resolves openai_api_key and anthropic_api_key as required by the selected models. GitHub authentication is owned by gh, with GH_TOKEN or GITHUB_TOKEN available as overrides. Secret values are never logged.

Structured logs are written only to ~/.local/state/localmcp/pr-council-mcp/logs/pr-council-mcp.log (or beneath $XDG_STATE_HOME) because stdout and stderr carry the MCP protocol. Langfuse tracing is optional and enabled with LOCALMCP_LANGFUSE_ENABLED=true. Tool inputs and outputs remain suppressed unless LOCALMCP_LANGFUSE_CAPTURE_PAYLOADS=true is also set.

Development

Clone localmcplib beside this repository, then run:

uv sync --frozen
make ci
uv run python -m pr_council.server

The checked-in .mcp.json and opencode.jsonc use that local environment. Launch Claude Code or opencode from the repository root to make the development checkout available as pr-council-mcp.

See AGENTS.md for detailed architecture and implementation contracts. See CONTRIBUTING.md for contribution guidance.

License

Apache-2.0