From c6080b4b98609b9b4b2f219b0d9b90f2e39f8fca Mon Sep 17 00:00:00 2001 From: Nicolas FRADIN Date: Tue, 19 May 2026 17:12:56 +0200 Subject: [PATCH] Update README and CLAUDE files --- CLAUDE.md | 4 +-- README.md | 98 +++++++++++++++++++++++++------------------------------ 2 files changed, 47 insertions(+), 55 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3d730ef..5c48210 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,7 +25,7 @@ The server is a 3-layer pipeline: **MCP protocol** -> **Router** -> **Bitbucket - `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/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 @@ -40,7 +40,7 @@ The server is a 3-layer pipeline: **MCP protocol** -> **Router** -> **Bitbucket | Variable | Purpose | |----------|---------| | `BITBUCKET_MCP_EMAIL` | Bitbucket account email (Basic Auth username) | -| `BITBUCKET_MCP_TOKEN` | Bitbucket app password (Basic Auth password) | +| `BITBUCKET_MCP_TOKEN` | Bitbucket API token (Basic Auth password) | | `DEFAULT_WORKSPACE` | Optional default workspace slug | | `DEFAULT_REPO` | Optional default repository slug | diff --git a/README.md b/README.md index 43413e0..d858d08 100644 --- a/README.md +++ b/README.md @@ -31,71 +31,37 @@ This MCP server exposes **read-only** Bitbucket Cloud Pull Request operations as ## Quick Start -### Prerequisites +Get up and running in 4 steps: + +### 1. Prerequisites - Node.js **24.13+** (see `.nvmrc`) -- A Bitbucket Cloud [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) with **repository read** permissions +- A Bitbucket Cloud [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) with **repository read** permissions (note: App Passwords are no longer supported by Bitbucket) -### Installation +### 2. Install & Build ```bash git clone cd bitbucket-mcp npm install -``` - -### Configuration - -Create a `.env` file in the project root: - -```env -BITBUCKET_MCP_EMAIL=your_email@example.com -BITBUCKET_MCP_TOKEN=your_app_password - -# Optional defaults (avoids passing workspace/repo on every call) -DEFAULT_WORKSPACE=my-workspace -DEFAULT_REPO=my-repo -``` - -Or export as environment variables (takes priority over `.env`): - -```bash -export BITBUCKET_MCP_EMAIL=your_email@example.com -export BITBUCKET_MCP_TOKEN=your_app_password -``` - -### Run - -```bash -# Production -npm start - -# Development (hot reload) -npm run dev - -# Build npm run build ``` ---- +### 3. Configure in Claude -## MCP Client Configuration +Add the MCP server to your Claude configuration: -### Claude Code - -Add the following to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`): +**Claude Code** — edit `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project): ```json { "mcpServers": { "bitbucket": { "command": "node", - "args": [ - "/absolute/path/to/bitbucket-mcp/dist/index.js" - ], + "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"], "env": { "BITBUCKET_MCP_EMAIL": "your_email@example.com", - "BITBUCKET_MCP_TOKEN": "your_bitbucket_app_password", + "BITBUCKET_MCP_TOKEN": "your_api_token", "DEFAULT_WORKSPACE": "your-workspace", "DEFAULT_REPO": "your-repo" } @@ -104,21 +70,17 @@ Add the following to your Claude Code MCP settings (`~/.claude/settings.json` or } ``` -### Claude Desktop - -Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows): +**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "bitbucket": { "command": "node", - "args": [ - "/absolute/path/to/bitbucket-mcp/dist/index.js" - ], + "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"], "env": { "BITBUCKET_MCP_EMAIL": "your_email@example.com", - "BITBUCKET_MCP_TOKEN": "your_bitbucket_app_password", + "BITBUCKET_MCP_TOKEN": "your_api_token", "DEFAULT_WORKSPACE": "your-workspace", "DEFAULT_REPO": "your-repo" } @@ -127,7 +89,14 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_ } ``` -> **Note:** You must build the project first (`npm run build`) since the config points to `dist/index.js`. Use the **absolute path** to the compiled entry point. Setting `DEFAULT_WORKSPACE` and `DEFAULT_REPO` is optional but convenient — it lets you omit those parameters from every tool call. +> **Important:** +> - Replace `/absolute/path/to/bitbucket-mcp` with the actual absolute path where you cloned the repo. +> - `DEFAULT_WORKSPACE` and `DEFAULT_REPO` are optional but convenient — they let you omit those parameters from every tool call. +> - Get your API token from [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens). + +### 4. Verify + +Restart Claude (or reload MCP servers), then ask Claude to run the `validate_token` tool. If credentials are correct, it will confirm the connection is working. --- @@ -213,6 +182,27 @@ Response: ## Development +### Running Locally + +For development, you can use a `.env` file instead of configuring credentials in the MCP client: + +```env +BITBUCKET_MCP_EMAIL=your_email@example.com +BITBUCKET_MCP_TOKEN=your_api_token +DEFAULT_WORKSPACE=my-workspace +DEFAULT_REPO=my-repo +``` + +```bash +# Run with hot reload +npm run dev + +# Or run directly +npm start +``` + +### Testing + ```bash # Run tests npm test @@ -250,7 +240,9 @@ tests/ This server uses **HTTP Basic Authentication** with the Bitbucket Cloud REST API v2.0: - **Username** = your Bitbucket email -- **Password** = an [App Password](https://bitbucket.org/account/settings/app-passwords/) +- **Password** = an [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) + +> **Note:** Bitbucket no longer supports App Passwords. You must use an API Token instead. Credential resolution order: 1. Environment variables (`BITBUCKET_MCP_EMAIL` + `BITBUCKET_MCP_TOKEN`)