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 を省略します。configuration を指定せずにテンプレートを割り当てるには UUID を指定し、 削除するには null を送信します。削除と同時に、置き換え用の configuration を指定できます。設定要件と組織のテンプレートポリシーは API によって適用されます。パイプラインの完全なレスポンスでは割り当てられた UUID が保持されます。割り当てが null または存在しない場合、go-buildkite はこのフィールドを省略します。

get_pipeline_github_webhook_processing、 enable_pipeline_github_webhook_processing、および disable_pipeline_github_webhook_processing を使用して、従来型の GitHub Webhook 処理を確認または変更します。これらは POST の webhook 作成エンドポイントではなく、GET／PUT／DELETE の github-webhooks を使用します。 リポジトリの Webhook を削除したり、専用の GitHub Actions トリガーを変更したりすることはありません。レスポンスでは、enabled と null 許容の disabled_at および disabled_by メタデータが保持されます。disabled_by はユーザー名です。 3 つの操作すべてで 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 認証エラーを除き、ログのエラーによって比較結果が破棄されることはありません。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（スラッグまたは UUID）を指定します。

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

特定のワークフローを調べるには、同じ組織とスイートを指定し、項目の id を workflow_id として get_test_workflow を呼び出します。

設定済みのラベルを list_tests とともに使用すると、マークされたテストを見つけられます。ラベルだけでは、フレーク性の順位はわかりません。ワークフローで確認できるのは設定であり、アクションが実行された証拠やイベント履歴ではありません。呼び出し元の API 権限にかかわらず、どちらのツールでも webhook エンドポイントは常に [REDACTED] に置き換えられます。

---

ライブラリの使用

このモジュールのエクスポートされた Go API は安定しておらず、このプロジェクトの進化に伴って互換性を損なう変更が加わる可能性があります。

---

セキュリティ

MCP サーバーを安全な環境で実行するため、コンテナー内での実行を推奨します。

このイメージは cgr.dev/chainguard/static を基にビルドされており、非特権ユーザーとして実行されます。

HTTP モードでの ID ヘッダーの転送

セルフホストの 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 ヘッダーをちょうど 1 つ含める必要があります。認証情報がない場合は HTTP 401 が返され、サーバーが共有 API トークンにフォールバックすることはありません。MCP サーバーの前段にあるリバースプロキシは、呼び出し元を認証し、転送する ID ヘッダーを設定または検証する責任を負います。

ヘッダーのパススルーは stdio モードでは利用できません。ジョブログを提供する前に、サーバーは現在の呼び出し元がそのジョブログにアクセスできることを検証します。この検証は、ログデータがすでにキャッシュされている場合も含め、ログツールへのリクエストごとに実行されます。

---

貢献

開発ガイドラインについては、DEVELOPMENT.md を参照してください。

---

ライセンス

MIT © Buildkite

SPDX-License-Identifier: MIT