Buildkite

buildkite-mcp-server

Model Context Protocol (MCP) 伺服器，將 Buildkite 資料（管線、建置、工作、測試）提供給 AI 工具和編輯器使用。

完整文件請參閱 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，而非 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。此工具會選取同一管線和完全相同分支上，目前狀態為 passed 且建立時間早於目標建置的最新建置。它不要求基準建置在目標建置開始時就已通過。提供 baseline_build_number 可改為比較該管線中的指定建置，包括失敗的建置或位於其他分支的建置。

回應會指出基準建置和選取規則、統計所有工作的結果，並回傳最多 100 項工作比較，優先列出新近失敗、已恢復和仍然失敗的步驟。比對依據為步驟金鑰、工作類型、矩陣值和平行索引／總數。若兩個工作都沒有金鑰，則會改用完全相同且非空白的名稱，加上類型、群組金鑰、矩陣值和平行索引／總數；只有在此組合於兩個建置中都唯一時才會比對。配對結果會顯示 match_method: "step_key" 或 "name_fallback"；以備援方式比對的項目會附上警告，指出這是啟發式比對。未命名且無金鑰的工作，以及重複的識別資訊，都不會配對。明確指定的金鑰絕不會改用名稱比對，即使金鑰在兩個建置之間新增、移除或變更也一樣。新增／移除表示某個工作識別資訊只存在於其中一個建置，因此重新命名無金鑰的工作，或變更矩陣值或平行度，也可能產生新增／移除項目。重試的嘗試不會納入；仍會顯示最後一次嘗試的狀態和重試次數。

執行時間和時間差只涵蓋最後一次嘗試。排程時間是從 scheduled_at 到 started_at，不包含相依性等待或人工等待。這些不是建置的總耗時比較，也不是重試的總成本。時間戳記缺失或不一致時，會省略相應的時間資訊。未完成的建置會明確標示為持續變動的快照。

任何 soft_failed 的變更都會回報為 state_changed：軟性失敗與硬性失敗之間的轉換，即使兩個工作都處於 failed 狀態；以及 passed 與軟性失敗工作之間的轉換。這些情況絕不會回報為 newly_failing 或 recovered，因為軟性失敗不會阻擋建置。passed 的基準建置可能包含軟性失敗的工作。

預設情況下，最多三個新出現且會阻擋建置的失敗會附上最後 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 尋找已標記的測試；標籤本身不會對不穩定程度排序。工作流程描述的是設定，不代表動作確實執行或包含事件歷史記錄。無論呼叫者的 API 權限為何，這兩項工具都會將 webhook 端點替換為 [REDACTED]。

---

檢查 Test Engine span 彙總資料

唯讀的 tests 工具集包含四項 span 彙總工具，皆需要 read_suites：

• list_span_aggregate_scopes：提供 org_slug、test_suite_slug，以及可選的 period，即可依總持續時間列出檢測範圍。必須啟用 OTel 追蹤資料擷取。彙總資料的精度為小時，保留期限為一個月；要求的期間必須符合組織 API 歷史資料的可用範圍。
• list_span_aggregate_scopes_for_build：提供 org_slug 和 build_uuid，即可列出建置中可見套件的檢測範圍。需要啟用 OTel 追蹤資料擷取，並具備管線中該建置的存取權。
• list_span_aggregate_names：提供 org_slug、test_suite_slug 和 scope_name，即可取得套件的 span 名稱統計資料。支援與 list_span_aggregate_scopes 相同的 period 值和保留期限，另支援下文所述的 sort 和 limit 選項。需要啟用 OTel 追蹤資料擷取。
• list_span_aggregate_names_for_build：提供 org_slug、build_uuid（不是管線建置編號）和 scope_name，即可取得建置中可見套件的 span 名稱統計資料。未命名範圍請使用空字串。需要具備管線中該建置的存取權。可選的 sort 預設為 -total，而 limit 預設為 20（上限 100）。在將結果視為完整資料前，請先檢查 span_names_truncated。

持續時間的單位為奈秒。總計是 span 持續時間的加總，而非實際經過時間；p50 和 p95 值為近似值。span 彙總工具皆不支援分頁。兩項 span 名稱工具都接受空白的 scope_name 以指定未命名範圍，並會在還有更多名稱時回傳 span_names_truncated。

---

程式庫使用方式

此模組匯出的 Go 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