Add tooling to auto-generate server.schema.json from OpenAPI spec (#629)

This PR adds a Go tool that extracts the ServerDetail schema from
openapi.yaml and generates server.schema.json, ensuring the two specs
stay in sync.

## Key Changes

### New Tooling
- **Go tool** at `tools/extract-server-schema/` that auto-discovers all
schemas referenced by ServerDetail and extracts them from OpenAPI
- **make targets**: `generate-schema` (generates schema) and
`check-schema` (verifies sync)
- `check-schema` is now included in `make validate` and `make check`

### Preserved Validation Constraints
The initial auto-generated schema lost many important validation rules
and descriptive guidance from the hand-crafted version. The OpenAPI spec
has been updated to preserve:

**Security & Descriptions:**
- Command injection security warning on Arguments
- Detailed field descriptions with usage guidance  
- `placeholder` field for Input schema

**Validation Constraints:**
- `fileSha256` pattern validation (`^[a-f0-9]{64}$`)
- Package version restrictions (minLength: 1, no "latest")
- `transport` as required field in Package
- ServerDetail `name` pattern and length constraints (3-200 chars)
- Description, title, and version length limits

**Documentation:**
- Repository field descriptions (url, source, id, subfolder)
- PositionalArgument `valueHint` explains transport URL substitution
- Updated examples to match hand-crafted version (Weather API theme)

**Intentional Changes:**
- Removed `additionalProperties` constraints for flexibility
- Updated schema title to be more descriptive
- Added `$comment` noting auto-generation

See the commit "Preserve validation constraints in auto-generated
server.schema.json" for details.

### Fixed Missing Package.transport
- Added `transport` field to OpenAPI Package schema (was in Go model at
`pkg/model/types.go:30` but missing from OpenAPI)
- Split transport types into three separate schemas with proper
discriminated unions:
  - `StdioTransport` - Only requires `type: stdio`
- `StreamableHttpTransport` - Requires `type` and `url`, supports
`headers`
  - `SseTransport` - Requires `type` and `url`, supports `headers`
- `Package.transport` uses `anyOf` with all three types
- `ServerDetail.remotes` uses `anyOf` with only remote types (no stdio)

### Other Improvements
- Added `GOTOOLCHAIN=auto` to Makefile for Go 1.25 compatibility
- Added `DRIFT_ANALYSIS.md` documenting all schema drift issues found
between specs

## Benefits

**Single Source of Truth**: The OpenAPI spec now serves as the
authoritative schema definition, with server.schema.json automatically
derived from it.

**Better Validation**: All critical validation rules (patterns, length
constraints, required fields) and security warnings are preserved in the
generated schema.

**Improved Developer Experience**: 
- Schema changes only need to be made in one place (openapi.yaml)
- CI validation ensures specs never drift apart
- Clear auto-generation comment prevents manual edits

## Validation
✅ All 20 examples validate correctly
✅ Lint passes with 0 issues
✅ Schema is in sync with OpenAPI
✅ All validation constraints from hand-crafted schema preserved

---------

Co-authored-by: Claude <noreply@anthropic.com>

tools/extract-server-schema/main.go

@@ -0,0 +1,182 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+const (
+	openAPIPath     = "docs/reference/api/openapi.yaml"
+	schemaOutputDir = "docs/reference/server-json"
+)
+
+func main() {
+	var check bool
+	flag.BoolVar(&check, "check", false, "Check if schema is in sync (exit 1 if not)")
+	flag.Parse()
+
+	// Read OpenAPI spec
+	openapiData, err := os.ReadFile(openAPIPath)
+	if err != nil {
+		log.Fatalf("Failed to read OpenAPI spec: %v", err)
+	}
+
+	// Parse YAML
+	var openapi map[string]interface{}
+	if err := yaml.Unmarshal(openapiData, &openapi); err != nil {
+		log.Fatalf("Failed to parse OpenAPI YAML: %v", err)
+	}
+
+	// Extract components/schemas
+	components, ok := openapi["components"].(map[string]interface{})
+	if !ok {
+		log.Fatal("Missing 'components' in OpenAPI spec")
+	}
+
+	schemas, ok := components["schemas"].(map[string]interface{})
+	if !ok {
+		log.Fatal("Missing 'components/schemas' in OpenAPI spec")
+	}
+
+	// Extract ServerDetail
+	serverDetail, ok := schemas["ServerDetail"].(map[string]interface{})
+	if !ok {
+		log.Fatal("Missing 'ServerDetail' schema in OpenAPI spec")
+	}
+
+	// Auto-discover all schemas referenced by ServerDetail
+	referencedSchemas := make(map[string]bool)
+	findReferencedSchemas(serverDetail, referencedSchemas)
+
+	// Build definitions by recursively collecting all referenced schemas
+	definitions := make(map[string]interface{})
+	definitions["ServerDetail"] = serverDetail
+
+	// Keep discovering until we've found all transitively referenced schemas
+	for {
+		added := false
+		for schemaName := range referencedSchemas {
+			if _, exists := definitions[schemaName]; !exists {
+				schema, ok := schemas[schemaName]
+				if !ok {
+					log.Fatalf("Referenced schema '%s' not found in OpenAPI spec", schemaName)
+				}
+				definitions[schemaName] = schema
+				// Find schemas referenced by this newly added schema
+				findReferencedSchemas(schema, referencedSchemas)
+				added = true
+			}
+		}
+		if !added {
+			break
+		}
+	}
+
+	// Build the JSON Schema document
+	jsonSchema := map[string]interface{}{
+		"$comment":    "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.",
+		"$schema":     "http://json-schema.org/draft-07/schema#",
+		"$id":         "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+		"title":       "server.json defining a Model Context Protocol (MCP) server",
+		"$ref":        "#/definitions/ServerDetail",
+		"definitions": definitions,
+	}
+
+	// Replace all #/components/schemas/ references with #/definitions/
+	jsonSchema = replaceComponentRefs(jsonSchema).(map[string]interface{})
+
+	// Convert to JSON
+	jsonData, err := json.MarshalIndent(jsonSchema, "", "  ")
+	if err != nil {
+		log.Fatalf("Failed to marshal JSON schema: %v", err)
+	}
+
+	// Append newline at end
+	jsonStr := string(jsonData) + "\n"
+
+	outputPath := schemaOutputDir + "/server.schema.json"
+
+	if check {
+		// Check mode: compare with existing file
+		existingData, err := os.ReadFile(outputPath)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error reading existing schema: %v\n", err)
+			os.Exit(1)
+		}
+
+		if string(existingData) != jsonStr {
+			fmt.Fprintf(os.Stderr, "ERROR: server.schema.json is out of sync with openapi.yaml\n")
+			fmt.Fprintf(os.Stderr, "Run 'make generate-schema' to update it.\n")
+			os.Exit(1)
+		}
+
+		log.Println("✓ server.schema.json is in sync with openapi.yaml")
+		return
+	}
+
+	// Write mode: update the file
+	if err := os.WriteFile(outputPath, []byte(jsonStr), 0644); err != nil { //nolint:gosec // This is a documentation file that should be world-readable
+		log.Fatalf("Failed to write schema file: %v", err)
+	}
+
+	log.Printf("✓ Generated %s from %s\n", outputPath, openAPIPath)
+}
+
+// findReferencedSchemas recursively finds all schema names referenced via $ref
+func findReferencedSchemas(obj interface{}, found map[string]bool) {
+	switch v := obj.(type) {
+	case map[string]interface{}:
+		for key, value := range v {
+			if key == "$ref" {
+				if ref, ok := value.(string); ok {
+					// Extract schema name from #/components/schemas/SchemaName
+					if strings.HasPrefix(ref, "#/components/schemas/") {
+						schemaName := strings.TrimPrefix(ref, "#/components/schemas/")
+						found[schemaName] = true
+					}
+				}
+			} else {
+				findReferencedSchemas(value, found)
+			}
+		}
+	case []interface{}:
+		for _, item := range v {
+			findReferencedSchemas(item, found)
+		}
+	}
+}
+
+// replaceComponentRefs recursively replaces #/components/schemas/ with #/definitions/
+func replaceComponentRefs(obj interface{}) interface{} {
+	switch v := obj.(type) {
+	case map[string]interface{}:
+		result := make(map[string]interface{})
+		for key, value := range v {
+			if key == "$ref" {
+				if ref, ok := value.(string); ok {
+					// Replace the reference path
+					result[key] = strings.ReplaceAll(ref, "#/components/schemas/", "#/definitions/")
+				} else {
+					result[key] = value
+				}
+			} else {
+				result[key] = replaceComponentRefs(value)
+			}
+		}
+		return result
+	case []interface{}:
+		result := make([]interface{}, len(v))
+		for i, item := range v {
+			result[i] = replaceComponentRefs(item)
+		}
+		return result
+	default:
+		return obj
+	}
+}