Add code

CLAUDE.md

@@ -0,0 +1,49 @@
+# 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 + 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.