50 lines
2.4 KiB
Markdown
50 lines
2.4 KiB
Markdown
# 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.
|