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
GitHub
parent
923b2e07b9
commit
5fb6ee2982
1 changed files with 36 additions and 18 deletions
|
|
@ -1,362 +0,0 @@
|
|||
{
|
||||
"$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": {
|
||||
"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": {
|
||||
"packages": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/Package"
|
||||
}
|
||||
},
|
||||
"remotes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/Remote"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue