# Bitbucket MCP Server

MCP (Model Context Protocol) server for AI agents to interact with **Bitbucket Cloud Pull Requests**.

## Features

- ✅ List pull requests in repositories
- ✅ Get detailed PR information
- ✅ Get PR activities/events
- ✅ Get PR changes (files modified)
- ✅ Get PR comments and individual comments
- ✅ Get PR commits
- ✅ Get PR diff and patch
- ✅ Get PR participants and reviewers
- ✅ Get PR status/state
- ✅ Get PR tasks
- ✅ Flexible credential configuration (env var or .env file)
- ✅ Rate limiting protection
- ✅ Error handling and retry logic

## Installation

```bash
npm install
```

## Configuration

### Credentials Sources (Priority Order)

1. **Environment Variables** (highest priority):
   ```bash
   export BITBUCKET_MCP_EMAIL=your_email@example.com
   export BITBUCKET_MCP_TOKEN=your_token_here
   ```

2. **.env file** in project root:
   ```
   BITBUCKET_MCP_EMAIL=your_email@example.com
   BITBUCKET_MCP_TOKEN=your_token_here
   ```

3. **Interactive prompt** (development fallback)

### Getting Your Access Token

1. Go to [Bitbucket Applications](https://bitbucket.org/account/applications/)
2. Click "New application" or select existing
3. Set callback URL to `http://localhost:8080` (or any placeholder)
4. Copy the **Access token**

**Note:** Bitbucket uses Basic Authentication with your email as username and the access token as password.

## Usage

### Start the Server

```bash
npm start
# Or for development:
npm run dev
```

The server will output:
```
✅ Bitbucket MCP Server started
   Name: bitbucket-pullrequests v1.0.0
   Token source: environment variable
```

### Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `list_pull_requests` | List PRs in a repository | workspace, repository, state (optional), author (optional) |
| `get_pull_request` | Get PR details | workspace, repository, pullRequestId |
| `get_pull_request_activities` | Get PR activities/events | workspace, repository, pullRequestId, limit (optional), start (optional) |
| `get_pull_request_changes` | Get files changed in PR | workspace, repository, pullRequestId, limit (optional), start (optional) |
| `get_pull_request_comments` | Get all PR comments | workspace, repository, pullRequestId, limit (optional), start (optional) |
| `get_pull_request_comment` | Get a specific PR comment | workspace, repository, pullRequestId, commentId |
| `get_pull_request_commits` | Get commits in PR | workspace, repository, pullRequestId, limit (optional), start (optional) |
| `get_pull_request_diff` | Get PR diff | workspace, repository, pullRequestId, path (optional), context (optional) |
| `get_pull_request_patch` | Get PR patch | workspace, repository, pullRequestId |
| `get_pull_request_participants` | Get PR participants | workspace, repository, pullRequestId |
| `get_pull_request_reviewers` | Get PR reviewers | workspace, repository, pullRequestId |
| `get_pull_request_status` | Get PR status/state | workspace, repository, pullRequestId |
| `get_pull_request_tasks` | Get PR tasks | workspace, repository, pullRequestId |
| `get_pull_request_task_count` | Get PR task count | workspace, repository, pullRequestId |
| `get_full_pull_request` | Get full PR details | workspace, repository, pullRequestId |

### Example MCP Call

```json
{
  "name": "list_pull_requests",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repo",
    "state": "open"
  }
}
```

## API Reference

### list_pull_requests(workspace, repository, options?)

List pull requests in a repository.

**Options:**
- `state`: 'open' | 'closed' | 'all' (default: open)
- `author`: Filter by author username

**Returns:** Array of pull request objects with metadata.

### get_pull_request(workspace, repository, pullRequestId)

Get detailed information about a specific pull request.

**Returns:** Complete PR object including title, description, source/destination branches, reviewers, etc.

### merge_pull_request(workspace, repository, pullRequestId, options?)

Merge a pull request into the target branch.

**Options:**
- `mergeStrategy`: 'merge' | 'squash' | 'fastforward' (default: merge)
- `deleteSourceBranch`: boolean (default: false)

### create_pull_request(workspace, repository, title, description, sourceBranch, destinationBranch)

Create a new pull request.

**Returns:** Created PR object with ID and URL.

## Error Handling

The server handles the following errors:

| Error | Cause |
|-------|-------|
| `AuthenticationFailed` | Invalid or expired token |
| `RateLimited` | API rate limit exceeded (429) |
| `RepositoryNotFound` | Workspace/repo doesn't exist |
| `PRNotFound` | Pull request ID invalid |

## Development

```bash
# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build
```

## License

MIT