Metadata-Version: 2.4
Name: bitbucket-mcp-server
Version: 0.1.0
Summary: MCP server for Bitbucket Cloud API integration
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# Bitbucket Cloud MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with Bitbucket Cloud APIs for generating timeline reports on Jira issues.

## Features

This MCP server exposes the following tools to analyze Jira issue timelines through Bitbucket data:

- **Repository Management**: List repositories in a workspace
- **Pull Request Search**: Search PRs by issue keys, branch names, or custom queries  
- **Pull Request Analysis**: Get detailed PR information including commits and activity
- **Branch Operations**: List branches and search commits across branches
- **Timeline Calculation**: Comprehensive tools for computing development timelines

## Setup

### Prerequisites

- Python 3.11+
- Bitbucket Cloud account with API access
- App Password for Bitbucket authentication

### Installation

1. Clone this repository
2. Install dependencies:
```bash
uv sync
```

3. Set up environment variables:
```bash
export BITBUCKET_USERNAME="your-username"
export BITBUCKET_APP_PASSWORD="your-app-password"
```

### Creating a Bitbucket App Password

1. Go to Bitbucket Settings → App passwords
2. Create new app password with these permissions:
   - Repositories: Read
   - Pull requests: Read
   - Account: Read

## Usage

### Running the Server

```bash
# Using uv
uv run bitbucket_mcp_server.py

# Or directly with Python
python bitbucket_mcp_server.py
```

### Available Tools

#### Repository Tools
- `list_repositories(workspace, pagelen?, cursor?)` - List repositories in workspace
- `list_branches(workspace, repo, pagelen?, cursor?, prefixes?)` - List branches with optional filtering
- `list_commits(workspace, repo, rev, pagelen?, cursor?)` - List commits on branch/from commit

#### Pull Request Tools  
- `search_pull_requests(workspace, repo, q, states?, pagelen?, cursor?)` - Search PRs with query
- `get_pull_request(workspace, repo, pr_id)` - Get detailed PR information
- `list_pull_request_commits(workspace, repo, pr_id, pagelen?, cursor?)` - List PR commits
- `list_pull_request_activity(workspace, repo, pr_id, pagelen?, cursor?)` - List PR comments/activity

#### Advanced Search Tools
- `workspace_search_prs_by_branch_keys(workspace, branch_keys, match_side?, states?, repos?, page_size?, max_concurrency?, time_window?)` - Search PRs by branch names across workspace
- `search_prs_by_issue_key(workspace, issue_key, repos?, states?, page_size?, max_concurrency?)` - Search PRs by Jira issue key
- `search_commits_by_message(workspace, repo, branches, contains, since?, until?, page_size?)` - Search commits by message content
- `get_pr_full(workspace, repo, pr_id)` - Get complete PR data (details + commits + activity)

### Timeline Report Generation

The server is designed to work with an LLM that follows the system prompt in `system_prompt.md`. The LLM will:

1. Search for PRs related to a Jira issue key
2. Analyze PR commits and activity 
3. Calculate four key timeline metrics:
   - First commit → PR creation
   - PR creation → first review comment
   - First review comment → PR merged
   - Develop branch → release/hotfix branch

## Example Usage with Claude/LLM

```
Generate a timeline report for Jira issue ABC-123 in workspace "mycompany"
```

The LLM will use the MCP tools to:
1. Call `search_prs_by_issue_key("mycompany", "ABC-123")`
2. For each PR, call `get_pr_full()` to get complete data
3. Calculate timeline metrics and return structured JSON report

## Configuration

### Environment Variables

- `BITBUCKET_USERNAME` - Your Bitbucket username (required)
- `BITBUCKET_APP_PASSWORD` - Your Bitbucket app password (required)

### Query Examples

The search tools support Bitbucket's query syntax:

```python
# Search PRs by title containing issue key
q = 'title~"ABC-123"'

# Search PRs by branch name
q = 'source.branch.name~"feature/ABC-123"'

# Complex query with multiple conditions
q = '(title~"ABC-123" OR description~"ABC-123") AND state="MERGED"'
```

## Development

### Running Tests

```bash
uv run pytest
```

### Code Formatting

```bash
uv run black .
uv run ruff check .
```

## API Rate Limits

The server implements:
- Automatic retry with exponential backoff
- Concurrent request limiting (configurable via `max_concurrency`)
- Pagination handling for large datasets
- Request timeout handling (30 second default)

## Error Handling

- Network errors are logged and retried automatically
- Missing repositories/PRs return empty results rather than errors
- Partial failures in batch operations continue processing remaining items
- All errors are logged with context for debugging

## Security

- Credentials are loaded from environment variables only
- HTTP basic authentication is used for Bitbucket API
- No credentials are logged or exposed in responses
- All API requests use HTTPS

## License

MIT License - see LICENSE file for details.



