diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml index d183b9d3..2680619d 100644 --- a/docs/reference/api/openapi.yaml +++ b/docs/reference/api/openapi.yaml @@ -1,9 +1,9 @@ openapi: 3.1.0 jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema" -$id: https://modelcontextprotocol.io/schemas/draft/2025-09-29/server-registry-openapi +$id: https://modelcontextprotocol.io/schemas/draft/2025-10-11/server-registry-openapi info: title: MCP Server Registry API - version: "2025-09-29" + version: "2025-10-11" summary: API for discovering and accessing MCP server metadata description: | Specification for a theoretical REST API that serves up metadata about MCP servers. @@ -616,7 +616,7 @@ components: type: string format: uri description: JSON Schema URI for this server.json format - example: "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json" + example: "https://static.modelcontextprotocol.io/schemas/2025-10-11/server.schema.json" packages: type: array items: diff --git a/docs/reference/server-json/CHANGELOG.md b/docs/reference/server-json/CHANGELOG.md index f828ee8e..9e749887 100644 --- a/docs/reference/server-json/CHANGELOG.md +++ b/docs/reference/server-json/CHANGELOG.md @@ -2,6 +2,62 @@ Changes to the server.json schema and format. +## 2025-10-11 + +### Changed + +#### Package Format Enhancements ([#634](https://github.com/modelcontextprotocol/registry/pull/634)) + +The `Package` schema has been refactored to better support different package types with dedicated handling per registry type. + +**Key Changes:** + +- **`version` field is now optional** - Previously required for all packages, now only used by npm, pypi, and nuget. OCI packages include version in the identifier (e.g., `ghcr.io/owner/repo:v1.0.0`), and MCPB packages use direct download URLs. + +- **Enhanced documentation** - Added detailed comments explaining which fields are relevant for each `registryType`: + - **NPM/PyPI/NuGet**: Use `registryType`, `identifier` (package name), `version`, optional `registryBaseUrl` + - **OCI**: Use `registryType`, `identifier` (full image reference with tag) + - **MCPB**: Use `registryType`, `identifier` (download URL), `fileSha256` (required) + +- **Field clarifications**: + - `identifier`: Now clearly documented as package name for registries, full image reference for OCI, or download URL for MCPB + - `fileSha256`: Clarified as required for MCPB packages and optional for other types + - `registryBaseUrl`: Clarified as used by npm/pypi/nuget but not by oci/mcpb + +**Migration:** + +Publishers using OCI or MCPB packages can now omit the `version` field, as it's either embedded in the identifier (OCI) or not applicable (MCPB direct downloads). Publishers using npm, pypi, or nuget should continue to provide the `version` field as before. + +**Example - OCI Package (version in identifier):** +```json +{ + "packages": [{ + "registryType": "oci", + "identifier": "ghcr.io/modelcontextprotocol/server-example:v1.2.3", + "transport": { + "type": "stdio" + } + }] +} +``` + +**Example - MCPB Package (no version field):** +```json +{ + "packages": [{ + "registryType": "mcpb", + "identifier": "https://github.com/example/releases/download/v1.0.0/package.mcpb", + "fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce", + "transport": { + "type": "stdio" + } + }] +} +``` + +### Schema Version +- Schema version: `2025-09-29` → `2025-10-11` + ## 2025-09-29 ### ⚠️ BREAKING CHANGES diff --git a/docs/reference/server-json/server.schema.json b/docs/reference/server-json/server.schema.json index bcd76439..8022347a 100644 --- a/docs/reference/server-json/server.schema.json +++ b/docs/reference/server-json/server.schema.json @@ -1,6 +1,6 @@ { "$comment": "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.", - "$id": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json", + "$id": "https://static.modelcontextprotocol.io/schemas/2025-10-11/server.schema.json", "$ref": "#/definitions/ServerDetail", "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { @@ -373,7 +373,7 @@ "properties": { "$schema": { "description": "JSON Schema URI for this server.json format", - "example": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json", + "example": "https://static.modelcontextprotocol.io/schemas/2025-10-11/server.schema.json", "format": "uri", "type": "string" }, diff --git a/tools/extract-server-schema/main.go b/tools/extract-server-schema/main.go index 42f3af1c..a554e252 100644 --- a/tools/extract-server-schema/main.go +++ b/tools/extract-server-schema/main.go @@ -33,6 +33,16 @@ func main() { log.Fatalf("Failed to parse OpenAPI YAML: %v", err) } + // Extract version from info section + info, ok := openapi["info"].(map[string]interface{}) + if !ok { + log.Fatal("Missing 'info' in OpenAPI spec") + } + version, ok := info["version"].(string) + if !ok { + log.Fatal("Missing 'info.version' in OpenAPI spec") + } + // Extract components/schemas components, ok := openapi["components"].(map[string]interface{}) if !ok { @@ -78,11 +88,12 @@ func main() { } } - // Build the JSON Schema document + // Build the JSON Schema document with dynamic version from OpenAPI spec + schemaID := fmt.Sprintf("https://static.modelcontextprotocol.io/schemas/%s/server.schema.json", version) 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", + "$id": schemaID, "title": "server.json defining a Model Context Protocol (MCP) server", "$ref": "#/definitions/ServerDetail", "definitions": definitions,