From a5f417b6f5b518f34e623a5262c38c38ababeba0 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Wed, 9 Jul 2025 14:02:43 -0700 Subject: [PATCH] Split "general" server.json from "registry-specific" server.json (#167) Closes #155 The "generalized" `server.json` is the one that can be used in a variety of situations: - Discoverability on a centralized registry (i.e. our official Registry work) - Discoverability on a decentralized .well-known endpoint - As a response to an initialization call, so the client knows information about the MCP server to which it is connecting - As an input into crafting a [DXT file](https://www.anthropic.com/engineering/desktop-extensions) - Packaged in with the source code of an MCP server, so as to have a structured way context Of these, the official Registry is but one use case. The Registry has a unique set of concerns for which we are optimizing, like whitelisting of specific registries we trust to host MCP server source code for the public community (`npm`, `pypi`, etc). It is not necessary to have such a constraint for the generalized server.json, which may be used in, for example, an internal context where such a validation doesn't make sense. So I've done the following at a high level: - Renamed the prior `schema.json` to be `registry-schema.json` - Introduced a more generic `schema.json` to serve as the schema for the generalized `server.json` - Refactored `registry-schema.json` to be simply a constraint on the base `schema.json` I made a few small changes in this transition: - Removed `gitlab` as an option in `repository.source` for `registry-schema.json`. I'm fine going live with just GitHub support; would be happy to take a contribution from e.g. Gitlab employees or a motivated Gitlab customer to expand anytime. - Removed `homebrew` as an option in `packages.registry_name`; never really made sense, not a place where folks are publishing MCP servers - Added `docker` to `packages.runtime_hint`; was just a missing oversight - Gave both schemas a global `$id` ~- Removed `release_date` from both schemas. Certainly not something that makes sense for the generalized schema. It actually doesn't make sense for the Registry schema either, because this is the server.json that _users will submit_, i.e. the _input_ into the Registry publication API. `release_date` will be a piece of _output_ metadata. The Registry API will be free to append such extra metadata for GET /:id requests of servers, and the data can be present in the OpenAPI spec, but it does not need to be in the registry-server.json JSON schema.~ - Note this is no longer in this PR; rebased on #168 which included it - Removed unnecessary enums from the generalized `schema.json` --- docs/server-json/README.md | 3 +- docs/server-json/registry-schema.json | 40 +++++++++++++++++++++++++++ docs/server-json/schema.json | 14 ++-------- 3 files changed, 45 insertions(+), 12 deletions(-) create mode 100644 docs/server-json/registry-schema.json diff --git a/docs/server-json/README.md b/docs/server-json/README.md index 6b8f6f1..b836133 100644 --- a/docs/server-json/README.md +++ b/docs/server-json/README.md @@ -13,4 +13,5 @@ Please note: this is different from the file commonly referred to as `mcp.json`, References: - [schema.json](./schema.json) - The official JSON schema specification for this representation -- [examples.md](./examples.md) - Example manifestations of the JSON schema \ No newline at end of file +- [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 diff --git a/docs/server-json/registry-schema.json b/docs/server-json/registry-schema.json new file mode 100644 index 0000000..5b57898 --- /dev/null +++ b/docs/server-json/registry-schema.json @@ -0,0 +1,40 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$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", + "properties": { + "repository": { + "properties": { + "source": { + "enum": [ + "github" + ] + } + } + }, + "packages": { + "items": { + "properties": { + "registry_name": { + "enum": [ + "npm", + "pypi", + "docker", + "nuget" + ] + }, + "runtime_hint": { + "enum": [ + "npx", + "uvx", + "docker", + "dnx" + ] + } + } + } + } + } +} \ No newline at end of file diff --git a/docs/server-json/schema.json b/docs/server-json/schema.json index 207a8eb..122a9ab 100644 --- a/docs/server-json/schema.json +++ b/docs/server-json/schema.json @@ -1,5 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json", "title": "MCP Server Detail", "$ref": "#/$defs/ServerDetail", "$defs": { @@ -18,10 +19,7 @@ }, "source": { "type": "string", - "enum": [ - "github", - "gitlab" - ], + "description": "Repository hosting service", "example": "github" }, "id": { @@ -32,6 +30,7 @@ }, "VersionDetail": { "type": "object", + "description": "Version information for this server. Defined as an object to allow for downstream extensibility (e.g. release_date)", "required": [ "version" ], @@ -79,13 +78,6 @@ "properties": { "registry_name": { "type": "string", - "enum": [ - "npm", - "docker", - "pypi", - "homebrew", - "nuget" - ], "description": "Package registry type", "example": "npm" },