fdcb38537fPrepared by Claude Code, reviewed by me. ## Summary - Update all API endpoint paths from `/v0/` to `/v0.1/` in the OpenAPI spec - Bump OpenAPI spec version from `2025-10-17` to `2025-12-01` (in `$id` and `info.version`) ## Rationale This ensures sub-registries implementing the spec are adhering to the stable v0.1 version rather than the unstable v0. The API freeze (v0.1) provides stability guarantees that sub-registries need. ## Additional cleanup ### Make `_meta` optional in `ServerResponse` The `_meta` field (and its `io.modelcontextprotocol.registry/official` extension) were never intended to be required parts of the spec. Sub-registries may not use these registry-specific metadata fields, so they should be optional. ### Move extensions docs to use /v0.1/ instead of /v0/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com>
2.6 KiB
2.6 KiB
Registry Extensions Specification
A standardized way for registries to provide experimental or community-driven features without committing them to the core API specification.
Motivation
The core generic registry API intentionally stays minimal to ensure stability and broad adoption. Extensions provide a path for:
- Experimentation: Try new features without core API changes
- Community innovation: Anyone can implement custom extensions
- Gradual adoption: Popular extensions may inform future core API features
- Avoiding breaking changes: Failed experiments can be deprecated without API versioning churn
URL Structure
Extensions live under the /v0.1/x/ prefix:
/v0.1/x/<namespace>/<extension>[/<path>]
Components:
<namespace>: Reverse domain ownership (e.g.,com.example,io.github.username)<extension>: Extension name (lowercase, hyphens for word separation)<path>: Extension-specific path structure (optional)
Examples:
/v0.1/x/com.example/search?q=database
/v0.1/x/com.example/stats
/v0.1/x/io.github.username/custom-feature
Conventions
Where possible:
- Follow standard REST conventions, return simple JSON responses, and avoid special headers
- For list endpoints, use cursor-based pagination matching the core API
- Extensions requiring authentication SHOULD follow the Registry Authorization Specification
- Build open-source implementations in a composable way on top of the core APIs (e.g. as opposed to via custom database integration)
Implementation Requirements
Registries implementing extensions SHOULD namespace extensions properly to avoid conflicts.
Clients consuming extensions MUST gracefully handle missing extensions.
Example
A simple server stats extension:
GET /v0.1/x/com.example/stats
{
"totalServers": 1234,
"totalVersions": 5678,
"recentPublishes": 42
}
Future Considerations
- Extension discovery: A potential
/v0.1/xendpoint to list available extensions - Extension metadata: Standardized metadata format for extension capabilities
- Defining common extensions: Like semantic conventions from OpenTelemetry, develop common extensions that registries can adopt (possibly under an experimental namespace)