feat: add server.schema.json for MCP registry schema versioning (#1)
Add JSON schema file for MCP server.json format to enable schema versioning and IDE support. This schema will be served at https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json to support the $schema property added in modelcontextprotocol/registry#308. The hosted schema enables: - Self-describing server.json files - IDE validation and autocomplete - Version tracking for schema evolution - Better tooling integration Supports modelcontextprotocol/registry#308
This commit is contained in:
adam jones
GitHub
parent
4c3c434b94
commit
f1cd60bb88
1 changed files with 368 additions and 0 deletions
368
schemas/2025-07-09/server.schema.json
Normal file
368
schemas/2025-07-09/server.schema.json
Normal 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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue