9357e767c9<!-- Provide a brief summary of your changes -->
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
The following PR adds a PUT method for updating a server version
(optional, not implemented by the registry but still provides the
ability for other registry implementations to standardise on it)
**Details:**
- Path: PUT /v0.1/servers/{serverName}/versions/{version}
- Purpose: Update a specific version of an MCP server in the registry
- Authentication: Uses bearer token authentication (registry-specific)
- Request Body: Accepts a ServerDetail schema
- Response: Returns a ServerResponse on success (200)
- Error Handling: Includes proper HTTP status codes:
- 401: Unauthorized
- 403: Forbidden - Insufficient permissions
- 404: Server or version not found
- 500: Internal server error
- 501: Not Implemented - Registry doesn't support updates
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
## 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)
- [ ] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [ ] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
# Generic Registry API Specification
|
|
|
|
A standardized RESTful HTTP API for MCP registries to provide consistent endpoints for discovering and retrieving MCP servers.
|
|
|
|
Also see:
|
|
- For authentication and authorization, see the [registry authorization specification](./registry-authorization.md).
|
|
|
|
## Browse the Complete API Specification
|
|
|
|
**📋 View the full API specification interactively**: Open [openapi.yaml](./openapi.yaml) in an OpenAPI viewer like [Stoplight Elements](https://elements-demo.stoplight.io/?spec=https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/reference/api/openapi.yaml).
|
|
|
|
The official registry has some more endpoints and restrictions on top of this. See the [official registry API spec](./official-registry-api.md) for details.
|
|
|
|
## Quick Reference
|
|
|
|
### Core Endpoints
|
|
- **`GET /v0.1/servers`** - List all servers with pagination
|
|
- **`GET /v0.1/servers/{serverName}/versions`** - List all versions of a server
|
|
- **`GET /v0.1/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version.
|
|
- **`POST /v0.1/publish`** - Publish new server (optional, registry-specific authentication)
|
|
- **`PUT /v0.1/servers/{serverName}/versions/{version}`** - Update specific server version (optional, not implemented by official registry)
|
|
- **`DELETE /v0.1/servers/{serverName}/versions/{version}`** - Delete specific server version (optional, not implemented by official registry)
|
|
|
|
Server names and version strings should be URL-encoded in paths.
|
|
|
|
### Authentication
|
|
|
|
No authentication required by default. Subregistries may optionally require authentication following the [registry authorization specification](./registry-authorization.md).
|
|
|
|
### Content Type
|
|
All requests and responses use `application/json`
|
|
|
|
### Pagination
|
|
List endpoints use cursor-based pagination for efficient, stable results.
|
|
|
|
#### Usage
|
|
1. **Initial request**: Omit the `cursor` parameter
|
|
2. **Subsequent requests**: Use the `nextCursor` value from the previous response
|
|
3. **End of results**: When `nextCursor` is null or empty, there are no more results
|
|
|
|
**Important**: Always treat cursors as opaque strings. Never manually construct or modify cursor values.
|
|
|
|
### Basic Example: List Servers
|
|
|
|
```bash
|
|
curl https://registry.example.com/v0.1/servers?limit=10
|
|
```
|
|
|
|
```json
|
|
{
|
|
"servers": [
|
|
{
|
|
"server": {
|
|
"name": "io.modelcontextprotocol/filesystem",
|
|
"description": "Filesystem operations server",
|
|
"version": "1.0.2"
|
|
},
|
|
"_meta": {
|
|
"io.modelcontextprotocol.registry/official": {
|
|
"status": "active",
|
|
"publishedAt": "2025-01-01T10:30:00Z",
|
|
"isLatest": true
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"metadata": {
|
|
"count": 10,
|
|
"nextCursor": "com.example/my-server:1.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
For complete endpoint documentation, view the OpenAPI specification in a schema viewer.
|