bitbucket-automation

通过 Rube MCP 自动化 Bitbucket

通过 Composio 的 Bitbucket 工具包自动执行 Bitbucket 操作，包括仓库管理、拉取请求工作流、分支操作、问题跟踪和工作区管理。

工具包文档：composio.dev/toolkits/bitbucket

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Bitbucket 连接，工具包为 bitbucket
• 始终先调用 RUBE_SEARCH_TOOLS 以获取当前工具架构

设置

获取 Rube MCP：在客户端配置中添加 https://rube.app/mcp 作为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 可用
2. 调用 RUBE_MANAGE_CONNECTIONS，并指定工具包 bitbucket
3. 如果连接状态不是 ACTIVE，请通过返回的授权链接完成 Bitbucket OAuth
4. 确认连接状态显示为 ACTIVE 后，再运行任何工作流

核心工作流

1. 管理拉取请求

适用场景：用户希望创建、审查或查看拉取请求

工具调用顺序：

1. BITBUCKET_LIST_WORKSPACES - 查找可访问的工作区 [前置条件]
2. BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - 查找目标仓库 [前置条件]
3. BITBUCKET_LIST_BRANCHES - 确认源分支和目标分支存在 [前置条件]
4. BITBUCKET_CREATE_PULL_REQUEST - 使用标题、源分支和可选的审查者创建新的 PR [必需]
5. BITBUCKET_LIST_PULL_REQUESTS - 按状态（OPEN、MERGED、DECLINED）筛选并列出 PR [可选]
6. BITBUCKET_GET_PULL_REQUEST - 按 ID 获取特定 PR 的完整详情 [可选]
7. BITBUCKET_GET_PULL_REQUEST_DIFF - 获取统一差异以供代码审查 [可选]
8. BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - 获取已更改文件及新增／删除的行数 [可选]

关键参数：

• workspace：工作区 slug 或 UUID（所有操作均必需）
• repo_slug：适用于 URL 的仓库名称
• source_branch：包含待合并更改的分支
• destination_branch：目标分支（若省略，则默认为仓库的主分支）
• reviewers：包含 uuid 字段的对象列表，用于指定审查者
• state：用于筛选 LIST_PULL_REQUESTS 的状态——OPEN、MERGED 或 DECLINED
• max_chars：GET_PULL_REQUEST_DIFF 的截断限制，用于处理较大的差异

注意事项：

• reviewers 需要的是包含 uuid 键的对象数组，而不是用户名：[{"uuid": "{...}"}]
• UUID 格式必须包含花括号：{123e4567-e89b-12d3-a456-426614174000}
• 若省略 destination_branch，则默认为仓库的主分支，该分支可能并非 main
• pull_request_id 在 GET／DIFF 操作中是整数，但会作为 PR 列表的一部分返回
• 较大的差异可能会占用过多上下文；调用 GET_PULL_REQUEST_DIFF 时务必设置 max_chars（例如 50000）

2. 管理仓库和工作区

适用场景：用户想要列出、创建或删除仓库，或浏览工作区

工具调用顺序：

1. BITBUCKET_LIST_WORKSPACES - 列出所有可访问的工作区【必需】
2. BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - 列出仓库，并可选择使用 BBQL 过滤【必需】
3. BITBUCKET_CREATE_REPOSITORY - 创建新仓库，并设置语言、隐私选项和项目【可选】
4. BITBUCKET_DELETE_REPOSITORY - 永久删除仓库（不可撤销）【可选】
5. BITBUCKET_LIST_WORKSPACE_MEMBERS - 列出工作区成员，以便指定审核者或检查访问权限【可选】

关键参数：

• workspace：工作区标识（通过 LIST_WORKSPACES 查找）
• repo_slug：用于创建或删除操作的 URL 友好名称
• q：BBQL 查询过滤条件（例如，name~"api"、project.key="PROJ"、is_private=true）
• role：按用户角色过滤仓库：member、contributor、admin、owner
• sort：排序字段；添加可选的 - 前缀表示降序（例如，-updated_on）
• is_private：用于设置仓库可见性的布尔值（默认为 true）
• project_key：Bitbucket 项目密钥；省略时使用工作区中最早创建的项目

注意事项：

