a5f417b6f5Closes #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`
345 lines
No EOL
10 KiB
JSON
345 lines
No EOL
10 KiB
JSON
{
|
|
"$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",
|
|
"id"
|
|
],
|
|
"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",
|
|
"example": "1.0.2",
|
|
"description": "Equivalent of Implementation.version in MCP specification."
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
},
|
|
"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",
|
|
"value_hint"
|
|
],
|
|
"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
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
} |