Introduce serverId, rename id to versionId (#465)
Wielded Claude Code to do this; across many iterations and have reviewed all the code + largely rewritten the PR commentary here. This PR implements the server ID consistency changes from [#396](https://github.com/modelcontextprotocol/registry/issues/396). Our goal is to: - Rename `id` to `versionId` to make it clear that it is the ID for a specific version, not a server - Introduce `serverId` as a net new concept. This will be 1:1 with `name`. While not strictly necessary (we could just use name as a PK), the convention of having a UUID as an ID on our objects is just a helpful subjective architecture decision. Plus also leaves open the door to reconsidering the "should we allow renames" question. ## Key Changes ### 🗄️ Database Schema Changes - **Renamed**: `id` column → `version_id` (unique identifier for each server version) ### 📋 Metadata Structure Updates - **JSON Schema**: Updated `_meta.io.modelcontextprotocol.registry/official` to include: - `serverId`: Consistent ID across all versions of a server - `versionId`: Unique ID for this specific version (renamed from `id`) ### 🔧 API Endpoint Updates - **New endpoint structure**: Changed from version-ID-based to server-ID-based URLs: - `GET /v0/servers/{server_id}` - Get latest version of server - `GET /v0/servers/{server_id}?version=X.X.X` - Get specific version - `GET /v0/servers/{server_id}/versions` - List all versions of a server - `PUT /v0/servers/{server_id}?version=X.X.X` - Edit specific version - **Consistent URL patterns**: All server endpoints now use `server_id` as the primary identifier ### Database Migration Strategy The migration (`005_add_server_id_rename_version_id.sql`): 1. Adds new `version_id` column 2. Generates deterministic UUIDs for servers with the same name 3. Updates JSON metadata to add `serverId` and rename `id` to `versionId` 4. Copies existing `id` values to `version_id` column 5. Drops old `id` column and makes `version_id` the new primary key ## Testing Besides of course automated tests passing, I: 1. Set up my local db with the pre-005-migration state, imported all the production data 2. Ran the migration 3. Spot checked some diffs of the data that resulted -- ```json // before { "name": "io.github.ruvnet/ruv-swarm", "_meta": { "io.modelcontextprotocol.registry/official": { "id": "0a9cda7f-2b73-4839-844b-6582f335de42", "is_latest": false, "updated_at": "2025-09-10T17:21:34.92137012Z", "published_at": "2025-09-10T17:15:32.69690433Z" } }, "version": "1.0.18", "repository": { "url": "", "source": "" }, "description": "Neural network swarm orchestration with WebAssembly acceleration and MCP integration" } // after { "name": "io.github.ruvnet/ruv-swarm", "_meta": { "io.modelcontextprotocol.registry/official": { "serverId": "e8538952-96af-4a33-9e31-7fbed012521e", "is_latest": false, "versionId": "0a9cda7f-2b73-4839-844b-6582f335de42", "updated_at": "2025-09-10T17:21:34.92137012Z", "published_at": "2025-09-10T17:15:32.69690433Z" } }, "version": "1.0.18", "repository": { "url": "", "source": "" }, "description": "Neural network swarm orchestration with WebAssembly acceleration and MCP integration" } ``` Servers that have multiple versions stayed consistent in their `serverId`: ```json // First version { "name": "app.getdialer/dialer", "_meta": { "io.modelcontextprotocol.registry/official": { "serverId": "80f08bdb-f3e4-4f19-b072-1676ae49b663", "is_latest": false, "versionId": "04f25b17-331d-48d7-b08b-37baece208a7", "updated_at": "2025-09-09T00:16:49.162620072Z", "published_at": "2025-09-08T23:47:09.452137971Z" } }, "status": "active", "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json", "remotes": [ { "url": "https://getdialer.app/mcp", "type": "streamable-http" }, { "url": "https://getdialer.app/sse", "type": "sse" } ], "version": "1.0.0", "repository": { "url": "", "source": "" }, "description": "An MCP server that provides your you make outbound phone calls using your own phone number" } // Second version { "name": "app.getdialer/dialer", "_meta": { "io.modelcontextprotocol.registry/official": { "serverId": "80f08bdb-f3e4-4f19-b072-1676ae49b663", "is_latest": true, "versionId": "faa26cb9-3aad-415e-aece-f715fff5fe5e", "updated_at": "2025-09-09T00:16:49.107842808Z", "published_at": "2025-09-09T00:16:49.107842808Z" } }, "status": "active", "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json", "remotes": [ { "url": "https://getdialer.app/mcp", "type": "streamable-http" }, { "url": "https://getdialer.app/sse", "type": "sse" } ], "version": "1.0.1", "repository": { "url": "", "source": "" }, "description": "An MCP server that provides lets you make outbound phone calls using your own phone number" } ``` And I also tried publishing a test server anew; looked good: ```bash ⏺ Bash(curl -s "http://localhost:8080/v0/servers/102dc4e4-6ca8-40e6-aa11-cd45763d3352" | jq '.') ⎿ { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json", "name": "io.modelcontextprotocol.anonymous/test-claude-migration-server", "description": "A test server to verify the new migration and API endpoints work correctly", "status": "active", "repository": { "url": "https://github.com/example/test-claude-migration-server", "source": "github", "id": "example/test-claude-migration-server" }, "version": "1.0.0", "_meta": { "io.modelcontextprotocol.registry/official": { "serverId": "102dc4e4-6ca8-40e6-aa11-cd45763d3352", "versionId": "48c9cd55-7bc4-4ac2-896e-59e81eb653e4", "published_at": "2025-09-12T18:33:23.264203-07:00", "updated_at": "2025-09-12T18:33:23.264203-07:00", "is_latest": true } } } ⏺ Bash(curl -s "http://localhost:8080/v0/servers/102dc4e4-6ca8-40e6-aa11-cd45763d3352/versions" | jq '.') ⎿ { "servers": [ { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json", "name": "io.modelcontextprotocol.anonymous/test-claude-migration-server", "description": "A test server to verify the new migration and API endpoints work correctly", "status": "active", "repository": { "url": "https://github.com/example/test-claude-migration-server", "source": "github", "id": "example/test-claude-migration-server" }, "version": "1.0.0", "_meta": { "io.modelcontextprotocol.registry/official": { "serverId": "102dc4e4-6ca8-40e6-aa11-cd45763d3352", "versionId": "48c9cd55-7bc4-4ac2-896e-59e81eb653e4", "published_at": "2025-09-12T18:33:23.264203-07:00", "updated_at": "2025-09-12T18:33:23.264203-07:00", "is_latest": true } } } ], "metadata": { "count": 1 } } ``` Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Preeti Dewani <preetidewani1990@gmail.com> Co-authored-by: adam jones <adamj+git@anthropic.com> Co-authored-by: Adam Jones <adamj@anthropic.com>
This commit is contained in:
Tadas Antanavicius
GitHub
parent
52b1dc71b6
commit
56e8b4879b
1 changed files with 5185 additions and 3466 deletions
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
|
||||
"$id": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
|
||||
"title": "MCP Server Detail",
|
||||
"$ref": "#/definitions/ServerDetail",
|
||||
"definitions": {
|
||||
|
|
@ -74,7 +74,7 @@
|
|||
"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. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '>=1.2.3', '1.x', '1.*')."
|
||||
},
|
||||
"website_url": {
|
||||
"websiteUrl": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements.",
|
||||
|
|
@ -86,18 +86,18 @@
|
|||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"registry_type",
|
||||
"registryType",
|
||||
"identifier",
|
||||
"version",
|
||||
"transport"
|
||||
],
|
||||
"properties": {
|
||||
"registry_type": {
|
||||
"registryType": {
|
||||
"type": "string",
|
||||
"description": "Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'oci', 'nuget', 'mcpb')",
|
||||
"examples": ["npm", "pypi", "oci", "nuget", "mcpb"]
|
||||
},
|
||||
"registry_base_url": {
|
||||
"registryBaseUrl": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Base URL of the package registry",
|
||||
|
|
@ -117,15 +117,15 @@
|
|||
"example": "1.0.2",
|
||||
"minLength": 1
|
||||
},
|
||||
"file_sha256": {
|
||||
"fileSha256": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-f0-9]{64}$",
|
||||
"description": "SHA-256 hash of the package file for integrity verification. Required for MCPB packages and optional for other package types. Authors are responsible for generating correct SHA-256 hashes when creating server.json. If present, MCP clients must validate the downloaded file matches the hash before running packages to ensure file integrity.",
|
||||
"example": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce"
|
||||
},
|
||||
"runtime_hint": {
|
||||
"runtimeHint": {
|
||||
"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.",
|
||||
"description": "A hint to help clients determine the appropriate runtime for the package. This field should be provided when `runtimeArguments` are present.",
|
||||
"examples": [
|
||||
"npx",
|
||||
"uvx",
|
||||
|
|
@ -147,21 +147,21 @@
|
|||
],
|
||||
"description": "Transport protocol configuration for the package"
|
||||
},
|
||||
"runtime_arguments": {
|
||||
"runtimeArguments": {
|
||||
"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.",
|
||||
"description": "A list of arguments to be passed to the package's runtime command (such as docker or npx). The `runtimeHint` field should be provided when `runtimeArguments` are present.",
|
||||
"items": {
|
||||
"$ref": "#/definitions/Argument"
|
||||
}
|
||||
},
|
||||
"package_arguments": {
|
||||
"packageArguments": {
|
||||
"type": "array",
|
||||
"description": "A list of arguments to be passed to the package's binary.",
|
||||
"items": {
|
||||
"$ref": "#/definitions/Argument"
|
||||
}
|
||||
},
|
||||
"environment_variables": {
|
||||
"environmentVariables": {
|
||||
"type": "array",
|
||||
"description": "A mapping of environment variables to be set when running the package.",
|
||||
"items": {
|
||||
|
|
@ -177,7 +177,7 @@
|
|||
"description": "A description of the input, which clients can use to provide context to the user.",
|
||||
"type": "string"
|
||||
},
|
||||
"is_required": {
|
||||
"isRequired": {
|
||||
"type": "boolean",
|
||||
"default": false
|
||||
},
|
||||
|
|
@ -196,7 +196,7 @@
|
|||
"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": {
|
||||
"isSecret": {
|
||||
"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
|
||||
|
|
@ -253,12 +253,12 @@
|
|||
],
|
||||
"example": "positional"
|
||||
},
|
||||
"value_hint": {
|
||||
"valueHint": {
|
||||
"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": {
|
||||
"isRepeated": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the argument can be repeated multiple times in the command line.",
|
||||
"default": false
|
||||
|
|
@ -267,7 +267,7 @@
|
|||
"anyOf": [
|
||||
{
|
||||
"required": [
|
||||
"value_hint"
|
||||
"valueHint"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
@ -304,7 +304,7 @@
|
|||
"description": "The flag name, including any leading dashes.",
|
||||
"example": "--port"
|
||||
},
|
||||
"is_repeated": {
|
||||
"isRepeated": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the argument can be repeated multiple times.",
|
||||
"default": false
|
||||
|
|
@ -377,7 +377,7 @@
|
|||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"description": "URL template for the streamable-http transport. Variables in {curly_braces} reference argument value_hints, argument names, or environment variable names. After variable substitution, this should produce a valid URI.",
|
||||
"description": "URL template for the streamable-http transport. Variables in {curly_braces} reference argument valueHints, argument names, or environment variable names. After variable substitution, this should produce a valid URI.",
|
||||
"example": "https://api.example.com/mcp"
|
||||
},
|
||||
"headers": {
|
||||
|
|
@ -432,7 +432,7 @@
|
|||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "JSON Schema URI for this server.json format",
|
||||
"example": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json"
|
||||
"example": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json"
|
||||
},
|
||||
"packages": {
|
||||
"type": "array",
|
||||
|
|
@ -475,4 +475,4 @@
|
|||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue