@atercates/bitbucket-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matan Yemini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,347 @@
+# Bitbucket MCP Server
+
+A Model Context Protocol (MCP) server for integrating with Bitbucket Cloud and Server APIs. This MCP server enables AI assistants like Claude and Cursor to interact with your Bitbucket repositories, pull requests, pipelines, and other resources.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://badge.fury.io/js/bitbucket-mcp.svg)](https://www.npmjs.com/package/bitbucket-mcp)
+
+## Features
+
+✨ **Comprehensive Bitbucket Integration** - 59 tools covering repositories, PRs, branches, commits, pipelines, and more
+
+🔒 **Secure Authentication** - App password tokens or basic auth with granular permission control via Bitbucket
+
+📝 **Well-Documented** - Complete API reference, architecture guides, and deployment instructions in `/docs`
+
+🧪 **Fully Tested** - Comprehensive unit test suite with full tool coverage (Vitest)
+
+⚡ **Modular Design** - Clean, maintainable architecture organized by feature domain (11 handler modules)
+
+🛡️ **Safety First** - Dangerous operations (deletes) require explicit `BITBUCKET_ALLOW_DANGEROUS=true`
+
+🚀 **Production Ready** - Built with pnpm, ESLint, Prettier, and modern TypeScript
+
+## Quick Start
+
+### Installation
+
+```bash
+# Option 1: Global install with NPM
+npm install -g bitbucket-mcp
+
+# Option 2: Use with NPX (no installation required)
+npx -y bitbucket-mcp@latest
+
+# Option 3: Local development
+git clone <repository>
+cd bitbucket-mcp
+pnpm install
+pnpm build
+pnpm start
+```
+
+### Configuration
+
+Set environment variables before running:
+
+```bash
+# Authentication (choose one method)
+export BITBUCKET_TOKEN="your_app_password"
+# OR
+export BITBUCKET_USERNAME="your_email@example.com"
+export BITBUCKET_PASSWORD="your_app_password"
+
+# Basic configuration
+export BITBUCKET_WORKSPACE="my-workspace"  # Optional: default workspace
+
+# Optional: Enable dangerous operations (delete branch, delete tag, etc.)
+export BITBUCKET_ALLOW_DANGEROUS=true
+```
+
+### Running the Server
+
+```bash
+# If installed globally
+bitbucket-mcp
+
+# If using NPX
+npx -y bitbucket-mcp@latest
+
+# If installed locally
+pnpm start
+```
+
+The server will start and listen for MCP protocol connections via stdio.
+
+## Integration with MCP Clients
+
+### Claude / Cursor Configuration
+
+Add to your MCP configuration (`.mcp.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "bitbucket": {
+      "command": "bitbucket-mcp",
+      "env": {
+        "BITBUCKET_TOKEN": "your_app_password",
+        "BITBUCKET_WORKSPACE": "my-workspace"
+      }
+    }
+  }
+}
+```
+
+Or with npx:
+
+```json
+{
+  "mcpServers": {
+    "bitbucket": {
+      "command": "npx",
+      "args": ["-y", "bitbucket-mcp@latest"],
+      "env": {
+        "BITBUCKET_TOKEN": "your_app_password",
+        "BITBUCKET_WORKSPACE": "my-workspace"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+The server provides 59 tools organized into 11 categories:
+
+| Category | Tools |
+|----------|-------|
+| **Repositories** | List, get, create repositories |
+| **Pull Requests** | Create, approve, merge, decline PRs |
+| **PR Comments** | Create, delete PR comments |
+| **PR Tasks** | Create, update, delete PR tasks (TODOs) |
+| **PR Content** | Get diffs and commits |
+| **Branches & Tags** | List, create, delete branches and tags |
+| **Commits** | List commits and commit details |
+| **Pipelines** | List, run, stop pipeline runs |
+| **Source Code** | Read file content from repositories |
+| **Users** | Get current user and workspace info |
+| **Branching Model** | Get branching strategy configuration |
+
+**Complete reference:** See [docs/TOOLS.md](docs/TOOLS.md)
+
+## Environment Variables
+
+### Authentication (Required - one method)
+
+- `BITBUCKET_TOKEN` - App password (recommended)
+- OR `BITBUCKET_USERNAME` + `BITBUCKET_PASSWORD` - Basic authentication
+
+### Configuration (Optional)
+
+- `BITBUCKET_URL` - API base URL (default: `https://api.bitbucket.org/2.0`)
+- `BITBUCKET_WORKSPACE` - Default workspace name
+- `BITBUCKET_ALLOW_DANGEROUS` - Enable delete operations (default: false)
+
+### Logging (Optional)
+
+- `BITBUCKET_LOG_DISABLE` - Disable file logging (default: false)
+- `BITBUCKET_LOG_FILE` - Custom log file path
+- `BITBUCKET_LOG_DIR` - Custom log directory
+- `BITBUCKET_LOG_PER_CWD` - Create per-directory logs (default: false)
+
+## Getting Credentials
+
+### Create Bitbucket App Password
+
+1. Go to https://bitbucket.org/account/settings/app-passwords/
+2. Click "Create app password"
+3. Give it a name (e.g., "MCP Server")
+4. Select permissions:
+   - Pipelines: Read
+   - Repositories: Read, Write
+   - Pull requests: Read, Write
+5. Copy the generated password
+6. Set `BITBUCKET_TOKEN` to this password
+
+### Find Your Workspace
+
+The workspace name is visible in your Bitbucket URL: `https://bitbucket.org/{workspace}`
+
+## Documentation
+
+- **[Getting Started Guide](docs/guides/GETTING_STARTED.md)** - Installation, configuration, and basic usage
+- **[Tools Reference](docs/TOOLS.md)** - Complete API documentation for all 59 tools with examples
+- **[Architecture Guide](docs/architecture/ARCHITECTURE.md)** - Technical design, modular structure, and extension guide
+- **[Environment Variables](docs/guides/ENVIRONMENT_VARIABLES.md)** - Complete reference for all configuration options
+- **[NPM Deployment](docs/guides/NPM_DEPLOYMENT.md)** - Publishing and deployment instructions
+- **[Main Documentation](docs/README.md)** - Overview and quick links
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm (or npm)
+
+### Setup
+
+```bash
+git clone <repository>
+cd bitbucket-mcp
+pnpm install
+```
+
+### Build
+
+```bash
+pnpm build          # Compile TypeScript
+pnpm lint           # Run ESLint  
+pnpm format         # Format with Prettier
+pnpm format:check   # Check formatting
+```
+
+### Testing
+
+```bash
+pnpm test           # Run Vitest suite
+pnpm test:watch     # Watch mode
+```
+
+### Running in Development
+
+```bash
+pnpm dev            # Run with tsx (watch mode, no build required)
+# OR
+pnpm build && pnpm start
+```
+
+### MCP Inspector (Debugging)
+
+```bash
+pnpm inspector      # Launch interactive MCP inspector to test tools
+```
+
+## Project Structure
+
+```
+src/
+├─ index.ts              # Entry point
+├─ server.ts             # MCP server orchestration
+├─ client.ts             # Bitbucket API client
+├─ config.ts             # Configuration management
+├─ logger.ts             # File-based logging
+├─ types.ts              # TypeScript definitions
+├─ schemas.ts            # JSON schemas
+├─ utils.ts              # Utilities
+├─ pagination.ts         # Pagination helper
+└─ handlers/             # Feature modules
+   ├─ repositories.ts
+   ├─ pull-requests.ts
+   ├─ pr-comments.ts
+   ├─ pr-tasks.ts
+   ├─ pr-content.ts
+   ├─ refs.ts
+   ├─ commits.ts
+   ├─ pipelines.ts
+   ├─ source.ts
+   ├─ users.ts
+   ├─ branching-model.ts
+   └─ index.ts
+
+docs/
+├─ README.md             # Documentation overview
+├─ TOOLS.md              # Tools reference
+├─ guides/
+│  └─ GETTING_STARTED.md # Setup guide
+└─ architecture/
+   └─ ARCHITECTURE.md    # Technical design
+
+__tests__/
+├─ test-utils.ts         # Test helpers
+└─ handlers/             # Handler tests
+```
+
+## Architecture
+
+The server uses a modular handler-based architecture:
+
+```
+MCP Client → Server → Handler Modules → BitbucketClient → Bitbucket API
+```
+
+Each handler module:
+- Defines tools (names, schemas, descriptions)
+- Implements handlers (async functions)
+- Can mark tools as dangerous
+- Is automatically registered by the server
+
+See [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) for details.
+
+## Dangerous Operations
+
+Some tools that perform destructive operations are marked as dangerous:
+
+- `deletePullRequestComment`
+- `deletePullRequestTask`
+- `deleteBranch`
+- `deleteTag`
+
+These require `BITBUCKET_ALLOW_DANGEROUS=true` to use, preventing accidental data loss.
+
+## Troubleshooting
+
+### Authentication Issues
+
+```bash
+# Test your credentials
+curl -X GET https://api.bitbucket.org/2.0/user \
+  -u your_username:your_app_password
+```
+
+### View Logs
+
+**macOS:**
+```bash
+tail -f ~/Library/Logs/bitbucket-mcp/bitbucket.log
+```
+
+**Linux:**
+```bash
+tail -f ~/.local/state/bitbucket-mcp/bitbucket.log
+```
+
+**Windows:**
+```bash
+Get-Content -Path "$env:LOCALAPPDATA\bitbucket-mcp\bitbucket.log" -Tail 50 -Wait
+```
+
+### Self-Hosted Bitbucket
+
+For self-hosted Bitbucket Server, set the API URL:
+
+```bash
+BITBUCKET_URL=https://bitbucket.mycompany.com/rest/api/2.0 bitbucket-mcp
+```
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📖 See [docs/guides/GETTING_STARTED.md](docs/guides/GETTING_STARTED.md) for setup help
+- 🔧 Check [docs/TOOLS.md](docs/TOOLS.md) for tool documentation with examples
+- 🏗️ Review [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) for technical details
+- ⚙️ Check [docs/guides/ENVIRONMENT_VARIABLES.md](docs/guides/ENVIRONMENT_VARIABLES.md) for all configuration options
+- 🚀 See [docs/guides/NPM_DEPLOYMENT.md](docs/guides/NPM_DEPLOYMENT.md) for deployment to NPM
+- 🐛 Enable logging with `BITBUCKET_LOG_DISABLE=false` for debugging
+- 📝 Check [docs/README.md](docs/README.md) for complete documentation index
+
+---
+
+**Version:** 5.0.6  
+**Last Updated:** January 2025  
+**Architecture:** Modular handler-based design with 11 feature modules  
+**Test Framework:** Vitest  
+**Package Manager:** pnpm

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import { AxiosInstance } from "axios";
+import { BitbucketPaginator } from "./pagination.js";
+import { BitbucketConfig } from "./types.js";
+/**
+ * Bitbucket API client that wraps axios and provides paginator support
+ */
+export declare class BitbucketClient {
+    readonly api: AxiosInstance;
+    readonly config: BitbucketConfig;
+    readonly paginator: BitbucketPaginator;
+    constructor(config: BitbucketConfig);
+    /**
+     * Resolves workspace from argument or falls back to default config
+     */
+    resolveWorkspace(workspace?: string): string;
+}

package/dist/client.js

@@ -0,0 +1,35 @@
+import axios from "axios";
+import { BitbucketPaginator } from "./pagination.js";
+import { logger } from "./logger.js";
+/**
+ * Bitbucket API client that wraps axios and provides paginator support
+ */
+export class BitbucketClient {
+    constructor(config) {
+        this.config = config;
+        // Setup Axios instance
+        const headers = {};
+        if (config.token) {
+            headers.Authorization = `Bearer ${config.token}`;
+        }
+        this.api = axios.create({
+            baseURL: config.baseUrl,
+            headers,
+            auth: config.username && config.password
+                ? { username: config.username, password: config.password }
+                : undefined,
+        });
+        this.paginator = new BitbucketPaginator(this.api, logger);
+    }
+    /**
+     * Resolves workspace from argument or falls back to default config
+     */
+    resolveWorkspace(workspace) {
+        const resolved = workspace || this.config.defaultWorkspace;
+        if (!resolved) {
+            throw new Error("Workspace must be provided either as a parameter or through BITBUCKET_WORKSPACE environment variable");
+        }
+        return resolved;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;GAEG;AACH,MAAM,OAAO,eAAe;IAK1B,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,uBAAuB;QACvB,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,CAAC,aAAa,GAAG,UAAU,MAAM,CAAC,KAAK,EAAE,CAAC;QACnD,CAAC;QAED,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;YACtB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO;YACP,IAAI,EACF,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;gBAChC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;gBAC1D,CAAC,CAAC,SAAS;SAChB,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,GAAG,IAAI,kBAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,SAAkB;QACjC,MAAM,QAAQ,GAAG,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC;QAC3D,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,sGAAsG,CACvG,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+import type { BitbucketConfig } from "./types.js";
+/**
+ * Normalize Bitbucket configuration for backward compatibility and DX.
+ * Handles URL normalization and workspace extraction from web URLs.
+ */
+export declare function normalizeBitbucketConfig(rawConfig: BitbucketConfig): BitbucketConfig;
+/**
+ * Load Bitbucket configuration from environment variables.
+ * Reads all relevant BITBUCKET_* env vars and returns a normalized config.
+ */
+export declare function loadConfigFromEnv(): BitbucketConfig;

package/dist/config.js

@@ -0,0 +1,54 @@
+import { isTruthyEnv } from "./logger.js";
+/**
+ * Normalize Bitbucket configuration for backward compatibility and DX.
+ * Handles URL normalization and workspace extraction from web URLs.
+ */
+export function normalizeBitbucketConfig(rawConfig) {
+    const normalizedConfig = { ...rawConfig };
+    try {
+        const parsed = new URL(rawConfig.baseUrl);
+        const host = parsed.hostname.toLowerCase();
+        // If users provide a web URL like https://bitbucket.org/<workspace>,
+        // extract the workspace and switch to the public API base URL
+        if (host === "bitbucket.org" || host === "www.bitbucket.org") {
+            const segments = parsed.pathname.split("/").filter(Boolean);
+            if (!normalizedConfig.defaultWorkspace && segments.length >= 1) {
+                normalizedConfig.defaultWorkspace = segments[0];
+            }
+            normalizedConfig.baseUrl = "https://api.bitbucket.org/2.0";
+        }
+        // If users provide https://api.bitbucket.org (without /2.0), ensure /2.0
+        if (host === "api.bitbucket.org") {
+            const pathname = parsed.pathname.replace(/\/+$/, "");
+            if (!pathname.startsWith("/2.0")) {
+                normalizedConfig.baseUrl = "https://api.bitbucket.org/2.0";
+            }
+            else {
+                normalizedConfig.baseUrl = "https://api.bitbucket.org/2.0";
+            }
+        }
+        // Remove trailing slashes for a consistent axios baseURL
+        normalizedConfig.baseUrl = normalizedConfig.baseUrl.replace(/\/+$/, "");
+    }
+    catch {
+        // If baseUrl is not a valid absolute URL, keep as-is (custom/self-hosted cases)
+    }
+    return normalizedConfig;
+}
+/**
+ * Load Bitbucket configuration from environment variables.
+ * Reads all relevant BITBUCKET_* env vars and returns a normalized config.
+ */
+export function loadConfigFromEnv() {
+    const initialConfig = {
+        baseUrl: process.env.BITBUCKET_URL || "https://api.bitbucket.org/2.0",
+        token: process.env.BITBUCKET_TOKEN,
+        username: process.env.BITBUCKET_USERNAME,
+        password: process.env.BITBUCKET_PASSWORD,
+        defaultWorkspace: process.env.BITBUCKET_WORKSPACE,
+        allowDangerousCommands: isTruthyEnv(process.env.BITBUCKET_ENABLE_DANGEROUS) ||
+            isTruthyEnv(process.env.BITBUCKET_ALLOW_DANGEROUS),
+    };
+    return normalizeBitbucketConfig(initialConfig);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAA0B;IACjE,MAAM,gBAAgB,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QAE3C,qEAAqE;QACrE,8DAA8D;QAC9D,IAAI,IAAI,KAAK,eAAe,IAAI,IAAI,KAAK,mBAAmB,EAAE,CAAC;YAC7D,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC5D,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;gBAC/D,gBAAgB,CAAC,gBAAgB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAClD,CAAC;YACD,gBAAgB,CAAC,OAAO,GAAG,+BAA+B,CAAC;QAC7D,CAAC;QAED,yEAAyE;QACzE,IAAI,IAAI,KAAK,mBAAmB,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACrD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACjC,gBAAgB,CAAC,OAAO,GAAG,+BAA+B,CAAC;YAC7D,CAAC;iBAAM,CAAC;gBACN,gBAAgB,CAAC,OAAO,GAAG,+BAA+B,CAAC;YAC7D,CAAC;QACH,CAAC;QAED,yDAAyD;QACzD,gBAAgB,CAAC,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,gFAAgF;IAClF,CAAC;IAED,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,aAAa,GAAoB;QACrC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,+BAA+B;QACrE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe;QAClC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB;QACxC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB;QACxC,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;QACjD,sBAAsB,EACpB,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;YACnD,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;KACrD,CAAC;IAEF,OAAO,wBAAwB,CAAC,aAAa,CAAC,CAAC;AACjD,CAAC"}

package/dist/handlers/branching-model.d.ts

@@ -0,0 +1,2 @@
+import { HandlerModule } from "./types.js";
+export declare const branchingModelModule: HandlerModule;