名称： bitbucket-automation
描述： 通过 Rube MCP (Composio) 自动化管理 Bitbucket 仓库、拉取请求、分支、问题和工作空间。务必先搜索工具以获取最新模式。
requires:
mcp: [rube]

通过 Rube MCP 实现 Bitbucket 自动化

通过 Composio 的 Bitbucket 工具包，自动化执行 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：工作空间标识符或 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

常见陷阱：
- pull_request_id 在 CREATE_PULL_REQUEST_COMMENT 中是字符串，但在 GET_PULL_REQUEST 中是整数
- 内联评论至少需要 inline.path；from/to 是可选的行号
- parent_comment_id 用于创建线程化回复；省略则表示顶级评论
- 内联评论中的行号引用的是差异内容，而不是源文件

通用模式

ID 解析

在执行操作前，始终将人类可读的名称解析为 ID：
- 工作空间：调用 BITBUCKET_LIST_WORKSPACES 获取工作空间标识符
- 仓库：调用 BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE 并使用 q 筛选器查找仓库标识符
- 分支：在创建 PR 前调用 BITBUCKET_LIST_BRANCHES 验证分支是否存在
- 成员：调用 BITBUCKET_LIST_WORKSPACE_MEMBERS 获取用于分配审阅者的 UUID

分页

Bitbucket 使用基于页面的分页（非基于游标）：
- 使用 page（从 1 开始）和 pagelen（每页项目数）参数
- 默认页面大小通常为 10；请显式设置 pagelen（PR 最大 50，其他最大 100）
- 检查响应中的 next URL 或总数以确定是否存在更多页面
- 始终遍历所有页面以获取完整结果

BBQL 筛选

Bitbucket 查询语言在列表端点可用：
- 字符串值必须使用双引号：name~"pattern"
- 运算符：=（精确）、~（包含）、!=（不等于）、>、>=、<、<=
- 使用 AND / OR 组合：name~"api" AND is_private=true

已知陷阱

ID 格式

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

参数特性

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

速率限制

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

破坏性操作

• BITBUCKET_DELETE_REPOSITORY 是不可逆的，且不会删除分叉仓库
• BITBUCKET_DELETE_ISSUE 是永久性的，无法恢复
• 在执行删除操作前，务必与用户确认

快速参考