feat: add resources for listing specs in the registry and get a summary for a specific one (#1205)

Author: yelizhenden-mdb

tools/cli/pkg/apiversion/apiversion.go

@@ -0,0 +1,23 @@
+// Package apiversion exposes API version parsing utilities for use outside the cli module.
+package apiversion
+
+import (
+	"github.com/mongodb/openapi/tools/cli/internal/apiversion"
+)
+
+// Parse extracts the API version string from a versioned media type
+// (e.g. "application/vnd.atlas.2024-01-01+json" → "2024-01-01").
+// Returns an error if the media type does not match the expected pattern.
+func Parse(contentType string) (string, error) {
+	return apiversion.Parse(contentType)
+}
+
+// IsPreviewStabilityLevel reports whether the given version string represents a preview release.
+func IsPreviewStabilityLevel(version string) bool {
+	return apiversion.IsPreviewStabilityLevel(version)
+}
+
+// IsUpcomingStabilityLevel reports whether the given version string represents an upcoming release.
+func IsUpcomingStabilityLevel(version string) bool {
+	return apiversion.IsUpcomingStabilityLevel(version)
+}

tools/cli/pkg/openapi/openapi.go

@@ -24,6 +24,15 @@ import (
 	"github.com/spf13/afero"
 )
 
+// ExtractVersions returns all API version strings present in the spec,
+// including stable date versions (e.g. "2024-01-01"), preview names
+// (e.g. "preview", "public-preview"), and upcoming versions
+// (e.g. "2024-01-01.upcoming") when no stable counterpart exists.
+// The returned slice is sorted.
+func ExtractVersions(spec *openapi3.T) ([]string, error) {
+	return openapi.ExtractVersionsWithEnv(spec, "")
+}
+
 // SliceCriteria defines the selection criteria for slicing an OpenAPI spec.
 // Operations matching ANY of the specified criteria will be included (OR logic).
 type SliceCriteria = slice.Criteria

tools/mcp-server/cmd/main.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/mongodb/openapi/tools/mcp-server/internal/registry"
+	"github.com/mongodb/openapi/tools/mcp-server/internal/resources"
 	"github.com/mongodb/openapi/tools/mcp-server/internal/tools"
 )
 
@@ -31,6 +32,7 @@ func run() error {
 	server := mcp.NewServer(impl, nil)
 
 	tools.Register(server, reg)
+	resources.Register(server, reg)
 
 	// Log to stderr (stdout is reserved for MCP protocol)
 	log.SetOutput(os.Stderr)

tools/mcp-server/go.mod

@@ -25,6 +25,7 @@ require (
 	github.com/perimeterx/marshmallow v1.1.5 // indirect
 	github.com/segmentio/asm v1.1.3 // indirect
 	github.com/segmentio/encoding v0.5.4 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
 	github.com/tidwall/gjson v1.18.0 // indirect
 	github.com/tidwall/match v1.2.0 // indirect
 	github.com/tidwall/pretty v1.2.1 // indirect

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

@@ -0,0 +1,123 @@
+package resources
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/mongodb/openapi/tools/cli/pkg/apiversion"
+	"github.com/mongodb/openapi/tools/cli/pkg/openapi"
+	"github.com/mongodb/openapi/tools/mcp-server/internal/registry"
+	"github.com/oasdiff/kin-openapi/openapi3"
+)
+
+// SpecStats holds counts of the spec's top-level components.
+type SpecStats struct {
+	Paths      int `json:"paths"`
+	Operations int `json:"operations"`
+	Schemas    int `json:"schemas"`
+	Tags       int `json:"tags"`
+}
+
+// SpecOverview is the response body for the openapi://specs/{alias} resource.
+type SpecOverview struct {
+	Alias               string              `json:"alias"`
+	SourceType          registry.SourceType `json:"sourceType"`
+	Title               string              `json:"title,omitempty"`
+	Description         string              `json:"description,omitempty"`
+	Stats               SpecStats           `json:"stats"`
+	LatestStableVersion string              `json:"latestStableVersion"`
+	AvailableVersions   []string            `json:"availableVersions"`
+	HasPreview          bool                `json:"hasPreview"`
+	HasUpcoming         bool                `json:"hasUpcoming"`
+}
+
+func handleAlias(reg *registry.Registry, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
+	alias, err := aliasFromURI(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)
+	}
+
+	overview := buildSpecOverview(entry)
+
+	data, err := json.Marshal(overview)
+	if err != nil {
+		return nil, err
+	}
+
+	return &mcp.ReadResourceResult{
+		Contents: []*mcp.ResourceContents{
+			{URI: req.Params.URI, MIMEType: mimeTypeJSON, Text: string(data)},
+		},
+	}, nil
+}
+
+func buildSpecOverview(entry *registry.Entry) SpecOverview {
+	overview := SpecOverview{
+		Alias:      entry.Alias,
+		SourceType: entry.SourceType,
+	}
+
+	if entry.Spec == nil {
+		return overview
+	}
+
+	if entry.Spec.Info != nil {
+		overview.Title = entry.Spec.Info.Title
+		overview.Description = entry.Spec.Info.Description
+	}
+
+	if entry.Spec.Paths != nil {
+		overview.Stats.Paths = len(entry.Spec.Paths.Map())
+		overview.Stats.Operations = countOperations(entry.Spec)
+	}
+
+	if entry.Spec.Components != nil {
+		overview.Stats.Schemas = len(entry.Spec.Components.Schemas)
+	}
+
+	overview.Stats.Tags = len(entry.Spec.Tags)
+
+	stable, hasPreview, hasUpcoming := extractVersions(entry.Spec)
+	overview.HasPreview = hasPreview
+	overview.HasUpcoming = hasUpcoming
+	// ExtractVersions returns versions sorted ascending by date string (YYYY-MM-DD).
+	overview.AvailableVersions = stable
+	if len(stable) > 0 {
+		overview.LatestStableVersion = stable[len(stable)-1]
+	}
+
+	return overview
+}
+
+func countOperations(spec *openapi3.T) int {
+	count := 0
+	for _, item := range spec.Paths.Map() {
+		count += len(item.Operations())
+	}
+	return count
+}
+
+func extractVersions(spec *openapi3.T) (stable []string, hasPreview, hasUpcoming bool) {
+	stable = []string{}
+	all, err := openapi.ExtractVersions(spec)
+	if err != nil || len(all) == 0 {
+		return stable, false, false
+	}
+	for _, v := range all {
+		switch {
+		case apiversion.IsPreviewStabilityLevel(v):
+			hasPreview = true
+		case apiversion.IsUpcomingStabilityLevel(v):
+			hasUpcoming = true
+		default:
+			stable = append(stable, v)
+		}
+	}
+	return stable, hasPreview, hasUpcoming
+}

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

