Buildkite

Implements the Model Context Protocol (MCP) specification to expose Buildkite's REST API as a standardized tool registry that MCP-compatible clients (Claude Desktop, VSCode, GitHub Copilot, Goose, Zed Editor) can discover and invoke. The server translates MCP tool invocations into authenticated Buildkite API calls, handles response marshaling, and returns structured JSON results through stdio or HTTP transport layers. This abstraction eliminates the need for clients to implement Buildkite API authentication and request formatting directly.

Exposes two tools (get_pipeline, list_pipelines) that query Buildkite's pipeline API to retrieve full pipeline definitions, including steps, environment variables, branch configuration, and metadata. The server caches pipeline metadata in memory to reduce API calls for repeated queries. Responses include pipeline ID, name, repository URL, and step definitions in structured JSON format, enabling AI tools to understand pipeline structure for analysis or modification recommendations.

Implements MCP tool registration mechanism that exposes 20+ Buildkite tools (pipelines, builds, jobs, clusters, tests, artifacts) as discoverable MCP tools with JSON schema definitions. The server registers tools with mark3labs/mcp-go framework, which handles tool discovery requests from MCP clients and returns tool names, descriptions, and parameter schemas. Enables MCP clients to discover available Buildkite operations and understand required parameters without external documentation.

Implements error handling layer that catches Buildkite API errors (authentication failures, not found, rate limits) and translates them into MCP-compliant error responses with descriptive messages. The server formats all responses (success and error) according to MCP protocol specification, ensuring clients receive consistent, parseable responses. Enables MCP clients to handle errors gracefully and provide meaningful feedback to users.

Implements get_build and list_builds tools that retrieve build execution records from Buildkite, including status (passed/failed/running), timestamps, commit information, and branch metadata. The server translates MCP parameters (pipeline slug, build number, filters) into Buildkite API queries and returns paginated results. Supports filtering by branch, state, and commit to enable targeted queries of build history without retrieving entire datasets.

Exposes get_jobs and get_job_logs tools that retrieve individual job records and their execution logs from Buildkite builds. The server queries the Buildkite API for job metadata (status, duration, agent name) and raw log output, returning logs as plain text or structured JSON. Enables AI tools to analyze job failures, performance issues, or error patterns by examining actual execution output without requiring access to external log storage systems.

Implements test engine tools (list_test_runs, get_test_run, get_failed_test_executions, get_test) that query Buildkite's test analytics API to retrieve test execution records, including pass/fail status, duration, and failure reasons. The server translates MCP parameters into Buildkite test engine API queries and returns structured test data. Enables AI tools to identify flaky tests, analyze failure patterns, and correlate test failures with code changes.

Exposes cluster management tools (get_cluster, list_clusters, get_cluster_queue, list_cluster_queues) that retrieve information about Buildkite agent clusters and job queues. The server queries the Buildkite API for cluster configuration, queue status, and agent availability. Enables AI tools to understand job routing, identify queue bottlenecks, and make recommendations for cluster scaling or queue optimization.

Implements current_user, user_token_organization, and access_token tools that retrieve authenticated user information and organization context from Buildkite. The server validates the provided API token against Buildkite's authentication API and returns user identity, organization membership, and token metadata. Enables AI tools to determine which organization context to use for subsequent API calls and verify token validity without exposing credentials.

Exposes list_artifacts and get_artifact tools that retrieve build artifacts (compiled binaries, test reports, logs) and annotations (metadata, custom fields) from Buildkite builds. The server queries the Buildkite API for artifact metadata (filename, size, upload timestamp) and download URLs. Enables AI tools to access build outputs and custom metadata without requiring direct access to external storage systems (S3, GCS, etc.).

Implements dual transport layer supporting both stdio (for desktop applications) and HTTP (for web/server deployments) communication with MCP clients. The server uses mark3labs/mcp-go framework to handle protocol-level message serialization, request routing, and response formatting. Enables deployment flexibility: stdio mode for Claude Desktop and VSCode plugins, HTTP mode for server-based deployments or custom integrations.

Implements authentication layer that accepts Buildkite API tokens (user or organization tokens) and uses them to sign all outbound API requests to Buildkite. The server stores tokens securely (environment variables or configuration) and injects them into request headers for each API call. Enables MCP clients to access Buildkite without managing credentials directly; authentication is handled transparently by the server.