diff --git a/docs/new_package_registry.md b/docs/new_package_registry.md index 76be4dc..9d6d2da 100644 --- 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 index 527aed3..e579386 100644 --- 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 index 897906d..d4a76f3 100644 --- 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 index 5b57898..ad14e70 100644 --- 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 index 1b9034b..6e608c4 100644 --- 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/schema.json b/docs/server-json/server.schema.json similarity index 96% rename from docs/server-json/schema.json rename to docs/server-json/server.schema.json index 7d3982f..fd8c98b 100644 --- a/docs/server-json/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 index f3b5048..fc851ad 100644 --- 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 index dbcc23b..0e61d95 100644 --- 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 index 721aa6f..08d433d 100644 --- 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 index b495201..4b768a0 100644 --- 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": "", "name": "io.github./", "status": "active", diff --git a/tools/validate-examples/main.go b/tools/validate-examples/main.go index 7ff9bf4..f084248 100644 --- 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 index 4e10621..bc7f8b9 100644 --- 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) } }