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
└── 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. Retained revision history is migrated from old paths only after a new encrypted revision is valid. 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 PR 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 includes live approval and build counts, plus open review thread summaries. These are fetched on each pack read and are not stored in the encrypted revision; comment text is capped at 4,000 characters and build statuses are limited to two pages.

To discover cached PRs, call list_synced_prs and filter by status. Then use the returned pr_url with get_pr_context_pack or the file tools. 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 and read the encrypted cache. list_synced_prs, file readers, and get_pr_sync_status read local cache after a repository access check; they do not fetch PR details or migrate directories. list_my_open_prs and get_pr_comments fetch live data from Bitbucket. get_pr_context_pack checks freshness and can sync; if freshness metadata is unavailable, it shows cached context with a note and skips other live requests. 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. Keep credentials in this repository's .env. The Hub does not pass secrets.

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. 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: