# mcp-bitbucket

![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
![Version](https://img.shields.io/badge/version-2.1.2-blue)
[![GitHub Container Registry](https://img.shields.io/badge/ghcr.io-n11tech%2Fmcp--bitbucket-blue?logo=github&logoColor=white)](https://github.com/n11tech/mcp-bitbucket/pkgs/container/mcp-bitbucket)
[![Docker Build](https://img.shields.io/github/actions/workflow/status/n11tech/mcp-bitbucket/docker-publish.yml?branch=main&label=Docker%20Build&logo=docker&logoColor=white)](https://github.com/n11tech/mcp-bitbucket/actions/workflows/docker-publish.yml)

**A Node.js/TypeScript Model Context Protocol (MCP) server for Atlassian Bitbucket Server/Data Center.**

This server enables AI systems (e.g., LLMs, AI coding assistants) to securely interact with your self-hosted Bitbucket repositories, pull requests, projects, and code in real time through both standard stdio and HTTP streaming transports.

## Version 2.1.2 Release Notes

**Bitbucket File Content Path Fix** (June 2026)

This patch release fixes Bitbucket Server/Data Center path handling for file and directory operations.

### 🐛 Bug Fixes
- **Fixed**: `bitbucket_get_file_content` path encoding for nested file paths. Path segments are now encoded safely while preserving `/` separators required by Bitbucket REST path parameters.
- **Fixed**: `bitbucket_browse_directory` path handling for nested directories using the same segment-based encoding behavior.

### ⚠️ Breaking Changes
None - this is a backward-compatible bugfix.

---

## Version 2.1.1 Release Notes

**Environment Configuration Bugfix** (June 2026)

This patch release fixes a critical bug where the `.env` file was not being loaded correctly when running from the compiled output.

### 🐛 Bug Fixes
- **Fixed**: `.env` file path resolution when running from `dist/` directory. The `env.ts` module used `import.meta.url` to determine `__dirname`, which resolves to the `dist/` folder at runtime. The `.env` lookup path now correctly navigates one level up to the project root.

### ⚠️ Breaking Changes
None - this is a backward-compatible bugfix.

---

## Version 2.1.0 Release Notes

**Approval Tool & Security Hardening** (June 2026)

This minor release adds pull request approval support and includes non-breaking security and maintainability improvements.

### ✨ New Features
- **Pull Request Approval Tool**: Added `bitbucket_approve_pull_request` tool backed by Bitbucket Server/Data Center approve endpoint semantics.

### 🔒 Security & Reliability
- **Input/Path Safety Improvements**: Strengthened schema and path-handling behavior in core request flows.
- **HTTP Transport Hardening**: Improved authentication/session behavior for safer HTTP streaming operation.
- **Logging Hygiene**: Reduced sensitive argument exposure by using safer request argument summaries.

### ⚠️ Breaking Changes
None - changes are backward compatible.

---

## Version 2.0.0 Release Notes

**Major Core Refactor & Transport Alignment** (June 2026)

This major release reflects substantial changes in the core architecture and runtime behavior of the server to improve maintainability, consistency, and protocol alignment for Bitbucket-focused deployments.

### ✨ Core Improvements
- **Core Application Refactor**: Internal layering and wiring were reorganized around cleaner boundaries across application, domain, and infrastructure modules.
- **MCP SDK HTTP Streaming Model Adoption**: The transport/session lifecycle now follows MCP SDK's `StreamableHTTPServerTransport` pattern instead of a fully custom session-management flow.
- **HTTP Streaming Stabilization**: Session lifecycle handling was improved for initialize/connect/close flows and more predictable session cleanup.
- **Bitbucket Service Identity Cleanup**: Runtime logs and service naming were aligned to Bitbucket terminology.
- **Type-Safety Hardening**: Core infrastructure paths use stricter typing and safer error handling patterns.

### 📦 Runtime & Dependency Updates
- **Node.js Runtime Baseline Updated**: Runtime expectations were refreshed; use the version declared in `package.json` under `engines`.
- **Dependency Refresh**: Core/runtime and development dependencies were upgraded to newer versions for compatibility, security, and maintainability.

### ⚠️ Breaking Changes
- **Major Version Bump**: Package version moved to `2.0.0` to reflect core-level changes.
- **Package Rename**: NPM package metadata now uses `mcp-bitbucket`.

### Migration Notes
- If you pin package metadata or release automation to the old package name, update it to `mcp-bitbucket`.
- HTTP transport internals now align with MCP SDK session semantics; if you depended on custom session handling behavior, re-validate your client integration.
- HTTP startup command remains available as `npm run start:http`; `npm run start:http-streaming` is kept as a compatibility alias.
- Reinstall dependencies after upgrade to pick up new transitive versions (`rm -rf node_modules && npm install`).

---

## Version 1.2.0 Release Notes

**LLM Compatibility: Google Gemini Schema Sanitizer** (May 2026)

This release fixes a known interoperability issue where Google Gemini-based MCP clients (e.g. n8n MCP Client with Gemini, Vertex AI function calling) reject tool schemas emitted by this server.

### ✨ New Features
- **Gemini-Compatible `tools/list` Output**: Tool `inputSchema` payloads are now normalized server-side so they validate against Gemini's stricter JSON Schema subset.
  - JSON Schema unions expressed as `type: ["string", "null"]` are automatically rewritten to `anyOf: [{type: "string"}, {type: "null"}]`.
  - Anthropic Claude and OpenAI ChatGPT clients are unaffected (the rewritten form is semantically equivalent and natively supported).
  - Eliminates the need for downstream workarounds such as n8n Code-node sanitizers.

### 🔒 Security Hardening
- **Prototype Pollution Defense**: Schema sanitizer skips `__proto__`, `prototype`, and `constructor` keys and uses `Object.create(null)` as the recursion accumulator.
- **Recursion Depth Cap**: Sanitizer bounds recursion at depth 64 to prevent stack-overflow DoS on hostile or cyclic schema input.
- **Pure Transformation**: Sanitizer never mutates caller input and performs no I/O, logging, or credential handling.

### 📚 Documentation
- Documented Gemini interoperability fix in release notes.

### ⚠️ Breaking Changes
None - all changes are backward compatible.

---

## Version 1.1.0 Release Notes

**New Feature: Directory Browsing & Security Fix** (April 2026)

This release adds directory browsing capabilities and fixes a critical path traversal vulnerability:

### ✨ New Features
- **Directory Browsing Tool**: Added `bitbucket_browse_directory` tool for exploring repository structure
  - Browse root directory with empty path, `.`, or `/`
  - Navigate subdirectories efficiently
  - Returns file/folder metadata without fetching content (lightweight operation)
  - Enables AI agents to discover repository structure autonomously
  - Resolves [Issue #2](https://github.com/n11techhub/mcp-bitbucket/issues/2)

### 🔒 Security Fixes
- **CRITICAL**: Fixed path traversal vulnerability in `browseBitbucketDirectory` path parameter
  - Added validation to block `..` sequences (path traversal prevention)
  - Added control character filtering to prevent null byte injection
  - Added path length limits (max 1000 characters) to prevent DoS attacks
  - Multi-layer defense: schema validation + URL encoding + API-level checks

### 📚 Documentation
- Added `bitbucket_browse_directory` tool to Available Tools section
- Updated security documentation with path validation details

### ⚠️ Breaking Changes
None - all changes are backward compatible.

---

## Version 1.0.1 Release Notes

**Security Improvements & Bug Fixes** (February 2026)

This release includes critical security enhancements and implements the `BITBUCKET_DEFAULT_PROJECT` feature:

### 🔒 Security Enhancements
- **Input Validation**: Added strict regex validation for project keys and workspace slugs to prevent path traversal and injection attacks
- **URL Encoding**: All API path parameters are now properly URL-encoded to prevent path manipulation
- **Environment Variable Validation**: `BITBUCKET_DEFAULT_PROJECT` is validated and sanitized before use
- **Comprehensive Security Tests**: Added extensive test coverage for path traversal, SQL injection, command injection, and DoS attacks

### 🐛 Bug Fixes
- **Fixed**: `BITBUCKET_DEFAULT_PROJECT` environment variable was being ignored (PR #1)
- **Fixed**: `getDefaultProjectKey()` method now properly returns the configured default project instead of always returning `undefined`

### 📚 Documentation
- Added security notes for `BITBUCKET_DEFAULT_PROJECT` configuration
- Documented valid and invalid project key formats
- Added multi-tenant environment warnings

### ⚠️ Breaking Changes
None - all changes are backward compatible.

---

## Table of Contents

- [Features](#features)
- [What is MCP?](#what-is-mcp)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
  - [Docker (Recommended)](#docker-recommended)
  - [Local Development](#local-development)
- [Configuration](#configuration)
  - [Environment Variables](#environment-variables)
  - [MCP Client Setup](#mcp-client-setup)
- [Transport Options](#transport-options)
  - [Standard I/O Transport (Default)](#standard-io-transport-default)
  - [HTTP Streaming Transport](#http-streaming-transport)
- [Security](#security)
  - [API Key Authentication](#api-key-authentication)
- [Usage Examples](#usage-examples)
- [Available Tools](#available-tools)
- [Development](#development)
- [License](#license)

## Features

- **Dual Transport Support**: Choose between stdio and HTTP streaming transports
- **Secure Authentication**: Optional API key authentication for HTTP transport
- **Comprehensive Bitbucket Integration**: Full access to Bitbucket Server/Data Center APIs
- **Developer Focused**: Designed to help AI assistants understand and interact with your codebase
- **Production Ready**: Built with TypeScript, proper error handling, and security best practices
- **Container Support**: Docker support for easy deployment and scaling

## What is MCP?

Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This server implements MCP for Bitbucket Server/Data Center, enabling AI assistants to interact with your Bitbucket data programmatically through standardized interfaces.

## Prerequisites

- **Node.js**: Version defined by `package.json` `engines` (currently `>=18`)
- **Bitbucket Server/Data Center**: Access with a Personal Access Token (PAT)
- **Docker**: (Recommended) For containerized deployment
- **Git**: For cloning the repository

## Installation

### Docker (Recommended)

#### Using Pre-built Image from GHCR

**Pull and run the latest image:**
```bash
# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/n11techhub/mcp-bitbucket:latest

# Run with environment variables
docker run -i --rm \
  -e BITBUCKET_URL="https://your-bitbucket-server.com" \
  -e BITBUCKET_TOKEN="your_personal_access_token" \
  ghcr.io/n11techhub/mcp-bitbucket:latest
```

#### Building from Source

1. **Clone the Repository:**
   ```bash
   git clone https://github.com/n11tech/mcp-bitbucket.git
   cd mcp-bitbucket
   ```

2. **Build the Docker Image:**
   ```bash
   docker build -t mcp-bitbucket:latest .
   ```

3. **Run with Docker:**
   ```bash
   docker run -i --rm \
     -e BITBUCKET_URL="https://your-bitbucket-server.com" \
     -e BITBUCKET_TOKEN="your_personal_access_token" \
     mcp-bitbucket:latest
   ```

### Local Development

1. **Clone and Install:**
   ```bash
   git clone https://github.com/n11tech/mcp-bitbucket.git
   cd mcp-bitbucket
   npm install
   ```

2. **Build:**
   ```bash
   npm run build
   ```

3. **Start:**
   ```bash
   npm start
   ```

## Using This MCP Server with Smithery CLI

You can use this Bitbucket MCP server locally with the [Smithery CLI](https://smithery.ai/docs). This allows you to connect your AI tools or agents to your self-hosted Bitbucket Server/Data Center. **This server is not hosted on Smithery AI cloud; you must run it yourself (locally or on your own server).**

### Prerequisites
- Node.js version defined by `package.json` `engines` (currently `>=18`)
- [Smithery CLI](https://smithery.ai/docs/build/getting-started)

### 1. Install Smithery CLI
```bash
npm install -g @smithery/cli
```

### 2. Start the Bitbucket MCP Server Locally
You must run your own instance of the server (Docker recommended):
```bash
docker run -it --rm \
  -e BITBUCKET_URL="https://your-bitbucket-server.com" \
  -e BITBUCKET_TOKEN="your_personal_access_token" \
  -e ENABLE_HTTP_TRANSPORT="true" \
  -e MCP_HTTP_PORT="3001" \
  -e MCP_HTTP_ENDPOINT="/mcp" \
  -p 3001:3001 \
  ghcr.io/n11techhub/mcp-bitbucket:latest
```

Or, using npm:
```bash
npm run start:http
```

### 3. Connect to Your Local MCP Server with Smithery CLI
Once your server is running locally, connect to it using the local address:
```bash
npx @smithery/cli connect http://localhost:3001/mcp
```

### 4. Example: Using with Smithery CLI
Once connected, you can call tools (e.g., list repositories):
```bash
npx @smithery/cli call http://localhost:3001/mcp bitbucket_list_repositories --params '{"workspaceSlug": "your-workspace"}'
```

For more details, see the [Smithery CLI documentation](https://smithery.ai/docs/build/getting-started).

> **Note for Smithery Users:**
>
> When connecting to this MCP server via Smithery, you only need to provide:
> - **Bitbucket Server URL** (e.g., `<your-bitbucket-url>`)
> - **Bitbucket Personal Access Token**
>
> All other environment variables (such as port, endpoint, API key) are managed by the server administrator or deployment and do not need to be set by end users.
>
> If the server administrator has enabled API key authentication, you may be asked to provide an API key as well. In that case, enter the value provided by your admin.

**Example:**

When prompted by Smithery, enter:
```
bitbucketUrl: <your-bitbucket-url>
bitbucketToken: <your-bitbucket-token>
```

## Advanced: Using STDIO Transport

By default, this MCP server is configured for HTTP transport, which is recommended for most users and for Smithery CLI/web integrations.

**Advanced users** who want to run the MCP server as a local subprocess (STDIO transport) can use the following Smithery configuration:

```yaml
startCommand:
  type: "stdio"
  configSchema:
    type: "object"
    required: ["bitbucketUrl", "bitbucketToken"]
    properties:
      bitbucketUrl:
        type: "string"
        description: "The base URL of your self-hosted Bitbucket instance (e.g., https://<your-bitbucket-url>)"
      bitbucketToken:
        type: "string"
        description: "Personal Access Token for Bitbucket Server/Data Center"
  commandFunction: |-
    (config) => ({
      command: 'node',
      args: ['build/infrastructure/index.js'],
      env: {
        BITBUCKET_URL: config.bitbucketUrl,
        BITBUCKET_TOKEN: config.bitbucketToken
      }
    })
  exampleConfig:
    bitbucketUrl: "https://<your-bitbucket-url>"
    bitbucketToken: "<your-bitbucket-token>"
```

This allows you to launch the MCP server as a subprocess and communicate via standard input/output, which may be useful for certain local agent or automation scenarios.

## Configuration

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `BITBUCKET_URL` | Your Bitbucket Server/Data Center URL | - | ✅ |
| `BITBUCKET_TOKEN` | Personal Access Token | - | ✅ |
| `BITBUCKET_DEFAULT_PROJECT` | Default project key for operations (see Security Notes below) | - | ❌ |
| `ENABLE_HTTP_TRANSPORT` | Enable HTTP streaming transport | `false` | ❌ |
| `MCP_HTTP_PORT` | HTTP server port | `3001` | ❌ |
| `MCP_HTTP_ENDPOINT` | HTTP endpoint path | `/stream` | ❌ |
| `MCP_API_KEY` | API key for authentication | - | ❌ |

#### Security Notes for `BITBUCKET_DEFAULT_PROJECT`

**⚠️ Important Security Considerations:**

- **Input Validation**: The `BITBUCKET_DEFAULT_PROJECT` value is automatically validated to prevent path traversal and injection attacks. Only alphanumeric characters, hyphens, and underscores are allowed.
- **Multi-Tenant Environments**: In shared or multi-tenant deployments, be aware that the default project applies globally to all requests that don't specify a `workspaceSlug`. Consider using explicit workspace slugs in API calls instead.
- **Valid Format**: Project keys must match the pattern `^[A-Z0-9_-]+$` (case-insensitive) and be between 1-255 characters.
- **Invalid Values**: If an invalid project key is provided, the server will log an error and ignore the value, requiring explicit `workspaceSlug` in all API calls.

**Example Valid Values:**
```bash
BITBUCKET_DEFAULT_PROJECT=MYPROJECT
BITBUCKET_DEFAULT_PROJECT=my-project-123
BITBUCKET_DEFAULT_PROJECT=TEAM_ALPHA
```

**Example Invalid Values (will be rejected):**
```bash
BITBUCKET_DEFAULT_PROJECT=../../../admin  # Path traversal attempt
BITBUCKET_DEFAULT_PROJECT=PROJ; rm -rf /  # Command injection attempt
BITBUCKET_DEFAULT_PROJECT=PROJ/test       # Contains invalid character
```

### MCP Client Setup

Configure your MCP-compatible client to connect to this server. The configuration depends on your chosen transport method.

## Transport Options

### Standard I/O Transport (Default)

The default transport method uses standard input/output for communication. This is suitable for direct integration with AI systems that launch the server as a child process.

**Example MCP Configuration:**

```json
{
  "mcpServers": {
    "mcp-bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network=host",
        "-e", "BITBUCKET_URL",
        "-e", "BITBUCKET_TOKEN",
        "ghcr.io/n11techhub/mcp-bitbucket:latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_TOKEN": "your_personal_access_token"
      }
    }
  }
}
```

### HTTP Streaming Transport

For scenarios requiring remote connections or web-based integrations, the server supports HTTP streaming transport with Server-Sent Events (SSE).

**Enable HTTP Transport:**

```bash
# Using GHCR image
docker run -i --rm \
  -p 3001:3001 \
  -e BITBUCKET_URL="https://your-bitbucket-server.com" \
  -e BITBUCKET_TOKEN="your_personal_access_token" \
  -e ENABLE_HTTP_TRANSPORT="true" \
  -e MCP_HTTP_PORT="3001" \
  -e MCP_HTTP_ENDPOINT="mcp" \
  ghcr.io/n11techhub/mcp-bitbucket:latest

# Using npm script
npm run start:http
```

**Example MCP Configuration for HTTP Transport:**

```json
{
  "mcpServers": {
    "mcp-bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "3001:3001",
        "-e", "BITBUCKET_URL",
        "-e", "BITBUCKET_TOKEN", 
        "-e", "ENABLE_HTTP_TRANSPORT",
        "-e", "MCP_HTTP_PORT",
        "-e", "MCP_HTTP_ENDPOINT",
        "ghcr.io/n11techhub/mcp-bitbucket:latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_TOKEN": "your_personal_access_token",
        "ENABLE_HTTP_TRANSPORT": "true",
        "MCP_HTTP_PORT": "3001",
        "MCP_HTTP_ENDPOINT": "mcp"
      }
    }
  }
}
```

**HTTP Endpoints:**

- **POST** `http://localhost:3001/mcp` - Send MCP requests
- **GET** `http://localhost:3001/mcp` - Server-Sent Events stream
- **GET** `http://localhost:3001/health` - Health check endpoint

## Security

### API Key Authentication

For HTTP transport, you can enable API key authentication to secure your server:

**Setup API Key Authentication:**

```bash
# Generate a secure API key (recommended: 32+ characters)
export MCP_API_KEY="your-secure-api-key-here"

# Run with authentication enabled
docker run -i --rm \
  -p 3001:3001 \
  -e BITBUCKET_URL="https://your-bitbucket-server.com" \
  -e BITBUCKET_TOKEN="your_personal_access_token" \
  -e ENABLE_HTTP_TRANSPORT="true" \
  -e MCP_API_KEY="your-secure-api-key-here" \
  mcp-bitbucket:latest
```

**Configuration with API Key:**

```json
{
  "mcpServers": {
    "mcp-bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "3001:3001",
        "-e", "BITBUCKET_URL",
        "-e", "BITBUCKET_TOKEN",
        "-e", "ENABLE_HTTP_TRANSPORT",
        "-e", "MCP_API_KEY",
        "mcp-bitbucket:latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_TOKEN": "your_personal_access_token",
        "ENABLE_HTTP_TRANSPORT": "true",
        "MCP_API_KEY": "your-secure-api-key-here"
      }
    }
  }
}
```

When API key authentication is enabled, all HTTP requests must include the API key in the request headers or parameters.

## Usage Examples

### Pull Request Management

```javascript
// Create a pull request
await callTool('bitbucket_create_pull_request', {
  repository: 'my-repo',
  title: 'Feature: Add new API endpoint',
  sourceBranch: 'feature/api-endpoint',
  targetBranch: 'main',
  description: 'This PR adds a new REST API endpoint for user management.'
});

// Get pull request details
await callTool('bitbucket_get_pull_request_details', {
  repository: 'my-repo',
  prId: 123
});
```

### Repository Operations

```javascript
// Search gateway content
await callTool('bitbucket_search_content', {
  workspaceSlug: 'my-workspace',
  query: 'authentication',
  extension: 'js'
});

// Get file content
await callTool('bitbucket_get_file_content', {
  workspaceSlug: 'my-workspace',
  repoSlug: 'my-repo',
  filePath: 'src/auth/login.js'
});
```

## Available Tools

This server provides a comprehensive suite of tools for interacting with Bitbucket Server/Data Center:

### Pull Request Management
- `bitbucket_create_pull_request` - Create new pull requests
- `bitbucket_get_pull_request_details` - Get PR details and metadata  
- `bitbucket_approve_pull_request` - Approve pull requests
- `bitbucket_get_pull_request_diff` - Retrieve PR diffs
- `bitbucket_get_pull_request_reviews` - Get PR review status
- `bitbucket_merge_pull_request` - Merge pull requests
- `bitbucket_decline_pull_request` - Decline pull requests
- `bitbucket_add_pull_request_comment` - Add general PR comments

### Repository Operations
- `bitbucket_list_workspaces` - List available workspaces
- `bitbucket_list_repositories` - Browse repositories
- `bitbucket_get_repository_details` - Get repository information
- `bitbucket_search_content` - Search within repositories
- `bitbucket_get_file_content` - Read file contents
- `bitbucket_browse_directory` - Browse directory contents (returns file/folder metadata without content)

### Branch Management
- `bitbucket_create_branch` - Create new branches
- `bitbucket_list_repository_branches` - List repository branches

### User Management
- `bitbucket_get_user_profile` - Get user profile details

For detailed parameter information and usage examples, refer to the individual tool schemas in `src/domain/contracts/schemas/`.

## Development

### Available Scripts

- **Build**: `npm run build` - Compile TypeScript to JavaScript
- **Start**: `npm start` - Run the server with stdio transport
- **HTTP**: `npm run start:http` - Run with HTTP streaming transport
- **Development**: `npm run dev` - Watch mode for development
- **Lint**: `npm run lint` - Code quality checks
- **Test**: `npm run test` - Run test suite
- **Inspector**: `npm run inspector` - Debug MCP server interactions

### Development Setup

```bash
# Clone and setup
git clone <repository_url>
cd mcp-bitbucket
npm install

# Create environment file
cp .env.example .env
# Edit .env with your Bitbucket credentials

# Development with watch mode
npm run dev
```

### Architecture

The codebase follows clean architecture principles:

```
src/
├── application/          # Application layer
│   ├── facade/          # Client facades  
│   └── use-cases/       # Business logic
├── domain/              # Domain layer
│   ├── contracts/       # Interfaces and schemas
│   ├── entity/          # Domain entities
│   └── repository/      # Repository interfaces
├── infrastructure/      # Infrastructure layer
│   ├── clients/         # External API clients
│   ├── config/          # Configuration management
│   ├── http/            # HTTP transport implementation
│   └── setup/           # Server setup and initialization
```

## License

This project is licensed under the Apache License, Version 2.0.

See the `LICENSE` file for more details.

---

Built with the [Model Context Protocol](https://modelcontextprotocol.io)