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
<!-- Provide a brief summary of your changes -->
## Motivation and Context
This is in support of
https://github.com/modelcontextprotocol/registry/issues/159, to make it
easier, I hope. My team noticed some differences in the JSON schema,
most notably the "choices" property was missing. I tried to write a tool
to do this but slowed down since I am not experienced with Go. This is a
first pass, maybe someone else can finish the tooling.
I restructured the JSON schema to break out child objects like the YAML
file, and brought the descriptions and example into sync. The only
differences are two extra properties in the YAML which are computed by
the server:
- `VersionDetail.is_latest` is not present in the JSON schema, computed
by the registry based on
https://github.com/modelcontextprotocol/registry/issues/158
- `Server.id` is not present in the JSON schema, generated by the
registry
The idea is the a tool could look at ServerDetail in the YAML and then
generate the schema.json with minimal fix-ups (add a root title, remove
`VersionDetail.is_latest` and `Server.id`.
~Question for @tadasant - should `VersionDetail.release_date` be in the
JSON schema? I think _no_ (and let it be computed) but it's there right
now.~ - aligned with
https://github.com/modelcontextprotocol/registry/pull/167 and removed
## How Has This Been Tested?
I have tested the JSON schema against the sample server.json in the repo
(files and markdown blocks).
## Breaking Changes
None.
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [x] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
<!-- Provide a brief summary of your changes -->
Add more information about the value field under Input in the API doc.
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
the descrioption for
[value](81e5174a59/docs/openapi.yaml (L219))
is not clearly.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
No need.
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
No
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ x ] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [ x ] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ x ] My code follows the repository's style guidelines
- [ x ] New and existing tests pass locally
- [ x ] I have added appropriate error handling
- [ x ] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
