Buildkite

buildkite-mcp-server

เซิร์ฟเวอร์ Model Context Protocol (MCP) ที่เปิดเผยข้อมูล Buildkite (pipelines, builds, jobs, tests) ให้เครื่องมือ AI และโปรแกรมแก้ไข

ดูเอกสารฉบับเต็มได้ที่ buildkite.com/docs/apis/mcp-server.

---

การลอง build ใหม่ด้วยสิทธิ์ที่จำกัด

ชุดเครื่องมือ retries รองรับการตรวจสอบความล้มเหลวและลอง jobs ใหม่โดยไม่ต้องมีสิทธิ์เขียน build ในวงกว้าง ซึ่งประกอบด้วย list_builds, get_build, wait_for_build, list_jobs, get_job, search_logs, tail_logs, read_logs, retry_job, และ retry_failed_jobs โดยต้องใช้ scopes read_builds, read_build_logs, และ retry_builds ไม่ใช่ write_builds.

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

retry_failed_jobs จะลองใหม่เฉพาะความล้มเหลวของโครงสร้างพื้นฐาน ใช้ตัวเลือก dry_run เพื่อตรวจสอบรายการที่จะลองใหม่โดยไม่ดำเนินการจริง ส่วน retry_job จะลอง job ที่ระบุใหม่ ทั้งสองเป็นเครื่องมือที่เปลี่ยนแปลงข้อมูลและไม่รวมอยู่ใน --read-only ชุดเครื่องมือนี้ไม่มีการดำเนินการสร้างใหม่ สร้าง build ใหม่ ยกเลิก หรือปลดบล็อก เครื่องมือลองใหม่ที่มีอยู่ยังคงใช้ได้ใน builds; การเลือก builds หรือ all ยังคงต้องใช้ write_builds สำหรับการเปลี่ยนแปลงอื่น ๆ

API ของ Buildkite ต้องเปิดใช้ฟีเจอร์ RetryBuildsScope เพื่อให้เจ้าของโทเค็นยอมรับ retry_builds; โทเค็น write_builds ที่มีอยู่ยังคงใช้ได้ Hosted MCP OAuth สามารถเลือกชุดเครื่องมือนี้ด้วย /mcp/x/retries เมื่อเซิร์ฟเวอร์ hosted นำรีลีสที่มีฟีเจอร์นี้มาใช้ การเลือกชุดเครื่องมือผ่าน request headers จะไม่เปลี่ยน OAuth scopes ของโทเค็นที่มีอยู่

สำหรับผู้ใช้ไลบรารี WithDisabledToolsets และชุดเครื่องมือที่ปิดใช้งานของ HTTP factory จะยกเว้นสมาชิกทั้งหมดของชุดเครื่องมือเหล่านั้น แม้จะอยู่ในกลุ่มที่ทับซ้อนกันก็ตาม ตัวอย่างเช่น การปิดใช้ logs จะนำเครื่องมือ log ออกจาก retries ด้วย; การปิดใช้ retries จะนำเครื่องมือตรวจสอบและลองใหม่ออกจากกลุ่มอื่น ๆ ด้วย

---

การกำหนดค่า pipelines ของ GitHub Actions

create_pipeline และ update_pipeline รองรับ provider_settings และ branch_configuration ของ GitHub หากไม่ระบุคีย์ provider ระบบจะใช้ค่าเริ่มต้นของ API เมื่อสร้าง หรือคงค่าเดิมไว้เมื่ออัปเดต ค่า false ที่ระบุไว้อย่างชัดเจนจะยังคงอยู่ ตั้งค่า filter_condition หรือ pull_request_branch_filter_configuration เป็น null เพื่อล้างค่า โดยสตริงว่างจะถูกส่งเป็นสตริงว่าง ตั้งค่า branch_configuration: null ขณะอัปเดต เพื่อล้างตัวกรอง branch ที่มีอยู่ เมื่อสร้าง หากไม่ระบุตัวกรอง branch เป็น null หรือเป็นค่าว่าง ระบบจะใช้ค่าเริ่มต้น null ของ API การตอบกลับแบบเต็มของ get_pipeline และ list_pipelines จะคงการตั้งค่า GitHub ที่รองรับไว้ สตริงการตอบกลับของ go-buildkite ไม่สามารถแยกความแตกต่างระหว่าง null กับค่าว่างได้ จึงไม่ควรสร้างการอัปเดตบางส่วนขึ้นใหม่จากข้อมูลที่อ่านกลับมา

