feat: add tags resource to mcp server (#1230)

Author: yelizhenden-mdb

tools/mcp-server/internal/resources/alias_test.go

@@ -20,14 +20,14 @@ func TestHandleAlias_Overview(t *testing.T) {
 	assert.Equal(t, "test-api", body.Alias)
 	assert.Equal(t, "Test API", body.Title)
 	assert.Equal(t, registry.SourceTypeFile, body.SourceType)
-	assert.Equal(t, 3, body.Stats.Paths)
-	assert.Equal(t, 4, body.Stats.Operations)
-	assert.Equal(t, 1, body.Stats.Tags)
-	assert.Equal(t, 1, body.Stats.Schemas)
+	assert.Equal(t, 4, body.Stats.Paths)
+	assert.Equal(t, 6, body.Stats.Operations)
+	assert.Equal(t, 2, body.Stats.Tags)
+	assert.Equal(t, 2, body.Stats.Schemas)
 	assert.Equal(t, "2025-01-01", body.LatestStableVersion)
 	assert.Equal(t, []string{"2024-01-01", "2025-01-01"}, body.AvailableVersions)
 	assert.True(t, body.HasPreview)
-	assert.False(t, body.HasUpcoming)
+	assert.True(t, body.HasUpcoming)
 }
 
 // TestHandleAlias_NotFound verifies that reading a non-existent alias returns an error.

tools/mcp-server/internal/resources/tags.go

@@ -0,0 +1,105 @@
+package resources
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+
+	"github.com/getkin/kin-openapi/openapi3"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/mongodb/openapi/tools/mcp-server/internal/registry"
+)
+
+// TagOperation represents a single operation belonging to a tag.
+type TagOperation struct {
+	OperationID string `json:"operationId"`
+	Method      string `json:"method"`
+	Path        string `json:"path"`
+	Summary     string `json:"summary"`
+}
+
+// TagsResource is the response body for the openapi://specs/{alias}/tags/{tagName} resource.
+type TagsResource struct {
+	Tag        string         `json:"tag"`
+	Total      int            `json:"total"`
+	Operations []TagOperation `json:"operations"`
+}
+
+func handleTags(reg *registry.Registry, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
+	alias, tagName, err := aliasAndTagFromURI(req.Params.URI)
+	if err != nil {
+		return nil, err
+	}
+
+	entry, err := reg.GetByAlias(alias)
+	if err != nil {
+		return nil, fmt.Errorf("spec with alias %q not found", alias)
+	}
+
+	ops, err := operationsByTag(entry.Spec, tagName)
+	if err != nil {
+		return nil, err
+	}
+
+	resource := TagsResource{
+		Tag:        tagName,
+		Total:      len(ops),
+		Operations: ops,
+	}
+
+	data, err := json.Marshal(resource)
+	if err != nil {
+		return nil, err
+	}
+
+	return &mcp.ReadResourceResult{
+		Contents: []*mcp.ResourceContents{
+			{URI: req.Params.URI, MIMEType: mimeTypeJSON, Text: string(data)},
+		},
+	}, nil
+}
+
+// operationsByTag returns all operations in the spec tagged with tagName,
+// sorted by path then method for deterministic output.
+// Returns an error if no operations are found for the given tag.
+func operationsByTag(spec *openapi3.T, tagName string) ([]TagOperation, error) {
+	if spec == nil || spec.Paths == nil {
+		return nil, fmt.Errorf("tag %q not found in spec", tagName)
+	}
+
+	var ops []TagOperation
+	for path, item := range spec.Paths.Map() {
+		if item == nil {
+			continue
+		}
+		for method, op := range item.Operations() {
+			if op == nil {
+				continue
+			}
+			for _, t := range op.Tags {
+				if t == tagName {
+					ops = append(ops, TagOperation{
+						OperationID: op.OperationID,
+						Method:      method,
+						Path:        path,
+						Summary:     op.Summary,
+					})
+					break
+				}
+			}
+		}
+	}
+
+	if len(ops) == 0 {
+		return nil, fmt.Errorf("tag %q not found in spec", tagName)
+	}
+
+	sort.Slice(ops, func(i, j int) bool {
+		if ops[i].Path != ops[j].Path {
+			return ops[i].Path < ops[j].Path
+		}
+		return ops[i].Method < ops[j].Method
+	})
+
+	return ops, nil
+}

tools/mcp-server/internal/resources/tags_test.go

