mcp-pr-companion

A read-only Bitbucket Cloud pull request tool that turns PRs into compact context packs for AI agents such as Claude, Copilot, and Cursor.

You can use it in three ways:

1. Quick start

Step 1: Clone the repository

git clone <repo-url>
cd mcp-pr-companion

Step 2: Start the tool

On first launch, the tool prepares the environment:

1. Installs Node.js if it is missing or older than 20.12.

2. Runs npm ci if dependencies are missing.

3. Builds the project if needed.

4. Creates a .env file if one does not exist, then stops so you can fill it in.

The check command checks Node.js, installed dependencies, build output, and required configuration. It does not install dependencies, build, create .env, or call Bitbucket. The run.cmd and run.sh wrappers may still install Node.js before invoking check. To install dependencies and build without starting the app, run .\run.cmd prepare or ./run.sh prepare. The MCP tool check_bitbucket_connection separately checks the live Bitbucket credentials and account allowlist.

Step 3: Configure .env

Fill in the repository root .env file:

BITBUCKET_EMAIL=user@example.com
BITBUCKET_API_TOKEN=ATATT...
BITBUCKET_WORKSPACE=acme
BITBUCKET_REPOSITORY=api,web

BITBUCKET_REPOSITORY accepts comma-separated repositories. Entries without a workspace use BITBUCKET_WORKSPACE. Use workspace/repo for a repository in another workspace, such as api,other-team/tool.

Run .\run.cmd check. A successful check looks like this:

✓ Node.js: Node.js 22.20.0 (requires >=20.12)
✓ Dependencies: dependencies match package-lock.json
✓ Build: dist/ is up to date
✓ Config (.env): required settings present

Create an API token in Bitbucket under Personal settings → API tokens → Create API token with scopes. Grant only the read scopes read:user:bitbucket, read:pullrequest:bitbucket, and read:repository:bitbucket. Do not grant write, admin, or delete scopes.

Related MCP server: Bitbucket Cloud MCP Server

2. Daily use

.\run.cmd cmd
.\run.cmd generate-all
.\run.cmd sync open
.\run.cmd sync draft
.\run.cmd sync merged
.\run.cmd sync declined
.\run.cmd sync all
.\run.cmd check
.\run.cmd purge-plaintext

The sync command accepts exactly one mode: open, draft, merged, declined, or all. It syncs PRs authored by the configured account across every repository in BITBUCKET_REPOSITORY. The groups do not overlap: open excludes drafts; draft includes open draft PRs; merged and declined use their matching Bitbucket states; all includes all four groups. If Bitbucket stops pagination early, the command reports incomplete results and exits with an error code. A failed PR is reported while the remaining PRs continue.

The older generate-all command keeps its existing behavior and generates context for your open PRs. The sync_my_open_prs MCP tool also keeps its existing meaning.

With Node.js 20.12 or newer, these npm commands are equivalent:

In PowerShell, prefix the command with .\ (for example, .\run.cmd). Typing run.cmd by itself will not find the command.

Where data is stored

The canonical directory for each synced PR is:

ai-context/[<AI_CONTEXT_COMPANY>/]<workspace>/<repo>/<open|draft|merged|declined>/pr_<id>/
├── current.json
├── context.md
├── files.md
├── actions.md
├── manifest.json
├── files/file_NNNN.md
├── live-review/
│   ├── current.json
│   ├── last-attempt.json
│   └── snapshots/<snapshot-id>/{index.json,comments.jsonl}
└── revisions/rev_<src7>_<dst7>/

The status directory reflects the last successful sync. The active commits are stored in current.json; the PR state and draft flag are stored in the manifest. Review comments are kept in an independently refreshed encrypted sidecar, outside commit-bound revision folders. A complete snapshot contains sanitized comment records; last-attempt.json records only the latest refresh outcome and warnings. Sidecars move with PR status-directory migrations, which preserve the newest complete snapshot. If migration is interrupted, the source directory remains readable and the next successful sync retries, even when the PR itself is unchanged. Readers also find legacy directories during migration. The file names and schema v4 layout inside each revision remain unchanged. Files under ai-context are encrypted; AI agents must read them through MCP tools.

CLI logs are written under Logs//. MCP server logs are written to Logs/mcp-server.log.

3. Use with an AI client

Add the server to the MCP configuration for Claude Code, Cursor, VS Code, or another MCP client. Replace the placeholder path:

{
  "mcpServers": {
    "mcp-pr-companion": {
      "command": "node",
      "args": ["<path-to>/mcp-pr-companion/bin/cli.js", "server"]
    }
  }
}

Give the AI a Bitbucket PR URL, for example: Summarize https://bitbucket.org///pull-requests/123.

The MCP tools (prefixed with pr__ when exposed through mcp-hub) are:

The context pack checks the latest PR head before returning data and refreshes all comment pages on every report, even when commits are unchanged. Sanitized full comment bodies are stored in the encrypted review sidecar; report summaries show a bounded preview. If a comment fetch is incomplete, the previous complete snapshot stays active and the report identifies its age and the sanitized warning. If the PR metadata check is unavailable, comments are still refreshed independently. Approval and build counts are fetched live and never stored; build statuses are limited to two pages. The companion does not assign severity to review comments; the AI agent interprets their text.

