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 + app password). 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 app password (Basic Auth password)
DEFAULT_WORKSPACE	Optional default workspace slug
DEFAULT_REPO	Optional default repository slug

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.