@@ -0,0 +1,87 @@
+package resources
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/mongodb/openapi/tools/mcp-server/internal/registry"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type wantOp struct {
+	operationID string
+	method      string
+	path        string
+	summary     string
+}
+
+func assertOp(t *testing.T, got TagOperation, want wantOp) {
+	t.Helper()
+	assert.Equal(t, want.operationID, got.OperationID)
+	assert.Equal(t, want.method, got.Method)
+	assert.Equal(t, want.path, got.Path)
+	assert.Equal(t, want.summary, got.Summary)
+}
+
+// TestHandleTags_Clusters verifies Clusters operations are returned sorted by path then method.
+func TestHandleTags_Clusters(t *testing.T) {
+	result, err := handleTags(newTestRegistry(t), makeRequest("openapi://specs/test-api/tags/Clusters"))
+	require.NoError(t, err)
+
+	var body TagsResource
+	require.NoError(t, json.Unmarshal([]byte(result.Contents[0].Text), &body))
+	assert.Equal(t, "Clusters", body.Tag)
+	require.Equal(t, 4, body.Total)
+
+	assertOp(t, body.Operations[0], wantOp{"listClusterDetails", "GET",
+		"/api/atlas/v2/clusters", "Return All Authorized Clusters in All Projects"})
+	assertOp(t, body.Operations[1], wantOp{"listGroupClusters", "GET",
+		"/api/atlas/v2/groups/{groupId}/clusters", "Return All Clusters in One Project"})
+	assertOp(t, body.Operations[2], wantOp{"createGroupCluster", "POST",
+		"/api/atlas/v2/groups/{groupId}/clusters", "Create One Cluster in One Project"})
+	assertOp(t, body.Operations[3], wantOp{"deleteGroupCluster", "DELETE",
+		"/api/atlas/v2/groups/{groupId}/clusters/{clusterName}", "Remove One Cluster from One Project"})
+}
+
+// TestHandleTags_FlexClusters verifies that tag names containing spaces are resolved correctly.
+// The server decodes the URI automatically so agents can use tag names as they appear in the spec.
+func TestHandleTags_FlexClusters(t *testing.T) {
+	result, err := handleTags(newTestRegistry(t), makeRequest("openapi://specs/test-api/tags/Flex%20Clusters"))
+	require.NoError(t, err)
+
+	var body TagsResource
+	require.NoError(t, json.Unmarshal([]byte(result.Contents[0].Text), &body))
+	assert.Equal(t, "Flex Clusters", body.Tag)
+	require.Equal(t, 2, body.Total)
+
+	// Sorted: GET before POST on the same path.
+	assertOp(t, body.Operations[0], wantOp{"listGroupFlexClusters", "GET",
+		"/api/atlas/v2/groups/{groupId}/flexClusters", "Return All Flex Clusters from One Project"})
+	assertOp(t, body.Operations[1], wantOp{"createGroupFlexCluster", "POST",
+		"/api/atlas/v2/groups/{groupId}/flexClusters", "Create One Flex Cluster in One Project"})
+}
+
+// TestHandleTags_TagNotFound verifies that a non-existent tag returns an error.
+func TestHandleTags_TagNotFound(t *testing.T) {
+	_, err := handleTags(newTestRegistry(t), makeRequest("openapi://specs/test-api/tags/NonExistent"))
+	require.Error(t, err)
+}
+
+// TestHandleTags_TagCaseSensitive verifies that tag matching is case-sensitive.
+func TestHandleTags_TagCaseSensitive(t *testing.T) {
+	_, err := handleTags(newTestRegistry(t), makeRequest("openapi://specs/test-api/tags/clusters"))
+	require.Error(t, err)
+}
+
+// TestHandleTags_AliasNotFound verifies that a non-existent alias returns an error.
+func TestHandleTags_AliasNotFound(t *testing.T) {
+	_, err := handleTags(registry.New(), makeRequest("openapi://specs/nonexistent/tags/Clusters"))
+	require.Error(t, err)
+}
+
+// TestHandleTags_URIInvalid verifies that a URI missing the tag segment returns an error.
+func TestHandleTags_URIInvalid(t *testing.T) {
+	_, err := handleTags(registry.New(), makeRequest("openapi://specs/test-api"))
+	require.Error(t, err)
+}

tools/mcp-server/internal/resources/testhelper_test.go