PRIVACY_REMOVE_AUTHOR is true by default. Set it to false only in a deployment that permits sanitized commenter display names. author_kind remains available in either setting.

To discover cached PRs, call list_synced_prs and filter by status. Then start each report with get_pr_context_pack, which checks current commits/state/draft and refreshes the comment snapshot. Use get_pr_comments for bounded comment previews and follow text_next_offset with get_pr_comment until next_offset is null. Do not read ai-context files directly because they are encrypted.

Run the CLI sync command locally to fetch historical groups, then use list_synced_prs through MCP to browse the encrypted cache. Every PR-specific read checks the latest head by default (FRESHNESS_TTL_SECONDS=0); unchanged revisions avoid another commits/diff download, while changed or missing revisions sync before data is returned. Comment reads use the last complete encrypted snapshot; only a context-pack report refreshes comments from Bitbucket. list_my_open_prs discovers open PRs live. If freshness metadata is unavailable, cached revision data is labeled with a warning, and comment refresh is still attempted independently. The Hub's pr__sync_my_open_prs tool keeps its existing open-only behavior. AUTO_SYNC_ON_START=true syncs open PRs in the background whenever the MCP server starts.

Run under mcp-hub

1. Clone this repository beside mcp-hub: /mcp-hub and /mcp-pr-companion. The Hub template runs node bin/cli.js server from the child repository.

2. Run node bin/cli.js prepare once to install dependencies and build.

3. Put credentials in the Hub's bitbucket block (the Hub passes its file as CENTRAL_CONFIG_PATH) or in this repository's .env. Per value, process env wins over the Hub block, which wins over .env; empty values count as unset. A missing or broken Hub file logs a warning and .env is used. check and check_bitbucket_connection report where each value group came from (env, hub, local, or unset), never the values.

4. The Hub exposes child tools with the pr__ prefix.

See docs/HUB_INTEGRATION.md and the Hub contract at ../mcp-hub/docs/mcps/mcp-pr-companion.md.

4. Configuration

All configuration is stored in .env. Under mcp-hub, the five Bitbucket values below can also come from the Hub's bitbucket block (priority: process env > Hub block > .env > default; empty = unset). See .env.example for the full list.

Security

• .env is ignored by Git and excluded from the Docker image.

• The API token stays in .env and process memory. The tool never writes or prints it.

• Only the empty template .env.example is committed.

• Secrets in diffs and emails in titles, descriptions, and commit messages are redacted before storage and output.

Encrypted ai-context data

• Every file under ai-context is encrypted with AES-256-GCM. File names reveal the workspace, repository, PR number, and file ids, but file content is not readable in a file browser.

• Read content through MCP tools or the CLI menu after a Bitbucket access check using .env credentials and ALLOWED_EMAILS. The successful repository check is cached for 60 seconds. If a later PR metadata request fails during that window, get_pr_context_pack can show the cached revision with a note; if the repository access check fails or expires, the encrypted cache stays sealed.

• The encryption key is derived from the repository UUID returned by Bitbucket and held only in memory.

• Data created before encryption can be removed with .\run.cmd purge-plaintext; sync the PRs again afterward.

• See docs/ENCRYPTION.md for details and limitations.

5. Docker (optional)

docker build -t mcp-pr-companion .

# Generate context for all open PRs
docker run --rm --env-file .env -v "$PWD/ai-context:/app/ai-context" mcp-pr-companion generate-all

# Sync selected PR states
docker run --rm --env-file .env -v "$PWD/ai-context:/app/ai-context" mcp-pr-companion sync all

# Interactive menu
docker run --rm -it --env-file .env -v "$PWD/ai-context:/app/ai-context" mcp-pr-companion cmd

# MCP server
docker run --rm -i --env-file .env -v "$PWD/ai-context:/app/ai-context" mcp-pr-companion

6. Troubleshooting

Run .\run.cmd check first.

7. How it works

flowchart LR
    A[PR URL / CLI] --> B[Read-only Bitbucket API]
    B --> C[Analyze changes and risks]
    C --> D[Redact sensitive information]
    D --> E[Encrypt and write context pack]
    E --> F[AI reads through MCP]

Small PRs receive concise summaries. Large or high-risk PRs identify the files that need closer review. Writes are staged and validated so an interrupted sync does not replace the previous active revision.

8. Development

npm run dev
npm run build
npm test

• run.cmd and run.sh check and install Node.js when required.

• bin/cli.js checks dependencies, builds when needed, loads .env, and starts the requested command.

• The build refreshes when src/, tsconfig.json, package-lock.json, or package.json changes.

• CI tests Windows, macOS, and Ubuntu with Node.js 20.12.0 and 22; Ubuntu also builds the Docker image.

• Source code is in src/ and tests are in tests/.

Developer and agent documentation: