Merge pull request #46 from RemyDeWolf/feat-list-annotations

Issue #42 support build annotations (draft)

Author: wolfeidau

README.md

@@ -20,6 +20,7 @@ This is an [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introd
 * `access_token` - Get the details for the API access token that was used to authenticate the request
 * `list_artifacts` - List the artifacts for a Buildkite build
 * `get_artifact` - Get an artifact from a Buildkite build
+* `list_annotations` - List the annotations for a Buildkite build
 
 Example of the `get_pipeline` tool in action.
 

internal/buildkite/annotations.go

@@ -0,0 +1,104 @@
+package buildkite
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/buildkite/buildkite-mcp-server/internal/trace"
+	"github.com/buildkite/go-buildkite/v4"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+	"go.opentelemetry.io/otel/attribute"
+)
+
+// AnnotationsClient describes the subset of the Buildkite client we need for annotations.
+type AnnotationsClient interface {
+	ListByBuild(ctx context.Context, org, pipelineSlug, buildNumber string, opts *buildkite.AnnotationListOptions) ([]buildkite.Annotation, *buildkite.Response, error)
+}
+
+// ListAnnotations returns an MCP tool + handler pair that lists annotations for a build.
+func ListAnnotations(ctx context.Context, client AnnotationsClient) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("list_annotations",
+			mcp.WithDescription("List the annotations for a Buildkite build"),
+			mcp.WithString("org",
+				mcp.Required(),
+				mcp.Description("The organization slug for the owner of the pipeline"),
+			),
+			mcp.WithString("pipeline_slug",
+				mcp.Required(),
+				mcp.Description("The slug of the pipeline"),
+			),
+			mcp.WithString("build_number",
+				mcp.Required(),
+				mcp.Description("The build number"),
+			),
+			withPagination(),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        "List Annotations",
+				ReadOnlyHint: mcp.ToBoolPtr(true),
+			}),
+		), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			ctx, span := trace.Start(ctx, "buildkite.ListAnnotations")
+			defer span.End()
+
+			org, err := request.RequireString("org")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			pipelineSlug, err := request.RequireString("pipeline_slug")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			buildNumber, err := request.RequireString("build_number")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			paginationParams, err := optionalPaginationParams(request)
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			span.SetAttributes(
+				attribute.String("org", org),
+				attribute.String("pipeline_slug", pipelineSlug),
+				attribute.String("build_number", buildNumber),
+				attribute.Int("page", paginationParams.Page),
+				attribute.Int("per_page", paginationParams.PerPage),
+			)
+
+			annotations, resp, err := client.ListByBuild(ctx, org, pipelineSlug, buildNumber, &buildkite.AnnotationListOptions{
+				ListOptions: paginationParams,
+			})
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			if resp.StatusCode != http.StatusOK {
+				body, err := io.ReadAll(resp.Body)
+				if err != nil {
+					return nil, fmt.Errorf("failed to read response body: %w", err)
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("failed to list annotations: %s", string(body))), nil
+			}
+
+			result := PaginatedResult[buildkite.Annotation]{
+				Items: annotations,
+				Headers: map[string]string{
+					"Link": resp.Header.Get("Link"),
+				},
+			}
+
+			r, err := json.Marshal(&result)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal annotations: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}

internal/buildkite/annotations_test.go

@@ -0,0 +1,63 @@
+package buildkite
+
+import (
+	"context"
+	"net/http"
+	"testing"
+
+	"github.com/buildkite/go-buildkite/v4"
+	"github.com/stretchr/testify/require"
+)
+
+type MockAnnotationsClient struct {
+	ListByBuildFunc func(ctx context.Context, org, pipelineSlug, buildNumber string, opts *buildkite.AnnotationListOptions) ([]buildkite.Annotation, *buildkite.Response, error)
+	GetFunc         func(ctx context.Context, org, pipelineSlug, buildNumber, id string) (buildkite.Annotation, *buildkite.Response, error)
+}
+
+func (m *MockAnnotationsClient) ListByBuild(ctx context.Context, org, pipelineSlug, buildNumber string, opts *buildkite.AnnotationListOptions) ([]buildkite.Annotation, *buildkite.Response, error) {
+	if m.ListByBuildFunc != nil {
+		return m.ListByBuildFunc(ctx, org, pipelineSlug, buildNumber, opts)
+	}
+	return nil, nil, nil
+}
+
+var _ AnnotationsClient = (*MockAnnotationsClient)(nil)
+
+func TestListAnnotations(t *testing.T) {
+	assert := require.New(t)
+
+	ctx := context.Background()
+
+	client := &MockAnnotationsClient{
+		ListByBuildFunc: func(ctx context.Context, org, pipelineSlug, buildNumber string, opts *buildkite.AnnotationListOptions) ([]buildkite.Annotation, *buildkite.Response, error) {
+			return []buildkite.Annotation{
+					{
+						ID:       "1",
+						BodyHTML: "Test annotation 1",
+					},
+					{
+						ID:       "2",
+						BodyHTML: "Test annotation 2",
+					},
+				}, &buildkite.Response{
+					Response: &http.Response{
+						StatusCode: 200,
+					},
+				}, nil
+		},
+	}
+
+	tool, handler := ListAnnotations(ctx, client)
+	assert.NotNil(tool)
+	assert.NotNil(handler)
+	request := createMCPRequest(t, map[string]any{
+		"org":           "org",
+		"pipeline_slug": "pipeline",
+		"build_number":  "1",
+	})
+	result, err := handler(ctx, request)
+	assert.NoError(err)
+	textContent := getTextResult(t, result)
+
+	assert.Equal(`{"headers":{"Link":""},"items":[{"id":"1","body_html":"Test annotation 1"},{"id":"2","body_html":"Test annotation 2"}]}`, textContent.Text)
+}

internal/commands/mcp.go

@@ -70,5 +70,8 @@ func BuildkiteTools(ctx context.Context, client *gobuildkite.Client) []server.Se
 	tools = addTool(buildkite.ListArtifacts(ctx, clientAdapter))
 	tools = addTool(buildkite.GetArtifact(ctx, clientAdapter))
 
+	// Annotation tools
+	tools = addTool(buildkite.ListAnnotations(ctx, client.Annotations))
+
 	return tools
 }