Clarify approach to managing server.json schema versions

[tadasant]

I think the state we want to be in is:

• Registry code (including API and CLI) uses exclusively finalized versions of server.json from https://github.com/modelcontextprotocol/static/tree/main/schemas
• This file is a draft that should not be used by any systems (neither registry code nor others) until it is finalized and in the static repo
• After a server.json version release to static, we should always cut a ticket to update the registry code (API and CLI) to use the new version

If agreed, we should:

1. Change that server.schema.json $id field to point to draft
2. Document the sequencing for handling server.schema.json changes in accordance with the above

Are there any dependencies between our code and that server.schema.json field right now? If so, I think we should sever them and have the API/CLI code reference the static versions.

See: https://discord.com/channels/1358869848138059966/1369487942862504016/1424904131331625031

[rdimitrov]

Thanks for raising this! 🙏 I do agree we have to decide on a release/versioning strategy for this 👍

We touched this with @domdomegg and my reasoning based on what we have now is:

• I think we should keep releases (and versions in that sense) together for all assets maintained by the registry project, at least for now. This ensures we have the registry API server, the mcp-publisher, the server.json and the OpenAPI schema be in sync.
• Move away from date references in favour of semver. For example, cutting a v1.2.3 release should also produce a schema with $id of v1.2.3 (not the date ref).
• Have automation that opens a PR against modelcontextprotocol/static with the released schema

How it would look in practice:

1. We rename the $id to draft in the repo. Note that when a release is created the schemas are already part of the sources tar so that's good.
2. Upon publishing a release, i.e. v1.2.3 have an automated workflow that: a. Fetches the latest release (v1.2.3) b. Downloads the tar ball for v1.2.3 c. Extracts the schema files out of it d. Updates their references to match the version of the release, i.e. s/draft/v1.2.3 I guess we can change the ref before the release, but I don't think it's really necessary. e. Opens PRs against modelcontextprotocol/static.