circleci-automation

通过 Rube MCP 自动化 CircleCI

通过 Rube MCP 使用 Composio 的 CircleCI 工具包自动化 CircleCI CI/CD 操作。

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

前提条件

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

设置

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

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 使用工具包 circleci 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接不是 ACTIVE，请访问返回的授权链接，完成 CircleCI 身份验证
4. 运行任何工作流前，确认连接状态显示为 ACTIVE

核心工作流

1. 触发流水线

适用场景：用户希望启动新的 CI/CD 流水线运行

工具调用顺序：

1. CIRCLECI_TRIGGER_PIPELINE - 在项目上触发新流水线 [必需]
2. CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID - 监控生成的工作流 [可选]

关键参数：

• project_slug：项目标识符，格式为 gh/org/repo 或 bb/org/repo
• branch：运行流水线所用的 Git 分支
• tag：运行流水线所用的 Git 标签（与 branch 互斥）
• parameters：流水线参数键值对

注意事项：

• project_slug 的格式为 {vcs}/{org}/{repo}（例如 gh/myorg/myrepo）
• branch 和 tag 互斥；同时提供两者会导致错误
• 流水线参数必须与 .circleci/config.yml 中定义的参数一致
• 触发操作会返回流水线 ID；工作流会异步启动

2. 监控流水线和工作流

适用场景：用户希望查看流水线或工作流的状态

工具调用顺序：

1. CIRCLECI_LIST_PIPELINES_FOR_PROJECT - 列出项目的近期流水线 [必需]
2. CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID - 列出流水线中的工作流 [必需]
3. CIRCLECI_GET_PIPELINE_CONFIG - 查看使用的流水线配置 [可选]

关键参数：

• project_slug：项目标识符，格式为 {vcs}/{org}/{repo}
• pipeline_id：特定流水线的 UUID
• branch：按分支名称筛选流水线
• page_token：用于获取下一页结果的分页游标

注意事项：

• 流水线 ID 是 UUID，而非数字 ID
• 工作流继承流水线 ID；单个流水线可以包含多个工作流
• 工作流状态包括：success、running、not_run、failed、error、failing、on_hold、canceled、unauthorized
• 响应中会返回用于分页的 page_token；请持续获取，直到该字段不再出现

3. 检查任务详情

适用场景：用户希望深入查看特定任务的执行详情

工具调用顺序：

1. CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID - 查找包含该任务的工作流 [前置条件]
2. CIRCLECI_GET_JOB_DETAILS - 获取任务详细信息 [必需]

关键参数：

• project_slug：项目标识符
• job_number：数字任务编号（非 UUID）

注意事项：

• 任务编号是整数，而非 UUID（与流水线和工作流 ID 不同）
• 任务详情包括执行器类型、并行度、开始和停止时间以及状态
• 任务状态：success、running、not_run、failed、retried、timedout、infrastructure_fail、canceled

4. 获取构建产物

使用时机：用户想下载或列出某个任务生成的产物

工具调用顺序：

1. CIRCLECI_GET_JOB_DETAILS - 确认任务已成功完成 [前置条件]
2. CIRCLECI_GET_JOB_ARTIFACTS - 列出该任务的所有产物 [必需]

关键参数：

• project_slug：项目标识符
• job_number：任务编号（数字）

注意事项：

• 任务完成后才能获取产物
• 每个产物都有用于下载的 path 和 url
• 下载产物时，URL 可能需要身份验证标头
• 大型产物可能受到下载大小限制

5. 查看测试结果

使用时机：用户想检查特定任务的测试结果

工具调用顺序：

1. CIRCLECI_GET_JOB_DETAILS - 确认任务运行了测试 [前置条件]
2. CIRCLECI_GET_TEST_METADATA - 获取测试结果和元数据 [必需]

关键参数：

• project_slug：项目标识符
• job_number：任务编号（数字）

注意事项：

• 任务必须上传测试结果（JUnit XML 格式），才能获取测试元数据
• 如果未上传测试结果，响应将为空
• 测试元数据包含 classname、name、result、message 和 run_time 字段
• 失败的测试会在 message 字段中包含失败消息

常见模式

项目标识符格式

Format: {vcs_type}/{org_name}/{repo_name}
- GitHub:    gh/myorg/myrepo
- Bitbucket: bb/myorg/myrepo

Pipeline -> Workflow -> Job 层级结构

1. Call CIRCLECI_LIST_PIPELINES_FOR_PROJECT to get pipeline IDs
2. Call CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID with pipeline_id
3. Extract job numbers from workflow details
4. Call CIRCLECI_GET_JOB_DETAILS with job_number

分页

• 检查响应中是否包含 next_page_token 字段
• 在下一个请求中将令牌作为 page_token 传入
• 持续请求，直到 next_page_token 不存在或为 null

已知注意事项

ID 格式：

• Pipeline ID：UUID（例如，5034460f-c7c4-4c43-9457-de07e2029e7b）
• Workflow ID：UUID
• Job 编号：整数（例如，123）
• 不要混淆不同端点中的 UUID 和整数

项目标识符：

• 必须包含 VCS 前缀：GitHub 使用 gh/，Bitbucket 使用 bb/
• 组织名称和仓库名称区分大小写
• 标识符格式错误会导致 404 错误

速率限制：

• CircleCI API 对各端点设有速率限制
• 收到 429 响应时采用指数退避
• 避免过于频繁地轮询；使用合理的间隔（5-10 秒）

快速参考

任务	工具标识	关键参数
触发 Pipeline	CIRCLECI_TRIGGER_PIPELINE	project_slug, branch, parameters
列出 Pipeline	CIRCLECI_LIST_PIPELINES_FOR_PROJECT	project_slug, branch
列出 Workflow	CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID	pipeline_id
获取 Pipeline 配置	CIRCLECI_GET_PIPELINE_CONFIG	pipeline_id
获取任务详情	CIRCLECI_GET_JOB_DETAILS	project_slug, job_number
获取任务产物	CIRCLECI_GET_JOB_ARTIFACTS	project_slug, job_number
获取测试元数据	CIRCLECI_GET_TEST_METADATA	project_slug, job_number

---

由 Composio 提供支持