163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# 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
|