f1cd60bb88Add 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
368 lines
No EOL
11 KiB
JSON
368 lines
No EOL
11 KiB
JSON
{
|
|
"$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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
} |