buildkite-mcp-server

buildkite-mcp-server

Model Context Protocol (MCP) 服务，可向 AI 工具和编辑器提供 Buildkite 数据（流水线、构建、作业、测试）。

完整文档请参阅 buildkite.com/docs/apis/mcp-server。

---

使用有限权限重试构建

retries 工具集支持调查失败并重试作业，无需更广泛的构建写入权限。它包含 list_builds、get_build、wait_for_build、list_jobs、get_job、search_logs、tail_logs、read_logs、retry_job 和 retry_failed_jobs。它需要 read_builds、read_build_logs 和 retry_builds 作用域，而不需要 write_builds。

buildkite-mcp-server stdio --enabled-toolsets retries

retry_failed_jobs 仅重试基础设施故障；使用其 dry_run 选项可查看拟执行的重试，而不实际执行。retry_job 用于重试特定作业。两者都是会修改数据的工具，在 --read-only 模式下不可用。该工具集不提供创建、重建、取消或解除阻塞操作。现有重试工具仍可通过 builds 使用；选择 builds 或 all 时，其他修改操作仍需要 write_builds。

Buildkite API 必须为令牌所有者启用 RetryBuildsScope 功能，才能接受 retry_builds；现有的 write_builds 令牌仍然有效。托管 MCP OAuth 服务采用包含该功能的版本后，可通过 /mcp/x/retries 选择此工具集。通过请求标头选择工具集不会更改现有令牌的 OAuth 作用域。

对于库的使用者，WithDisabledToolsets 和 HTTP 工厂的已禁用工具集会排除这些工具集的所有成员，即使它们也属于其他重叠的工具集。例如，禁用 logs 也会从 retries 中移除日志工具；禁用 retries 则会从其他组中移除其检查和重试工具。

---

配置 GitHub Actions 流水线

create_pipeline 和 update_pipeline 接受 GitHub provider_settings 和 branch_configuration。创建时省略提供方键可使用 API 默认值； 更新时省略则保持不变。显式设置的 false 会保留。将 filter_condition 或 pull_request_branch_filter_configuration 设为 null 可清除它们；空字符串会作为空字符串发送。更新时将 branch_configuration: null 可清除现有分支筛选器。创建时，省略、设为 null 或为空的分支筛选器会使用 API 的 null 默认值。完整的 get_pipeline 和 list_pipelines 响应会保留受支持的 GitHub 设置。go-buildkite 响应字符串无法区分 null 和空值，因此不要根据读取结果重建部分更新。

请遵循手动设置 GitHub Actions。 将针对整个分支的 skip_queued_branch_builds 和 cancel_running_branch_builds 设为 false，避免跳过或取消同一分支上的其他工作流构建。使用 create_webhook: false：提供方设置不会创建专用的 GitHub Actions 触发器或其 webhook，而现有 webhook 工具创建的是传统仓库 webhook。服务器端功能可用性和令牌 权限仍然适用；接受设置并不能证明工作流能够执行。

创建时，提供非空的 configuration 或经批准的 pipeline_template_uuid，不可同时提供。更新时，省略 pipeline_template_uuid 可保留现有分配；提供 UUID 可在不提供 configuration 的情况下分配模板；发送 null 则可移除模板。移除模板时可以同时提供替代的 configuration； API 会强制执行配置要求和组织模板政策。完整的流水线响应会保留已分配的 UUID； 如果响应中的分配为 null 或缺失，go-buildkite 会省略此字段。

使用 get_pipeline_github_webhook_processing、 enable_pipeline_github_webhook_processing 和 disable_pipeline_github_webhook_processing，查看或更改传统 GitHub webhook 处理状态。这些操作使用 GET/PUT/DELETE github-webhooks，而非用于创建 webhook 的 POST webhook 端点。它们不会删除仓库 webhook，也不会更改专用的 GitHub Actions 触发器。响应会保留 enabled 以及可为 null 的 disabled_at 和 disabled_by 元数据；disabled_by 是用户名。三项操作都要求 Full Access、GitHub 或 GitHub Enterprise 流水线，以及组织已加入扩展 webhook 触发器计划。GET 要求 read_pipelines；启用/停用要求 write_pipelines，且在只读模式下不可用。404 可能表示这些控制功能不可用，并非流水线不存在。API 错误会直接返回，不会将失败 视为已停用状态。

这些约定通过本地合成 HTTP 测试夹具进行验证。托管环境中的可用性、权限、持久化和 工作流执行需要单独验证；本地成功并不能证明已部署环境支持这些功能。不包含专用 GitHub Actions 触发器管理。

---

比较构建

investigations 工具集中的只读 compare_builds 工具可以回答“自此构建上次在 main 上正常运行以来，发生了哪些变化？”之类的问题。请提供 org_slug、pipeline_slug 和目标 build_number。该工具会选择同一流水线、完全相同分支上，创建时间最晚且当前通过的较早构建作为基线。它不要求基线在目标构建开始时就已通过。请提供 baseline_build_number，即可改为与该流水线中的指定构建进行比较，包括失败的构建或位于其他分支的构建。

