Add $schema to server.json specification to enable versioning, IDE autocomplete (#308)

## Summary
- Add optional `$schema` property to ServerDetail specification
- Update JSON Schema, OpenAPI spec, Go models, examples, and publisher
template
- Enable schema versioning and IDE validation support

## Changes
- Added `$schema` as optional string property with URI format in specs
- Updated Go ServerDetail struct with new Schema field
- Added `$schema` to examples and publisher template
- Copy schema file to ../static for GitHub Pages hosting

Fixes #139

tools/publisher/main.go

@@ -52,6 +52,7 @@ type Package struct {
 }
 
 type ServerJSON struct {
+	Schema        string        `json:"$schema"`
 	Name          string        `json:"name"`
 	Description   string        `json:"description"`
 	Status        string        `json:"status,omitempty"`
@@ -489,6 +490,7 @@ func createServerStructure(
 
 	// Create server structure
 	return ServerJSON{
+		Schema:      "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
 		Name:        name,
 		Description: description,
 		Status:      status,

tools/publisher/server.json

@@ -1,4 +1,5 @@
 {
+    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
     "description": "<your description here>",
     "name": "io.github.<owner>/<server-name>",
     "status": "active",

tools/validate-examples/main.go

@@ -37,7 +37,7 @@ func runValidation() error {
 	basePath := filepath.Join("docs", "server-json")
 
 	examplesPath := filepath.Join(basePath, "examples.md")
-	schemaPath := filepath.Join(basePath, "schema.json")
+	schemaPath := filepath.Join(basePath, "server.schema.json")
 	registrySchemaPath := filepath.Join(basePath, "registry-schema.json")
 
 	examples, err := extractExamples(examplesPath)
@@ -56,7 +56,7 @@ func runValidation() error {
 
 	baseSchema, err := compileSchema(schemaPath)
 	if err != nil {
-		return fmt.Errorf("failed to compile schema.json: %w", err)
+		return fmt.Errorf("failed to compile server.schema.json: %w", err)
 	}
 
 	registrySchema, err := compileSchema(registrySchemaPath)
@@ -94,10 +94,10 @@ func runValidation() error {
 		registryValid := false
 
 		if err := baseSchema.Validate(serverData); err != nil {
-			log.Printf("  Validating against schema.json: ❌")
+			log.Printf("  Validating against server.schema.json: ❌")
 			log.Printf("    Error: %v", err)
 		} else {
-			log.Printf("  Validating against schema.json: ✅")
+			log.Printf("  Validating against server.schema.json: ✅")
 			baseValid = true
 		}
 
@@ -168,14 +168,14 @@ func compileSchema(path string) (*jsonschema.Schema, error) {
 
 	// For registry-schema.json, we need to register the base schema it references
 	if strings.Contains(path, "registry-schema.json") {
-		basePath := filepath.Join(filepath.Dir(path), "schema.json")
+		basePath := filepath.Join(filepath.Dir(path), "server.schema.json")
 		baseData, err := os.ReadFile(basePath)
 		if err != nil {
 			return nil, fmt.Errorf("failed to read base schema: %w", err)
 		}
 
 		// Add the base schema to the compiler with the expected URL
-		if err := compiler.AddResource("https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json", bytes.NewReader(baseData)); err != nil {
+		if err := compiler.AddResource("https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json", bytes.NewReader(baseData)); err != nil {
 			return nil, fmt.Errorf("failed to add base schema resource: %w", err)
 		}
 	}

tools/validate-schemas/main.go

@@ -1,4 +1,4 @@
-// validate-schemas validates that schema.json and registry-schema.json
+// validate-schemas validates that server.schema.json and registry-schema.json
 // are valid JSON Schema documents.
 //
 // For more information, see docs/server-json/README.md
@@ -31,7 +31,7 @@ func runValidation() error {
 		name string
 		path string
 	}{
-		{"schema.json", filepath.Join(basePath, "schema.json")},
+		{"server.schema.json", filepath.Join(basePath, "server.schema.json")},
 		{"registry-schema.json", filepath.Join(basePath, "registry-schema.json")},
 	}
 
@@ -74,14 +74,14 @@ func validateSchema(path string) error {
 
 	// For registry-schema.json, we need to register the base schema it references
 	if strings.Contains(path, "registry-schema.json") {
-		basePath := filepath.Join(filepath.Dir(path), "schema.json")
+		basePath := filepath.Join(filepath.Dir(path), "server.schema.json")
 		baseData, err := os.ReadFile(basePath)
 		if err != nil {
 			return fmt.Errorf("failed to read base schema: %w", err)
 		}
 
 		// Add the base schema to the compiler with the expected URL
-		if err := compiler.AddResource("https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json", bytes.NewReader(baseData)); err != nil {
+		if err := compiler.AddResource("https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json", bytes.NewReader(baseData)); err != nil {
 			return fmt.Errorf("failed to add base schema resource: %w", err)
 		}
 	}