• BITBUCKET_DELETE_REPOSITORY 不可撤销，且不会影响分支仓库
• BBQL 字符串值必须用双引号括起来：使用 name~"my-repo"，而非 name~my-repo
• repository 不是有效的 BBQL 字段；请改用 name
• 默认分页结果数为 10；如需完整列表，请显式设置 pagelen
• CREATE_REPOSITORY 默认为私有仓库；如需公开仓库，请设置 is_private: false

3. 管理问题

适用场景：用户想要创建、更新、列出仓库问题，或对其发表评论

工具调用顺序：

1. BITBUCKET_LIST_ISSUES - 列出问题，并可选择按状态、优先级、类型、负责人过滤【必需】
2. BITBUCKET_CREATE_ISSUE - 创建新问题，并填写标题、内容、优先级和类型【必需】
3. BITBUCKET_UPDATE_ISSUE - 修改问题属性（状态、优先级、负责人等）【可选】
4. BITBUCKET_CREATE_ISSUE_COMMENT - 为现有问题添加 Markdown 评论【可选】
5. BITBUCKET_DELETE_ISSUE - 永久删除问题【可选】

关键参数：

• issue_id：问题的字符串标识符
• title、content：创建时必填
• kind：bug、enhancement、proposal 或 task
• priority：trivial、minor、major、critical 或 blocker
• state：new、open、resolved、on hold、invalid、duplicate、wontfix、closed
• assignee：CREATE 使用的 Bitbucket 用户名；UPDATE 使用 assignee_account_id（UUID）
• due_on：ISO 8601 格式的日期字符串

注意事项：

• 仓库必须启用问题跟踪器（has_issues: true），否则 API 调用会失败
• CREATE_ISSUE 使用 assignee（用户名字符串），而 UPDATE_ISSUE 使用 assignee_account_id（UUID）——二者是不同字段
• DELETE_ISSUE 会永久删除问题，且无法撤销
• state 的值可能包含空格：使用 "on hold"，而非 "on_hold"
• 在 LIST_ISSUES 中按 assignee 过滤时，使用的是账户 ID，而非用户名；未指定负责人时，请使用字符串 "null"

4. 管理分支

适用场景：用户希望创建分支或查看分支结构

工具调用顺序：

1. BITBUCKET_LIST_BRANCHES - 列出分支，可选使用 BBQL 筛选和排序 [必需]
2. BITBUCKET_CREATE_BRANCH - 从指定提交哈希创建新分支 [必需]

关键参数：

• name：不带 refs/heads/ 前缀的分支名称（例如，feature/new-login）
• target_hash：要从其创建分支的完整 SHA1 提交哈希（必须存在于仓库中）
• q：BBQL 筛选条件（例如，name~"feature/"、name="main"）
• sort：按 name 或 -target.date 排序（按提交日期降序）
• pagelen：每页 1-100 条结果（默认为 10）

注意事项：

• CREATE_BRANCH 的 target_hash 必须是完整提交哈希，而非分支名称
• 分支名称中不要包含 refs/heads/ 前缀
• 分支名称必须遵循 Bitbucket 命名规范（字母数字字符、/、.、_、-）
• BBQL 字符串值需要使用双引号：name~"feature/"，而不是 name~feature/

5. 带评论审查拉取请求

适用场景：用户希望为拉取请求添加审查评论，包括代码行内评论

工具调用顺序：

1. BITBUCKET_GET_PULL_REQUEST - 获取 PR 详情并确认其存在 [前置条件]
2. BITBUCKET_GET_PULL_REQUEST_DIFF - 审查实际代码更改 [前置条件]
3. BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - 获取已更改文件列表 [可选]
4. BITBUCKET_CREATE_PULL_REQUEST_COMMENT - 发布审查评论 [必需]

关键参数：

• pull_request_id：PR 的字符串 ID
• content_raw：采用 Markdown 格式的评论文本
• content_markup：默认为 markdown；也支持 plaintext
• inline：包含 path、from、to 的对象，用于代码行内评论
• parent_comment_id：用于回复现有评论的整数 ID，可创建评论串

注意事项：

• CREATE_PULL_REQUEST_COMMENT 中的 pull_request_id 是字符串，而 GET_PULL_REQUEST 中的是整数
• 行内评论至少需要 inline.path；from/to 是可选的行号
• parent_comment_id 用于创建评论串回复；顶级评论请省略此参数
• 行内评论中的行号对应的是差异内容，而非源文件