@@ -0,0 +1,49 @@
+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"
+)
+
+// TestHandleAlias_Overview verifies that the spec overview contains title, stats, and version info.
+func TestHandleAlias_Overview(t *testing.T) {
+	result, err := handleAlias(newTestRegistry(t), makeRequest("openapi://specs/test-api"))
+	require.NoError(t, err)
+
+	var body SpecOverview
+	require.NoError(t, json.Unmarshal([]byte(result.Contents[0].Text), &body))
+
+	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, "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)
+}
+
+// TestHandleAlias_NotFound verifies that reading a non-existent alias returns an error.
+func TestHandleAlias_NotFound(t *testing.T) {
+	_, err := handleAlias(registry.New(), makeRequest("openapi://specs/nonexistent"))
+	require.Error(t, err)
+}
+
+// TestHandleAlias_URIMissingAlias verifies that a URI without an alias segment returns an error.
+func TestHandleAlias_URIMissingAlias(t *testing.T) {
+	_, err := handleAlias(registry.New(), makeRequest("not-a-valid-uri"))
+	require.Error(t, err)
+}
+
+// TestHandleAlias_URIExtraSegments verifies that a URI with extra path segments is rejected.
+func TestHandleAlias_URIExtraSegments(t *testing.T) {
+	_, err := handleAlias(registry.New(), makeRequest("openapi://specs/test-api/tags/Clusters"))
+	require.Error(t, err)
+}

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

@@ -0,0 +1,52 @@
+package resources
+
+import (
+	"context"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/mongodb/openapi/tools/mcp-server/internal/registry"
+)
+
+const mimeTypeJSON = "application/json"
+
+// Register registers all static resources and resource template handlers with the server.
+func Register(server *mcp.Server, reg *registry.Registry) {
+	server.AddResource(&mcp.Resource{
+		URI:  "openapi://specs",
+		Name: "specs",
+		Description: "Start here. Lists all OpenAPI specifications currently loaded in the registry. " +
+			"Each entry includes the alias (used to reference the spec in all other resources and tools), " +
+			"sourceType ('file' for specs loaded from disk, 'virtual' for sliced subsets), " +
+			"and filePath (empty for virtual specs). " +
+			"Read this resource first to discover what aliases are available before using other resources or tools.",
+		MIMEType: mimeTypeJSON,
+	}, makeSpecsHandler(reg))
+
+	server.AddResourceTemplate(&mcp.ResourceTemplate{
+		URITemplate: "openapi://specs/{alias}",
+		Name:        "spec-overview",
+		Description: "Returns a structural overview of a single loaded spec identified by {alias}. " +
+			"Includes title, description, and stats (path count, operation count, schema count, tag count). " +
+			"For versioned APIs, also returns: " +
+			"latestStableVersion (the most recent stable YYYY-MM-DD version), " +
+			"availableVersions (all stable date-based versions in ascending order), " +
+			"hasPreview (true if any preview operations exist), " +
+			"hasUpcoming (true if any upcoming operations exist). " +
+			"Use this to understand the scope of a spec before searching or slicing it.",
+		MIMEType: mimeTypeJSON,
+	}, makeAliasHandler(reg))
+}
+
+// makeSpecsHandler creates the handler for the openapi://specs resource.
+func makeSpecsHandler(reg *registry.Registry) mcp.ResourceHandler {
+	return func(_ context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
+		return handleSpecs(reg, req)
+	}
+}
+
+// makeAliasHandler creates the handler for the openapi://specs/{alias} resource template.
+func makeAliasHandler(reg *registry.Registry) mcp.ResourceHandler {
+	return func(_ context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
+		return handleAlias(reg, req)
+	}
+}

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

