bitbucket-mcp: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This is a Model Context Protocol (MCP) server that provides AI assistants with programmatic access to Bitbucket Cloud and Server APIs. It's published as an npm package (@atercates/bitbucket-mcp) and enables operations on repositories, pull requests, pipelines, and more through a standardized MCP interface.

Safety First: Dangerous operations (deletes) require BITBUCKET_MODE=full. Every PR is analyzed with CodeQL for security.

Development Commands

Build and Run

pnpm install         # Install dependencies
pnpm build           # Compile TypeScript to dist/ (also sets executable permission)
pnpm start           # Run compiled server from dist/index.js
pnpm dev             # Run in development mode with watch (uses tsx)

Testing and Quality

pnpm test            # Run Vitest tests
pnpm test:watch      # Run Vitest in watch mode
pnpm lint            # Run ESLint on src/
pnpm lint:fix        # Auto-fix ESLint issues
pnpm format          # Format with Prettier
pnpm format:check    # Check formatting

MCP Inspector

pnpm inspector       # Launch MCP inspector for debugging tools

Publishing

pnpm publish:patch   # Bump patch version and publish
pnpm publish:minor   # Bump minor version and publish
pnpm publish:major   # Bump major version and publish
pnpm release         # Alias for publish:patch

Architecture

Modular Handler-Based Design

The server is organized into feature-based handler modules:

src/
├─ index.ts              # Entry point
├─ server.ts             # MCP server orchestration
├─ client.ts             # Bitbucket API client (axios + paginator)
├─ config.ts             # Environment config + URL normalization
├─ logger.ts             # Winston file-based logging
├─ types.ts              # TypeScript interfaces
├─ schemas.ts            # Shared pagination schemas
├─ utils.ts              # Response helpers
├─ pagination.ts         # Pagination helper
└─ handlers/             # Feature modules
   ├─ repositories.ts
   ├─ pull-requests.ts
   ├─ pr-comments.ts
   ├─ pr-tasks.ts
   ├─ pr-content.ts
   ├─ refs.ts            # Branches and tags
   ├─ commits.ts
   ├─ pipelines.ts
   ├─ source.ts
   ├─ users.ts
   ├─ branching-model.ts
   └─ index.ts           # Aggregates all modules