ทำตาม การตั้งค่า GitHub Actions ด้วยตนเอง. ตั้งค่า skip_queued_branch_builds และ cancel_running_branch_builds ที่ครอบคลุมทั้ง branch เป็น false เพื่อหลีกเลี่ยงการข้ามหรือยกเลิก workflow builds อื่นใน branch เดียวกัน ใช้ create_webhook: false: การตั้งค่า provider ไม่ได้จัดเตรียม trigger เฉพาะสำหรับ GitHub Actions หรือ webhook ของ trigger นั้น และเครื่องมือ webhook ที่มีอยู่จะสร้าง webhook แบบดั้งเดิมของ repository ความพร้อมใช้งานของฟีเจอร์ฝั่งเซิร์ฟเวอร์และสิทธิ์ของโทเค็นยังคงมีผล การยอมรับการตั้งค่าไม่ได้ยืนยันว่า workflow จะทำงานได้

เมื่อสร้าง ให้ระบุ configuration ที่ไม่ใช่ค่าว่าง หรือ pipeline_template_uuid ที่ได้รับอนุมัติ แต่ห้ามระบุทั้งสองอย่าง เมื่ออัปเดต ให้เว้น pipeline_template_uuid ไว้เพื่อคงการกำหนดเดิม ระบุ UUID เพื่อกำหนด template โดยไม่ใช้ configuration หรือส่ง null เพื่อนำออก การนำออกอาจระบุ configuration ใหม่ได้ด้วย API จะบังคับใช้ข้อกำหนดการกำหนดค่าและนโยบาย template ขององค์กร การตอบกลับ pipeline แบบเต็ม จะคง UUID ที่กำหนดไว้ ส่วน go-buildkite จะละเว้นฟิลด์นี้เมื่อการกำหนดในคำตอบเป็น null หรือไม่มีอยู่

ใช้ get_pipeline_github_webhook_processing, enable_pipeline_github_webhook_processing, และ disable_pipeline_github_webhook_processing เพื่อตรวจสอบหรือเปลี่ยนการประมวลผล GitHub webhook แบบดั้งเดิม เครื่องมือเหล่านี้ใช้ GET/PUT/DELETE github-webhooks ไม่ใช่ endpoint สำหรับสร้าง POST webhook เครื่องมือเหล่านี้จะไม่ลบ repository webhooks หรือ เปลี่ยน dedicated GitHub Actions triggers การตอบกลับจะคง enabled และข้อมูลเมตา disabled_at กับ disabled_by ที่เป็น nullable ไว้; disabled_by คือชื่อผู้ใช้ ทั้งสามเครื่องมือต้องใช้ Full Access, pipeline ประเภท GitHub หรือ GitHub Enterprise และ องค์กรต้องลงทะเบียนใช้ expanded webhook triggers การเรียก GET ต้องใช้ read_pipelines; การเปิด/ปิดต้องใช้ write_pipelines และจะไม่รวมในโหมดอ่านอย่างเดียว ข้อผิดพลาด 404 อาจหมายถึง ไม่มี controls เหล่านี้ ไม่ได้หมายความว่าไม่มี pipeline ระบบจะแสดง API errors โดยไม่ถือว่าความล้มเหลว หมายถึงสถานะปิดใช้งาน

สัญญาการทำงานเหล่านี้ผ่านการทดสอบด้วย HTTP fixtures สังเคราะห์ในเครื่อง ความพร้อมใช้งานบน hosted, สิทธิ์, การคงข้อมูล และการทำงานของ workflow ต้องตรวจสอบแยกต่างหาก การทำงานสำเร็จในเครื่อง ไม่ได้ยืนยันว่าระบบที่ deploy แล้วรองรับ การจัดการ dedicated GitHub Actions trigger ไม่รวมอยู่ด้วย

---

การเปรียบเทียบ builds

เครื่องมืออ่านอย่างเดียว compare_builds ในชุดเครื่องมือ investigations ตอบคำถาม เช่น “มีอะไรเปลี่ยนไปบ้างนับจาก build นี้ทำงานได้ครั้งล่าสุดบน main?” ระบุ org_slug, pipeline_slug และ build_number เป้าหมาย ระบบจะเลือก build ก่อนหน้าที่สร้างล่าสุด ซึ่งขณะนี้ผ่านแล้ว บน pipeline เดียวกันและ branch เดียวกันแบบตรงกัน โดยไม่กำหนดว่า baseline ต้องผ่านแล้วในเวลาที่ target เริ่มทำงาน ระบุ baseline_build_number เพื่อเปรียบเทียบกับ build ที่เจาะจงใน pipeline นั้นแทน ซึ่งอาจเป็น build ที่ล้มเหลวหรืออยู่บน branch อื่นก็ได้

