bitbucket-mcp

# 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 (`bitbucket-mcp`) and enables operations on repositories, pull requests, pipelines, and more through a standardized MCP interface.

**Safety First**: No DELETE operations are used to prevent accidental data loss. Every PR is analyzed with CodeQL for security.

## Development Commands

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

### Testing and Quality
```bash
npm test             # Run Jest tests
npm run lint         # Run ESLint on src/**/*.ts
```

### MCP Inspector
```bash
npm run inspector    # Launch MCP inspector for debugging tools
```

### Publishing
```bash
npm run publish:patch   # Bump patch version and publish
npm run publish:minor   # Bump minor version and publish
npm run publish:major   # Bump major version and publish
npm run release         # Alias for publish:patch
```

## Architecture

### Single-File Design
The entire server implementation lives in `src/index.ts` (~4,500 lines). This includes:
- Type definitions for Bitbucket API entities
- BitbucketClient class with all API methods
- MCP server setup and tool registration
- Logging configuration

### Core Components

**BitbucketClient Class**: Main API wrapper that handles:
- Axios-based HTTP client with authentication (token or username/password)
- URL normalization (converts web URLs like `bitbucket.org/workspace` to API URLs)
- All Bitbucket API operations grouped by category:
  - Repository operations (list, get details)
  - Pull request operations (CRUD, approve, merge, decline, etc.)
  - PR comments (general and inline)
  - PR tasks (TODO items)
  - PR diffs and patches
  - Pipeline operations (list, run, stop, get logs)

**Environment Configuration**:
- `BITBUCKET_URL`: API base URL (defaults to https://api.bitbucket.org/2.0)
- `BITBUCKET_TOKEN` OR `BITBUCKET_USERNAME` + `BITBUCKET_PASSWORD`: Authentication
- `BITBUCKET_WORKSPACE`: Default workspace (auto-extracted from URL if not provided)
- `BITBUCKET_ENABLE_DANGEROUS`: Enable destructive operations (disabled by default)
- `BITBUCKET_LOG_*`: Logging configuration (file, directory, disable, per-CWD)

**Logging**: Uses Winston with file-based logging to OS-specific directories:
- macOS: `~/Library/Logs/bitbucket-mcp/`
- Windows: `%LOCALAPPDATA%/bitbucket-mcp/`
- Linux: `~/.local/state/bitbucket-mcp/` or `$XDG_STATE_HOME/bitbucket-mcp/`

### MCP Tool Registration

All tools are registered in the `ListToolsRequestSchema` handler with JSON schemas for input validation. Tools are then routed to corresponding BitbucketClient methods in the `CallToolRequestSchema` handler.

### URL Normalization Logic

The `normalizeBitbucketConfig()` function handles backward compatibility:
- Converts `https://bitbucket.org/<workspace>` → `https://api.bitbucket.org/2.0` (auto-extracts workspace)
- Ensures `https://api.bitbucket.org` always has `/2.0` suffix
- Removes trailing slashes for consistent axios baseURL

## Key Implementation Details

### Authentication
Supports two methods (checked in order):
1. Token authentication via `BITBUCKET_TOKEN`
2. Basic auth via `BITBUCKET_USERNAME` + `BITBUCKET_PASSWORD`

Note: `BITBUCKET_USERNAME` is typically your email address for Bitbucket Cloud.

### Inline PR Comments
Uses special inline parameter format:
```typescript
{
  path: "src/file.ts",
  to: 15,    // Line in NEW version (for added/modified lines)
  from: 10   // Line in OLD version (for deleted/modified lines)
}
```

### Pipeline Operations
Requires "Pipelines: Read" permission in Bitbucket app password. Target configuration uses:
- `ref_type` + `ref_name` for branch/tag
- Optional `commit_hash` for specific commit
- Optional `selector_type` + `selector_pattern` for pipeline selection

### Dangerous Operations
When `BITBUCKET_ENABLE_DANGEROUS` is `true`, enables tools like:
- `deletePullRequestComment`
- `deletePullRequestTask`

## Build System

- **TypeScript**: Compiles ES2020 with strict mode to `dist/`
- **Module System**: ESM (type: "module" in package.json)
- **Entry Point**: `dist/index.js` (has shebang for CLI usage)
- **Bin**: Package exposes `bitbucket-mcp` command globally

## Integration

Designed to be used via:
1. **NPX**: `npx -y bitbucket-mcp@latest` (recommended)
2. **Global install**: `npm install -g bitbucket-mcp`
3. **Project install**: Add to MCP client config pointing to local or global install
4. **Docker**: Dockerfile provided for containerized deployment

MCP clients (like Cursor) communicate via stdio transport using the MCP protocol.

## Important Notes

- Single source file makes navigation straightforward but requires discipline with organization
- All API responses are returned as JSON-stringified text content in MCP format
- Error handling uses McpError with appropriate ErrorCodes
- Logger writes structured JSON logs (not console output, which would break stdio transport)
- No test files currently exist in the repository