Changes on the server.json format and the API (#562)
This commit is contained in:
Radoslav Dimitrov
GitHub
parent
4962609697
commit
b21c6f564d
1 changed files with 4056 additions and 5608 deletions
|
|
@ -1,9 +1,9 @@
|
|||
openapi: 3.1.0
|
||||
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
|
||||
$id: https://modelcontextprotocol.io/schemas/draft/2025-09-16/server-registry-openapi
|
||||
$id: https://modelcontextprotocol.io/schemas/draft/2025-09-29/server-registry-openapi
|
||||
info:
|
||||
title: MCP Server Registry API
|
||||
version: "2025-09-16"
|
||||
version: "2025-09-29"
|
||||
summary: API for discovering and accessing MCP server metadata
|
||||
description: |
|
||||
Specification for a theoretical REST API that serves up metadata about MCP servers.
|
||||
|
|
@ -19,7 +19,10 @@ paths:
|
|||
parameters:
|
||||
- name: cursor
|
||||
in: query
|
||||
description: Pagination cursor for retrieving next set of results
|
||||
description: |
|
||||
Pagination cursor for retrieving next set of results.
|
||||
|
||||
Cursors are opaque strings returned in the `metadata.nextCursor` field of paginated responses. Always use the exact cursor value returned by the API.
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -36,30 +39,25 @@ paths:
|
|||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ServerList'
|
||||
/v0/servers/{server_id}:
|
||||
/v0/servers/{serverName}:
|
||||
get:
|
||||
summary: Get MCP server details
|
||||
description: Returns detailed information about a specific MCP server. Returns latest version by default, or specific version if version query parameter is provided.
|
||||
description: Returns detailed information about the latest version of a specific MCP server.
|
||||
parameters:
|
||||
- name: server_id
|
||||
- name: serverName
|
||||
in: path
|
||||
required: true
|
||||
description: Unique server ID (consistent across all versions)
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
- name: version
|
||||
in: query
|
||||
description: Specific version to retrieve (e.g., "1.0.0"). If not provided, returns latest version.
|
||||
description: URL-encoded server name (e.g., "com.example%2Fmy-server")
|
||||
schema:
|
||||
type: string
|
||||
example: "com.example%2Fmy-server"
|
||||
responses:
|
||||
'200':
|
||||
description: Detailed server information
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ServerDetail'
|
||||
$ref: '#/components/schemas/ServerResponse'
|
||||
'404':
|
||||
description: Server not found
|
||||
content:
|
||||
|
|
@ -70,18 +68,18 @@ paths:
|
|||
error:
|
||||
type: string
|
||||
example: "Server not found"
|
||||
/v0/servers/{server_id}/versions:
|
||||
/v0/servers/{serverName}/versions:
|
||||
get:
|
||||
summary: List all versions of an MCP server
|
||||
description: Returns all available versions for a specific MCP server, ordered by publication date (newest first)
|
||||
parameters:
|
||||
- name: server_id
|
||||
- name: serverName
|
||||
in: path
|
||||
required: true
|
||||
description: Unique server ID (consistent across all versions)
|
||||
description: URL-encoded server name (e.g., "com.example%2Fmy-server")
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "com.example%2Fmy-server"
|
||||
responses:
|
||||
'200':
|
||||
description: A list of all versions for the server
|
||||
|
|
@ -99,6 +97,42 @@ paths:
|
|||
error:
|
||||
type: string
|
||||
example: "Server not found"
|
||||
/v0/servers/{serverName}/versions/{version}:
|
||||
get:
|
||||
summary: Get specific MCP server version
|
||||
description: Returns detailed information about a specific version of an MCP server.
|
||||
parameters:
|
||||
- name: serverName
|
||||
in: path
|
||||
required: true
|
||||
description: URL-encoded server name (e.g., "com.example%2Fmy-server")
|
||||
schema:
|
||||
type: string
|
||||
example: "com.example%2Fmy-server"
|
||||
- name: version
|
||||
in: path
|
||||
required: true
|
||||
description: URL-encoded version to retrieve (e.g., "1.0.0" or "1.0.0%2B20130313144700" for versions with build metadata)
|
||||
schema:
|
||||
type: string
|
||||
example: "1.0.0"
|
||||
responses:
|
||||
'200':
|
||||
description: Detailed server information
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ServerResponse'
|
||||
'404':
|
||||
description: Server or version not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
example: "Server not found"
|
||||
/v0/publish:
|
||||
post:
|
||||
summary: Publish MCP server (Optional)
|
||||
|
|
@ -122,7 +156,6 @@ paths:
|
|||
value:
|
||||
name: "io.modelcontextprotocol/filesystem"
|
||||
description: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
|
||||
status: "active"
|
||||
repository:
|
||||
url: "https://github.com/modelcontextprotocol/servers"
|
||||
source: "github"
|
||||
|
|
@ -136,7 +169,7 @@ paths:
|
|||
io.modelcontextprotocol.registry/publisher-provided:
|
||||
tool: "publisher-cli"
|
||||
version: "1.2.3"
|
||||
build_info:
|
||||
buildInfo:
|
||||
commit: "abc123def456"
|
||||
timestamp: "2023-12-01T10:30:00Z"
|
||||
example_org_server:
|
||||
|
|
@ -144,7 +177,6 @@ paths:
|
|||
value:
|
||||
name: "com.example/demo-server"
|
||||
description: "Example MCP server demonstrating publisher extensions."
|
||||
status: "active"
|
||||
repository:
|
||||
url: "https://github.com/example/mcp-demo"
|
||||
source: "github"
|
||||
|
|
@ -156,22 +188,22 @@ paths:
|
|||
version: "1.0.0"
|
||||
_meta:
|
||||
io.modelcontextprotocol.registry/publisher-provided:
|
||||
contact_email: "maintainer@example.com"
|
||||
build_metadata:
|
||||
contactEmail: "maintainer@example.com"
|
||||
buildMetadata:
|
||||
commit: "abc123"
|
||||
timestamp: "2024-01-15T10:30:00Z"
|
||||
com.example:
|
||||
marketplace_icon: "https://example.com/icon.png"
|
||||
marketplaceIcon: "https://example.com/icon.png"
|
||||
category: ["software_development"]
|
||||
documentation_url: "https://docs.example.org"
|
||||
verified_publisher: true
|
||||
documentationUrl: "https://docs.example.org"
|
||||
verifiedPublisher: true
|
||||
responses:
|
||||
'200':
|
||||
description: Successfully published server
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ServerDetail'
|
||||
$ref: '#/components/schemas/ServerResponse'
|
||||
'401':
|
||||
description: Unauthorized - Invalid or missing authentication token
|
||||
content:
|
||||
|
|
@ -250,12 +282,6 @@ components:
|
|||
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."
|
||||
example: "active"
|
||||
repository:
|
||||
$ref: '#/components/schemas/Repository'
|
||||
version:
|
||||
|
|
@ -277,13 +303,15 @@ components:
|
|||
servers:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/ServerDetail'
|
||||
$ref: '#/components/schemas/ServerResponse'
|
||||
metadata:
|
||||
type: object
|
||||
properties:
|
||||
next_cursor:
|
||||
nextCursor:
|
||||
type: string
|
||||
description: Cursor for next page of results
|
||||
description: |
|
||||
Pagination cursor for retrieving the next page of results.
|
||||
Use this exact value in the `cursor` query parameter of your next request. If null or empty, there are no more results.
|
||||
count:
|
||||
type: integer
|
||||
description: Number of items in current page
|
||||
|
|
@ -491,7 +519,7 @@ components:
|
|||
type: string
|
||||
format: uri
|
||||
description: JSON Schema URI for this server.json format
|
||||
example: "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json"
|
||||
example: "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"
|
||||
packages:
|
||||
type: array
|
||||
items:
|
||||
|
|
@ -511,43 +539,46 @@ components:
|
|||
example:
|
||||
tool: "publisher-cli"
|
||||
version: "1.2.3"
|
||||
build_info:
|
||||
buildInfo:
|
||||
commit: "abc123def456"
|
||||
timestamp: "2023-12-01T10:30:00Z"
|
||||
pipeline_id: "build-789"
|
||||
io.modelcontextprotocol.registry/official:
|
||||
type: object
|
||||
description: Registry-specific metadata managed by the MCP registry system
|
||||
required:
|
||||
- serverId
|
||||
- versionId
|
||||
- publishedAt
|
||||
- updatedAt
|
||||
- isLatest
|
||||
properties:
|
||||
serverId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Consistent ID across all versions of a server
|
||||
example: "550e8400-e29b-41d4-a716-446655440000"
|
||||
versionId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Unique ID for this specific version
|
||||
example: "773f9b2e-1a47-4c8d-b5e6-2f8d9c4a7b3e"
|
||||
publishedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Timestamp when the server was first published to the registry
|
||||
example: "2023-12-01T10:30:00Z"
|
||||
updatedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Timestamp when the server entry was last updated
|
||||
example: "2023-12-01T11:00:00Z"
|
||||
isLatest:
|
||||
type: boolean
|
||||
description: Whether this is the latest version of the server
|
||||
example: true
|
||||
additionalProperties: false
|
||||
additionalProperties: true
|
||||
pipelineId: "build-789"
|
||||
|
||||
ServerResponse:
|
||||
description: API response format with separated server data and registry metadata
|
||||
type: object
|
||||
required:
|
||||
- server
|
||||
- _meta
|
||||
properties:
|
||||
server:
|
||||
$ref: '#/components/schemas/ServerDetail'
|
||||
_meta:
|
||||
type: object
|
||||
description: Registry-managed metadata
|
||||
properties:
|
||||
io.modelcontextprotocol.registry/official:
|
||||
type: object
|
||||
description: Official MCP registry metadata
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
enum: ["active", "deprecated", "deleted"]
|
||||
description: Server lifecycle status
|
||||
example: "active"
|
||||
publishedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Timestamp when the server was first published to the registry
|
||||
example: "2023-12-01T10:30:00Z"
|
||||
updatedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Timestamp when the server entry was last updated
|
||||
example: "2023-12-01T11:00:00Z"
|
||||
isLatest:
|
||||
type: boolean
|
||||
description: Whether this is the latest version of the server
|
||||
example: true
|
||||
additionalProperties: false
|
||||
additionalProperties: true
|
||||
|
|
|
|||
Loading…
Reference in a new issue