คำตอบจะระบุ baseline และกฎการเลือก นับผลลัพธ์จาก jobs ทั้งหมด และส่งคืนการเปรียบเทียบ jobs สูงสุด 100 รายการ โดยจัดลำดับให้ jobs ที่เพิ่งล้มเหลว กลับมาทำงานได้ และยังคงล้มเหลวอยู่มาก่อน การจับคู่ใช้ step keys, job type, ค่า matrix และ parallel index/total เมื่อทั้งสอง jobs ไม่มี keys ระบบจะใช้ชื่อที่ไม่ว่างและตรงกันทุกประการร่วมกับ type, group key, ค่า matrix และ parallel index/total เป็นทางเลือก โดยใช้เฉพาะเมื่อชุดค่าดังกล่าวไม่ซ้ำกันในแต่ละ build คู่ที่จับคู่ได้จะแสดง match_method: "step_key" หรือ "name_fallback"; การจับคู่ด้วยวิธีสำรองจะแสดงคำเตือนว่าเป็นการจับคู่แบบคาดเดา jobs ที่ไม่มีชื่อและไม่มี key รวมถึงตัวตนที่ซ้ำกันจะจับคู่ไม่ได้ keys ที่ระบุไว้อย่างชัดเจนจะไม่ใช้ชื่อเป็นทางเลือก แม้ key จะถูกเพิ่ม ลบ หรือเปลี่ยนระหว่าง builds ก็ตาม รายการที่เพิ่ม/ลบหมายถึงตัวตนของ job ปรากฏอยู่ใน build เพียงรายการเดียว ดังนั้นการเปลี่ยนชื่อ jobs ที่ไม่มี key หรือการเปลี่ยนค่า matrix หรือ parallelism ก็อาจทำให้เกิดรายการเพิ่ม/ลบได้ ระบบจะไม่นับ attempts ที่ลองใหม่ แต่จะแสดงสถานะ ของ attempt สุดท้ายและจำนวนครั้งที่ลองใหม่

เวลาทำงานและส่วนต่างจะครอบคลุมเฉพาะ attempts สุดท้าย เวลาจัดตารางคือช่วงจาก scheduled_at ถึง started_at ไม่ใช่เวลารอ dependency หรือการดำเนินการด้วยตนเอง ข้อมูลเหล่านี้ไม่ใช่การเปรียบเทียบเวลารวมของ build หรือค่าใช้จ่ายรวมจากการลองใหม่ หาก timestamp ขาดหายหรือไม่สอดคล้องกัน ระบบจะไม่แสดงเวลาที่เกี่ยวข้อง builds ที่ยังไม่เสร็จจะระบุไว้อย่างชัดเจนว่า เป็น snapshot ที่อาจเปลี่ยนแปลงได้

การเปลี่ยนแปลงใด ๆ ใน soft_failed จะรายงานเป็น state_changed: การเปลี่ยนระหว่างความล้มเหลวแบบ soft และ hard แม้ทั้งสอง jobs จะมีสถานะ failed และการเปลี่ยนระหว่าง jobs ที่ผ่านกับ jobs ที่ soft-failed ซึ่งจะไม่รายงานเป็น newly_failing หรือ recovered เพราะ soft failure ไม่ได้ขัดขวาง build build baseline ที่ผ่านแล้วอาจมี jobs ที่ soft-failed ได้