@@ -34,10 +34,12 @@ func newTestSpec() *openapi3.T {
 		Paths: &openapi3.Paths{},
 		Tags: openapi3.Tags{
 			{Name: "Clusters"},
+			{Name: "Flex Clusters"}, // space in name → percent-encoded as "Flex%20Clusters" in URIs
 		},
 		Components: &openapi3.Components{
 			Schemas: map[string]*openapi3.SchemaRef{
-				"Cluster": {Value: &openapi3.Schema{Type: &openapi3.Types{"object"}}},
+				"Cluster":     {Value: &openapi3.Schema{Type: &openapi3.Types{"object"}}},
+				"FlexCluster": {Value: &openapi3.Schema{Type: &openapi3.Types{"object"}}},
 			},
 		},
 	}
@@ -65,6 +67,16 @@ func newTestSpec() *openapi3.T {
 			},
 		}))
 	}
+	newUpcomingResp := func() *openapi3.Responses {
+		return openapi3.NewResponses(openapi3.WithStatus(200, &openapi3.ResponseRef{
+			Value: &openapi3.Response{
+				Content: openapi3.Content{
+					"application/vnd.atlas.2026-01-01.upcoming+json": &openapi3.MediaType{},
+				},
+			},
+		}))
+	}
+
 	spec.Paths.Set("/api/atlas/v2/clusters", &openapi3.PathItem{
 		Get: &openapi3.Operation{
 			OperationID: "listClusterDetails",
@@ -98,5 +110,21 @@ func newTestSpec() *openapi3.T {
 		},
 	})
 
+	// Flex Clusters: tag name has a space, exercising percent-encoding in URIs.
+	spec.Paths.Set("/api/atlas/v2/groups/{groupId}/flexClusters", &openapi3.PathItem{
+		Get: &openapi3.Operation{
+			OperationID: "listGroupFlexClusters",
+			Summary:     "Return All Flex Clusters from One Project",
+			Tags:        []string{"Flex Clusters"},
+			Responses:   newStableResp(),
+		},
+		Post: &openapi3.Operation{
+			OperationID: "createGroupFlexCluster",
+			Summary:     "Create One Flex Cluster in One Project",
+			Tags:        []string{"Flex Clusters"},
+			Responses:   newUpcomingResp(),
+		},
+	})
+
 	return spec
 }

tools/mcp-server/internal/resources/uri.go

@@ -6,11 +6,21 @@ import (
 	"strings"
 )
 
-// aliasFromURI extracts the alias from openapi://specs/{alias}.
-// Returns an error if the scheme, host, or path structure does not match exactly.
-func aliasFromURI(uri string) (string, error) {
+// parseSpecURI parses a resource URI and validates that it uses the openapi://specs/ base.
+// It is the shared entry point for all URI parsing in this package.
+func parseSpecURI(uri string) (*url.URL, error) {
 	u, err := url.Parse(uri)
 	if err != nil || u.Scheme != "openapi" || u.Host != "specs" {
+		return nil, fmt.Errorf("invalid resource URI %q: must use openapi://specs/ scheme", uri)
+	}
+	return u, nil
+}
+
+// aliasFromURI extracts the alias from openapi://specs/{alias}.
+// Returns an error if the path has extra segments or the alias is empty.
+func aliasFromURI(uri string) (string, error) {
+	u, err := parseSpecURI(uri)
+	if err != nil {
 		return "", fmt.Errorf("invalid resource URI %q: expected openapi://specs/{alias}", uri)
 	}
 	parts := strings.Split(strings.TrimPrefix(u.Path, "/"), "/")
@@ -19,3 +29,24 @@ func aliasFromURI(uri string) (string, error) {
 	}
 	return parts[0], nil
 }
+
+// aliasAndTagFromURI extracts the alias and tag name from openapi://specs/{alias}/tags/{tagName}.
+// The tag name is percent-decoded so agents can use tag names as they appear in the spec.
+func aliasAndTagFromURI(uri string) (alias, tagName string, err error) {
+	u, err := parseSpecURI(uri)
+	if err != nil {
+		return "", "", fmt.Errorf("invalid resource URI %q: expected openapi://specs/{alias}/tags/{tagName}", uri)
+	}
+
+	// path: /{alias}/tags/{tagName}
+	parts := strings.SplitN(strings.TrimPrefix(u.Path, "/"), "/", 3)
+	if len(parts) != 3 || parts[0] == "" || parts[1] != "tags" || parts[2] == "" {
+		return "", "", fmt.Errorf("invalid resource URI %q: expected openapi://specs/{alias}/tags/{tagName}", uri)
+	}
+
+	tagName, err = url.PathUnescape(parts[2])
+	if err != nil {
+		return "", "", fmt.Errorf("invalid tag name in URI %q: %w", uri, err)
+	}
+	return parts[0], tagName, nil
+}