OpenAPI spec for official registry API (#3)
First (incomplete) cut of OpenAPI spec for registry API. To be continued in separate issues.
This commit is contained in:
Tadas Antanavicius
GitHub
parent
d3b607b18b
commit
b005e9c09a
2 changed files with 728 additions and 0 deletions
383
api/README.md
Normal file
383
api/README.md
Normal file
|
|
@ -0,0 +1,383 @@
|
|||
# Examples
|
||||
|
||||
## /v0/servers
|
||||
|
||||
### Request
|
||||
|
||||
```http
|
||||
GET /v0/servers?limit=5000&offset=0
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
|
||||
"name": "@modelcontextprotocol/servers/src/filesystem",
|
||||
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
|
||||
"repository": {
|
||||
"url": "https://github.com/modelcontextprotocol/servers",
|
||||
"source": "github",
|
||||
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
|
||||
},
|
||||
"version_detail": {
|
||||
"version": "1.0.2",
|
||||
"release_date": "2023-06-15T10:30:00Z",
|
||||
"is_latest": true
|
||||
}
|
||||
}
|
||||
],
|
||||
"next": "https://registry.modelcontextprotocol.io/servers?offset=50",
|
||||
"total_count": 1
|
||||
}
|
||||
```
|
||||
|
||||
## /v0/servers/:id
|
||||
|
||||
### Request
|
||||
|
||||
```http
|
||||
GET /v0/servers/a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1?version=0.0.3
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
|
||||
"name": "@modelcontextprotocol/servers/src/filesystem",
|
||||
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
|
||||
"repository": {
|
||||
"url": "https://github.com/modelcontextprotocol/servers",
|
||||
"source": "github",
|
||||
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
|
||||
},
|
||||
"version_detail": {
|
||||
"version": "1.0.2",
|
||||
"release_date": "2023-06-15T10:30:00Z",
|
||||
"is_latest": true
|
||||
},
|
||||
"package_canonical": "npm",
|
||||
"packages": [
|
||||
{
|
||||
"registry_name": "npm",
|
||||
"name": "@modelcontextprotocol/server-filesystem",
|
||||
"version": "1.0.2",
|
||||
"command": {
|
||||
"name": "npx",
|
||||
"subcommands": [],
|
||||
"positional_arguments": [
|
||||
{
|
||||
"position": 0,
|
||||
"name": "package",
|
||||
"description": "NPM package name",
|
||||
"default_value": "@modelcontextprotocol/server-filesystem",
|
||||
"is_required": true,
|
||||
"is_editable": false,
|
||||
"is_repeatable": false,
|
||||
"choices": []
|
||||
},
|
||||
{
|
||||
"position": 1,
|
||||
"name": "path",
|
||||
"description": "Path to access",
|
||||
"default_value": "/Users/username/Desktop",
|
||||
"is_required": true,
|
||||
"is_editable": true,
|
||||
"is_repeatable": true,
|
||||
"choices": []
|
||||
}
|
||||
],
|
||||
"named_arguments": [
|
||||
{
|
||||
"short_flag": "-y",
|
||||
"requires_value": false,
|
||||
"is_required": false,
|
||||
"is_editable": false,
|
||||
"description": "Skip prompts and automatically answer yes",
|
||||
"choices": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"environment_variables": [
|
||||
{
|
||||
"name": "LOG_LEVEL",
|
||||
"description": "Logging level (debug, info, warn, error)",
|
||||
"required": false,
|
||||
"default_value": "info"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "docker",
|
||||
"package_name": "mcp/filesystem",
|
||||
"version": "1.0.2",
|
||||
"command": {
|
||||
"name": "docker",
|
||||
"subcommands": [
|
||||
{
|
||||
"name": "run",
|
||||
"description": "Run the Docker container",
|
||||
"is_required": true,
|
||||
"subcommands": [],
|
||||
"positional_arguments": [],
|
||||
"named_arguments": [
|
||||
{
|
||||
"short_flag": "-i",
|
||||
"requires_value": false,
|
||||
"is_required": true,
|
||||
"is_editable": false,
|
||||
"description": "Run in interactive mode"
|
||||
},
|
||||
{
|
||||
"long_flag": "--rm",
|
||||
"requires_value": false,
|
||||
"is_required": true,
|
||||
"is_editable": false,
|
||||
"description": "Remove container when it exits"
|
||||
},
|
||||
{
|
||||
"long_flag": "--mount",
|
||||
"requires_value": true,
|
||||
"is_required": true,
|
||||
"is_repeatable": true,
|
||||
"is_editable": true,
|
||||
"description": "Mount a volume into the container",
|
||||
"default_value": "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
|
||||
"choices": []
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"positional_arguments": [
|
||||
{
|
||||
"position": 0,
|
||||
"name": "image",
|
||||
"description": "Docker image name",
|
||||
"default_value": "mcp/filesystem",
|
||||
"is_required": true,
|
||||
"is_editable": false,
|
||||
"is_repeatable": false,
|
||||
"choices": []
|
||||
},
|
||||
{
|
||||
"position": 1,
|
||||
"name": "root_path",
|
||||
"description": "Root path for filesystem access",
|
||||
"default_value": "/projects",
|
||||
"is_required": true,
|
||||
"is_editable": false,
|
||||
"is_repeatable": false,
|
||||
"choices": []
|
||||
}
|
||||
],
|
||||
"named_arguments": []
|
||||
},
|
||||
"environment_variables": [
|
||||
{
|
||||
"name": "LOG_LEVEL",
|
||||
"description": "Logging level (debug, info, warn, error)",
|
||||
"required": false,
|
||||
"default_value": "info"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"remotes": [
|
||||
{
|
||||
"transport_type": "sse",
|
||||
"url": "https://mcp-fs.example.com/sse"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Server Configuration Examples
|
||||
|
||||
#### Local Server with npx
|
||||
|
||||
API Response:
|
||||
```json
|
||||
{
|
||||
"id": "brave-search-12345",
|
||||
"name": "@modelcontextprotocol/server-brave-search",
|
||||
"description": "MCP server for Brave Search API integration",
|
||||
"repository": {
|
||||
"url": "https://github.com/modelcontextprotocol/servers",
|
||||
"source": "github",
|
||||
"id": "abc123de-f456-7890-ghij-klmnopqrstuv"
|
||||
},
|
||||
"version_detail": {
|
||||
"version": "1.0.2",
|
||||
"release_date": "2023-06-15T10:30:00Z",
|
||||
"is_latest": true
|
||||
},
|
||||
"package_canonical": "npm",
|
||||
"packages": [
|
||||
{
|
||||
"registry_name": "npm",
|
||||
"name": "@modelcontextprotocol/server-brave-search",
|
||||
"version": "1.0.2",
|
||||
"command": {
|
||||
"name": "npx",
|
||||
"subcommands": [],
|
||||
"positional_arguments": [],
|
||||
"named_arguments": [
|
||||
{
|
||||
"short_flag": "-y",
|
||||
"requires_value": false,
|
||||
"is_required": false,
|
||||
"description": "Skip prompts"
|
||||
}
|
||||
]
|
||||
},
|
||||
"environment_variables": [
|
||||
{
|
||||
"name": "BRAVE_API_KEY",
|
||||
"description": "Brave Search API Key",
|
||||
"required": true,
|
||||
"default_value": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
claude_desktop_config.json:
|
||||
```json
|
||||
{
|
||||
"brave-search": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-brave-search"
|
||||
],
|
||||
"env": {
|
||||
"BRAVE_API_KEY": "YOUR_API_KEY_HERE"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Local Server with Docker
|
||||
|
||||
API Response:
|
||||
```json
|
||||
{
|
||||
"id": "filesystem-67890",
|
||||
"name": "@modelcontextprotocol/servers/src/filesystem",
|
||||
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations",
|
||||
"repository": {
|
||||
"url": "https://github.com/modelcontextprotocol/servers",
|
||||
"source": "github",
|
||||
"id": "d94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
|
||||
},
|
||||
"version_detail": {
|
||||
"version": "1.0.2",
|
||||
"release_date": "2023-06-15T10:30:00Z",
|
||||
"is_latest": true
|
||||
},
|
||||
"package_canonical": "docker",
|
||||
"packages": [
|
||||
{
|
||||
"registry_name": "docker",
|
||||
"name": "mcp/filesystem",
|
||||
"version": "1.0.2",
|
||||
"command": {
|
||||
"name": "docker",
|
||||
"subcommands": [
|
||||
{
|
||||
"name": "run",
|
||||
"description": "Run the Docker container",
|
||||
"is_required": true,
|
||||
"named_arguments": [
|
||||
{
|
||||
"short_flag": "-i",
|
||||
"requires_value": false,
|
||||
"is_required": true,
|
||||
"description": "Run in interactive mode"
|
||||
},
|
||||
{
|
||||
"long_flag": "--rm",
|
||||
"requires_value": false,
|
||||
"is_required": true,
|
||||
"description": "Remove container when it exits"
|
||||
},
|
||||
{
|
||||
"long_flag": "--mount",
|
||||
"requires_value": true,
|
||||
"is_required": true,
|
||||
"is_repeatable": true,
|
||||
"description": "Mount a volume into the container"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"positional_arguments": [
|
||||
{
|
||||
"position": 0,
|
||||
"name": "image",
|
||||
"description": "Docker image name",
|
||||
"default_value": "mcp/filesystem"
|
||||
},
|
||||
{
|
||||
"position": 1,
|
||||
"name": "root_path",
|
||||
"description": "Root path for filesystem access",
|
||||
"default_value": "/projects"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
claude_desktop_config.json:
|
||||
```json
|
||||
{
|
||||
"filesystem": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
|
||||
"--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
|
||||
"--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
|
||||
"mcp/filesystem",
|
||||
"/projects"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Remote Server
|
||||
|
||||
API Response:
|
||||
```json
|
||||
{
|
||||
"id": "remote-fs-54321",
|
||||
"name": "Remote Brave Search Server",
|
||||
"description": "Cloud-hosted MCP Brave Search server",
|
||||
"repository": {
|
||||
"url": "https://github.com/example/remote-fs",
|
||||
"source": "github",
|
||||
"id": "xyz789ab-cdef-0123-4567-890ghijklmno"
|
||||
},
|
||||
"version_detail": {
|
||||
"version": "1.0.2",
|
||||
"release_date": "2023-06-15T10:30:00Z",
|
||||
"is_latest": true
|
||||
},
|
||||
"remotes": [
|
||||
{
|
||||
"transport_type": "sse",
|
||||
"url": "https://mcp-fs.example.com/sse"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
345
api/openapi.yaml
Normal file
345
api/openapi.yaml
Normal file
|
|
@ -0,0 +1,345 @@
|
|||
openapi: 3.1.0
|
||||
info:
|
||||
title: MCP Server Registry API
|
||||
summary: API for discovering and accessing MCP servers metadata
|
||||
description: |
|
||||
REST API that centralizes metadata about publicly available MCP servers by allowing server creators to submit
|
||||
and maintain metadata about their servers in a standardized format. This API enables MCP client
|
||||
applications and "server aggregator" type consumers to discover and install MCP servers.
|
||||
version: 0.0.1
|
||||
contact:
|
||||
name: MCP Community Working Group
|
||||
license:
|
||||
name: MIT
|
||||
identifier: MIT
|
||||
servers:
|
||||
# TODO: Still think a unique name would be better; maybe we open a public discussion on the topic and let people submit ideas?
|
||||
- url: https://registry.modelcontextprotocol.io
|
||||
description: MCP Server Registry
|
||||
# TODO: Webhooks here would be interesting, but out of scope for MVP
|
||||
|
||||
paths:
|
||||
/v0/servers:
|
||||
get:
|
||||
summary: List MCP servers
|
||||
description: Returns a list of all registered MCP servers
|
||||
parameters:
|
||||
- name: limit
|
||||
in: query
|
||||
description: Number of results per page (maximum 5000)
|
||||
schema:
|
||||
type: integer
|
||||
default: 5000
|
||||
maximum: 5000
|
||||
minimum: 1
|
||||
- name: offset
|
||||
in: query
|
||||
description: Number of results to skip for pagination
|
||||
schema:
|
||||
type: integer
|
||||
default: 0
|
||||
minimum: 0
|
||||
responses:
|
||||
'200':
|
||||
description: A list of MCP servers
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ServerList'
|
||||
/v0/servers/{id}:
|
||||
get:
|
||||
summary: Get MCP server details
|
||||
description: Returns detailed information about a specific MCP server
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
description: Unique ID of the server
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
- name: version
|
||||
in: query
|
||||
description: Desired MCP server version
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Detailed server information
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ServerDetail'
|
||||
'404':
|
||||
description: Server not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
example: "Server not found"
|
||||
components:
|
||||
schemas:
|
||||
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
|
||||
Repository:
|
||||
type: object
|
||||
required:
|
||||
- url
|
||||
- source
|
||||
- id
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
example: "https://github.com/modelcontextprotocol/servers"
|
||||
source:
|
||||
type: string
|
||||
enum: [github, gitlab] # TODO: Add all supported sources as a whitelist
|
||||
example: "github"
|
||||
id:
|
||||
type: string
|
||||
example: "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
|
||||
|
||||
Server:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
- description
|
||||
- repository
|
||||
- version_detail
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1"
|
||||
name:
|
||||
type: string
|
||||
example: "@modelcontextprotocol/servers/src/filesystem"
|
||||
description:
|
||||
type: string
|
||||
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
|
||||
repository:
|
||||
$ref: '#/components/schemas/Repository'
|
||||
version_detail:
|
||||
type: object
|
||||
required:
|
||||
- version
|
||||
- release_date
|
||||
- is_latest
|
||||
properties:
|
||||
version:
|
||||
type: string
|
||||
example: "1.0.2"
|
||||
description: Equivalent of Implementation.version in MCP specification.
|
||||
release_date:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2023-06-15T10:30:00Z"
|
||||
description: Datetime that the MCP server version was published to the registry.
|
||||
is_latest:
|
||||
type: boolean
|
||||
example: true
|
||||
description: Whether the MCP server version is the latest version available in the registry.
|
||||
$schema: "https://json-schema.org/draft/2020-12/schema"
|
||||
|
||||
ServerList:
|
||||
type: object
|
||||
required:
|
||||
- servers
|
||||
- total_count
|
||||
properties:
|
||||
servers:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Server'
|
||||
next:
|
||||
type: string
|
||||
format: uri
|
||||
example: "https://registry.modelcontextprotocol.io/servers?offset=50"
|
||||
total_count:
|
||||
type: integer
|
||||
example: 1
|
||||
|
||||
Argument:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- description
|
||||
- is_required
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
example: "path"
|
||||
description:
|
||||
type: string
|
||||
example: "Path to access"
|
||||
is_required:
|
||||
type: boolean
|
||||
example: true
|
||||
is_repeatable:
|
||||
type: boolean
|
||||
example: false
|
||||
is_editable:
|
||||
type: boolean
|
||||
example: true
|
||||
choices:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: []
|
||||
default_value:
|
||||
type: string
|
||||
example: "/Users/username/Desktop"
|
||||
|
||||
PositionalArgument:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/Argument'
|
||||
- type: object
|
||||
required:
|
||||
- position
|
||||
properties:
|
||||
position:
|
||||
type: integer
|
||||
example: 1
|
||||
|
||||
NamedArgument:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/Argument'
|
||||
- type: object
|
||||
properties:
|
||||
short_flag:
|
||||
type: string
|
||||
example: "-y"
|
||||
long_flag:
|
||||
type: string
|
||||
example: "--mount"
|
||||
requires_value:
|
||||
type: boolean
|
||||
example: true
|
||||
|
||||
Subcommand:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- description
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
example: "run"
|
||||
description:
|
||||
type: string
|
||||
example: "Run the Docker container"
|
||||
is_required:
|
||||
type: boolean
|
||||
example: true
|
||||
subcommands:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Subcommand'
|
||||
positional_arguments:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/PositionalArgument'
|
||||
named_arguments:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/NamedArgument'
|
||||
|
||||
Command:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
enum: [npx, docker, pypi, uvx] # TODO: Add all supported commands as a whitelist
|
||||
example: "npx"
|
||||
subcommands:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Subcommand'
|
||||
positional_arguments:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/PositionalArgument'
|
||||
named_arguments:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/NamedArgument'
|
||||
|
||||
EnvironmentVariable:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- description
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
example: "LOG_LEVEL"
|
||||
description:
|
||||
type: string
|
||||
example: "Logging level (debug, info, warn, error)"
|
||||
required:
|
||||
type: boolean
|
||||
example: false
|
||||
default_value:
|
||||
type: string
|
||||
example: "info"
|
||||
|
||||
Package:
|
||||
type: object
|
||||
required:
|
||||
- registry_name
|
||||
- name
|
||||
- version
|
||||
properties:
|
||||
registry_name:
|
||||
type: string
|
||||
enum: [npm, docker, pypi, homebrew]
|
||||
example: "npm"
|
||||
name:
|
||||
type: string
|
||||
example: "@modelcontextprotocol/server-filesystem"
|
||||
version:
|
||||
type: string
|
||||
example: "1.0.2"
|
||||
command:
|
||||
$ref: '#/components/schemas/Command'
|
||||
environment_variables:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/EnvironmentVariable'
|
||||
|
||||
Remote:
|
||||
type: object
|
||||
required:
|
||||
- transport_type
|
||||
- url
|
||||
properties:
|
||||
transport_type:
|
||||
type: string
|
||||
enum: [streamable, sse]
|
||||
example: "sse"
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
example: "https://mcp-fs.example.com/sse"
|
||||
|
||||
ServerDetail:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/Server'
|
||||
- type: object
|
||||
properties:
|
||||
package_canonical:
|
||||
type: string
|
||||
enum: [npm, docker, pypi, crates]
|
||||
example: "npm"
|
||||
packages:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Package'
|
||||
remotes:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Remote'
|
||||
Loading…
Reference in a new issue