@@ -0,0 +1,45 @@
+package resources
+
+import (
+	"encoding/json"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/mongodb/openapi/tools/mcp-server/internal/registry"
+)
+
+// SpecSummary is a summary of a single spec returned by the openapi://specs resource.
+type SpecSummary struct {
+	Alias      string              `json:"alias"`
+	SourceType registry.SourceType `json:"sourceType"`
+	FilePath   string              `json:"filePath,omitempty"`
+}
+
+// SpecsResource is the response body for the openapi://specs resource.
+type SpecsResource struct {
+	Specs []SpecSummary `json:"specs"`
+	Total int           `json:"total"`
+}
+
+func handleSpecs(reg *registry.Registry, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
+	entries := reg.List()
+
+	summaries := make([]SpecSummary, len(entries))
+	for i, entry := range entries {
+		summaries[i] = SpecSummary{
+			Alias:      entry.Alias,
+			SourceType: entry.SourceType,
+			FilePath:   entry.FilePath,
+		}
+	}
+
+	data, err := json.Marshal(SpecsResource{Specs: summaries, Total: len(summaries)})
+	if err != nil {
+		return nil, err
+	}
+
+	return &mcp.ReadResourceResult{
+		Contents: []*mcp.ResourceContents{
+			{URI: req.Params.URI, MIMEType: mimeTypeJSON, Text: string(data)},
+		},
+	}, nil
+}

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

@@ -0,0 +1,51 @@
+package resources
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/mongodb/openapi/tools/mcp-server/internal/registry"
+	"github.com/oasdiff/kin-openapi/openapi3"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestHandleSpecs_EmptyRegistry verifies that an empty registry returns an empty list.
+func TestHandleSpecs_EmptyRegistry(t *testing.T) {
+	result, err := handleSpecs(registry.New(), makeRequest("openapi://specs"))
+	require.NoError(t, err)
+
+	var body SpecsResource
+	require.NoError(t, json.Unmarshal([]byte(result.Contents[0].Text), &body))
+	assert.Equal(t, 0, body.Total)
+	assert.Empty(t, body.Specs)
+}
+
+// TestHandleSpecs_WithEntries verifies that loaded specs are returned with alias, sourceType, and filePath.
+func TestHandleSpecs_WithEntries(t *testing.T) {
+	result, err := handleSpecs(newTestRegistry(t), makeRequest("openapi://specs"))
+	require.NoError(t, err)
+
+	var body SpecsResource
+	require.NoError(t, json.Unmarshal([]byte(result.Contents[0].Text), &body))
+	require.Equal(t, 1, body.Total)
+
+	s := body.Specs[0]
+	assert.Equal(t, "test-api", s.Alias)
+	assert.Equal(t, registry.SourceTypeFile, s.SourceType)
+	assert.Equal(t, "/test/api.yaml", s.FilePath)
+}
+
+// TestHandleSpecs_VirtualSpecHasNoFilePath verifies that virtual specs omit filePath.
+func TestHandleSpecs_VirtualSpecHasNoFilePath(t *testing.T) {
+	reg := registry.New()
+	require.NoError(t, reg.Add("virtual-api", "", &openapi3.T{Info: &openapi3.Info{Title: "Virtual"}}, nil))
+
+	result, err := handleSpecs(reg, makeRequest("openapi://specs"))
+	require.NoError(t, err)
+
+	var body SpecsResource
+	require.NoError(t, json.Unmarshal([]byte(result.Contents[0].Text), &body))
+	assert.Empty(t, body.Specs[0].FilePath)
+	assert.Equal(t, registry.SourceTypeVirtual, body.Specs[0].SourceType)
+}