โดยค่าเริ่มต้น jobs ที่เพิ่งเกิดความล้มเหลวซึ่งขัดขวางการทำงานสูงสุดสามรายการจะแสดง log 20 รายการล่าสุด: เริ่มจาก jobs newly_failing ก่อน ตามด้วย jobs state_changed ที่กลายเป็น hard failure เช่น job ที่ soft-failed ใน baseline แต่ละรายการจำกัดเนื้อหา log ไว้ที่ 8 KiB ตั้งค่า include_logs: false เพื่อละเว้น logs ข้อผิดพลาดของ log จะไม่ทำให้การเปรียบเทียบถูกทิ้ง ยกเว้นข้อผิดพลาดการยืนยันตัวตน HTTP 401 ซึ่งจะส่งต่อผ่านเส้นทางการยืนยันตัวตนใหม่ของเซิร์ฟเวอร์ เครื่องมือนี้ต้องใช้ scopes read_builds และ read_build_logs ใช้ get_build_failure_summary หรือ tail_logs เพื่อตรวจสอบเพิ่มเติม; step ที่ล้มเหลวร่วมกัน ไม่ได้ยืนยันว่ามีสาเหตุรากเดียวกัน หรือทำให้การลองใหม่ปลอดภัย

การค้นหา baseline จะตรวจสอบ candidates ได้สูงสุด 500 รายการ หากไม่พบ ระบบจะแจ้งว่าไม่ได้ทำการเปรียบเทียบ และขอให้ระบุ baseline อย่างชัดเจน รายการ jobs จำกัดไว้ที่ 1,000 jobs ต่อ build; หากมีมากกว่านั้น ระบบจะแสดงข้อผิดพลาดแทนการแสดงผลเพิ่ม/ลบที่ไม่ครบถ้วน ระบบจะแจ้งรายการผลลัพธ์ที่ละเว้นแยกต่างหาก จากจำนวนผลลัพธ์ทั้งหมดที่ครบถ้วน

---

การตรวจสอบ workflows ของ Test Engine

เครื่องมืออ่านอย่างเดียว list_test_workflows และ get_test_workflow ในชุดเครื่องมือ tests จะแสดง monitors, filters, การดำเนินการแจ้งเตือน/กู้คืน และลิงก์ ที่กำหนดค่าไว้สำหรับ suite ทั้งสองต้องใช้ read_suites และสิทธิ์เข้าถึง suite ระบุ org_slug และ test_suite_slug (slug หรือ UUID) เพื่อแสดงรายการ workflows:

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

หากต้องการตรวจสอบรายการใดรายการหนึ่ง ให้เรียก get_test_workflow โดยใช้ organization และ suite เดียวกัน และส่ง id ของรายการนั้นเป็น workflow_id.

ใช้ labels ที่กำหนดค่าไว้ร่วมกับ list_tests เพื่อค้นหา tests ที่ทำเครื่องหมายไว้; labels เพียงอย่างเดียวไม่ได้จัดอันดับความไม่เสถียร workflows อธิบายการกำหนดค่า ไม่ใช่หลักฐานว่ามีการดำเนินการ หรือประวัติเหตุการณ์ เครื่องมือทั้งสองจะแทนที่ webhook endpoints ด้วย [REDACTED] เสมอ ไม่ว่าผู้เรียกจะมีสิทธิ์ API ใดก็ตาม

---

การตรวจสอบ span aggregates ของ Test Engine

ชุดเครื่องมืออ่านอย่างเดียว tests มีเครื่องมือ span aggregate สี่รายการที่ต้องใช้ read_suites:

• list_span_aggregate_scopes: ระบุ org_slug, test_suite_slug และ period ซึ่งเป็นตัวเลือก เพื่อแสดงรายการ instrumentation scopes โดยเรียงตามระยะเวลารวม ต้องเปิดใช้การรับข้อมูล OTel traces aggregates มีความละเอียดระดับชั่วโมงและเก็บรักษาไว้หนึ่งเดือน ช่วงเวลาที่ร้องขอต้องอยู่ภายในขอบเขตประวัติ API ขององค์กร
• list_span_aggregate_scopes_for_build: ระบุ org_slug และ build_uuid เพื่อแสดงรายการ instrumentation scopes ใน suites ที่มองเห็นได้ของ build ต้องเปิดใช้การรับข้อมูล OTel traces และต้องมีสิทธิ์เข้าถึง pipeline ของ build
• list_span_aggregate_names: ระบุ org_slug, test_suite_slug และ scope_name เพื่อดูสถิติชื่อ spans ของ suite รองรับค่า period และการเก็บรักษาแบบเดียวกับ list_span_aggregate_scopes รวมถึงตัวเลือก sort และ limit ที่อธิบายไว้ด้านล่าง ต้องเปิดใช้การรับข้อมูล OTel traces
• list_span_aggregate_names_for_build: ระบุ org_slug, build_uuid (ไม่ใช่ หมายเลข build ของ pipeline) และ scope_name เพื่อดูสถิติชื่อ spans ใน suites ที่มองเห็นได้ของ build ใช้สตริงว่างสำหรับ scope ที่ไม่มีชื่อ ต้องมีสิทธิ์เข้าถึง pipeline ของ build sort ซึ่งเป็นตัวเลือก มีค่าเริ่มต้นเป็น -total และ limit มีค่าเริ่มต้นเป็น 20 (สูงสุด 100) ตรวจสอบ span_names_truncated ก่อนถือว่าผลลัพธ์ครบถ้วน

