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
This commit is contained in:
adam jones 2025-08-27 01:30:25 +01:00 • committed by GitHub
commit 5fb6ee2982
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 36 additions and 18 deletions

View file

@ -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)

View file

@ -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

View file

@ -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": {

View file

@ -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": {

View file

@ -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.

View file

@ -0,0 +1,368 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"title": "MCP Server Detail",
"$ref": "#/$defs/ServerDetail",
"$defs": {
"Repository": {
"type": "object",
"required": [
"url",
"source"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"example": "https://github.com/modelcontextprotocol/servers"
},
"source": {
"type": "string",
"description": "Repository hosting service",
"example": "github"
},
"id": {
"type": "string",
"example": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
}
}
},
"VersionDetail": {
"type": "object",
"description": "Version information for this server. Defined as an object to allow for downstream extensibility (e.g. release_date)",
"required": [
"version"
],
"properties": {
"version": {
"type": "string",
"maxLength": 255,
"example": "1.0.2",
"description": "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification. Non-semantic versions are allowed but may not sort predictably."
}
}
},
"Server": {
"type": "object",
"required": [
"name",
"description",
"version_detail"
],
"properties": {
"name": {
"type": "string",
"description": "Server name/identifier",
"example": "io.modelcontextprotocol/filesystem"
},
"description": {
"type": "string",
"description": "Human-readable description of the server's functionality",
"example": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
},
"status": {
"type": "string",
"enum": ["active", "deprecated"],
"default": "active",
"description": "Server lifecycle status. 'deprecated' indicates the server is no longer recommended for new usage."
},
"repository": {
"$ref": "#/$defs/Repository"
},
"version_detail": {
"$ref": "#/$defs/VersionDetail"
}
}
},
"Package": {
"type": "object",
"required": [
"registry_name",
"name",
"version"
],
"properties": {
"registry_name": {
"type": "string",
"description": "Package registry type",
"example": "npm"
},
"name": {
"type": "string",
"description": "Package name in the registry",
"example": "io.modelcontextprotocol/filesystem"
},
"version": {
"type": "string",
"description": "Package version",
"example": "1.0.2"
},
"runtime_hint": {
"type": "string",
"description": "A hint to help clients determine the appropriate runtime for the package. This field should be provided when `runtime_arguments` are present.",
"examples": [
"npx",
"uvx",
"dnx"
]
},
"runtime_arguments": {
"type": "array",
"description": "A list of arguments to be passed to the package's runtime command (such as docker or npx). The `runtime_hint` field should be provided when `runtime_arguments` are present.",
"items": {
"$ref": "#/$defs/Argument"
}
},
"package_arguments": {
"type": "array",
"description": "A list of arguments to be passed to the package's binary.",
"items": {
"$ref": "#/$defs/Argument"
}
},
"environment_variables": {
"type": "array",
"description": "A mapping of environment variables to be set when running the package.",
"items": {
"$ref": "#/$defs/KeyValueInput"
}
}
}
},
"Input": {
"type": "object",
"properties": {
"description": {
"description": "A description of the input, which clients can use to provide context to the user.",
"type": "string"
},
"is_required": {
"type": "boolean",
"default": false
},
"format": {
"type": "string",
"description": "Specifies the input format. Supported values include `filepath`, which should be interpreted as a file on the user's filesystem.\n\nWhen the input is converted to a string, booleans should be represented by the strings \"true\" and \"false\", and numbers should be represented as decimal values.",
"enum": [
"string",
"number",
"boolean",
"filepath"
],
"default": "string"
},
"value": {
"type": "string",
"description": "The default value for the input. If this is not set, the user may be prompted to provide a value. If a value is set, it should not be configurable by end users.\n\nIdentifiers wrapped in `{curly_braces}` will be replaced with the corresponding properties from the input `variables` map. If an identifier in braces is not found in `variables`, or if `variables` is not provided, the `{curly_braces}` substring should remain unchanged.\n"
},
"is_secret": {
"type": "boolean",
"description": "Indicates whether the input is a secret value (e.g., password, token). If true, clients should handle the value securely.",
"default": false
},
"default": {
"type": "string",
"description": "The default value for the input."
},
"choices": {
"type": "array",
"description": "A list of possible values for the input. If provided, the user must select one of these values.",
"items": {
"type": "string"
},
"example": []
}
}
},
"InputWithVariables": {
"allOf": [
{
"$ref": "#/$defs/Input"
},
{
"type": "object",
"properties": {
"variables": {
"type": "object",
"description": "A map of variable names to their values. Keys in the input `value` that are wrapped in `{curly_braces}` will be replaced with the corresponding variable values.",
"additionalProperties": {
"$ref": "#/$defs/Input"
}
}
}
}
]
},
"PositionalArgument": {
"description": "A positional input is a value inserted verbatim into the command line.",
"allOf": [
{
"$ref": "#/$defs/InputWithVariables"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"positional"
],
"example": "positional"
},
"value_hint": {
"type": "string",
"description": "An identifier-like hint for the value. This is not part of the command line, but can be used by client configuration and to provide hints to users.",
"example": "file_path"
},
"is_repeated": {
"type": "boolean",
"description": "Whether the argument can be repeated multiple times in the command line.",
"default": false
}
},
"anyOf": [
{
"required": [
"value_hint"
]
},
{
"required": [
"value"
]
}
]
}
]
},
"NamedArgument": {
"description": "A command-line `--flag={value}`.",
"allOf": [
{
"$ref": "#/$defs/InputWithVariables"
},
{
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"named"
],
"example": "named"
},
"name": {
"type": "string",
"description": "The flag name, including any leading dashes.",
"example": "--port"
},
"is_repeated": {
"type": "boolean",
"description": "Whether the argument can be repeated multiple times.",
"default": false
}
}
}
]
},
"KeyValueInput": {
"allOf": [
{
"$ref": "#/$defs/InputWithVariables"
},
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the header or environment variable.",
"example": "SOME_VARIABLE"
}
}
}
]
},
"Argument": {
"anyOf": [
{
"$ref": "#/$defs/PositionalArgument"
},
{
"$ref": "#/$defs/NamedArgument"
}
]
},
"Remote": {
"type": "object",
"required": [
"transport_type",
"url"
],
"properties": {
"transport_type": {
"type": "string",
"enum": [
"streamable",
"sse"
],
"description": "Transport protocol type",
"example": "sse"
},
"url": {
"type": "string",
"format": "uri",
"description": "Remote server URL",
"example": "https://mcp-fs.example.com/sse"
},
"headers": {
"type": "array",
"description": "HTTP headers to include",
"items": {
"$ref": "#/$defs/KeyValueInput"
}
}
}
},
"ServerDetail": {
"description": "Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.",
"allOf": [
{
"$ref": "#/$defs/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": {
"$ref": "#/$defs/Package"
}
},
"remotes": {
"type": "array",
"items": {
"$ref": "#/$defs/Remote"
}
}
}
}
]
}
}
}

View file

@ -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:

View file

@ -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"`

View file

@ -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,

View file

@ -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",

View file

@ -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)
}
}

View file

@ -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)
}
}