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

domdomegg · web-flow · commit 5fb6ee298204 · 2025-08-27T01:30:25.000+01:00
## 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
diff --git a/docs/new_package_registry.md b/docs/new_package_registry.md
@@ -4,7 +4,7 @@ The MCP Registry project is a **metaregistry**, meaning that it hosts metadata f
 
 For local MCP servers, the MCP Registry has pointers in the `packages` node of the [`server.json`](server-json/README.md) schema that refer to packages in supported package managers.
 
-The list of supported package managers for hosting MCP servers is defined by the `properties.packages[N].properties.registry_name` string enum in the [`server.json` schema](server-json/schema.json). For example, this could be "npm" (for npmjs.com packages) or "pypi" (for PyPI packages).
+The list of supported package managers for hosting MCP servers is defined by the `properties.packages[N].properties.registry_name` string enum in the [`server.json` schema](server-json/server.schema.json). For example, this could be "npm" (for npmjs.com packages) or "pypi" (for PyPI packages).
 
 For remote MCP servers, the package registry is not relevant. The MCP client consumes the server via a URL instead of by downloading and running a package. In other words, this document only applies to local MCP servers.
 
@@ -29,7 +29,7 @@ These steps are currently very brief because the MCP Registry service is not yet
 1. [Create a feature request issue](https://github.com/modelcontextprotocol/registry/issues/new?template=feature_request.md) on the MCP Registry repository to begin the discussion about adding the package registry.
    - Example for NuGet: https://github.com/modelcontextprotocol/registry/issues/126
 1. Open a PR with the following changes:
-   - Update the [`server.json` schema](server-json/schema.json)
+   - Update the [`server.json` schema](server-json/server.schema.json)
      - Add your package registry name to the `registry_name` enum value array.
      - Add the single-shot CLI command name to the `runtime_hint` example value array.
    - Update the [`openapi.yaml`](openapi.yaml)
diff --git a/docs/server-json/README.md b/docs/server-json/README.md
@@ -12,14 +12,14 @@ All of these scenarios (and more) would benefit from an agreed-upon, standardize
 Please note: this is different from the file commonly referred to as `mcp.json`, which is _an MCP client's configuration file for **running** a specific set of MCP servers_. See [this issue](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/292).
 
 References:
-- [schema.json](./schema.json) - The official JSON schema specification for this representation
+- [server.schema.json](./server.schema.json) - The official JSON schema specification for this representation
 - [examples.md](./examples.md) - Example manifestations of the JSON schema
-- [registry-schema.json](./registry-schema.json) - A more constrained version of `schema.json` that the official registry supports
+- [registry-schema.json](./registry-schema.json) - A more constrained version of `server.schema.json` that the official registry supports
 
 ## Validation Tools
 
 Two validation tools are provided in the repository's `tools/` directory:
-- **validate-schemas** - Validates that `schema.json` and `registry-schema.json` are valid JSON Schema documents
+- **validate-schemas** - Validates that `server.schema.json` and `registry-schema.json` are valid JSON Schema documents
 - **validate-examples** - Validates that all JSON examples in `examples.md` conform to both schemas
 
 ### Usage
diff --git a/docs/server-json/examples.md b/docs/server-json/examples.md
@@ -7,6 +7,7 @@ _These examples show the PublishRequest format used by the `/v0/publish` API end
 ```json
 {
   "server": {
+    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
     "name": "io.modelcontextprotocol/brave-search",
     "description": "MCP server for Brave Search API integration",
     "status": "active",
@@ -91,6 +92,7 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp
 ```json
 {
   "server": {
+    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
     "name": "com.github.modelcontextprotocol/filesystem",
     "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
     "status": "active",
@@ -418,6 +420,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
 ```json
 {
   "server": {
+    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
     "name": "io.modelcontextprotocol.anonymous/hybrid-mcp",
     "description": "MCP server available as both local package and remote service",
     "repository": {
diff --git a/docs/server-json/registry-schema.json b/docs/server-json/registry-schema.json
@@ -3,7 +3,7 @@
   "$id": "https://modelcontextprotocol.io/schemas/draft/2025-07-09/registry-server.json",
   "title": "MCP Server Detail - Registry Schema",
   "description": "Registry-specific constraints for MCP server representation. Extends the base schema with additional validation rules.",
-  "$ref": "https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json",
+  "$ref": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
   "properties": {
     "repository": {
       "properties": {
diff --git a/docs/server-json/repository_references.md b/docs/server-json/repository_references.md
@@ -1,6 +1,6 @@
 # Repository References in server.json
 
-The [`server.json` schema](schema.json) MAY contain a `repository` property at the root of the JSON object. The `repository` object provides metadata about the MCP server's source code. This enables users and security experts to inspect the code of the MCP service, thereby improving the transparency of what the MCP server is doing at runtime.
+The [`server.json` schema](server.schema.json) MAY contain a `repository` property at the root of the JSON object. The `repository` object provides metadata about the MCP server's source code. This enables users and security experts to inspect the code of the MCP service, thereby improving the transparency of what the MCP server is doing at runtime.
 
 The inclusion of the `repository` object is RECOMMENDED for both local and remote MCP servers.
 
diff --git a/docs/server-json/server.schema.json b/docs/server-json/server.schema.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json",
+  "$id": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
   "title": "MCP Server Detail",
   "$ref": "#/$defs/ServerDetail",
   "$defs": {
@@ -342,6 +342,12 @@
         {
           "type": "object",
           "properties": {
+            "$schema": {
+              "type": "string",
+              "format": "uri",
+              "description": "JSON Schema URI for this server.json format",
+              "example": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json"
+            },
             "packages": {
               "type": "array",
               "items": {
diff --git a/docs/server-registry-api/openapi.yaml b/docs/server-registry-api/openapi.yaml
@@ -450,6 +450,11 @@ components:
         - $ref: '#/components/schemas/Server'
         - type: object
           properties:
+            $schema:
+              type: string
+              format: uri
+              description: JSON Schema URI for this server.json format
+              example: "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json"
             packages:
               type: array
               items:
diff --git a/internal/model/model.go b/internal/model/model.go
@@ -111,6 +111,7 @@ type VersionDetail struct {
 
 // ServerDetail represents complete server information as defined in the MCP spec (pure, no registry metadata)
 type ServerDetail struct {
+	Schema        string        `json:"$schema,omitempty" bson:"$schema,omitempty"`
 	Name          string        `json:"name" bson:"name"`
 	Description   string        `json:"description" bson:"description"`
 	Status        ServerStatus  `json:"status,omitempty" bson:"status,omitempty"`
diff --git a/tools/publisher/main.go b/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,
diff --git a/tools/publisher/server.json b/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",
diff --git a/tools/validate-examples/main.go b/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)
 		}
 	}
diff --git a/tools/validate-schemas/main.go b/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)
 		}
 	}

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`{`
	`2`	`+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",`
`2`	`3`	`"description": "<your description here>",`
`3`	`4`	`"name": "io.github.<owner>/<server-name>",`
`4`	`5`	`"status": "active",`