docs: Clean up API documentation (#236)
- Move API examples from docs into swagger.yaml - Align openapi.yaml docs with implementation
This commit is contained in:
adam jones
GitHub
parent
1a6dc930b3
commit
1821f68360
1 changed files with 327 additions and 566 deletions
201
README.md
201
README.md
|
|
@ -200,206 +200,7 @@ Publishing requires GitHub OAuth validation:
|
|||
GET /v0/swagger/index.html
|
||||
```
|
||||
|
||||
The API is documented using Swagger/OpenAPI. This page provides a complete reference of all endpoints with request/response schemas and allows you to test the API directly from your browser.
|
||||
|
||||
### Health Check
|
||||
|
||||
```
|
||||
GET /v0/health
|
||||
```
|
||||
|
||||
Returns the health status of the service:
|
||||
```json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
### Registry Endpoints
|
||||
|
||||
#### List Registry Server Entries
|
||||
|
||||
```
|
||||
GET /v0/servers
|
||||
```
|
||||
|
||||
Lists MCP registry server entries with pagination support.
|
||||
|
||||
Query parameters:
|
||||
- `limit`: Maximum number of entries to return (default: 30, max: 100)
|
||||
- `cursor`: Pagination cursor for retrieving next set of results
|
||||
|
||||
Response example:
|
||||
```json
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"id": "123e4567-e89b-12d3-a456-426614174000",
|
||||
"name": "Example MCP Server",
|
||||
"url": "https://example.com/mcp",
|
||||
"description": "An example MCP server",
|
||||
"created_at": "2025-05-17T17:34:22.912Z",
|
||||
"updated_at": "2025-05-17T17:34:22.912Z"
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"next_cursor": "123e4567-e89b-12d3-a456-426614174000",
|
||||
"count": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Server Details
|
||||
|
||||
```
|
||||
GET /v0/servers/{id}
|
||||
```
|
||||
|
||||
Retrieves detailed information about a specific MCP server entry.
|
||||
|
||||
Path parameters:
|
||||
- `id`: Unique identifier of the server entry
|
||||
|
||||
Response example:
|
||||
```json
|
||||
{
|
||||
"id": "01129bff-3d65-4e3d-8e82-6f2f269f818c",
|
||||
"name": "io.github.gongrzhe/redis-mcp-server",
|
||||
"description": "A Redis MCP server (pushed to https://github.com/modelcontextprotocol/servers/tree/main/src/redis) implementation for interacting with Redis databases. This server enables LLMs to interact with Redis key-value stores through a set of standardized tools.",
|
||||
"repository": {
|
||||
"url": "https://github.com/GongRzhe/REDIS-MCP-Server",
|
||||
"source": "github",
|
||||
"id": "907849235"
|
||||
},
|
||||
"version_detail": {
|
||||
"version": "0.0.1-seed",
|
||||
"release_date": "2025-05-16T19:13:21Z",
|
||||
"is_latest": true
|
||||
},
|
||||
"packages": [
|
||||
{
|
||||
"registry_name": "docker",
|
||||
"name": "@gongrzhe/server-redis-mcp",
|
||||
"version": "1.0.0",
|
||||
"package_arguments": [
|
||||
{
|
||||
"description": "Docker image to run",
|
||||
"is_required": true,
|
||||
"format": "string",
|
||||
"value": "mcp/redis",
|
||||
"default": "mcp/redis",
|
||||
"type": "positional",
|
||||
"value_hint": "mcp/redis"
|
||||
},
|
||||
{
|
||||
"description": "Redis server connection string",
|
||||
"is_required": true,
|
||||
"format": "string",
|
||||
"value": "redis://host.docker.internal:6379",
|
||||
"default": "redis://host.docker.internal:6379",
|
||||
"type": "positional",
|
||||
"value_hint": "host.docker.internal:6379"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Publish a Server Entry
|
||||
|
||||
```
|
||||
POST /v0/publish
|
||||
```
|
||||
|
||||
Publishes a new MCP server entry to the registry. Authentication is required via Bearer token in the Authorization header.
|
||||
|
||||
Headers:
|
||||
- `Authorization`: Bearer token for authentication (e.g., `Bearer your_token_here`)
|
||||
- `Content-Type`: application/json
|
||||
|
||||
Request body example:
|
||||
```json
|
||||
{
|
||||
"description": "<your description here>",
|
||||
"name": "io.github.<owner>/<server-name>",
|
||||
"packages": [
|
||||
{
|
||||
"registry_name": "npm",
|
||||
"name": "@<owner>/<server-name>",
|
||||
"version": "0.2.23",
|
||||
"package_arguments": [
|
||||
{
|
||||
"description": "Specify services and permissions.",
|
||||
"is_required": true,
|
||||
"format": "string",
|
||||
"value": "-s",
|
||||
"default": "-s",
|
||||
"type": "positional",
|
||||
"value_hint": "-s"
|
||||
}
|
||||
],
|
||||
"environment_variables": [
|
||||
{
|
||||
"description": "API Key to access the server",
|
||||
"name": "API_KEY"
|
||||
}
|
||||
]
|
||||
},{
|
||||
"registry_name": "docker",
|
||||
"name": "@<owner>/<server-name>-cli",
|
||||
"version": "0.123.223",
|
||||
"runtime_hint": "docker",
|
||||
"runtime_arguments": [
|
||||
{
|
||||
"description": "Specify services and permissions.",
|
||||
"is_required": true,
|
||||
"format": "string",
|
||||
"value": "--mount",
|
||||
"default": "--mount",
|
||||
"type": "positional",
|
||||
"value_hint": "--mount"
|
||||
}
|
||||
],
|
||||
"environment_variables": [
|
||||
{
|
||||
"description": "API Key to access the server",
|
||||
"name": "API_KEY"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"repository": {
|
||||
"url": "https://github.com/<owner>/<server-name>",
|
||||
"source": "github"
|
||||
},
|
||||
"version_detail": {
|
||||
"version": "0.0.1-<publisher_version>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response example:
|
||||
```json
|
||||
{
|
||||
"message": "Server publication successful",
|
||||
"id": "1234567890abcdef12345678"
|
||||
}
|
||||
```
|
||||
|
||||
### Ping Endpoint
|
||||
|
||||
```
|
||||
GET /v0/ping
|
||||
```
|
||||
|
||||
Simple ping endpoint that returns environment configuration information:
|
||||
```json
|
||||
{
|
||||
"environment": "dev",
|
||||
"version": "registry-<sha>"
|
||||
}
|
||||
```
|
||||
The API is documented using Swagger/OpenAPI. This page provides a complete reference of all endpoints with request/response schemas and examples, and allows you to test the API directly from your browser.
|
||||
|
||||
## Configuration
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue