bitbucket-mcp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

An MCP (Model Context Protocol) server that exposes Bitbucket Cloud Pull Request operations as tools for AI agents. It communicates over stdio using the @modelcontextprotocol/sdk.

Commands

npm start          # Run server (tsx src/index.ts)
npm run dev        # Run with hot reload (tsx watch)
npm run build      # Compile TypeScript to dist/
npm test           # Run all tests (vitest)
npm run test:integration  # Integration tests only (hits real Bitbucket API)
vitest run tests/unit/config.test.ts  # Run a single test file

Node version: 24.13.0 (see .nvmrc)

Architecture

The server is a 3-layer pipeline: MCP protocol -> Router -> Bitbucket Client.

• src/index.ts — MCP server setup. Registers tool schemas (inputSchema definitions) and delegates CallToolRequest to the router. This is where new tools must be declared.
• src/router.ts — BitbucketRouter maps tool names to client methods. Handles parameter extraction (supports both pullRequestId and pr_id forms) and wraps results in ToolResult { success, data?, error? }.
• src/bitbucket-client.ts — Axios-based HTTP client against api.bitbucket.org/2.0. Uses Basic Auth (email + API token). Has async initialization with a polling ensureInitialized() guard on every public method.
• src/config.ts — Credential loading with priority: env vars (BITBUCKET_MCP_EMAIL, BITBUCKET_MCP_TOKEN) > .env file > interactive prompt. Also loads DEFAULT_WORKSPACE and DEFAULT_REPO for optional parameter defaults.

Adding a New Tool

1. Add the tool schema in src/index.ts (in the ListToolsRequestSchema handler array)
2. Add a case in BitbucketRouter.executeTool() switch statement
3. Add the private handler method in the router
4. Add the underlying API call in BitbucketClient

Environment Variables

Variable	Purpose
BITBUCKET_MCP_EMAIL	Bitbucket account email (Basic Auth username)
BITBUCKET_MCP_TOKEN	Bitbucket API token (Basic Auth password)
DEFAULT_WORKSPACE	Optional default workspace slug
DEFAULT_REPO	Optional default repository slug
RUN_WRITE_TESTS	Set to true to enable write integration tests
TEST_PR_ID	PR ID to use for write integration tests (required when RUN_WRITE_TESTS=true)

Copy .env.template to .env and fill in your values for local development and testing.

Testing

Tests use vitest with 30s timeouts. Unit tests mock the Bitbucket client; integration tests call the real API and require valid credentials in the environment.

Write integration tests (approve/unapprove, comments, tasks) are skipped by default. They require both RUN_WRITE_TESTS=true and TEST_PR_ID to be set. Write tests never pick a random PR — if TEST_PR_ID is missing the test is skipped with a warning.