# 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

```bash
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 |

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