ระยะเวลามีหน่วยเป็น nanoseconds ผลรวมคือผลรวมของระยะเวลา spans ไม่ใช่การวัดเวลาตามนาฬิกา ค่า p50 และ p95 เป็นค่าประมาณ ไม่มีเครื่องมือ span aggregate ใดรองรับการแบ่งหน้า เครื่องมือชื่อ spans ทั้งสองยอมรับ scope_name ที่เป็นค่าว่างสำหรับ scope ที่ไม่มีชื่อ และส่งคืน span_names_truncated เมื่อมีชื่อเพิ่มเติม

---

การใช้งานไลบรารี

ควรถือว่า Go API ที่ส่งออกของโมดูลนี้ยังไม่เสถียร และอาจมีการเปลี่ยนแปลงที่ทำให้ใช้งานร่วมกันไม่ได้ ขณะที่เราพัฒนาโปรเจกต์นี้ต่อไป

---

ความปลอดภัย

เพื่อให้แน่ใจว่าเซิร์ฟเวอร์ MCP ทำงานในสภาพแวดล้อมที่ปลอดภัย เราแนะนำให้เรียกใช้ใน container

อิมเมจนี้สร้างจาก cgr.dev/chainguard/static และทำงานในฐานะผู้ใช้ที่ไม่มีสิทธิ์ระดับสูง

การส่งต่อ identity headers ผ่านโหมด HTTP

การติดตั้ง HTTP แบบ self-hosted สามารถส่งต่อ headers ที่เลือกไว้จาก MCP request ขาเข้าแต่ละรายการไปยัง API ของ Buildkite ได้:

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

ระบุ --passthrough-http-header ซ้ำเพื่ออนุญาตให้ใช้ headers ได้มากกว่าหนึ่งรายการ หรือกำหนดค่า BUILDKITE_PASSTHROUGH_HTTP_HEADERS เป็นรายการที่คั่นด้วยจุลภาค ระบบจะส่งต่อเฉพาะ headers ที่อนุญาตไว้อย่างชัดเจน และส่งต่อไปยัง origin ที่กำหนดค่าไว้ใน BUILDKITE_BASE_URL เท่านั้น โดยจะนำ headers เหล่านี้ออก จาก requests ที่ถูก redirect ไปที่อื่น

หากต้องการยืนยันตัวตน MCP request แต่ละรายการด้วย Buildkite API token ของตนเอง ให้อนุญาต Authorization และไม่ต้องระบุ token ระดับ process:

BUILDKITE_PASSTHROUGH_HTTP_HEADERS=Authorization \
  buildkite-mcp-server http

ในโหมดนี้ ทุก request ของ /mcp ต้องมี header Authorization ที่ไม่ว่างเพียงรายการเดียว หากไม่มีข้อมูลรับรอง ระบบจะตอบกลับ HTTP 401; เซิร์ฟเวอร์จะไม่ใช้ API token ที่ใช้ร่วมกันเป็นทางเลือก reverse proxy ที่อยู่หน้าเซิร์ฟเวอร์ MCP มีหน้าที่ตรวจสอบสิทธิ์ผู้เรียก และกำหนดหรือตรวจสอบ identity headers ที่ส่งต่อ ไม่รองรับการส่งต่อส่วนหัวในโหมด stdio ก่อนให้บริการบันทึกงาน เซิร์ฟเวอร์จะตรวจสอบว่าผู้เรียกปัจจุบันสามารถเข้าถึงบันทึกงานได้ การตรวจสอบนี้จะดำเนินการกับทุกคำขอใช้เครื่องมือบันทึก รวมถึงกรณีที่ข้อมูลบันทึกถูกแคชไว้แล้ว

---

การมีส่วนร่วม

แนวทางการพัฒนาอยู่ใน DEVELOPMENT.md.

---

ใบอนุญาต

MIT © Buildkite

SPDX-License-Identifier: MIT