From 0943c43d89be952f2d36c917e53d89265c7fe8a5 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 27 Nov 2025 17:51:28 +0000 Subject: [PATCH] docs: update API endpoint documentation from /v0/ to /v0.1/ Update user-facing documentation to use the stable /v0.1/ API version instead of the development /v0/ version, aligning with the API freeze announced in the CHANGELOG. Internal-only documentation (deploy/, admin-operations) left unchanged. --- docs/design/tech-architecture.md | 6 +++--- .../registry-aggregators.mdx | 4 ++-- docs/reference/api/generic-registry-api.md | 12 ++++++------ docs/reference/api/official-registry-api.md | 18 +++++++++--------- docs/reference/api/openapi.yaml | 8 ++++---- scripts/mirror_data/README.md | 2 +- 6 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/design/tech-architecture.md b/docs/design/tech-architecture.md index d163dff5..03097f78 100644 --- a/docs/design/tech-architecture.md +++ b/docs/design/tech-architecture.md @@ -177,7 +177,7 @@ sequenceDiagram Admin->>CLI: Request admin token CLI->>GCP: gcloud auth print-identity-token --audiences=mcp-registry GCP-->>CLI: ID Token (with hd: "modelcontextprotocol.io") - CLI->>API: POST /v0/auth/oidc {"oidc_token": "eyJ..."} + CLI->>API: POST /v0.1/auth/oidc {"oidc_token": "eyJ..."} API->>GCP: Verify token signature (JWKS) API->>API: Validate claims (issuer, audience, hd) API->>API: Grant admin permissions (edit: *, publish: *) @@ -193,10 +193,10 @@ sequenceDiagram ID_TOKEN=$(gcloud auth print-identity-token) # Exchange for Registry JWT token -REGISTRY_TOKEN=$(curl -X POST /v0/auth/oidc \ +REGISTRY_TOKEN=$(curl -X POST /v0.1/auth/oidc \ -H "Content-Type: application/json" \ -d '{"oidc_token": "'$ID_TOKEN'"}' | jq -r .registry_token) # Use for admin operations -curl -H "Authorization: Bearer $REGISTRY_TOKEN" /v0/... +curl -H "Authorization: Bearer $REGISTRY_TOKEN" /v0.1/... ``` \ No newline at end of file diff --git a/docs/modelcontextprotocol-io/registry-aggregators.mdx b/docs/modelcontextprotocol-io/registry-aggregators.mdx index 11848c70..685944fb 100644 --- a/docs/modelcontextprotocol-io/registry-aggregators.mdx +++ b/docs/modelcontextprotocol-io/registry-aggregators.mdx @@ -30,7 +30,7 @@ The `GET /v0.1/servers` endpoint supports cursor-based pagination. For example, the first page can be fetched using a `limit` query parameter: ```bash -curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100" +curl "https://registry.modelcontextprotocol.io/v0.1/servers?limit=100" ``` ```jsonc Output highlight={5} @@ -48,7 +48,7 @@ curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100" Then subsequent pages can be fetched by passing the `nextCursor` value as the `cursor` query parameter: ```bash -curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100&cursor=com.example/my-server:1.0.0" +curl "https://registry.modelcontextprotocol.io/v0.1/servers?limit=100&cursor=com.example/my-server:1.0.0" ``` ### Filtering Since diff --git a/docs/reference/api/generic-registry-api.md b/docs/reference/api/generic-registry-api.md index 614eb81f..e8a78bf5 100644 --- a/docs/reference/api/generic-registry-api.md +++ b/docs/reference/api/generic-registry-api.md @@ -14,11 +14,11 @@ The official registry has some more endpoints and restrictions on top of this. S ## Quick Reference ### Core Endpoints -- **`GET /v0/servers`** - List all servers with pagination -- **`GET /v0/servers/{serverName}/versions`** - List all versions of a server -- **`GET /v0/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version. -- **`POST /v0/publish`** - Publish new server (optional, registry-specific authentication) -- **`DELETE /v0/servers/{serverName}/versions/{version}`** - Delete specific server version (optional, not implemented by official registry) +- **`GET /v0.1/servers`** - List all servers with pagination +- **`GET /v0.1/servers/{serverName}/versions`** - List all versions of a server +- **`GET /v0.1/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version. +- **`POST /v0.1/publish`** - Publish new server (optional, registry-specific authentication) +- **`DELETE /v0.1/servers/{serverName}/versions/{version}`** - Delete specific server version (optional, not implemented by official registry) Server names and version strings should be URL-encoded in paths. @@ -42,7 +42,7 @@ List endpoints use cursor-based pagination for efficient, stable results. ### Basic Example: List Servers ```bash -curl https://registry.example.com/v0/servers?limit=10 +curl https://registry.example.com/v0.1/servers?limit=10 ``` ```json diff --git a/docs/reference/api/official-registry-api.md b/docs/reference/api/official-registry-api.md index 4215a790..f9e3c7dd 100644 --- a/docs/reference/api/official-registry-api.md +++ b/docs/reference/api/official-registry-api.md @@ -35,7 +35,7 @@ The official registry enforces additional [package validation requirements](../s ### Server List Filtering -The official registry extends the `GET /v0/servers` endpoint with additional query parameters for improved discovery and synchronization: +The official registry extends the `GET /v0.1/servers` endpoint with additional query parameters for improved discovery and synchronization: - `updated_since` - Filter servers updated after RFC3339 timestamp (e.g., `2025-08-07T13:15:04.280Z`) - `search` - Case-insensitive substring search on server names (e.g., `filesystem`) @@ -44,18 +44,18 @@ The official registry extends the `GET /v0/servers` endpoint with additional que These extensions enable efficient incremental synchronization for downstream registries and improved server discovery. Parameters can be combined and work with standard cursor-based pagination. -Example: `GET /v0/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest` +Example: `GET /v0.1/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest` ### Additional endpoints #### Auth endpoints -- POST `/v0/auth/dns` - Exchange signed DNS challenge for auth token -- POST `/v0/auth/http` - Exchange signed HTTP challenge for auth token -- POST `/v0/auth/github-at` - Exchange GitHub access token for auth token -- POST `/v0/auth/github-oidc` - Exchange GitHub OIDC token for auth token -- POST `/v0/auth/oidc` - Exchange Google OIDC token for auth token (for admins) +- POST `/v0.1/auth/dns` - Exchange signed DNS challenge for auth token +- POST `/v0.1/auth/http` - Exchange signed HTTP challenge for auth token +- POST `/v0.1/auth/github-at` - Exchange GitHub access token for auth token +- POST `/v0.1/auth/github-oidc` - Exchange GitHub OIDC token for auth token +- POST `/v0.1/auth/oidc` - Exchange Google OIDC token for auth token (for admins) #### Admin endpoints - GET `/metrics` - Prometheus metrics endpoint -- GET `/v0/health` - Basic health check endpoint -- PUT `/v0/servers/{serverName}/versions/{version}` - Edit specific server version +- GET `/v0.1/health` - Basic health check endpoint +- PUT `/v0.1/servers/{serverName}/versions/{version}` - Edit specific server version diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml index 1e8a842a..d1c2ea6c 100644 --- a/docs/reference/api/openapi.yaml +++ b/docs/reference/api/openapi.yaml @@ -18,7 +18,7 @@ tags: description: Operations for publishing MCP servers to the registry paths: - /v0/servers: + /v0.1/servers: get: tags: [servers] summary: List MCP servers @@ -68,7 +68,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ServerList' - /v0/servers/{serverName}/versions: + /v0.1/servers/{serverName}/versions: get: tags: [servers] summary: List all versions of an MCP server @@ -98,7 +98,7 @@ paths: error: type: string example: "Server not found" - /v0/servers/{serverName}/versions/{version}: + /v0.1/servers/{serverName}/versions/{version}: get: tags: [servers] summary: Get specific MCP server version @@ -218,7 +218,7 @@ paths: error: type: string example: "Deletion is not supported by this registry" - /v0/publish: + /v0.1/publish: post: tags: [publish] summary: Publish MCP server (Optional) diff --git a/scripts/mirror_data/README.md b/scripts/mirror_data/README.md index 5735c8d4..3237211f 100644 --- a/scripts/mirror_data/README.md +++ b/scripts/mirror_data/README.md @@ -31,7 +31,7 @@ go run scripts/mirror_data/fetch_production_data.go ``` This will: -- Fetch all servers from https://registry.modelcontextprotocol.io/v0/servers +- Fetch all servers from https://registry.modelcontextprotocol.io/v0.1/servers - Handle pagination automatically - Save data to `scripts/mirror_data/production_servers.json` - Be respectful to the API with rate limiting