Split OpenAPI specs into base and official registry versions #171
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
joelverhagen
reviewed
Jul 9, 2025
toby
approved these changes
Jul 9, 2025
domdomegg
pushed a commit
that referenced
this pull request
Aug 7, 2025
Closes #149 As noted in the FAQ update here, this is a helpful starting point in thinking about this: ``` ### What is the difference between "Official MCP Registry", "MCP Registry", "MCP registry", "MCP Registry API", etc? There are four underlying concepts: - "MCP Server Registry API" (or "MCP Registry API"): The OpenAPI specification defined in [openapi.yaml](./server-registry-api/openapi.yaml). This is a reusable API specification that anyone building any sort of "MCP server registry" should consider adopting / aligning with. - "Official MCP Registry" (or "MCP Registry"): The application that lives at `https://registry.modelcontextprotocol.io`. This registry currently only catalogs MCP servers, but may be extended in the future to also catalog MCP client/host apps and frameworks. - "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [official-registry-openapi.yaml](./server-registry-api/official-registry-openapi.yaml) - "MCP server registry" (or "MCP registry"): A third party, likely commercial, implementation of the MCP Server Registry API or derivative specification. ``` Prior to this PR, we were just treating "MCP Server Registry API" and "Official MCP Registry API" to be the same thing. They are not the same: the latter is inherently a more constrained version of the former. A private deployment of a similar registry need not have constraints like "the only valid source code repositories are `github` and `gitlab`". This PR separates out the definitions to match that path forward. ## Notable Changes ### Base OpenAPI spec (`openapi.yaml`) - Removed official-registry-specific constraints: - No maximum limit on `/servers` endpoint - No enum constraint on `Repository.source` - No enum constraint on `Package.registry_name` - Removed `/v0` prefix from paths (it's now just baked into the `official` one's URL prefix) - Added `$id` for proper schema identification ### Official Registry OpenAPI spec (`official-registry-openapi.yaml`) - Created as a derivative of the base spec using `$ref` - Re-adds official-registry-specific constraints: - `Repository.source` enum: `[github]` - `Package.registry_name` enum: `[npm, docker, pypi, nuget]` ### Documentation updates - Added `server-registry-api/README.md` explaining the relationship between specs - Updated FAQ to clarify terminology - Reorganized docs structure
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #149
As noted in the FAQ update here, this is a helpful starting point in thinking about this:
Prior to this PR, we were just treating "MCP Server Registry API" and "Official MCP Registry API" to be the same thing. They are not the same: the latter is inherently a more constrained version of the former. A private deployment of a similar registry need not have constraints like "the only valid source code repositories are
githubandgitlab".This PR separates out the definitions to match that path forward.
Notable Changes
Base OpenAPI spec (
openapi.yaml)/serversendpointRepository.sourcePackage.registry_name/v0prefix from paths (it's now just baked into theofficialone's URL prefix)$idfor proper schema identificationOfficial Registry OpenAPI spec (
official-registry-openapi.yaml)$refRepository.sourceenum:[github]Package.registry_nameenum:[npm, docker, pypi, nuget]Documentation updates
server-registry-api/README.mdexplaining the relationship between specs