Nicolas FRADIN
2df53cbf10
The `/workspaces` API endpoint was updated to `/user/workspaces` to correctly retrieve workspaces for the authenticated user. Configuration guidance for `DEFAULT_WORKSPACE` and `DEFAULT_REPO` in documentation and templates now explicitly references deriving these values from the Bitbucket repository URL, simplifying initial setup.
56 lines
3.0 KiB
Markdown
56 lines
3.0 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 + 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 (from your repo URL: `https://bitbucket.org/{workspace}/{repo}/...`) |
|
|
| `DEFAULT_REPO` | Optional default repository slug (from your repo URL: `https://bitbucket.org/{workspace}/{repo}/...`) |
|
|
| `RUN_WRITE_TESTS` | Set to `true` to enable write integration tests |
|
|
| `TEST_PR_ID` | PR ID to use for write integration tests (required when `RUN_WRITE_TESTS=true`) |
|
|
|
|
Copy `.env.template` to `.env` and fill in your values for local development and testing.
|
|
|
|
## 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.
|
|
|
|
Write integration tests (approve/unapprove, comments, tasks) are skipped by default. They require both `RUN_WRITE_TESTS=true` and `TEST_PR_ID` to be set. Write tests never pick a random PR — if `TEST_PR_ID` is missing the test is skipped with a warning.
|