# Directory Structure
```
├── .eslintrc.json
├── .github
│ └── workflows
│ └── build.yml
├── .gitignore
├── Dockerfile
├── jest.config.js
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── smithery.yaml
├── src
│ ├── __tests__
│ │ └── index.test.ts
│ └── index.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Build output
build/
dist/
*.tsbuildinfo
# IDE
.vscode/
.idea/
*.swp
*.swo
# Environment variables
.env
.env.local
.env.*.local
# System files
.DS_Store
Thumbs.db
```
--------------------------------------------------------------------------------
/.eslintrc.json:
--------------------------------------------------------------------------------
```json
{
"parser": "@typescript-eslint/parser",
"plugins": ["@typescript-eslint"],
"extends": [
"eslint:recommended",
"plugin:@typescript-eslint/recommended"
],
"env": {
"node": true,
"es6": true
},
"parserOptions": {
"ecmaVersion": 2022,
"sourceType": "module"
}
}
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# Bitbucket Server MCP
MCP (Model Context Protocol) server for Bitbucket Server Pull Request management. This server provides tools and resources to interact with the Bitbucket Server API through the MCP protocol.
[](https://smithery.ai/server/@garc33/bitbucket-server-mcp-server)
<a href="https://glama.ai/mcp/servers/jskr5c1zq3"><img width="380" height="200" src="https://glama.ai/mcp/servers/jskr5c1zq3/badge" alt="Bitbucket Server MCP server" /></a>
## ✨ New Features
- **🔍 Advanced Search**: Search code and files across repositories with project/repository filtering using the `search` tool
- **📄 File Operations**: Read file contents and browse repository directories with `get_file_content` and `browse_repository`
- **💬 Comment Management**: Extract and filter PR comments with `get_comments` tool
- **🔍 Project Discovery**: List all accessible Bitbucket projects with `list_projects`
- **📁 Repository Browsing**: Explore repositories across projects with `list_repositories`
- **🔧 Flexible Project Support**: Make the default project optional - specify per command or use `BITBUCKET_DEFAULT_PROJECT`
- **📖 Enhanced Documentation**: Improved README with usage examples and better configuration guidance
## Requirements
- Node.js >= 16
## Installation
### Installing via Smithery
To install Bitbucket Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@garc33/bitbucket-server-mcp-server):
```bash
npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude
```
### Manual Installation
```bash
npm install
```
## Build
```bash
npm run build
```
## Features
The server provides the following tools for comprehensive Bitbucket Server integration:
### `list_projects`
**Discover and explore Bitbucket projects**: Lists all accessible projects with their details. Essential for project discovery and finding the correct project keys to use in other operations.
**Use cases:**
- Find available projects when you don't know the exact project key
- Explore project structure and permissions
- Discover new projects you have access to
Parameters:
- `limit`: Number of projects to return (default: 25, max: 1000)
- `start`: Start index for pagination (default: 0)
### `list_repositories`
**Browse and discover repositories**: Explore repositories within specific projects or across all accessible projects. Returns comprehensive repository information including clone URLs and metadata.
**Use cases:**
- Find repository slugs for other operations
- Explore codebase structure across projects
- Discover repositories you have access to
- Browse a specific project's repositories
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `limit`: Number of repositories to return (default: 25, max: 1000)
- `start`: Start index for pagination (default: 0)
### `create_pull_request`
**Propose code changes for review**: Creates a new pull request to submit code changes, request reviews, or merge feature branches. Automatically handles branch references and reviewer assignments.
**Use cases:**
- Submit feature development for review
- Propose bug fixes
- Request code integration from feature branches
- Collaborate on code changes
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `title` (required): Clear, descriptive PR title
- `description`: Detailed description with context (supports Markdown)
- `sourceBranch` (required): Source branch containing changes
- `targetBranch` (required): Target branch for merging
- `reviewers`: Array of reviewer usernames
### `get_pull_request`
**Comprehensive PR information**: Retrieves detailed pull request information including status, reviewers, commits, and all metadata. Essential for understanding PR state before taking actions.
**Use cases:**
- Check PR approval status
- Review PR details and progress
- Understand changes before merging
- Monitor PR status
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `prId` (required): Pull request ID
### `merge_pull_request`
**Integrate approved changes**: Merges an approved pull request into the target branch. Supports different merge strategies based on your workflow preferences.
**Use cases:**
- Complete the code review process
- Integrate approved features
- Apply bug fixes to main branches
- Release code changes
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `prId` (required): Pull request ID
- `message`: Custom merge commit message
- `strategy`: Merge strategy:
- `merge-commit` (default): Creates merge commit preserving history
- `squash`: Combines all commits into one
- `fast-forward`: Moves branch pointer without merge commit
### `decline_pull_request`
**Reject unsuitable changes**: Declines a pull request that should not be merged, providing feedback to the author.
**Use cases:**
- Reject changes that don't meet standards
- Close PRs that conflict with project direction
- Request significant rework
- Prevent unwanted code integration
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `prId` (required): Pull request ID
- `message`: Reason for declining (helpful for author feedback)
### `add_comment`
**Participate in code review**: Adds comments to pull requests for review feedback, discussions, and collaboration. Supports threaded conversations.
**Use cases:**
- Provide code review feedback
- Ask questions about specific changes
- Suggest improvements
- Participate in technical discussions
- Document review decisions
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `prId` (required): Pull request ID
- `text` (required): Comment content (supports Markdown)
- `parentId`: Parent comment ID for threaded replies
### `get_diff`
**Analyze code changes**: Retrieves the code differences showing exactly what was added, removed, or modified in the pull request. Supports per-file truncation to manage large diffs effectively.
**Use cases:**
- Review specific code changes
- Understand scope of modifications
- Analyze impact before merging
- Inspect implementation details
- Code quality assessment
- Handle large files without overwhelming output
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `prId` (required): Pull request ID
- `contextLines`: Context lines around changes (default: 10)
- `maxLinesPerFile`: Maximum lines to show per file (optional, uses BITBUCKET_DIFF_MAX_LINES_PER_FILE env var if not specified, set to 0 for no limit)
**Large File Handling:**
When a file exceeds the `maxLinesPerFile` limit, it shows:
- File headers and metadata (always preserved)
- First 60% of allowed lines from the beginning
- Truncation message with file statistics
- Last 40% of allowed lines from the end
- Clear indication of how to see the complete diff
### `get_reviews`
**Track review progress**: Fetches review history, approval status, and reviewer feedback to understand the review state.
**Use cases:**
- Check if PR is ready for merging
- See who has reviewed the changes
- Understand review feedback
- Monitor approval requirements
- Track review progress
### `get_activities`
**Retrieve pull request activities**: Gets the complete activity timeline for a pull request including comments, reviews, commits, and other events.
**Use cases:**
- Read comment discussions and feedback
- Review the complete PR timeline
- Track commits added/removed from PR
- See approval and review history
- Understand the full PR lifecycle
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `prId` (required): Pull request ID
### `get_comments`
**Extract PR comments only**: Filters pull request activities to return only the comments, making it easier to focus on discussion content without reviews or other activities.
**Use cases:**
- Read PR discussion threads
- Extract feedback and questions
- Focus on comment content without noise
- Analyze conversation flow
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `prId` (required): Pull request ID
### `search`
**Advanced code and file search**: Search across repositories using the Bitbucket search API with support for project/repository filtering and query optimization. Searches both file contents and filenames. **Note**: Search only works on the default branch of repositories.
**Use cases:**
- Find specific code patterns across projects
- Locate files by name or content
- Search within specific projects or repositories
- Filter by file extensions
Parameters:
- `query` (required): Search query string
- `project`: Bitbucket project key to limit search scope
- `repository`: Repository slug for repository-specific search
- `type`: Query optimization - "file" (wraps query in quotes for exact filename matching) or "code" (default search behavior)
- `limit`: Number of results to return (default: 25, max: 100)
- `start`: Start index for pagination (default: 0)
**Query syntax examples:**
- `"README.md"` - Find exact filename
- `config ext:yml` - Find config in YAML files
- `function project:MYPROJECT` - Search for "function" in specific project
- `bug fix repo:PROJ/my-repo` - Search in specific repository
### `get_file_content`
**Read file contents with pagination**: Retrieve the content of specific files from repositories with support for large files through pagination.
**Use cases:**
- Read source code files
- View configuration files
- Extract documentation content
- Inspect specific file versions
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `filePath` (required): Path to the file in the repository
- `branch`: Branch or commit hash (optional, defaults to main/master)
- `limit`: Maximum lines per request (default: 100, max: 1000)
- `start`: Starting line number for pagination (default: 0)
### `browse_repository`
**Explore repository structure**: Browse files and directories in repositories to understand project organization and locate specific files.
**Use cases:**
- Explore repository structure
- Navigate directory trees
- Find files and folders
- Understand project organization
Parameters:
- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (required): Repository slug
- `path`: Directory path to browse (optional, defaults to root)
- `branch`: Branch or commit hash (optional, defaults to main/master)
- `limit`: Maximum items to return (default: 50)
## Usage Examples
### Listing Projects and Repositories
```bash
# List all accessible projects
list_projects
# List repositories in the default project (if BITBUCKET_DEFAULT_PROJECT is set)
list_repositories
# List repositories in a specific project
list_repositories --project "MYPROJECT"
# List projects with pagination
list_projects --limit 10 --start 0
```
### Search and File Operations
```bash
# Search for README files across all projects
search --query "README" --type "file" --limit 10
# Search for specific code patterns in a project
search --query "function getUserData" --type "code" --project "MYPROJECT"
# Search with file extension filter
search --query "config ext:yml" --project "MYPROJECT"
# Browse repository structure
browse_repository --project "MYPROJECT" --repository "my-repo"
# Browse specific directory
browse_repository --project "MYPROJECT" --repository "my-repo" --path "src/components"
# Read file contents
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "package.json" --limit 20
# Read specific lines from a large file
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "docs/CHANGELOG.md" --start 100 --limit 50
```
### Working with Pull Requests
```bash
# Create a pull request (using default project)
create_pull_request --repository "my-repo" --title "Feature: New functionality" --sourceBranch "feature/new-feature" --targetBranch "main"
# Create a pull request with specific project
create_pull_request --project "MYPROJECT" --repository "my-repo" --title "Bugfix: Critical issue" --sourceBranch "bugfix/critical" --targetBranch "develop" --description "Fixes critical issue #123"
# Get pull request details
get_pull_request --repository "my-repo" --prId 123
# Get only comments from a PR (no reviews/commits)
get_comments --project "MYPROJECT" --repository "my-repo" --prId 123
# Get full PR activity timeline
get_activities --repository "my-repo" --prId 123
# Merge a pull request with squash strategy
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash" --message "Feature: New functionality (#123)"
```
## Dependencies
- `@modelcontextprotocol/sdk` - SDK for MCP protocol implementation
- `axios` - HTTP client for API requests
- `winston` - Logging framework
## Configuration
The server requires configuration in the VSCode MCP settings file. Here's a sample configuration:
```json
{
"mcpServers": {
"bitbucket": {
"command": "node",
"args": ["/path/to/bitbucket-server/build/index.js"],
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
// Authentication (choose one):
// Option 1: Personal Access Token
"BITBUCKET_TOKEN": "your-access-token",
// Option 2: Username/Password
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_PASSWORD": "your-password",
// Optional: Default project
"BITBUCKET_DEFAULT_PROJECT": "your-default-project"
}
}
}
}
```
### Environment Variables
- `BITBUCKET_URL` (required): Base URL of your Bitbucket Server instance
- Authentication (one of the following is required):
- `BITBUCKET_TOKEN`: Personal access token
- `BITBUCKET_USERNAME` and `BITBUCKET_PASSWORD`: Basic authentication credentials
- `BITBUCKET_DEFAULT_PROJECT` (optional): Default project key to use when not specified in tool calls
- `BITBUCKET_DIFF_MAX_LINES_PER_FILE` (optional): Default maximum lines to show per file in diffs. Set to prevent large files from overwhelming output. Can be overridden by the `maxLinesPerFile` parameter in `get_diff` calls.
- `BITBUCKET_READ_ONLY` (optional): Set to `true` to enable read-only mode
**Note**: With the new optional project support, you can now:
- Set `BITBUCKET_DEFAULT_PROJECT` to work with a specific project by default
- Use `list_projects` to discover available projects
- Use `list_repositories` to browse repositories across projects
- Override the default project by specifying the `project` parameter in any tool call
### Read-Only Mode
The server supports a read-only mode for deployments where you want to prevent any modifications to your Bitbucket repositories. When enabled, only safe, non-modifying operations are available.
**To enable read-only mode**: Set the environment variable `BITBUCKET_READ_ONLY=true`
**Available tools in read-only mode:**
- `list_projects` - Browse and list projects
- `list_repositories` - Browse and list repositories
- `get_pull_request` - View pull request details
- `get_diff` - View code changes and diffs
- `get_reviews` - View review history and status
- `get_activities` - View pull request timeline
- `get_comments` - View pull request comments
- `search` - Search code and files across repositories
- `get_file_content` - Read file contents
- `browse_repository` - Browse repository structure
**Disabled tools in read-only mode:**
- `create_pull_request` - Creating new pull requests
- `merge_pull_request` - Merging pull requests
- `decline_pull_request` - Declining pull requests
- `add_comment` - Adding comments to pull requests
**Behavior:**
- When `BITBUCKET_READ_ONLY` is not set or set to any value other than `true`, all tools function normally (backward compatible)
- When `BITBUCKET_READ_ONLY=true`, write operations are filtered out and will return an error if called
- This is perfect for production deployments, CI/CD integration, or any scenario where you need safe, read-only Bitbucket access
## Logging
The server logs all operations to `bitbucket.log` using Winston for debugging and monitoring purposes.
```
--------------------------------------------------------------------------------
/jest.config.js:
--------------------------------------------------------------------------------
```javascript
export default {
preset: 'ts-jest',
testEnvironment: 'node',
extensionsToTreatAsEsm: ['.ts'],
moduleNameMapper: {
'^(\\.{1,2}/.*)\\.js$': '$1',
},
transform: {
'^.+\\.tsx?$': [
'ts-jest',
{
useESM: true,
},
],
},
};
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2020",
"module": "ES2020",
"moduleResolution": "node",
"esModuleInterop": true,
"strict": true,
"outDir": "build",
"rootDir": "src",
"declaration": true,
"sourceMap": true,
"types": ["node", "jest"]
},
"include": ["src/**/*"],
"exclude": ["node_modules", "build"]
}
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
# Copy source files
COPY src /app/src
COPY package.json package-lock.json tsconfig.json /app/
# Install dependencies and build the project
RUN npm install && npm run build
# Production image
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/build /app/build
COPY --from=builder /app/package.json /app/package-lock.json /app/
# Install only production dependencies
RUN npm ci --omit=dev
# Environment variables (replace with your actual values)
ENV BITBUCKET_URL=https://your-bitbucket-server.com
ENV BITBUCKET_TOKEN=your-access-token
ENTRYPOINT ["node", "build/index.js"]
```
--------------------------------------------------------------------------------
/.github/workflows/build.yml:
--------------------------------------------------------------------------------
```yaml
name: Build and Test
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18.x]
steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run ESLint
run: npm run lint
- name: Run tests
run: echo 'npm test'
- name: Build
run: npm run build
- name: Upload build artifacts
uses: actions/upload-artifact@v4
with:
name: build-files
path: build/
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
startCommand:
type: stdio
configSchema:
# JSON Schema defining the configuration options for the MCP.
type: object
required:
- bitbucketUrl
properties:
bitbucketUrl:
type: string
description: Base URL of your Bitbucket Server instance.
bitbucketToken:
type: string
description: Personal access token.
bitbucketUsername:
type: string
description: Username for basic authentication.
bitbucketPassword:
type: string
description: Password for basic authentication.
commandFunction:
# A function that produces the CLI command to start the MCP on stdio.
|-
(config) => ({
command: 'node',
args: ['build/index.js'],
env: {
BITBUCKET_URL: config.bitbucketUrl,
BITBUCKET_TOKEN: config.bitbucketToken,
BITBUCKET_USERNAME: config.bitbucketUsername,
BITBUCKET_PASSWORD: config.bitbucketPassword
}
})
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "bitbucket-server",
"version": "1.0.0",
"description": "MCP Server for Bitbucket Server PR management",
"type": "module",
"main": "build/index.js",
"types": "build/index.d.ts",
"bin": {
"bitbucket-server-mcp": "./build/index.js"
},
"scripts": {
"build": "tsc && node -e \"if (process.platform !== 'win32') require('child_process').execSync('chmod +x build/index.js')\"",
"postinstall": "node -e \"const fs=require('fs'); if (process.platform !== 'win32' && fs.existsSync('build/index.js')) require('child_process').execSync('chmod +x build/index.js')\"",
"start": "node build/index.js",
"dev": "tsc -w",
"dev:server": "npm run build && npx @modelcontextprotocol/inspector -e DEBUG=true node build/index.js",
"test": "jest",
"lint": "eslint src/**/*.ts",
"format": "prettier --write 'src/**/*.ts'",
"update:check": "npx npm-check-updates",
"update:deps": "npx npm-check-updates -u && npm install --legacy-peer-deps",
"inspector": "npx @modelcontextprotocol/inspector build/index.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.1.1",
"axios": "^1.6.5",
"winston": "^3.11.0"
},
"devDependencies": {
"@types/jest": "^29.5.11",
"@types/node": "^22.10.7",
"@typescript-eslint/eslint-plugin": "^6.19.0",
"@typescript-eslint/parser": "^6.19.0",
"eslint": "^8.56.0",
"jest": "^29.7.0",
"ts-jest": "^29.1.1",
"typescript": "^5.3.3",
"prettier": "^3.0.0",
"npm-check-updates": "^16.0.0"
},
"engines": {
"node": ">=18"
}
}
```
--------------------------------------------------------------------------------
/src/__tests__/index.test.ts:
--------------------------------------------------------------------------------
```typescript
// Mock dependencies
jest.mock('@modelcontextprotocol/sdk/server/index.js');
jest.mock('axios');
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
import axios, { AxiosInstance } from 'axios';
// MCP SDK Types
type ToolResponse = {
content: Array<{
type: string;
text: string;
}>;
};
type ToolRequest = {
method: 'call_tool';
tool: string;
arguments: unknown;
};
type RequestExtra = {
signal: AbortSignal;
};
// Mock Server class
const MockServer = Server as jest.MockedClass<typeof Server>;
// Import code to test after mocks
import '../index';
describe('BitbucketServer', () => {
// Mock variables
let mockAxios: jest.Mocked<typeof axios>;
let originalEnv: NodeJS.ProcessEnv;
let mockServer: jest.Mocked<Server>;
let mockAbortController: AbortController;
beforeEach(() => {
// Save environment variables
originalEnv = process.env;
process.env = {
BITBUCKET_URL: 'https://bitbucket.example.com',
BITBUCKET_TOKEN: 'test-token',
BITBUCKET_DEFAULT_PROJECT: 'DEFAULT'
};
// Reset mocks
jest.clearAllMocks();
// Configure axios mock
mockAxios = axios as jest.Mocked<typeof axios>;
mockAxios.create.mockReturnValue({} as AxiosInstance);
// Configure Server mock
mockServer = {
setRequestHandler: jest.fn(),
connect: jest.fn(),
close: jest.fn(),
onerror: jest.fn()
} as unknown as jest.Mocked<Server>;
MockServer.mockImplementation(() => mockServer);
// Configure AbortController for signal
mockAbortController = new AbortController();
});
afterEach(() => {
// Restore environment variables
process.env = originalEnv;
});
describe('Configuration', () => {
test('should throw if BITBUCKET_URL is not defined', () => {
// Arrange
process.env.BITBUCKET_URL = '';
// Act & Assert
expect(() => {
require('../index');
}).toThrow('BITBUCKET_URL is required');
});
test('should throw if neither token nor credentials are provided', () => {
// Arrange
process.env = {
BITBUCKET_URL: 'https://bitbucket.example.com'
};
// Act & Assert
expect(() => {
require('../index');
}).toThrow('Either BITBUCKET_TOKEN or BITBUCKET_USERNAME/PASSWORD is required');
});
test('should configure axios with token and read default project', () => {
// Arrange
const expectedConfig = {
baseURL: 'https://bitbucket.example.com/rest/api/1.0',
headers: { Authorization: 'Bearer test-token' },
};
// Act
require('../index');
// Assert
expect(mockAxios.create).toHaveBeenCalledWith(expect.objectContaining(expectedConfig));
});
});
describe('Pull Request Operations', () => {
const mockHandleRequest = async <T>(toolName: string, args: T): Promise<ToolResponse> => {
const handlers = mockServer.setRequestHandler.mock.calls;
const callHandler = handlers.find(([schema]) =>
(schema as { method?: string }).method === 'call_tool'
)?.[1];
if (!callHandler) throw new Error('Handler not found');
const request: ToolRequest = {
method: 'call_tool',
tool: toolName,
arguments: args
};
const extra: RequestExtra = {
signal: mockAbortController.signal
};
return callHandler(request, extra) as Promise<ToolResponse>;
};
test('should create a pull request with explicit project', async () => {
// Arrange
const input = {
project: 'TEST',
repository: 'repo',
title: 'Test PR',
description: 'Test description',
sourceBranch: 'feature',
targetBranch: 'main',
reviewers: ['user1']
};
mockAxios.post.mockResolvedValueOnce({ data: { id: 1 } });
// Act
const result = await mockHandleRequest('create_pull_request', input);
// Assert
expect(mockAxios.post).toHaveBeenCalledWith(
'/projects/TEST/repos/repo/pull-requests',
expect.objectContaining({
title: input.title,
description: input.description,
fromRef: expect.any(Object),
toRef: expect.any(Object),
reviewers: [{ user: { name: 'user1' } }]
})
);
expect(JSON.parse(result.content[0].text)).toEqual({ id: 1 });
});
test('should create a pull request using default project', async () => {
// Arrange
const input = {
repository: 'repo',
title: 'Test PR',
description: 'Test description',
sourceBranch: 'feature',
targetBranch: 'main',
reviewers: ['user1']
};
mockAxios.post.mockResolvedValueOnce({ data: { id: 1 } });
// Act
const result = await mockHandleRequest('create_pull_request', input);
// Assert
expect(mockAxios.post).toHaveBeenCalledWith(
'/projects/DEFAULT/repos/repo/pull-requests',
expect.objectContaining({
title: input.title,
description: input.description,
fromRef: expect.any(Object),
toRef: expect.any(Object),
reviewers: [{ user: { name: 'user1' } }]
})
);
expect(JSON.parse(result.content[0].text)).toEqual({ id: 1 });
});
test('should throw error when no project is provided or defaulted', async () => {
// Arrange
delete process.env.BITBUCKET_DEFAULT_PROJECT;
const input = {
repository: 'repo',
title: 'Test PR',
sourceBranch: 'feature',
targetBranch: 'main'
};
// Act & Assert
await expect(mockHandleRequest('create_pull_request', input))
.rejects.toThrow(new McpError(
ErrorCode.InvalidParams,
'Project must be provided either as a parameter or through BITBUCKET_DEFAULT_PROJECT environment variable'
));
});
test('should merge a pull request', async () => {
// Arrange
const input = {
project: 'TEST',
repository: 'repo',
prId: 1,
message: 'Merged PR',
strategy: 'squash' as const
};
mockAxios.post.mockResolvedValueOnce({ data: { state: 'MERGED' } });
// Act
const result = await mockHandleRequest('merge_pull_request', input);
// Assert
expect(mockAxios.post).toHaveBeenCalledWith(
'/projects/TEST/repos/repo/pull-requests/1/merge',
expect.objectContaining({
version: -1,
message: input.message,
strategy: input.strategy
})
);
expect(JSON.parse(result.content[0].text)).toEqual({ state: 'MERGED' });
});
test('should handle API errors', async () => {
// Arrange
const input = {
project: 'TEST',
repository: 'repo',
prId: 1
};
const error = {
isAxiosError: true,
response: {
data: {
message: 'Not found'
}
}
};
mockAxios.get.mockRejectedValueOnce(error);
// Act & Assert
await expect(mockHandleRequest('get_pull_request', input))
.rejects.toThrow(new McpError(
ErrorCode.InternalError,
'Bitbucket API error: Not found'
));
});
});
describe('Reviews and Comments', () => {
const mockHandleRequest = async <T>(toolName: string, args: T): Promise<ToolResponse> => {
const handlers = mockServer.setRequestHandler.mock.calls;
const callHandler = handlers.find(([schema]) =>
(schema as { method?: string }).method === 'call_tool'
)?.[1];
if (!callHandler) throw new Error('Handler not found');
const request: ToolRequest = {
method: 'call_tool',
tool: toolName,
arguments: args
};
const extra: RequestExtra = {
signal: mockAbortController.signal
};
return callHandler(request, extra) as Promise<ToolResponse>;
};
test('should filter review activities', async () => {
// Arrange
const input = {
project: 'TEST',
repository: 'repo',
prId: 1
};
const activities = {
values: [
{ action: 'APPROVED', user: { name: 'user1' } },
{ action: 'COMMENTED', user: { name: 'user2' } },
{ action: 'REVIEWED', user: { name: 'user3' } }
]
};
mockAxios.get.mockResolvedValueOnce({ data: activities });
// Act
const result = await mockHandleRequest('get_reviews', input);
// Assert
const reviews = JSON.parse(result.content[0].text);
expect(reviews).toHaveLength(2);
expect(reviews.every((r: { action: string }) =>
['APPROVED', 'REVIEWED'].includes(r.action)
)).toBe(true);
});
test('should add comment with parent', async () => {
// Arrange
const input = {
project: 'TEST',
repository: 'repo',
prId: 1,
text: 'Test comment',
parentId: 123
};
mockAxios.post.mockResolvedValueOnce({ data: { id: 456 } });
// Act
const result = await mockHandleRequest('add_comment', input);
// Assert
expect(mockAxios.post).toHaveBeenCalledWith(
'/projects/TEST/repos/repo/pull-requests/1/comments',
{
text: input.text,
parent: { id: input.parentId }
}
);
expect(JSON.parse(result.content[0].text)).toEqual({ id: 456 });
});
});
});
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ErrorCode,
ListToolsRequestSchema,
McpError,
} from '@modelcontextprotocol/sdk/types.js';
import axios, { AxiosInstance } from 'axios';
import winston from 'winston';
// Configuration du logger
const logger = winston.createLogger({
level: 'info',
format: winston.format.json(),
transports: [
new winston.transports.File({ filename: 'bitbucket.log' })
]
});
interface BitbucketActivity {
action: string;
[key: string]: unknown;
}
interface BitbucketConfig {
baseUrl: string;
token?: string;
username?: string;
password?: string;
defaultProject?: string;
maxLinesPerFile?: number;
readOnly?: boolean;
}
interface RepositoryParams {
project?: string;
repository?: string;
}
interface PullRequestParams extends RepositoryParams {
prId?: number;
}
interface MergeOptions {
message?: string;
strategy?: 'merge-commit' | 'squash' | 'fast-forward';
}
interface CommentOptions {
text: string;
parentId?: number;
}
interface InlineCommentOptions extends CommentOptions {
filePath: string;
line: number;
lineType: 'ADDED' | 'REMOVED';
}
interface PullRequestInput extends RepositoryParams {
title: string;
description: string;
sourceBranch: string;
targetBranch: string;
reviewers?: string[];
}
interface ListOptions {
limit?: number;
start?: number;
}
interface ListRepositoriesOptions extends ListOptions {
project?: string;
}
interface SearchOptions extends ListOptions {
project?: string;
repository?: string;
query: string;
type?: 'code' | 'file';
}
interface FileContentOptions extends ListOptions {
project?: string;
repository?: string;
filePath: string;
branch?: string;
}
class BitbucketServer {
private readonly server: Server;
private readonly api: AxiosInstance;
private readonly config: BitbucketConfig;
constructor() {
this.server = new Server(
{
name: 'bitbucket-server-mcp-server',
version: '1.0.0',
},
{
capabilities: {
tools: {},
},
}
);
// Configuration initiale à partir des variables d'environnement
this.config = {
baseUrl: process.env.BITBUCKET_URL ?? '',
token: process.env.BITBUCKET_TOKEN,
username: process.env.BITBUCKET_USERNAME,
password: process.env.BITBUCKET_PASSWORD,
defaultProject: process.env.BITBUCKET_DEFAULT_PROJECT,
maxLinesPerFile: process.env.BITBUCKET_DIFF_MAX_LINES_PER_FILE
? parseInt(process.env.BITBUCKET_DIFF_MAX_LINES_PER_FILE, 10)
: undefined,
readOnly: process.env.BITBUCKET_READ_ONLY === 'true'
};
if (!this.config.baseUrl) {
throw new Error('BITBUCKET_URL is required');
}
if (!this.config.token && !(this.config.username && this.config.password)) {
throw new Error('Either BITBUCKET_TOKEN or BITBUCKET_USERNAME/PASSWORD is required');
}
// Configuration de l'instance Axios
this.api = axios.create({
baseURL: `${this.config.baseUrl}/rest/api/1.0`,
headers: this.config.token
? { Authorization: `Bearer ${this.config.token}` }
: {},
auth: this.config.username && this.config.password
? { username: this.config.username, password: this.config.password }
: undefined,
});
this.setupToolHandlers();
this.server.onerror = (error) => logger.error('[MCP Error]', error);
}
private isPullRequestInput(args: unknown): args is PullRequestInput {
const input = args as Partial<PullRequestInput>;
return typeof args === 'object' &&
args !== null &&
typeof input.project === 'string' &&
typeof input.repository === 'string' &&
typeof input.title === 'string' &&
typeof input.sourceBranch === 'string' &&
typeof input.targetBranch === 'string' &&
(input.description === undefined || typeof input.description === 'string') &&
(input.reviewers === undefined || Array.isArray(input.reviewers));
}
private setupToolHandlers() {
const readOnlyTools = ['list_projects', 'list_repositories', 'get_pull_request', 'get_diff', 'get_reviews', 'get_activities', 'get_comments', 'search', 'get_file_content', 'browse_repository'];
this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'list_projects',
description: 'Discover and list all Bitbucket projects you have access to. Use this first to explore available projects, find project keys, or when you need to work with a specific project but don\'t know its exact key. Returns project keys, names, descriptions and visibility settings.',
inputSchema: {
type: 'object',
properties: {
limit: { type: 'number', description: 'Number of projects to return (default: 25, max: 1000)' },
start: { type: 'number', description: 'Start index for pagination (default: 0)' }
}
}
},
{
name: 'list_repositories',
description: 'Browse and discover repositories within a specific project or across all accessible projects. Use this to find repository slugs, explore codebases, or understand the repository structure. Returns repository names, slugs, clone URLs, and project associations.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key to list repositories from. If omitted, uses BITBUCKET_DEFAULT_PROJECT or lists all accessible repositories across projects.' },
limit: { type: 'number', description: 'Number of repositories to return (default: 25, max: 1000)' },
start: { type: 'number', description: 'Start index for pagination (default: 0)' }
}
}
},
{
name: 'create_pull_request',
description: 'Create a new pull request to propose code changes, request reviews, or merge feature branches. Use this when you want to submit code for review, merge a feature branch, or contribute changes to a repository. Automatically sets up branch references and can assign reviewers.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable. Use list_projects to discover available projects.' },
repository: { type: 'string', description: 'Repository slug where the pull request will be created. Use list_repositories to find available repositories.' },
title: { type: 'string', description: 'Clear, descriptive title for the pull request that summarizes the changes.' },
description: { type: 'string', description: 'Detailed description of changes, context, and any relevant information for reviewers. Supports Markdown formatting.' },
sourceBranch: { type: 'string', description: 'Source branch name containing the changes to be merged (e.g., "feature/new-login", "bugfix/security-patch").' },
targetBranch: { type: 'string', description: 'Target branch where changes will be merged (e.g., "main", "develop", "release/v1.2").' },
reviewers: {
type: 'array',
items: { type: 'string' },
description: 'Array of Bitbucket usernames to assign as reviewers for this pull request.'
}
},
required: ['repository', 'title', 'sourceBranch', 'targetBranch']
}
},
{
name: 'get_pull_request',
description: 'Retrieve comprehensive details about a specific pull request including status, reviewers, commits, and metadata. Use this to check PR status, review progress, understand changes, or gather information before performing actions like merging or commenting.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Unique pull request ID number (e.g., 123, 456).' }
},
required: ['repository', 'prId']
}
},
{
name: 'merge_pull_request',
description: 'Merge an approved pull request into the target branch. Use this when a PR has been reviewed, approved, and is ready to be integrated. Choose the appropriate merge strategy based on your team\'s workflow and repository history preferences.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Pull request ID to merge.' },
message: { type: 'string', description: 'Custom merge commit message. If not provided, uses default merge message format.' },
strategy: {
type: 'string',
enum: ['merge-commit', 'squash', 'fast-forward'],
description: 'Merge strategy: "merge-commit" creates a merge commit preserving branch history, "squash" combines all commits into one, "fast-forward" moves the branch pointer without creating a merge commit.'
}
},
required: ['repository', 'prId']
}
},
{
name: 'decline_pull_request',
description: 'Decline or reject a pull request that should not be merged. Use this when changes are not acceptable, conflicts with project direction, or when the PR needs significant rework. This closes the PR without merging.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Pull request ID to decline.' },
message: { type: 'string', description: 'Reason for declining the pull request. Helps the author understand why it was rejected.' }
},
required: ['repository', 'prId']
}
},
{
name: 'add_comment',
description: 'Add a comment to a pull request for code review, feedback, questions, or discussion. Use this to provide review feedback, ask questions about specific changes, suggest improvements, or participate in code review discussions. Supports threaded conversations.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Pull request ID to comment on.' },
text: { type: 'string', description: 'Comment text content. Supports Markdown formatting for code blocks, links, and emphasis.' },
parentId: { type: 'number', description: 'ID of parent comment to reply to. Omit for top-level comments.' }
},
required: ['repository', 'prId', 'text']
}
},
{
name: 'add_comment_inline',
description: 'Add an inline comment (to specific lines) to the diff of a pull request for code review, feedback, questions, or discussion. Use this to provide review feedback, ask questions about specific changes, suggest improvements, or participate in code review discussions. Supports threaded conversations.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Pull request ID to comment on.' },
text: { type: 'string', description: 'Comment text content. Supports Markdown formatting for code blocks, links, and emphasis.' },
parentId: { type: 'number', description: 'ID of parent comment to reply to. Omit for top-level comments.' },
filePath: { type: 'string', description: 'Path to the file in the repository where the comment should be added (e.g., "src/main.py", "README.md").' },
line: { type: 'number', description: 'Line number in the file to attach the comment to (1-based).' },
lineType: { type: 'string', enum: ['ADDED', 'REMOVED'], description: 'Type of change the comment is associated with: ADDED for additions, REMOVED for deletions.' }
},
required: ['repository', 'prId', 'text', 'filePath', 'line', 'lineType']
}
},
{
name: 'get_diff',
description: 'Retrieve the code differences (diff) for a pull request showing what lines were added, removed, or modified. Use this to understand the scope of changes, review specific code modifications, or analyze the impact of proposed changes before merging.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Pull request ID to get diff for.' },
contextLines: { type: 'number', description: 'Number of context lines to show around changes (default: 10). Higher values provide more surrounding code context.' },
maxLinesPerFile: { type: 'number', description: 'Maximum number of lines to show per file (default: uses BITBUCKET_DIFF_MAX_LINES_PER_FILE env var). Set to 0 for no limit. Prevents large files from overwhelming the diff output.' }
},
required: ['repository', 'prId']
}
},
{
name: 'get_reviews',
description: 'Fetch the review history and approval status of a pull request. Use this to check who has reviewed the PR, see approval status, understand review feedback, or determine if the PR is ready for merging based on review requirements.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Pull request ID to get reviews for.' }
},
required: ['repository', 'prId']
}
},
{
name: 'get_activities',
description: 'Retrieve all activities for a pull request including comments, reviews, commits, and other timeline events. Use this to get the complete activity history and timeline of the pull request.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Pull request ID to get activities for.' }
},
required: ['repository', 'prId']
}
},
{
name: 'get_comments',
description: 'Retrieve only the comments from a pull request. Use this when you specifically want to read the discussion and feedback comments without other activities like reviews or commits.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the pull request.' },
prId: { type: 'number', description: 'Pull request ID to get comments for.' }
},
required: ['repository', 'prId']
}
},
{
name: 'search',
description: 'Search for code or files across repositories. Use this to find specific code patterns, file names, or content within projects and repositories. Searches both file contents and filenames. Supports filtering by project, repository, and query optimization.',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string', description: 'Search query string to look for in code or file names.' },
project: { type: 'string', description: 'Bitbucket project key to limit search scope. If omitted, searches across accessible projects.' },
repository: { type: 'string', description: 'Repository slug to limit search to a specific repository within the project.' },
type: {
type: 'string',
enum: ['code', 'file'],
description: 'Query optimization: "file" wraps query in quotes for exact filename matching, "code" uses default search behavior. Both search file contents and filenames.'
},
limit: { type: 'number', description: 'Number of results to return (default: 25, max: 100)' },
start: { type: 'number', description: 'Start index for pagination (default: 0)' }
},
required: ['query']
}
},
{
name: 'get_file_content',
description: 'Retrieve the content of a specific file from a Bitbucket repository with pagination support. Use this to read source code, configuration files, documentation, or any text-based files. For large files, use start parameter to paginate through content.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug containing the file.' },
filePath: { type: 'string', description: 'Path to the file in the repository (e.g., "src/main.py", "README.md", "config/settings.json").' },
branch: { type: 'string', description: 'Branch or commit hash to read from (defaults to main/master branch if not specified).' },
limit: { type: 'number', description: 'Maximum number of lines to return per request (default: 100, max: 1000).' },
start: { type: 'number', description: 'Starting line number for pagination (0-based, default: 0).' }
},
required: ['repository', 'filePath']
}
},
{
name: 'browse_repository',
description: 'Browse and list files and directories in a Bitbucket repository. Use this to explore repository structure, find files, or navigate directories.',
inputSchema: {
type: 'object',
properties: {
project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
repository: { type: 'string', description: 'Repository slug to browse.' },
path: { type: 'string', description: 'Directory path to browse (empty or "/" for root directory).' },
branch: { type: 'string', description: 'Branch or commit hash to browse (defaults to main/master branch if not specified).' },
limit: { type: 'number', description: 'Maximum number of items to return (default: 50).' }
},
required: ['repository']
}
}
].filter(tool => !this.config.readOnly || readOnlyTools.includes(tool.name))
}));
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
logger.info(`Called tool: ${request.params.name}`, { arguments: request.params.arguments });
const args = request.params.arguments ?? {};
// Check if tool is allowed in read-only mode
if (this.config.readOnly && !readOnlyTools.includes(request.params.name)) {
throw new McpError(
ErrorCode.MethodNotFound,
`Tool ${request.params.name} is not available in read-only mode`
);
}
// Helper function to get project with fallback to default
const getProject = (providedProject?: string): string => {
const project = providedProject || this.config.defaultProject;
if (!project) {
throw new McpError(
ErrorCode.InvalidParams,
'Project must be provided either as a parameter or through BITBUCKET_DEFAULT_PROJECT environment variable'
);
}
return project;
};
switch (request.params.name) {
case 'list_projects': {
return await this.listProjects({
limit: args.limit as number,
start: args.start as number
});
}
case 'list_repositories': {
return await this.listRepositories({
project: args.project as string,
limit: args.limit as number,
start: args.start as number
});
}
case 'create_pull_request': {
if (!this.isPullRequestInput(args)) {
throw new McpError(
ErrorCode.InvalidParams,
'Invalid pull request input parameters'
);
}
// Ensure project is set
const createArgs = { ...args, project: getProject(args.project) };
return await this.createPullRequest(createArgs);
}
case 'get_pull_request': {
const getPrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.getPullRequest(getPrParams);
}
case 'merge_pull_request': {
const mergePrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.mergePullRequest(mergePrParams, {
message: args.message as string,
strategy: args.strategy as 'merge-commit' | 'squash' | 'fast-forward'
});
}
case 'decline_pull_request': {
const declinePrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.declinePullRequest(declinePrParams, args.message as string);
}
case 'add_comment': {
const commentPrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.addComment(commentPrParams, {
text: args.text as string,
parentId: args.parentId as number
});
}
case 'add_comment_inline': {
const commentPrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.addCommentInline(commentPrParams, {
text: args.text as string,
parentId: args.parentId as number,
filePath: args.filePath as string,
line: args.line as number,
lineType: args.lineType as 'ADDED' | 'REMOVED'
});
}
case 'get_diff': {
const diffPrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.getDiff(
diffPrParams,
args.contextLines as number,
args.maxLinesPerFile as number
);
}
case 'get_reviews': {
const reviewsPrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.getReviews(reviewsPrParams);
}
case 'get_activities': {
const activitiesPrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.getActivities(activitiesPrParams);
}
case 'get_comments': {
const commentsPrParams: PullRequestParams = {
project: getProject(args.project as string),
repository: args.repository as string,
prId: args.prId as number
};
return await this.getComments(commentsPrParams);
}
case 'search': {
return await this.search({
query: args.query as string,
project: args.project as string,
repository: args.repository as string,
type: args.type as 'code' | 'file',
limit: args.limit as number,
start: args.start as number
});
}
case 'get_file_content': {
return await this.getFileContent({
project: getProject(args.project as string),
repository: args.repository as string,
filePath: args.filePath as string,
branch: args.branch as string,
limit: args.limit as number,
start: args.start as number
});
}
case 'browse_repository': {
return await this.browseRepository({
project: getProject(args.project as string),
repository: args.repository as string,
path: args.path as string,
branch: args.branch as string,
limit: args.limit as number
});
}
default:
throw new McpError(
ErrorCode.MethodNotFound,
`Unknown tool: ${request.params.name}`
);
}
} catch (error) {
logger.error('Tool execution error', { error });
if (axios.isAxiosError(error)) {
throw new McpError(
ErrorCode.InternalError,
`Bitbucket API error: ${error.response?.data.message ?? error.message}`
);
}
throw error;
}
});
}
private async listProjects(options: ListOptions = {}) {
const { limit = 25, start = 0 } = options;
const response = await this.api.get('/projects', {
params: { limit, start }
});
const projects = response.data.values || [];
const summary = {
total: response.data.size || projects.length,
showing: projects.length,
projects: projects.map((project: { key: string; name: string; description?: string; public: boolean; type: string }) => ({
key: project.key,
name: project.name,
description: project.description,
public: project.public,
type: project.type
}))
};
return {
content: [{
type: 'text',
text: JSON.stringify(summary, null, 2)
}]
};
}
private async listRepositories(options: ListRepositoriesOptions = {}) {
const { project, limit = 25, start = 0 } = options;
let endpoint: string;
const params = { limit, start };
if (project || this.config.defaultProject) {
// List repositories for a specific project
const projectKey = project || this.config.defaultProject;
endpoint = `/projects/${projectKey}/repos`;
} else {
// List all accessible repositories
endpoint = '/repos';
}
const response = await this.api.get(endpoint, { params });
const repositories = response.data.values || [];
const summary = {
project: project || this.config.defaultProject || 'all',
total: response.data.size || repositories.length,
showing: repositories.length,
repositories: repositories.map((repo: {
slug: string;
name: string;
description?: string;
project?: { key: string };
public: boolean;
links?: { clone?: { name: string; href: string }[] };
state: string
}) => ({
slug: repo.slug,
name: repo.name,
description: repo.description,
project: repo.project?.key,
public: repo.public,
cloneUrl: repo.links?.clone?.find((link: { name: string; href: string }) => link.name === 'http')?.href,
state: repo.state
}))
};
return {
content: [{
type: 'text',
text: JSON.stringify(summary, null, 2)
}]
};
}
private async createPullRequest(input: PullRequestInput) {
const response = await this.api.post(
`/projects/${input.project}/repos/${input.repository}/pull-requests`,
{
title: input.title,
description: input.description,
fromRef: {
id: `refs/heads/${input.sourceBranch}`,
repository: {
slug: input.repository,
project: { key: input.project }
}
},
toRef: {
id: `refs/heads/${input.targetBranch}`,
repository: {
slug: input.repository,
project: { key: input.project }
}
},
reviewers: input.reviewers?.map(username => ({ user: { name: username } }))
}
);
return {
content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }]
};
}
private async getPullRequest(params: PullRequestParams) {
const { project, repository, prId } = params;
if (!project || !repository || !prId) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and prId are required'
);
}
const response = await this.api.get(
`/projects/${project}/repos/${repository}/pull-requests/${prId}`
);
return {
content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }]
};
}
private async mergePullRequest(params: PullRequestParams, options: MergeOptions = {}) {
const { project, repository, prId } = params;
if (!project || !repository || !prId) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and prId are required'
);
}
const { message, strategy = 'merge-commit' } = options;
const response = await this.api.post(
`/projects/${project}/repos/${repository}/pull-requests/${prId}/merge`,
{
version: -1,
message,
strategy
}
);
return {
content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }]
};
}
private async declinePullRequest(params: PullRequestParams, message?: string) {
const { project, repository, prId } = params;
if (!project || !repository || !prId) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and prId are required'
);
}
const response = await this.api.post(
`/projects/${project}/repos/${repository}/pull-requests/${prId}/decline`,
{
version: -1,
message
}
);
return {
content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }]
};
}
private async addComment(params: PullRequestParams, options: CommentOptions) {
const { project, repository, prId } = params;
if (!project || !repository || !prId) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and prId are required'
);
}
const { text, parentId } = options;
const response = await this.api.post(
`/projects/${project}/repos/${repository}/pull-requests/${prId}/comments`,
{
text,
parent: parentId ? { id: parentId } : undefined
}
);
return {
content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }]
};
}
private async addCommentInline(params: PullRequestParams, options: InlineCommentOptions) {
const { project, repository, prId } = params;
if (!project || !repository || !prId || !options.filePath || !options.line || !options.lineType) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, prId, filePath, line, and lineType are required'
);
}
const { text, parentId } = options;
const response = await this.api.post(
`/projects/${project}/repos/${repository}/pull-requests/${prId}/comments`,
{
text,
parent: parentId ? { id: parentId } : undefined,
anchor: {
path: options.filePath,
lineType: options.lineType,
line: options.line,
diffType: 'EFFECTIVE',
fileType: 'TO',}
}
);
logger.error(response);
return {
content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }]
};
}
private truncateDiff(diffContent: string, maxLinesPerFile: number): string {
if (!maxLinesPerFile || maxLinesPerFile <= 0) {
return diffContent;
}
const lines = diffContent.split('\n');
const result: string[] = [];
let currentFileLines: string[] = [];
let currentFileName = '';
let inFileContent = false;
for (const line of lines) {
// Detect file headers (diff --git, index, +++, ---)
if (line.startsWith('diff --git ')) {
// Process previous file if any
if (currentFileLines.length > 0) {
result.push(...this.truncateFileSection(currentFileLines, currentFileName, maxLinesPerFile));
currentFileLines = [];
}
// Extract filename for context
const match = line.match(/diff --git a\/(.+) b\/(.+)/);
currentFileName = match ? match[2] : 'unknown';
inFileContent = false;
// Always include file headers
result.push(line);
} else if (line.startsWith('index ') || line.startsWith('+++') || line.startsWith('---')) {
// Always include file metadata
result.push(line);
} else if (line.startsWith('@@')) {
// Hunk header - marks start of actual file content
inFileContent = true;
currentFileLines.push(line);
} else if (inFileContent) {
// Collect file content lines for potential truncation
currentFileLines.push(line);
} else {
// Other lines (empty lines between files, etc.)
result.push(line);
}
}
// Process the last file
if (currentFileLines.length > 0) {
result.push(...this.truncateFileSection(currentFileLines, currentFileName, maxLinesPerFile));
}
return result.join('\n');
}
private truncateFileSection(fileLines: string[], fileName: string, maxLines: number): string[] {
if (fileLines.length <= maxLines) {
return fileLines;
}
// Count actual content lines (excluding hunk headers)
const contentLines = fileLines.filter(line => !line.startsWith('@@'));
const hunkHeaders = fileLines.filter(line => line.startsWith('@@'));
if (contentLines.length <= maxLines) {
return fileLines; // No need to truncate if content is within limit
}
// Smart truncation: show beginning and end
const showAtStart = Math.floor(maxLines * 0.6); // 60% at start
const showAtEnd = Math.floor(maxLines * 0.4); // 40% at end
const truncatedCount = contentLines.length - showAtStart - showAtEnd;
const result: string[] = [];
// Add hunk headers first
result.push(...hunkHeaders);
// Add first portion
result.push(...contentLines.slice(0, showAtStart));
// Add truncation message
result.push('');
result.push(`[*** FILE TRUNCATED: ${truncatedCount} lines hidden from ${fileName} ***]`);
result.push(`[*** File had ${contentLines.length} total lines, showing first ${showAtStart} and last ${showAtEnd} ***]`);
result.push(`[*** Use maxLinesPerFile=0 to see complete diff ***]`);
result.push('');
// Add last portion
result.push(...contentLines.slice(-showAtEnd));
return result;
}
private async getDiff(params: PullRequestParams, contextLines: number = 10, maxLinesPerFile?: number) {
const { project, repository, prId } = params;
if (!project || !repository || !prId) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and prId are required'
);
}
const response = await this.api.get(
`/projects/${project}/repos/${repository}/pull-requests/${prId}/diff`,
{
params: { contextLines },
headers: { Accept: 'text/plain' }
}
);
// Determine max lines per file: parameter > env var > no limit
const effectiveMaxLines = maxLinesPerFile !== undefined
? maxLinesPerFile
: this.config.maxLinesPerFile;
const diffContent = effectiveMaxLines
? this.truncateDiff(response.data, effectiveMaxLines)
: response.data;
return {
content: [{ type: 'text', text: diffContent }]
};
}
private async getReviews(params: PullRequestParams) {
const { project, repository, prId } = params;
if (!project || !repository || !prId) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and prId are required'
);
}
const response = await this.api.get(
`/projects/${project}/repos/${repository}/pull-requests/${prId}/activities`
);
const reviews = response.data.values.filter(
(activity: BitbucketActivity) => activity.action === 'APPROVED' || activity.action === 'REVIEWED'
);
return {
content: [{ type: 'text', text: JSON.stringify(reviews, null, 2) }]
};
}
private async getActivities(params: PullRequestParams) {
const { project, repository, prId } = params;
if (!project || !repository || !prId) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and prId are required'
);
}
const response = await this.api.get(
`/projects/${project}/repos/${repository}/pull-requests/${prId}/activities`
);
return {
content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }]
};
}
private async getComments(params: PullRequestParams) {
const { project, repository, prId } = params;
if (!project || !repository || !prId) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and prId are required'
);
}
const response = await this.api.get(
`/projects/${project}/repos/${repository}/pull-requests/${prId}/activities`
);
const comments = response.data.values.filter(
(activity: BitbucketActivity) => activity.action === 'COMMENTED'
);
return {
content: [{ type: 'text', text: JSON.stringify(comments, null, 2) }]
};
}
private async search(options: SearchOptions) {
const { query, project, repository, type, limit = 25, start = 0 } = options;
if (!query) {
throw new McpError(
ErrorCode.InvalidParams,
'Query parameter is required'
);
}
// Build the search query with filters
let searchQuery = query;
// Add project filter if specified
if (project) {
searchQuery = `${searchQuery} project:${project}`;
}
// Add repository filter if specified (requires project)
if (repository && project) {
searchQuery = `${searchQuery} repo:${project}/${repository}`;
}
// Add file extension filter if type is specified
if (type === 'file') {
// For file searches, wrap query in quotes for exact filename matching
if (!query.includes('ext:') && !query.startsWith('"')) {
searchQuery = `"${query}"`;
if (project) searchQuery += ` project:${project}`;
if (repository && project) searchQuery += ` repo:${project}/${repository}`;
}
} else if (type === 'code' && !query.includes('ext:')) {
// For code searches, add common extension filters if not specified
// This can be enhanced based on user needs
}
const requestBody = {
query: searchQuery,
entities: {
code: {
start,
limit: Math.min(limit, 100)
}
}
};
try {
// Use full URL for search API since it uses different base path
const searchUrl = `${this.config.baseUrl}/rest/search/latest/search`;
const response = await axios.post(searchUrl, requestBody, {
headers: this.config.token
? {
Authorization: `Bearer ${this.config.token}`,
'Content-Type': 'application/json'
}
: { 'Content-Type': 'application/json' },
auth: this.config.username && this.config.password
? { username: this.config.username, password: this.config.password }
: undefined,
});
const codeResults = response.data.code || {};
const searchResults = {
query: searchQuery,
originalQuery: query,
project: project || 'global',
repository: repository || 'all',
type: type || 'code',
scope: response.data.scope || {},
total: codeResults.count || 0,
showing: codeResults.values?.length || 0,
isLastPage: codeResults.isLastPage || true,
nextStart: codeResults.nextStart || null,
results: codeResults.values?.map((result: any) => ({
repository: result.repository,
file: result.file,
hitCount: result.hitCount || 0,
pathMatches: result.pathMatches || [],
hitContexts: result.hitContexts || []
})) || []
};
return {
content: [{ type: 'text', text: JSON.stringify(searchResults, null, 2) }]
};
} catch (error) {
if (axios.isAxiosError(error)) {
if (error.response?.status === 404) {
throw new McpError(
ErrorCode.InternalError,
'Search API endpoint not available on this Bitbucket instance'
);
}
// Handle specific search API errors
const errorData = error.response?.data;
if (errorData?.errors && errorData.errors.length > 0) {
const firstError = errorData.errors[0];
throw new McpError(
ErrorCode.InvalidParams,
`Search error: ${firstError.message || 'Invalid search query'}`
);
}
}
throw error;
}
}
private async getFileContent(options: FileContentOptions) {
const { project, repository, filePath, branch, limit = 100, start = 0 } = options;
if (!project || !repository || !filePath) {
throw new McpError(
ErrorCode.InvalidParams,
'Project, repository, and filePath are required'
);
}
const params: Record<string, string | number> = {
limit: Math.min(limit, 1000),
start
};
if (branch) {
params.at = branch;
}
const response = await this.api.get(
`/projects/${project}/repos/${repository}/browse/${filePath}`,
{ params }
);
const fileContent = {
project,
repository,
filePath,
branch: branch || 'default',
isLastPage: response.data.isLastPage,
size: response.data.size,
showing: response.data.lines?.length || 0,
startLine: start,
lines: response.data.lines?.map((line: { text: string }) => line.text) || []
};
return {
content: [{ type: 'text', text: JSON.stringify(fileContent, null, 2) }]
};
}
private async browseRepository(options: { project: string; repository: string; path?: string; branch?: string; limit?: number }) {
const { project, repository, path = '', branch, limit = 50 } = options;
if (!project || !repository) {
throw new McpError(
ErrorCode.InvalidParams,
'Project and repository are required'
);
}
const params: Record<string, string | number> = {
limit
};
if (branch) {
params.at = branch;
}
const browsePath = path ? `/${path}` : '';
const response = await this.api.get(
`/projects/${project}/repos/${repository}/browse${browsePath}`,
{ params }
);
const children = response.data.children || {};
const browseResults = {
project,
repository,
path: path || 'root',
branch: branch || response.data.revision || 'default',
isLastPage: children.isLastPage || false,
size: children.size || 0,
showing: children.values?.length || 0,
items: children.values?.map((item: {
path: { name: string; toString: string };
type: string;
size?: number
}) => ({
name: item.path.name,
path: item.path.toString,
type: item.type,
size: item.size
})) || []
};
return {
content: [{ type: 'text', text: JSON.stringify(browseResults, null, 2) }]
};
}
async run() {
const transport = new StdioServerTransport();
await this.server.connect(transport);
logger.info('Bitbucket MCP server running on stdio');
}
}
const server = new BitbucketServer();
server.run().catch((error) => {
logger.error('Server error', error);
process.exit(1);
});
```