内容
# bitbucket-mcp
一款Go语言的MCP（模型上下文协议）服务器，将Bitbucket Cloud拉取请求操作作为工具暴露给Claude。它允许Claude获取拉取请求的差异，读取现有的评论，并发布内联评论。
## 工作原理
服务器通过**标准输入输出使用JSON-RPC 2.0**，这是标准的MCP传输协议。Claude Desktop启动二进制文件，并通过标准输入/标准输出进行通信。
## 先决条件
- Go 1.22+
- 一个Bitbucket Cloud账户
- 一个[Bitbucket API令牌](https://id.atlassian.com/manage-profile/security/api-tokens)，具有以下作用域：
- `pullrequest`（读取）
- `pullrequest:write`（发布评论）
## 安装
```bash
git clone https://github.com/kidboy-man/bitbucket-mcp.git
cd bitbucket-mcp
make build
```
这会在项目根目录中生成一个`bitbucket-mcp`二进制文件。
打印通用MCP配置：
```bash
./bitbucket-mcp install --target generic --print-config
```
运行诊断：
```bash
./bitbucket-mcp doctor --target generic
```
参见[INSTALL.md](INSTALL.md)了解Claude Desktop、Claude Code、Cursor、Codex和通用MCP设置。
## Claude Desktop设置
将以下内容添加到`~/.claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"bitbucket": {
"command": "/绝对路径/to/bitbucket-mcp",
"env": {
"BITBUCKET_WORKSPACE": "您的工作区slug",
"BITBUCKET_EMAIL": "您的Atlassian邮箱",
"BITBUCKET_API_TOKEN": "您的API令牌"
}
}
}
}
```
编辑后重启Claude Desktop。四个工具将自动出现在每个对话中。
## 可用工具
### `get_pr`
获取拉取请求的元数据、结构化差异和提交。
```json
{ "pr_url": "https://bitbucket.org/workspace/repo/pull-requests/42" }
```
返回：
- `pr` — id、title、description、author、branches、state、commits
- `diff` — 带有hunks的文件；每行包括`diff_position`、`old_line_no`、`new_line_no`、`type`和`content`
- `note` — 提醒使用`diff_position`（而不是`new_line_no`）发布评论
### `list_pr_comments`
列出拉取请求上现有的内联评论，以避免重复。
```json
{ "pr_url": "https://bitbucket.org/workspace/repo/pull-requests/42" }
```
返回一个评论数组，包含id、body、file、line、author和created_on。
### `post_inline_comment`
发布内联评论，锚定到特定的差异位置。
```json
{
"pr_url": "https://bitbucket.org/workspace/repo/pull-requests/42",
"file": "internal/handler/user.go",
"diff_position": 4,
"body": "考虑使用`fmt.Errorf`而不是`errors.New(fmt.Sprintf(...))`"
}
```
> **重要：** `diff_position`必须是`get_pr`输出的值 — 而不是文件的绝对行号。传递错误的值将导致Bitbucket API返回422错误。
### `get_pr_review_comments_with_context`
获取拉取请求上的所有内联评论，每个评论都包含±5个周围的差异行，以便Claude可以理解正在讨论的代码并提出有针对性的修复。
```json
{ "pr_url": "https://bitbucket.org/workspace/repo/pull-requests/42" }
```
返回一个丰富的评论数组。每个条目包括：
- `id`、`author`、`created_on`、`body`、`file`、`line` — 评论本身
- `diff_context` — 多达11个周围的差异行（±5个锚定行），每个包含`diff_position`、`old_line_no`、`new_line_no`、`type`和`content`。当行不在差异中时，数组为空。
## 审查工作流程
### 发布新评论（代码审查）
1. 在Claude中粘贴拉取请求URL。
2. Claude调用`get_pr` → 接收结构化差异和元数据。
3. Claude调用`list_pr_comments` → 查看现有评论以避免重复。
4. Claude提出按严重程度分组的内联评论，每个评论都有其`new_line_no`。
5. 您批准、编辑或删除个别评论。
6. Claude对每个批准的评论调用`post_inline_comment`。
### 处理现有反馈（提出修复）
1. 在Claude中粘贴拉取请求URL。
2. Claude调用`get_pr_review_comments_with_context` → 接收每个评论及其周围的代码片段。
3. Claude分析每个评论与其代码上下文，并提出一个具体的修复方案。
4. 您审查提出的修复方案，批准或调整它们。
5. Claude将更改应用于本地源文件（或通过`post_inline_comment`发布回复评论）。
## 开发
```bash
make test # 运行测试
make build # 编译
make clean # 删除二进制文件
```
无外部依赖 — 仅限标准库。