响应会说明基线和选择规则，统计所有作业的结果，并最多返回 100 条作业比较，优先显示新失败、已恢复和仍然失败的步骤。匹配依据包括步骤键、作业类型、矩阵值以及并行索引／总数。当两个作业都没有键时，只有在每个构建中该组合都唯一的情况下，才会回退到完全匹配的非空名称、类型、组键、矩阵值以及并行索引／总数。匹配的作业对会显示 match_method: "step_key" 或 "name_fallback"；回退匹配会附带一条说明其为启发式匹配的警告。没有名称且没有键的作业，以及重复身份的作业，均不会匹配。显式键不会回退到名称匹配，即使该键在两个构建之间新增、移除或更改也是如此。新增／移除表示某个作业身份只存在于一个构建中，因此，重命名没有键的作业或更改矩阵值、并行度，也可能产生新增／移除条目。重试尝试会被排除；最终尝试的状态和重试次数仍会显示。

执行时间和时间差仅涵盖最终尝试。排队时间是从 scheduled_at 到 started_at，不包括等待依赖项或人工操作的时间。这些并非构建的总耗时比较，也不代表重试的总成本。时间戳缺失或不一致时，相应的计时信息会省略。未完成的构建会明确标记为不断变化的快照。

soft_failed 的任何变化都会报告为 state_changed：包括软失败与硬失败之间的转换，即使两个作业的状态都为 failed；也包括通过与软失败作业之间的转换。由于软失败不会阻止构建，这些情况绝不会报告为 newly_failing 或 recovered。通过的基线构建中可能包含软失败作业。

默认情况下，最多 3 个新出现的阻断性失败会包含其最近 20 条日志：先显示 newly_failing 作业，再显示当前为硬失败的 state_changed 作业，例如基线中软失败的作业。每条日志内容最多为 8 KiB。设置 include_logs: false 可省略日志。日志错误不会丢弃比较结果，但 HTTP 401 身份验证错误除外；此类错误会通过服务端的重新身份验证路径传播。该工具需要 read_builds 和 read_build_logs 权限范围。可使用 get_build_failure_summary 或 tail_logs 进一步调查；共享的失败步骤并不能证明存在共同根因，也不意味着重试是安全的。

基线发现最多搜索 500 个候选项。如果找不到，响应会说明未执行比较，并要求提供明确的基线。每个构建的作业清单最多包含 1,000 个作业；超过此数量时会返回错误，而不是给出可能误导人的部分新增／移除结果。输出省略项会与完整的结果计数分开报告。

---

检查 Test Engine 工作流

tests 工具集中的只读 list_test_workflows 和 get_test_workflow 工具会公开套件配置的监控器、筛选条件、告警／恢复操作以及链接。两者都需要 read_suites 权限和套件访问权限。提供 org_slug 和 test_suite_slug（slug 或 UUID）即可列出工作流：

{"org_slug": "acme", "test_suite_slug": "backend"}

若要检查某个工作流，请使用相同的组织和套件调用 get_test_workflow，并将某项的 id 作为 workflow_id。

使用配置的标签，通过 list_tests 查找带有标记的测试；仅凭标签无法对易 flake 的程度进行排序。工作流描述的是配置，不能证明某项操作已运行或提供事件历史记录。无论调用者的 API 权限如何，这两个工具都会始终将 webhook 端点替换为 [REDACTED]。

---

库的用法

应将此模块导出的 Go API 视为不稳定 API；随着我们持续改进此项目，该 API 可能会发生破坏性变更。

---

安全

为确保 MCP 服务在安全环境中运行，我们建议在容器中运行它。

此映像基于 cgr.dev/chainguard/static 构建，并以非特权用户身份运行。

在 HTTP 模式下传递身份标头

自托管的 HTTP 部署可以将每个传入 MCP 请求中的选定标头转发给 Buildkite API：

BUILDKITE_API_TOKEN=bkua_xxx \
  buildkite-mcp-server http \
  --passthrough-http-header X-User-Identity

重复使用 --passthrough-http-header 可允许多个标头，或设置以逗号分隔的 BUILDKITE_PASSTHROUGH_HTTP_HEADERS 值。只有明确允许的标头会被转发，且只会转发到 BUILDKITE_BASE_URL 配置的源站。重定向到其他位置的请求会移除这些标头。

若要使用每个 MCP 请求各自的 Buildkite API 令牌进行身份验证，请允许 Authorization，并省略进程级令牌：

BUILDKITE_PASSTHROUGH_HTTP_HEADERS=Authorization \
  buildkite-mcp-server http

在此模式下，每个 /mcp 请求都必须包含且仅包含一个非空的 Authorization 标头。缺少凭据时会返回 HTTP 401；服务绝不会回退到共享 API 令牌。MCP 服务前面的反向代理负责对调用者进行身份验证，并设置或验证任何转发的身份标头。

stdio 模式不支持标头传递。在提供作业日志之前，服务会验证当前调用者是否有权访问该作业日志。每次日志工具请求都会执行此检查，包括日志数据已缓存的情况。

---

贡献

开发指南请参阅 DEVELOPMENT.md。

---

许可证

MIT © Buildkite

SPDX-License-Identifier: MIT