常见模式

ID 解析

操作前始终先将人类可读的名称解析为 ID：

• 工作区：使用 BITBUCKET_LIST_WORKSPACES 获取工作区 slug
• 仓库：使用带 q 筛选条件的 BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE 查找仓库 slug
• 分支：创建 PR 前使用 BITBUCKET_LIST_BRANCHES 确认分支存在
• 成员：使用 BITBUCKET_LIST_WORKSPACE_MEMBERS 获取用于分配审阅者的 UUID

分页

Bitbucket 使用基于页码的分页（而非基于游标的分页）：

• 使用 page（从 1 开始）和 pagelen（每页条目数）参数
• 默认页大小通常为 10；请明确设置 pagelen（PR 最多为 50，其他最多为 100）
• 检查响应中的 next URL 或总数，以确定是否还有更多页面
• 始终遍历所有页面以获取完整结果

BBQL 筛选

列表端点支持 Bitbucket Query Language：

• 字符串值必须使用双引号：name~"pattern"
• 运算符：=（精确匹配）、~（包含）、!=（不等于）、>、>=、<、<=
• 使用 AND / OR 组合条件：name~"api" AND is_private=true

已知注意事项

ID 格式

• 工作区：slug 字符串（例如，my-workspace）或带大括号的 UUID（{uuid}）
• 审阅者 UUID 必须包含大括号：{123e4567-e89b-12d3-a456-426614174000}
• Issue ID 是字符串；在某些工具中，PR ID 是整数，在其他工具中则是字符串
• 提交哈希必须是完整 SHA1（40 个字符）

参数差异

• assignee 与 assignee_account_id：CREATE_ISSUE 使用用户名，UPDATE_ISSUE 使用 UUID
• Issue 的 state 值包含空格：使用 "on hold"，而不是 "on_hold"
• 省略 destination_branch 时，默认使用仓库的主分支，而不是字面上的 main
• BBQL 中的 repository 不是有效字段，请使用 name

速率限制

• Bitbucket Cloud API 有速率限制；大批量操作应加入延迟
• 分页请求会计入速率限制；尽量减少不必要的页面请求

破坏性操作

• BITBUCKET_DELETE_REPOSITORY 不可撤销，且不会删除分叉仓库
• BITBUCKET_DELETE_ISSUE 会永久删除，无法恢复
• 执行删除操作前，务必先征得用户确认

快速参考

任务	工具标识	关键参数
列出工作区	BITBUCKET_LIST_WORKSPACES	q, sort
列出仓库	BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE	workspace, q, role
创建仓库	BITBUCKET_CREATE_REPOSITORY	workspace, repo_slug, is_private
删除仓库	BITBUCKET_DELETE_REPOSITORY	workspace, repo_slug
列出分支	BITBUCKET_LIST_BRANCHES	workspace, repo_slug, q
创建分支	BITBUCKET_CREATE_BRANCH	workspace, repo_slug, name, target_hash
列出 PR	BITBUCKET_LIST_PULL_REQUESTS	workspace, repo_slug, state
创建 PR	BITBUCKET_CREATE_PULL_REQUEST	workspace, repo_slug, title, source_branch
获取 PR 详情	BITBUCKET_GET_PULL_REQUEST	workspace, repo_slug, pull_request_id
获取 PR 差异	BITBUCKET_GET_PULL_REQUEST_DIFF	workspace, repo_slug, pull_request_id, max_chars
获取 PR 差异统计	BITBUCKET_GET_PULL_REQUEST_DIFFSTAT	workspace, repo_slug, pull_request_id
评论 PR	BITBUCKET_CREATE_PULL_REQUEST_COMMENT	workspace, repo_slug, pull_request_id, content_raw
列出问题	BITBUCKET_LIST_ISSUES	workspace, repo_slug, state, priority
创建问题	BITBUCKET_CREATE_ISSUE	workspace, repo_slug, title, content
更新问题	BITBUCKET_UPDATE_ISSUE	workspace, repo_slug, issue_id
评论问题	BITBUCKET_CREATE_ISSUE_COMMENT	workspace, repo_slug, issue_id, content
删除问题	BITBUCKET_DELETE_ISSUE	workspace, repo_slug, issue_id
列出成员	BITBUCKET_LIST_WORKSPACE_MEMBERS	workspace

---

由 Composio 提供支持