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:
parent
52b1dc71b6
commit
56e8b4879b
1 changed files with 5185 additions and 3466 deletions
|
|
@ -55,13 +55,13 @@ func (s *registryServiceImpl) List(filter *database.ServerFilter, cursor string,
|
|||
return result, nextCursor, nil
|
||||
}
|
||||
|
||||
// GetByID retrieves a specific server by its registry metadata ID in flattened format
|
||||
func (s *registryServiceImpl) GetByID(id string) (*apiv0.ServerJSON, error) {
|
||||
// GetByVersionID retrieves a specific server by its registry metadata version ID
|
||||
func (s *registryServiceImpl) GetByVersionID(versionID string) (*apiv0.ServerJSON, error) {
|
||||
// Create a timeout context for the database operation
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
|
||||
serverRecord, err := s.db.GetByID(ctx, id)
|
||||
serverRecord, err := s.db.GetByVersionID(ctx, versionID)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
|
@ -70,6 +70,56 @@ func (s *registryServiceImpl) GetByID(id string) (*apiv0.ServerJSON, error) {
|
|||
return serverRecord, nil
|
||||
}
|
||||
|
||||
// GetByServerID retrieves the latest version of a server by its server ID
|
||||
func (s *registryServiceImpl) GetByServerID(serverID string) (*apiv0.ServerJSON, error) {
|
||||
// Create a timeout context for the database operation
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
|
||||
serverRecord, err := s.db.GetByServerID(ctx, serverID)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// Return the server record directly
|
||||
return serverRecord, nil
|
||||
}
|
||||
|
||||
// GetByServerIDAndVersion retrieves a specific version of a server by server ID and version
|
||||
func (s *registryServiceImpl) GetByServerIDAndVersion(serverID string, version string) (*apiv0.ServerJSON, error) {
|
||||
// Create a timeout context for the database operation
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
|
||||
serverRecord, err := s.db.GetByServerIDAndVersion(ctx, serverID, version)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// Return the server record directly
|
||||
return serverRecord, nil
|
||||
}
|
||||
|
||||
// GetAllVersionsByServerID retrieves all versions of a server by server ID
|
||||
func (s *registryServiceImpl) GetAllVersionsByServerID(serverID string) ([]apiv0.ServerJSON, error) {
|
||||
// Create a timeout context for the database operation
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
|
||||
serverRecords, err := s.db.GetAllVersionsByServerID(ctx, serverID)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// Return ServerJSONs directly
|
||||
result := make([]apiv0.ServerJSON, len(serverRecords))
|
||||
for i, record := range serverRecords {
|
||||
result[i] = *record
|
||||
}
|
||||
|
||||
return result, nil
|
||||
}
|
||||
|
||||
// Publish publishes a server with flattened _meta extensions
|
||||
func (s *registryServiceImpl) Publish(req apiv0.ServerJSON) (*apiv0.ServerJSON, error) {
|
||||
// Create a timeout context for the database operation
|
||||
|
|
@ -125,20 +175,7 @@ func (s *registryServiceImpl) Publish(req apiv0.ServerJSON) (*apiv0.ServerJSON,
|
|||
}
|
||||
|
||||
// Create complete server with metadata
|
||||
server := serverJSON // Copy the input
|
||||
|
||||
// Initialize meta if not present
|
||||
if server.Meta == nil {
|
||||
server.Meta = &apiv0.ServerMeta{}
|
||||
}
|
||||
|
||||
// Set registry metadata
|
||||
server.Meta.Official = &apiv0.RegistryExtensions{
|
||||
ID: uuid.New().String(),
|
||||
PublishedAt: publishTime,
|
||||
UpdatedAt: publishTime,
|
||||
IsLatest: isNewLatest,
|
||||
}
|
||||
server := s.createServerWithMetadata(serverJSON, existingServerVersions, publishTime, isNewLatest)
|
||||
|
||||
// Create server in database
|
||||
serverRecord, err := s.db.CreateServer(ctx, &server)
|
||||
|
|
@ -148,15 +185,15 @@ func (s *registryServiceImpl) Publish(req apiv0.ServerJSON) (*apiv0.ServerJSON,
|
|||
|
||||
// Mark previous latest as no longer latest
|
||||
if isNewLatest && existingLatest != nil {
|
||||
var existingLatestID string
|
||||
var existingLatestVersionID string
|
||||
if existingLatest.Meta != nil && existingLatest.Meta.Official != nil {
|
||||
existingLatestID = existingLatest.Meta.Official.ID
|
||||
existingLatestVersionID = existingLatest.Meta.Official.VersionID
|
||||
}
|
||||
if existingLatestID != "" {
|
||||
// Update the existing server to set is_latest = false
|
||||
if existingLatestVersionID != "" {
|
||||
// Update the existing server to set isLatest = false
|
||||
existingLatest.Meta.Official.IsLatest = false
|
||||
existingLatest.Meta.Official.UpdatedAt = time.Now()
|
||||
if _, err := s.db.UpdateServer(ctx, existingLatestID, existingLatest); err != nil {
|
||||
if _, err := s.db.UpdateServer(ctx, existingLatestVersionID, existingLatest); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
}
|
||||
|
|
@ -166,6 +203,46 @@ func (s *registryServiceImpl) Publish(req apiv0.ServerJSON) (*apiv0.ServerJSON,
|
|||
return serverRecord, nil
|
||||
}
|
||||
|
||||
// createServerWithMetadata creates a server with proper metadata including server_id and version_id
|
||||
func (s *registryServiceImpl) createServerWithMetadata(
|
||||
serverJSON apiv0.ServerJSON,
|
||||
existingServerVersions []*apiv0.ServerJSON,
|
||||
publishTime time.Time,
|
||||
isNewLatest bool,
|
||||
) apiv0.ServerJSON {
|
||||
server := serverJSON // Copy the input
|
||||
|
||||
// Initialize meta if not present
|
||||
if server.Meta == nil {
|
||||
server.Meta = &apiv0.ServerMeta{}
|
||||
}
|
||||
|
||||
// Determine server_id - either from existing versions or generate new one
|
||||
var serverID string
|
||||
if len(existingServerVersions) > 0 {
|
||||
// Use existing server_id from any existing version
|
||||
firstExisting := existingServerVersions[0]
|
||||
if firstExisting.Meta != nil && firstExisting.Meta.Official != nil {
|
||||
serverID = firstExisting.Meta.Official.ServerID
|
||||
}
|
||||
}
|
||||
if serverID == "" {
|
||||
// This is the first version of a new server
|
||||
serverID = uuid.New().String()
|
||||
}
|
||||
|
||||
// Set registry metadata
|
||||
server.Meta.Official = &apiv0.RegistryExtensions{
|
||||
ServerID: serverID,
|
||||
VersionID: uuid.New().String(),
|
||||
PublishedAt: publishTime,
|
||||
UpdatedAt: publishTime,
|
||||
IsLatest: isNewLatest,
|
||||
}
|
||||
|
||||
return server
|
||||
}
|
||||
|
||||
// validateNoDuplicateRemoteURLs checks that no other server is using the same remote URLs
|
||||
func (s *registryServiceImpl) validateNoDuplicateRemoteURLs(ctx context.Context, serverDetail apiv0.ServerJSON) error {
|
||||
// Check each remote URL in the new server for conflicts
|
||||
|
|
@ -201,24 +278,45 @@ func (s *registryServiceImpl) getCurrentLatestVersion(existingServerVersions []*
|
|||
}
|
||||
|
||||
// EditServer updates an existing server with new details (admin operation)
|
||||
func (s *registryServiceImpl) EditServer(id string, req apiv0.ServerJSON) (*apiv0.ServerJSON, error) {
|
||||
func (s *registryServiceImpl) EditServer(versionID string, req apiv0.ServerJSON) (*apiv0.ServerJSON, error) {
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
|
||||
// First get the current server to preserve metadata
|
||||
currentServer, err := s.db.GetByVersionID(ctx, versionID)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// Validate the request
|
||||
if err := validators.ValidatePublishRequest(req, s.cfg); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
serverJSON := req
|
||||
// Merge the request with the current server, preserving metadata
|
||||
updatedServer := *currentServer // Copy the current server with all metadata
|
||||
|
||||
// Check for duplicate remote URLs
|
||||
if err := s.validateNoDuplicateRemoteURLs(ctx, serverJSON); err != nil {
|
||||
// Update only the user-modifiable fields from the request
|
||||
updatedServer.Name = req.Name
|
||||
updatedServer.Description = req.Description
|
||||
updatedServer.Version = req.Version
|
||||
updatedServer.Status = req.Status
|
||||
updatedServer.Repository = req.Repository
|
||||
updatedServer.Remotes = req.Remotes
|
||||
updatedServer.Packages = req.Packages
|
||||
|
||||
// Update the UpdatedAt timestamp in metadata
|
||||
if updatedServer.Meta != nil && updatedServer.Meta.Official != nil {
|
||||
updatedServer.Meta.Official.UpdatedAt = time.Now()
|
||||
}
|
||||
|
||||
// Check for duplicate remote URLs using the updated server
|
||||
if err := s.validateNoDuplicateRemoteURLs(ctx, updatedServer); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// Update server in database
|
||||
serverRecord, err := s.db.UpdateServer(ctx, id, &serverJSON)
|
||||
serverRecord, err := s.db.UpdateServer(ctx, versionID, &updatedServer)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue