mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-23 18:29:21 -05:00
Add API documentation (#275)
This commit is contained in:
samanhappy
147
docs/api-reference/auth.mdx
Normal file
147
docs/api-reference/auth.mdx
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "Authentication"
|
||||
description: "Manage users and authentication."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="POST /api/auth/login"
|
||||
href="#login"
|
||||
>
|
||||
Log in to get a JWT token.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/auth/register"
|
||||
href="#register"
|
||||
>
|
||||
Register a new user.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/auth/user"
|
||||
href="#get-current-user"
|
||||
>
|
||||
Get the currently authenticated user.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/auth/change-password"
|
||||
href="#change-password"
|
||||
>
|
||||
Change the password for the current user.
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### Login
|
||||
|
||||
Authenticates a user and returns a JWT token along with user details.
|
||||
|
||||
- **Endpoint**: `/api/auth/login`
|
||||
- **Method**: `POST`
|
||||
- **Body**:
|
||||
- `username` (string, required): The user's username.
|
||||
- `password` (string, required): The user's password.
|
||||
- **Request Example**:
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
```
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Login successful",
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"user": {
|
||||
"username": "admin",
|
||||
"isAdmin": true,
|
||||
"permissions": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Register
|
||||
|
||||
Registers a new user and returns a JWT token.
|
||||
|
||||
- **Endpoint**: `/api/auth/register`
|
||||
- **Method**: `POST`
|
||||
- **Body**:
|
||||
- `username` (string, required): The desired username.
|
||||
- `password` (string, required): The desired password (must be at least 6 characters).
|
||||
- `isAdmin` (boolean, optional): Whether the user should have admin privileges.
|
||||
- **Request Example**:
|
||||
```json
|
||||
{
|
||||
"username": "newuser",
|
||||
"password": "password123",
|
||||
"isAdmin": false
|
||||
}
|
||||
```
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"user": {
|
||||
"username": "newuser",
|
||||
"isAdmin": false,
|
||||
"permissions": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Get Current User
|
||||
|
||||
Retrieves the profile of the currently authenticated user.
|
||||
|
||||
- **Endpoint**: `/api/auth/user`
|
||||
- **Method**: `GET`
|
||||
- **Authentication**: Bearer Token required.
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"user": {
|
||||
"username": "admin",
|
||||
"isAdmin": true,
|
||||
"permissions": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Change Password
|
||||
|
||||
Allows the authenticated user to change their password.
|
||||
|
||||
- **Endpoint**: `/api/auth/change-password`
|
||||
- **Method**: `POST`
|
||||
- **Authentication**: Bearer Token required.
|
||||
- **Body**:
|
||||
- `currentPassword` (string, required): The user's current password.
|
||||
- `newPassword` (string, required): The desired new password (must be at least 6 characters).
|
||||
- **Request Example**:
|
||||
```json
|
||||
{
|
||||
"currentPassword": "oldpassword",
|
||||
"newPassword": "newpassword123"
|
||||
}
|
||||
```
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Password updated successfully"
|
||||
}
|
||||
```
|
||||
111
docs/api-reference/config.mdx
Normal file
111
docs/api-reference/config.mdx
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: "Config"
|
||||
description: "Manage and retrieve system-wide configurations."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card title="PUT /api/system-config" href="#update-system-config">Update the main system configuration.</Card>
|
||||
<Card title="GET /api/settings" href="#get-all-settings">Get all system settings, including servers and groups.</Card>
|
||||
<Card title="GET /config" href="#get-runtime-config">Get public runtime configuration for the frontend.</Card>
|
||||
<Card title="GET /public-config" href="#get-public-config">Get public configuration to check for auth skip.</Card>
|
||||
|
||||
---
|
||||
|
||||
### Update System Config
|
||||
|
||||
Updates various parts of the system configuration. You only need to provide the keys for the sections you want to update.
|
||||
|
||||
- **Endpoint**: `/api/system-config`
|
||||
- **Method**: `PUT`
|
||||
- **Body**: A JSON object containing one or more of the following top-level keys: `routing`, `install`, `smartRouting`, `mcpRouter`.
|
||||
|
||||
#### Routing Configuration (`routing`)
|
||||
|
||||
- `enableGlobalRoute` (boolean): Enable or disable the global `/api/mcp` route.
|
||||
- `enableGroupNameRoute` (boolean): Enable or disable group-based routing (e.g., `/api/mcp/group/:groupName`).
|
||||
- `enableBearerAuth` (boolean): Enable bearer token authentication for MCP routes.
|
||||
- `bearerAuthKey` (string): The secret key to use for bearer authentication.
|
||||
- `skipAuth` (boolean): If true, skips all authentication, making the instance public.
|
||||
|
||||
#### Install Configuration (`install`)
|
||||
|
||||
- `pythonIndexUrl` (string): The base URL of the Python Package Index (PyPI) to use for installations.
|
||||
- `npmRegistry` (string): The URL of the npm registry to use for installations.
|
||||
- `baseUrl` (string): The public base URL of this MCPHub instance.
|
||||
|
||||
#### Smart Routing Configuration (`smartRouting`)
|
||||
|
||||
- `enabled` (boolean): Enable or disable the Smart Routing feature.
|
||||
- `dbUrl` (string): The database connection URL for storing embeddings.
|
||||
- `openaiApiBaseUrl` (string): The base URL for the OpenAI-compatible API for generating embeddings.
|
||||
- `openaiApiKey` (string): The API key for the embeddings service.
|
||||
- `openaiApiEmbeddingModel` (string): The name of the embedding model to use.
|
||||
|
||||
#### MCP Router Configuration (`mcpRouter`)
|
||||
|
||||
- `apiKey` (string): The API key for the MCP Router service.
|
||||
- `referer` (string): The referer header to use for MCP Router requests.
|
||||
- `title` (string): The title to display for this instance on MCP Router.
|
||||
- `baseUrl` (string): The base URL for the MCP Router API.
|
||||
|
||||
- **Request Example**:
|
||||
```json
|
||||
{
|
||||
"routing": {
|
||||
"skipAuth": true
|
||||
},
|
||||
"smartRouting": {
|
||||
"enabled": true,
|
||||
"dbUrl": "postgresql://user:pass@host:port/db"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Get All Settings
|
||||
|
||||
Retrieves the entire settings object for the instance, including all server configurations, groups, and system settings. This is a comprehensive dump of the `mcp_settings.json` file.
|
||||
|
||||
- **Endpoint**: `/api/settings`
|
||||
- **Method**: `GET`
|
||||
|
||||
---
|
||||
|
||||
### Get Runtime Config
|
||||
|
||||
Retrieves the essential runtime configuration required for the frontend application. This endpoint does not require authentication.
|
||||
|
||||
- **Endpoint**: `/config`
|
||||
- **Method**: `GET`
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"basePath": "",
|
||||
"version": "1.0.0",
|
||||
"name": "MCPHub"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Get Public Config
|
||||
|
||||
Retrieves public configuration, primarily to check if authentication is skipped. This allows the frontend to adjust its behavior accordingly before a user has logged in. This endpoint does not require authentication.
|
||||
|
||||
- **Endpoint**: `/public-config`
|
||||
- **Method**: `GET`
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"skipAuth": false,
|
||||
"permissions": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,4 +0,0 @@
|
||||
---
|
||||
title: 'Create Plant'
|
||||
openapi: 'POST /plants'
|
||||
---
|
||||
@@ -1,4 +0,0 @@
|
||||
---
|
||||
title: 'Delete Plant'
|
||||
openapi: 'DELETE /plants/{id}'
|
||||
---
|
||||
@@ -1,4 +0,0 @@
|
||||
---
|
||||
title: 'Get Plants'
|
||||
openapi: 'GET /plants'
|
||||
---
|
||||
@@ -1,4 +0,0 @@
|
||||
---
|
||||
title: 'New Plant'
|
||||
openapi: 'WEBHOOK /plant/webhook'
|
||||
---
|
||||
212
docs/api-reference/groups.mdx
Normal file
212
docs/api-reference/groups.mdx
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
title: "Groups"
|
||||
description: "Manage server groups to organize and route requests."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card title="GET /api/groups" href="#get-all-groups">Get a list of all groups.</Card>
|
||||
<Card title="POST /api/groups" href="#create-a-new-group">Create a new group.</Card>
|
||||
<Card title="GET /api/groups/:id" href="#get-a-group">Get details of a specific group.</Card>
|
||||
<Card title="PUT /api/groups/:id" href="#update-a-group">Update an existing group.</Card>
|
||||
<Card title="DELETE /api/groups/:id" href="#delete-a-group">Delete a group.</Card>
|
||||
<Card title="POST /api/groups/:id/servers" href="#add-server-to-group">Add a server to a group.</Card>
|
||||
<Card title="DELETE /api/groups/:id/servers/:serverName" href="#remove-server-from-group">Remove a server from a group.</Card>
|
||||
<Card title="PUT /api/groups/:id/servers/batch" href="#batch-update-group-servers">Batch update servers in a group.</Card>
|
||||
<Card title="GET /api/groups/:id/server-configs" href="#get-group-server-configs">Get detailed server configurations in a group.</Card>
|
||||
<Card title="PUT /api/groups/:id/server-configs/:serverName/tools" href="#update-group-server-tools">Update tool selection for a server in a group.</Card>
|
||||
|
||||
---
|
||||
|
||||
### Get All Groups
|
||||
|
||||
Retrieves a list of all server groups.
|
||||
|
||||
- **Endpoint**: `/api/groups`
|
||||
- **Method**: `GET`
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": "group-1",
|
||||
"name": "My Group",
|
||||
"description": "A collection of servers.",
|
||||
"servers": ["server1", "server2"],
|
||||
"owner": "admin"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Create a New Group
|
||||
|
||||
Creates a new server group.
|
||||
|
||||
- **Endpoint**: `/api/groups`
|
||||
- **Method**: `POST`
|
||||
- **Body**:
|
||||
- `name` (string, required): The name of the group.
|
||||
- `description` (string, optional): A description for the group.
|
||||
- `servers` (array of strings, optional): A list of server names to include in the group.
|
||||
- **Request Example**:
|
||||
```json
|
||||
{
|
||||
"name": "My New Group",
|
||||
"description": "A description for the new group",
|
||||
"servers": ["server1", "server2"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Get a Group
|
||||
|
||||
Retrieves details for a specific group by its ID or name.
|
||||
|
||||
- **Endpoint**: `/api/groups/:id`
|
||||
- **Method**: `GET`
|
||||
- **Parameters**:
|
||||
- `:id` (string, required): The ID or name of the group.
|
||||
|
||||
---
|
||||
|
||||
### Update a Group
|
||||
|
||||
Updates an existing group's name, description, or server list.
|
||||
|
||||
- **Endpoint**: `/api/groups/:id`
|
||||
- **Method**: `PUT`
|
||||
- **Parameters**:
|
||||
- `:id` (string, required): The ID or name of the group to update.
|
||||
- **Body**:
|
||||
- `name` (string, optional): The new name for the group.
|
||||
- `description` (string, optional): The new description for the group.
|
||||
- `servers` (array, optional): The new list of servers for the group. See [Batch Update Group Servers](#batch-update-group-servers) for format.
|
||||
- **Request Example**:
|
||||
```json
|
||||
{
|
||||
"name": "Updated Group Name",
|
||||
"description": "Updated description"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Delete a Group
|
||||
|
||||
Deletes a group by its ID or name.
|
||||
|
||||
- **Endpoint**: `/api/groups/:id`
|
||||
- **Method**: `DELETE`
|
||||
- **Parameters**:
|
||||
- `:id` (string, required): The ID or name of the group to delete.
|
||||
|
||||
---
|
||||
|
||||
### Add Server to Group
|
||||
|
||||
Adds a single server to a group.
|
||||
|
||||
- **Endpoint**: `/api/groups/:id/servers`
|
||||
- **Method**: `POST`
|
||||
- **Parameters**:
|
||||
- `:id` (string, required): The ID or name of the group.
|
||||
- **Body**:
|
||||
- `serverName` (string, required): The name of the server to add.
|
||||
- **Request Example**:
|
||||
```json
|
||||
{
|
||||
"serverName": "my-server"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Remove Server from Group
|
||||
|
||||
Removes a single server from a group.
|
||||
|
||||
- **Endpoint**: `/api/groups/:id/servers/:serverName`
|
||||
- **Method**: `DELETE`
|
||||
- **Parameters**:
|
||||
- `:id` (string, required): The ID or name of the group.
|
||||
- `:serverName` (string, required): The name of the server to remove.
|
||||
|
||||
---
|
||||
|
||||
### Batch Update Group Servers
|
||||
|
||||
Replaces all servers in a group with a new list. The list can be simple strings or detailed configuration objects.
|
||||
|
||||
- **Endpoint**: `/api/groups/:id/servers/batch`
|
||||
- **Method**: `PUT`
|
||||
- **Parameters**:
|
||||
- `:id` (string, required): The ID or name of the group.
|
||||
- **Body**:
|
||||
- `servers` (array, required): An array of server names (strings) or server configuration objects.
|
||||
- **Request Example (Simple)**:
|
||||
```json
|
||||
{
|
||||
"servers": ["server1", "server2"]
|
||||
}
|
||||
```
|
||||
- **Request Example (Detailed)**:
|
||||
```json
|
||||
{
|
||||
"servers": [
|
||||
{ "name": "server1", "tools": "all" },
|
||||
{ "name": "server2", "tools": ["toolA", "toolB"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Get Group Server Configs
|
||||
|
||||
Retrieves the detailed configuration for all servers within a group, including which tools are enabled.
|
||||
|
||||
- **Endpoint**: `/api/groups/:id/server-configs`
|
||||
- **Method**: `GET`
|
||||
- **Parameters**:
|
||||
- `:id` (string, required): The ID or name of the group.
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"name": "server1",
|
||||
"tools": "all"
|
||||
},
|
||||
{
|
||||
"name": "server2",
|
||||
"tools": ["toolA", "toolB"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Update Group Server Tools
|
||||
|
||||
Updates the tool selection for a specific server within a group.
|
||||
|
||||
- **Endpoint**: `/api/groups/:id/server-configs/:serverName/tools`
|
||||
- **Method**: `PUT`
|
||||
- **Parameters**:
|
||||
- `:id` (string, required): The ID or name of the group.
|
||||
- `:serverName` (string, required): The name of the server to update.
|
||||
- **Body**:
|
||||
- `tools` (string or array of strings, required): Either the string `"all"` to enable all tools, or an array of tool names to enable specifically.
|
||||
- **Request Example**:
|
||||
```json
|
||||
{
|
||||
"tools": ["toolA", "toolC"]
|
||||
}
|
||||
```
|
||||
@@ -1,33 +1,13 @@
|
||||
---
|
||||
title: 'Introduction'
|
||||
description: 'Example section for showcasing API endpoints'
|
||||
title: "Introduction"
|
||||
description: "Welcome to the MCPHub API documentation."
|
||||
---
|
||||
|
||||
<Note>
|
||||
If you're not looking to build API reference documentation, you can delete
|
||||
this section by removing the api-reference folder.
|
||||
</Note>
|
||||
The MCPHub API provides a comprehensive set of endpoints to manage your MCP servers, groups, users, and more. The API is divided into two main categories:
|
||||
|
||||
## Welcome
|
||||
- **MCP Endpoints**: These are the primary endpoints for interacting with your MCP servers. They provide a unified interface for sending requests to your servers and receiving responses in real-time.
|
||||
- **Management API**: These endpoints are used for managing the MCPHub instance itself. This includes managing servers, groups, users, and system settings.
|
||||
|
||||
There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.
|
||||
All API endpoints are available under the `/api` path. For example, the endpoint to get all servers is `/api/servers`.
|
||||
|
||||
<Card
|
||||
title="Plant Store Endpoints"
|
||||
icon="leaf"
|
||||
href="https://github.com/mintlify/starter/blob/main/api-reference/openapi.json"
|
||||
>
|
||||
View the OpenAPI specification file
|
||||
</Card>
|
||||
|
||||
## Authentication
|
||||
|
||||
All API endpoints are authenticated using Bearer tokens and picked up from the specification file.
|
||||
|
||||
```json
|
||||
"security": [
|
||||
{
|
||||
"bearerAuth": []
|
||||
}
|
||||
]
|
||||
```
|
||||
Authentication is required for most Management API endpoints. See the [Authentication](/api-reference/auth) section for more details.
|
||||
81
docs/api-reference/logs.mdx
Normal file
81
docs/api-reference/logs.mdx
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: "Logs"
|
||||
description: "Access and manage server logs."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="GET /api/logs"
|
||||
href="#get-all-logs"
|
||||
>
|
||||
Get all logs.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="DELETE /api/logs"
|
||||
href="#clear-logs"
|
||||
>
|
||||
Clear all logs.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/logs/stream"
|
||||
href="#stream-logs"
|
||||
>
|
||||
Stream logs in real-time.
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### Get All Logs
|
||||
|
||||
Retrieves all stored logs.
|
||||
|
||||
- **Endpoint**: `/api/logs`
|
||||
- **Method**: `GET`
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"timestamp": "2023-10-27T10:00:00.000Z",
|
||||
"level": "info",
|
||||
"message": "Server started successfully.",
|
||||
"service": "system"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Clear Logs
|
||||
|
||||
Deletes all stored logs.
|
||||
|
||||
- **Endpoint**: `/api/logs`
|
||||
- **Method**: `DELETE`
|
||||
- **Success Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Logs cleared successfully"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stream Logs
|
||||
|
||||
Streams logs in real-time using Server-Sent Events (SSE). The connection will remain open, and new log entries will be sent as they occur.
|
||||
|
||||
- **Endpoint**: `/api/logs/stream`
|
||||
- **Method**: `GET`
|
||||
- **Response Format**: The stream sends events with a `data` field containing a JSON object. The first event has `type: 'initial'` and contains all historical logs. Subsequent events have `type: 'log'` and contain a single new log entry.
|
||||
|
||||
- **Example Event**:
|
||||
```
|
||||
data: {"type":"log","log":{"timestamp":"2023-10-27T10:00:05.000Z","level":"debug","message":"Processing request for /api/some-endpoint","service":"mcp-server"}}
|
||||
```
|
||||
33
docs/api-reference/mcp-http.mdx
Normal file
33
docs/api-reference/mcp-http.mdx
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "MCP HTTP Endpoints"
|
||||
description: "Connect to your MCP servers using the unified HTTP endpoint."
|
||||
---
|
||||
|
||||
MCPHub provides a unified streamable HTTP interface for all your MCP servers. This allows you to send requests to any configured MCP server and receive responses in real-time.
|
||||
|
||||
### Unified Endpoint
|
||||
|
||||
This endpoint provides access to all enabled MCP servers.
|
||||
|
||||
- **Endpoint**: `http://localhost:3000/mcp`
|
||||
- **Method**: `POST`
|
||||
|
||||
### Group-Specific Endpoint
|
||||
|
||||
For targeted access to specific server groups, use the group-based HTTP endpoint.
|
||||
|
||||
- **Endpoint**: `http://localhost:3000/mcp/{group}`
|
||||
- **Method**: `POST`
|
||||
- **Parameters**:
|
||||
- `{group}`: The ID or name of the group.
|
||||
|
||||
### Server-Specific Endpoint
|
||||
|
||||
For direct access to individual servers, use the server-specific HTTP endpoint.
|
||||
|
||||
- **Endpoint**: `http://localhost:3000/mcp/{server}`
|
||||
- **Method**: `POST`
|
||||
- **Parameters**:
|
||||
- `{server}`: The name of the server.
|
||||
|
||||
> **Note**: If a server name and group name are the same, the group will take precedence.
|
||||
25
docs/api-reference/mcp-sse.mdx
Normal file
25
docs/api-reference/mcp-sse.mdx
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "MCP SSE Endpoints (Deprecated)"
|
||||
description: "Connect to your MCP servers using the SSE endpoint."
|
||||
---
|
||||
|
||||
The SSE endpoint is deprecated and will be removed in a future version. Please use the [MCP HTTP Endpoints](/api-reference/mcp-http) instead.
|
||||
|
||||
### Unified Endpoint
|
||||
|
||||
- **Endpoint**: `http://localhost:3000/sse`
|
||||
- **Method**: `GET`
|
||||
|
||||
### Group-Specific Endpoint
|
||||
|
||||
- **Endpoint**: `http://localhost:3000/sse/{group}`
|
||||
- **Method**: `GET`
|
||||
- **Parameters**:
|
||||
- `{group}`: The ID or name of the group.
|
||||
|
||||
### Server-Specific Endpoint
|
||||
|
||||
- **Endpoint**: `http://localhost:3000/sse/{server}`
|
||||
- **Method**: `GET`
|
||||
- **Parameters**:
|
||||
- `{server}`: The name of the server.
|
||||
209
docs/api-reference/servers.mdx
Normal file
209
docs/api-reference/servers.mdx
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
title: "Servers"
|
||||
description: "Manage your MCP servers."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="GET /api/servers"
|
||||
href="#get-all-servers"
|
||||
>
|
||||
Get a list of all MCP servers.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/servers"
|
||||
href="#create-a-new-server"
|
||||
>
|
||||
Create a new MCP server.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/servers/:name"
|
||||
href="#update-a-server"
|
||||
>
|
||||
Update an existing MCP server.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="DELETE /api/servers/:name"
|
||||
href="#delete-a-server"
|
||||
>
|
||||
Delete an MCP server.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/servers/:name/toggle"
|
||||
href="#toggle-a-server"
|
||||
>
|
||||
Toggle the enabled state of a server.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/servers/:serverName/tools/:toolName/toggle"
|
||||
href="#toggle-a-tool"
|
||||
>
|
||||
Toggle the enabled state of a tool.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/servers/:serverName/tools/:toolName/description"
|
||||
href="#update-tool-description"
|
||||
>
|
||||
Update the description of a tool.
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### Get All Servers
|
||||
|
||||
Retrieves a list of all configured MCP servers, including their status and available tools.
|
||||
|
||||
- **Endpoint**: `/api/servers`
|
||||
- **Method**: `GET`
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"name": "example-server",
|
||||
"status": "connected",
|
||||
"tools": [
|
||||
{
|
||||
"name": "tool1",
|
||||
"description": "Description of tool 1"
|
||||
}
|
||||
],
|
||||
"config": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["server.js"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Create a New Server
|
||||
|
||||
Adds a new MCP server to the configuration.
|
||||
|
||||
- **Endpoint**: `/api/servers`
|
||||
- **Method**: `POST`
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"name": "my-new-server",
|
||||
"config": {
|
||||
"type": "stdio",
|
||||
"command": "python",
|
||||
"args": ["-u", "my_script.py"],
|
||||
"owner": "admin"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `name` (string, required): The unique name for the server.
|
||||
- `config` (object, required): The server configuration object.
|
||||
- `type` (string): `stdio`, `sse`, `streamable-http`, or `openapi`.
|
||||
- `command` (string): Command to execute for `stdio` type.
|
||||
- `args` (array of strings): Arguments for the command.
|
||||
- `url` (string): URL for `sse`, `streamable-http`, or `openapi` types.
|
||||
- `openapi` (object): OpenAPI configuration.
|
||||
- `url` (string): URL to the OpenAPI schema.
|
||||
- `schema` (object): The OpenAPI schema object itself.
|
||||
- `headers` (object): Headers to send with requests for `sse`, `streamable-http`, and `openapi` types.
|
||||
- `keepAliveInterval` (number): Keep-alive interval in milliseconds for `sse` type. Defaults to 60000.
|
||||
- `owner` (string): The owner of the server. Defaults to the current user or 'admin'.
|
||||
|
||||
---
|
||||
|
||||
### Update a Server
|
||||
|
||||
Updates the configuration of an existing MCP server.
|
||||
|
||||
- **Endpoint**: `/api/servers/:name`
|
||||
- **Method**: `PUT`
|
||||
- **Parameters**:
|
||||
- `:name` (string, required): The name of the server to update.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["new_server.js"]
|
||||
}
|
||||
}
|
||||
```
|
||||
- `config` (object, required): The updated server configuration object. See "Create a New Server" for details.
|
||||
|
||||
---
|
||||
|
||||
### Delete a Server
|
||||
|
||||
Removes an MCP server from the configuration.
|
||||
|
||||
- **Endpoint**: `/api/servers/:name`
|
||||
- **Method**: `DELETE`
|
||||
- **Parameters**:
|
||||
- `:name` (string, required): The name of the server to delete.
|
||||
|
||||
---
|
||||
|
||||
### Toggle a Server
|
||||
|
||||
Enables or disables an MCP server.
|
||||
|
||||
- **Endpoint**: `/api/servers/:name/toggle`
|
||||
- **Method**: `POST`
|
||||
- **Parameters**:
|
||||
- `:name` (string, required): The name of the server to toggle.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
- `enabled` (boolean, required): `true` to enable the server, `false` to disable it.
|
||||
|
||||
---
|
||||
|
||||
### Toggle a Tool
|
||||
|
||||
Enables or disables a specific tool on a server.
|
||||
|
||||
- **Endpoint**: `/api/servers/:serverName/tools/:toolName/toggle`
|
||||
- **Method**: `POST`
|
||||
- **Parameters**:
|
||||
- `:serverName` (string, required): The name of the server.
|
||||
- `:toolName` (string, required): The name of the tool.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
- `enabled` (boolean, required): `true` to enable the tool, `false` to disable it.
|
||||
|
||||
---
|
||||
|
||||
### Update Tool Description
|
||||
|
||||
Updates the description of a specific tool.
|
||||
|
||||
- **Endpoint**: `/api/servers/:serverName/tools/:toolName/description`
|
||||
- **Method**: `PUT`
|
||||
- **Parameters**:
|
||||
- `:serverName` (string, required): The name of the server.
|
||||
- `:toolName` (string, required): The name of the tool.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"description": "New tool description"
|
||||
}
|
||||
```
|
||||
- `description` (string, required): The new description for the tool.
|
||||
29
docs/api-reference/smart-routing.mdx
Normal file
29
docs/api-reference/smart-routing.mdx
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "Smart Routing"
|
||||
description: "Intelligent tool discovery using vector semantic search."
|
||||
---
|
||||
|
||||
Smart Routing is MCPHub's intelligent tool discovery system that uses vector semantic search to automatically find the most relevant tools for any given task.
|
||||
|
||||
### HTTP Endpoint
|
||||
|
||||
- **Endpoint**: `http://localhost:3000/mcp/$smart`
|
||||
- **Method**: `POST`
|
||||
|
||||
### SSE Endpoint (Deprecated)
|
||||
|
||||
- **Endpoint**: `http://localhost:3000/sse/$smart`
|
||||
- **Method**: `GET`
|
||||
|
||||
### How it Works
|
||||
|
||||
1. **Tool Indexing**: All MCP tools are automatically converted to vector embeddings and stored in PostgreSQL with pgvector.
|
||||
2. **Semantic Search**: User queries are converted to vectors and matched against tool embeddings using cosine similarity.
|
||||
3. **Intelligent Filtering**: Dynamic thresholds ensure relevant results without noise.
|
||||
4. **Precise Execution**: Found tools can be directly executed with proper parameter validation.
|
||||
|
||||
### Setup Requirements
|
||||
|
||||
- PostgreSQL with pgvector extension
|
||||
- OpenAI API key (or compatible embedding service)
|
||||
- Enable Smart Routing in MCPHub settings
|
||||
@@ -70,26 +70,58 @@
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "API",
|
||||
"groups": [
|
||||
{
|
||||
"group": "MCP Endpoints",
|
||||
"pages": [
|
||||
"api-reference/introduction",
|
||||
"api-reference/mcp-http",
|
||||
"api-reference/mcp-sse",
|
||||
"api-reference/smart-routing"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Management Endpoints",
|
||||
"pages": [
|
||||
"api-reference/servers",
|
||||
"api-reference/groups",
|
||||
"api-reference/auth",
|
||||
"api-reference/logs",
|
||||
"api-reference/config"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "接口",
|
||||
"groups": [
|
||||
{
|
||||
"group": "MCP 端点",
|
||||
"pages": [
|
||||
"zh/api-reference/introduction",
|
||||
"zh/api-reference/mcp-http",
|
||||
"zh/api-reference/mcp-sse",
|
||||
"zh/api-reference/smart-routing"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "管理端点",
|
||||
"pages": [
|
||||
"zh/api-reference/servers",
|
||||
"zh/api-reference/groups",
|
||||
"zh/api-reference/auth",
|
||||
"zh/api-reference/logs",
|
||||
"zh/api-reference/config"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"global": {
|
||||
"anchors": [
|
||||
{
|
||||
"anchor": "GitHub",
|
||||
"href": "https://github.com/samanhappy/mcphub",
|
||||
"icon": "github"
|
||||
},
|
||||
{
|
||||
"anchor": "Discord",
|
||||
"href": "https://discord.gg/qMKNsn5Q",
|
||||
"icon": "discord"
|
||||
},
|
||||
{
|
||||
"anchor": "Sponsor",
|
||||
"href": "https://ko-fi.com/samanhappy",
|
||||
"icon": "heart"
|
||||
}
|
||||
]
|
||||
"anchors": []
|
||||
}
|
||||
},
|
||||
"logo": {
|
||||
|
||||
147
docs/zh/api-reference/auth.mdx
Normal file
147
docs/zh/api-reference/auth.mdx
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "身份验证"
|
||||
description: "管理用户和身份验证。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="POST /api/auth/login"
|
||||
href="#login"
|
||||
>
|
||||
登录以获取 JWT 令牌。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/auth/register"
|
||||
href="#register"
|
||||
>
|
||||
注册一个新用户。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/auth/user"
|
||||
href="#get-current-user"
|
||||
>
|
||||
获取当前已验证的用户。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/auth/change-password"
|
||||
href="#change-password"
|
||||
>
|
||||
更改当前用户的密码。
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### 登录
|
||||
|
||||
验证用户身份并返回 JWT 令牌及用户详细信息。
|
||||
|
||||
- **端点**: `/api/auth/login`
|
||||
- **方法**: `POST`
|
||||
- **正文**:
|
||||
- `username` (string, 必填): 用户名。
|
||||
- `password` (string, 必填): 用户密码。
|
||||
- **请求示例**:
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
```
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "登录成功",
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"user": {
|
||||
"username": "admin",
|
||||
"isAdmin": true,
|
||||
"permissions": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 注册
|
||||
|
||||
注册一个新用户并返回 JWT 令牌。
|
||||
|
||||
- **端点**: `/api/auth/register`
|
||||
- **方法**: `POST`
|
||||
- **正文**:
|
||||
- `username` (string, 必填): 新的用户名。
|
||||
- `password` (string, 必填): 新的用户密码 (至少6个字符)。
|
||||
- `isAdmin` (boolean, 可选): 用户是否应有管理员权限。
|
||||
- **请求示例**:
|
||||
```json
|
||||
{
|
||||
"username": "newuser",
|
||||
"password": "password123",
|
||||
"isAdmin": false
|
||||
}
|
||||
```
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"user": {
|
||||
"username": "newuser",
|
||||
"isAdmin": false,
|
||||
"permissions": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 获取当前用户
|
||||
|
||||
检索当前通过身份验证的用户的个人资料。
|
||||
|
||||
- **端点**: `/api/auth/user`
|
||||
- **方法**: `GET`
|
||||
- **身份验证**: 需要承载令牌 (Bearer Token)。
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"user": {
|
||||
"username": "admin",
|
||||
"isAdmin": true,
|
||||
"permissions": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 更改密码
|
||||
|
||||
允许通过身份验证的用户更改其密码。
|
||||
|
||||
- **端点**: `/api/auth/change-password`
|
||||
- **方法**: `POST`
|
||||
- **身份验证**: 需要承载令牌 (Bearer Token)。
|
||||
- **正文**:
|
||||
- `currentPassword` (string, 必填): 用户的当前密码。
|
||||
- `newPassword` (string, 必填): 新的密码 (至少6个字符)。
|
||||
- **请求示例**:
|
||||
```json
|
||||
{
|
||||
"currentPassword": "oldpassword",
|
||||
"newPassword": "newpassword123"
|
||||
}
|
||||
```
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "密码更新成功"
|
||||
}
|
||||
```
|
||||
111
docs/zh/api-reference/config.mdx
Normal file
111
docs/zh/api-reference/config.mdx
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: "配置"
|
||||
description: "管理和检索系统级配置。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card title="PUT /api/system-config" href="#update-system-config">更新主系统配置。</Card>
|
||||
<Card title="GET /api/settings" href="#get-all-settings">获取所有系统设置，包括服务器和群组。</Card>
|
||||
<Card title="GET /config" href="#get-runtime-config">获取前端的公共运行时配置。</Card>
|
||||
<Card title="GET /public-config" href="#get-public-config">获取公共配置以检查是否跳过身份验证。</Card>
|
||||
|
||||
---
|
||||
|
||||
### 更新系统配置
|
||||
|
||||
更新系统配置的各个部分。您只需提供要更新部分的键。
|
||||
|
||||
- **端点**: `/api/system-config`
|
||||
- **方法**: `PUT`
|
||||
- **正文**: 一个 JSON 对象，包含以下一个或多个顶级键：`routing`、`install`、`smartRouting`、`mcpRouter`。
|
||||
|
||||
#### 路由配置 (`routing`)
|
||||
|
||||
- `enableGlobalRoute` (boolean): 启用或禁用全局 `/api/mcp` 路由。
|
||||
- `enableGroupNameRoute` (boolean): 启用或禁用基于群组的路由 (例如 `/api/mcp/group/:groupName`)。
|
||||
- `enableBearerAuth` (boolean): 为 MCP 路由启用承载令牌身份验证。
|
||||
- `bearerAuthKey` (string): 用于承载身份验证的密钥。
|
||||
- `skipAuth` (boolean): 如果为 true，则跳过所有身份验证，使实例公开。
|
||||
|
||||
#### 安装配置 (`install`)
|
||||
|
||||
- `pythonIndexUrl` (string): 用于安装的 Python 包索引 (PyPI) 的基础 URL。
|
||||
- `npmRegistry` (string): 用于安装的 npm 注册表 URL。
|
||||
- `baseUrl` (string): 此 MCPHub 实例的公共基础 URL。
|
||||
|
||||
#### 智能路由配置 (`smartRouting`)
|
||||
|
||||
- `enabled` (boolean): 启用或禁用智能路由功能。
|
||||
- `dbUrl` (string): 用于存储嵌入的数据库连接 URL。
|
||||
- `openaiApiBaseUrl` (string): 用于生成嵌入的 OpenAI 兼容 API 的基础 URL。
|
||||
- `openaiApiKey` (string): 嵌入服务的 API 密钥。
|
||||
- `openaiApiEmbeddingModel` (string): 要使用的嵌入模型的名称。
|
||||
|
||||
#### MCP 路由器配置 (`mcpRouter`)
|
||||
|
||||
- `apiKey` (string): MCP 路由器服务的 API 密钥。
|
||||
- `referer` (string): 用于 MCP 路由器请求的 referer 头。
|
||||
- `title` (string): 在 MCP 路由器上显示的此实例的标题。
|
||||
- `baseUrl` (string): MCP 路由器 API 的基础 URL。
|
||||
|
||||
- **请求示例**:
|
||||
```json
|
||||
{
|
||||
"routing": {
|
||||
"skipAuth": true
|
||||
},
|
||||
"smartRouting": {
|
||||
"enabled": true,
|
||||
"dbUrl": "postgresql://user:pass@host:port/db"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 获取所有设置
|
||||
|
||||
检索实例的整个设置对象，包括所有服务器配置、群组和系统设置。这是 `mcp_settings.json` 文件的完整转储。
|
||||
|
||||
- **端点**: `/api/settings`
|
||||
- **方法**: `GET`
|
||||
|
||||
---
|
||||
|
||||
### 获取运行时配置
|
||||
|
||||
检索前端应用程序所需的基本运行时配置。此端点不需要身份验证。
|
||||
|
||||
- **端点**: `/config`
|
||||
- **方法**: `GET`
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"basePath": "",
|
||||
"version": "1.0.0",
|
||||
"name": "MCPHub"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 获取公共配置
|
||||
|
||||
检索公共配置，主要用于检查是否跳过身份验证。这允许前端在用户登录前相应地调整其行为。此端点不需要身份验证。
|
||||
|
||||
- **端点**: `/public-config`
|
||||
- **方法**: `GET`
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"skipAuth": false,
|
||||
"permissions": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,572 +0,0 @@
|
||||
---
|
||||
title: '创建资源'
|
||||
description: '创建新的 MCP 服务器、用户和组'
|
||||
---
|
||||
|
||||
## 创建服务器
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
POST /api/servers
|
||||
```
|
||||
|
||||
### 请求
|
||||
|
||||
#### 请求头
|
||||
|
||||
```http
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_JWT_TOKEN
|
||||
```
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "文件系统服务器",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
|
||||
"env": {
|
||||
"NODE_ENV": "production",
|
||||
"DEBUG": "mcp:*",
|
||||
"MAX_FILES": "1000"
|
||||
},
|
||||
"cwd": "/app/workspace",
|
||||
"timeout": 30000,
|
||||
"retries": 3,
|
||||
"enabled": true,
|
||||
"description": "提供文件系统访问的 MCP 服务器",
|
||||
"tags": ["filesystem", "production"],
|
||||
"healthCheck": {
|
||||
"enabled": true,
|
||||
"interval": 30000,
|
||||
"timeout": 5000,
|
||||
"retries": 3,
|
||||
"endpoint": "/health"
|
||||
},
|
||||
"resources": {
|
||||
"memory": {
|
||||
"limit": "512MB",
|
||||
"warning": "400MB"
|
||||
},
|
||||
"cpu": {
|
||||
"limit": "50%"
|
||||
}
|
||||
},
|
||||
"logging": {
|
||||
"level": "info",
|
||||
"file": "/var/log/mcphub/server.log",
|
||||
"maxSize": "100MB",
|
||||
"maxFiles": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 必填字段
|
||||
|
||||
- `name` (string): 服务器唯一名称
|
||||
- `command` (string): 执行命令
|
||||
- `args` (array): 命令参数数组
|
||||
|
||||
#### 可选字段
|
||||
|
||||
- `env` (object): 环境变量键值对
|
||||
- `cwd` (string): 工作目录
|
||||
- `timeout` (number): 超时时间（毫秒）
|
||||
- `retries` (number): 重试次数
|
||||
- `enabled` (boolean): 是否启用（默认 true）
|
||||
- `description` (string): 服务器描述
|
||||
- `tags` (array): 标签数组
|
||||
- `healthCheck` (object): 健康检查配置
|
||||
- `resources` (object): 资源限制配置
|
||||
- `logging` (object): 日志配置
|
||||
|
||||
### 响应
|
||||
|
||||
#### 成功响应 (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "server-abc123",
|
||||
"name": "文件系统服务器",
|
||||
"status": "stopped",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
|
||||
"env": {
|
||||
"NODE_ENV": "production",
|
||||
"DEBUG": "mcp:*",
|
||||
"MAX_FILES": "1000"
|
||||
},
|
||||
"cwd": "/app/workspace",
|
||||
"timeout": 30000,
|
||||
"retries": 3,
|
||||
"enabled": true,
|
||||
"description": "提供文件系统访问的 MCP 服务器",
|
||||
"tags": ["filesystem", "production"],
|
||||
"healthCheck": {
|
||||
"enabled": true,
|
||||
"interval": 30000,
|
||||
"timeout": 5000,
|
||||
"retries": 3,
|
||||
"endpoint": "/health",
|
||||
"status": "unknown"
|
||||
},
|
||||
"resources": {
|
||||
"memory": {
|
||||
"limit": "512MB",
|
||||
"warning": "400MB",
|
||||
"current": "0MB"
|
||||
},
|
||||
"cpu": {
|
||||
"limit": "50%",
|
||||
"current": "0%"
|
||||
}
|
||||
},
|
||||
"logging": {
|
||||
"level": "info",
|
||||
"file": "/var/log/mcphub/server.log",
|
||||
"maxSize": "100MB",
|
||||
"maxFiles": 5,
|
||||
"currentSize": "0MB"
|
||||
},
|
||||
"createdAt": "2024-01-01T12:00:00Z",
|
||||
"updatedAt": "2024-01-01T12:00:00Z",
|
||||
"createdBy": "user123"
|
||||
},
|
||||
"message": "服务器创建成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
**400 Bad Request - 参数错误**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "请求数据验证失败",
|
||||
"details": [
|
||||
{
|
||||
"field": "name",
|
||||
"message": "服务器名称不能为空"
|
||||
},
|
||||
{
|
||||
"field": "command",
|
||||
"message": "执行命令不能为空"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**409 Conflict - 名称冲突**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "RESOURCE_CONFLICT",
|
||||
"message": "服务器名称已存在",
|
||||
"details": {
|
||||
"field": "name",
|
||||
"value": "文件系统服务器",
|
||||
"conflictingResourceId": "server-xyz789"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 示例
|
||||
|
||||
#### cURL
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/servers \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"name": "文件系统服务器",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
|
||||
"env": {
|
||||
"NODE_ENV": "production"
|
||||
},
|
||||
"description": "生产环境文件系统服务器"
|
||||
}'
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
const response = await fetch('/api/servers', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
Authorization: `Bearer ${token}`,
|
||||
},
|
||||
body: JSON.stringify({
|
||||
name: '文件系统服务器',
|
||||
command: 'npx',
|
||||
args: ['-y', '@modelcontextprotocol/server-filesystem', '/data'],
|
||||
env: {
|
||||
NODE_ENV: 'production',
|
||||
},
|
||||
description: '生产环境文件系统服务器',
|
||||
}),
|
||||
});
|
||||
|
||||
const result = await response.json();
|
||||
if (result.success) {
|
||||
console.log('服务器创建成功:', result.data);
|
||||
} else {
|
||||
console.error('创建失败:', result.error);
|
||||
}
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
'http://localhost:3000/api/servers',
|
||||
headers={
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': f'Bearer {token}'
|
||||
},
|
||||
json={
|
||||
'name': '文件系统服务器',
|
||||
'command': 'npx',
|
||||
'args': ['-y', '@modelcontextprotocol/server-filesystem', '/data'],
|
||||
'env': {
|
||||
'NODE_ENV': 'production'
|
||||
},
|
||||
'description': '生产环境文件系统服务器'
|
||||
}
|
||||
)
|
||||
|
||||
if response.status_code == 201:
|
||||
result = response.json()
|
||||
print('服务器创建成功:', result['data'])
|
||||
else:
|
||||
error = response.json()
|
||||
print('创建失败:', error['error'])
|
||||
```
|
||||
|
||||
## 创建用户
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
POST /api/users
|
||||
```
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "newuser",
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePassword123!",
|
||||
"role": "user",
|
||||
"groups": ["dev-team", "qa-team"],
|
||||
"profile": {
|
||||
"firstName": "张",
|
||||
"lastName": "三",
|
||||
"department": "开发部",
|
||||
"title": "软件工程师",
|
||||
"phone": "+86-138-0013-8000",
|
||||
"location": "北京"
|
||||
},
|
||||
"preferences": {
|
||||
"language": "zh-CN",
|
||||
"timezone": "Asia/Shanghai",
|
||||
"notifications": {
|
||||
"email": true,
|
||||
"slack": false,
|
||||
"browser": true
|
||||
}
|
||||
},
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### 响应 (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "user-abc123",
|
||||
"username": "newuser",
|
||||
"email": "user@example.com",
|
||||
"role": "user",
|
||||
"groups": [
|
||||
{
|
||||
"id": "dev-team",
|
||||
"name": "开发团队",
|
||||
"role": "member"
|
||||
}
|
||||
],
|
||||
"profile": {
|
||||
"firstName": "张",
|
||||
"lastName": "三",
|
||||
"fullName": "张三",
|
||||
"department": "开发部",
|
||||
"title": "软件工程师",
|
||||
"phone": "+86-138-0013-8000",
|
||||
"location": "北京",
|
||||
"avatar": null
|
||||
},
|
||||
"preferences": {
|
||||
"language": "zh-CN",
|
||||
"timezone": "Asia/Shanghai",
|
||||
"notifications": {
|
||||
"email": true,
|
||||
"slack": false,
|
||||
"browser": true
|
||||
}
|
||||
},
|
||||
"enabled": true,
|
||||
"lastLoginAt": null,
|
||||
"createdAt": "2024-01-01T12:00:00Z",
|
||||
"updatedAt": "2024-01-01T12:00:00Z"
|
||||
},
|
||||
"message": "用户创建成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 创建组
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
POST /api/groups
|
||||
```
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "dev-team",
|
||||
"displayName": "开发团队",
|
||||
"description": "前端和后端开发人员",
|
||||
"parentGroup": null,
|
||||
"permissions": {
|
||||
"servers": {
|
||||
"create": false,
|
||||
"read": true,
|
||||
"update": true,
|
||||
"delete": false,
|
||||
"execute": true
|
||||
},
|
||||
"tools": {
|
||||
"filesystem": {
|
||||
"read": true,
|
||||
"write": true,
|
||||
"paths": ["/app/data", "/tmp"]
|
||||
},
|
||||
"web-search": {
|
||||
"enabled": true,
|
||||
"maxQueries": 100
|
||||
}
|
||||
},
|
||||
"monitoring": {
|
||||
"viewLogs": true,
|
||||
"viewMetrics": true,
|
||||
"exportData": false
|
||||
}
|
||||
},
|
||||
"settings": {
|
||||
"autoAssign": false,
|
||||
"maxMembers": 50,
|
||||
"requireApproval": true,
|
||||
"sessionTimeout": "8h"
|
||||
},
|
||||
"quotas": {
|
||||
"requests": {
|
||||
"daily": 1000,
|
||||
"monthly": 30000
|
||||
},
|
||||
"storage": {
|
||||
"maxSize": "10GB"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 响应 (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "group-abc123",
|
||||
"name": "dev-team",
|
||||
"displayName": "开发团队",
|
||||
"description": "前端和后端开发人员",
|
||||
"parentGroup": null,
|
||||
"permissions": {
|
||||
"servers": {
|
||||
"create": false,
|
||||
"read": true,
|
||||
"update": true,
|
||||
"delete": false,
|
||||
"execute": true
|
||||
},
|
||||
"tools": {
|
||||
"filesystem": {
|
||||
"read": true,
|
||||
"write": true,
|
||||
"paths": ["/app/data", "/tmp"]
|
||||
},
|
||||
"web-search": {
|
||||
"enabled": true,
|
||||
"maxQueries": 100
|
||||
}
|
||||
},
|
||||
"monitoring": {
|
||||
"viewLogs": true,
|
||||
"viewMetrics": true,
|
||||
"exportData": false
|
||||
}
|
||||
},
|
||||
"settings": {
|
||||
"autoAssign": false,
|
||||
"maxMembers": 50,
|
||||
"requireApproval": true,
|
||||
"sessionTimeout": "8h"
|
||||
},
|
||||
"quotas": {
|
||||
"requests": {
|
||||
"daily": 1000,
|
||||
"monthly": 30000
|
||||
},
|
||||
"storage": {
|
||||
"maxSize": "10GB"
|
||||
}
|
||||
},
|
||||
"memberCount": 0,
|
||||
"serverCount": 0,
|
||||
"createdAt": "2024-01-01T12:00:00Z",
|
||||
"updatedAt": "2024-01-01T12:00:00Z",
|
||||
"createdBy": "admin"
|
||||
},
|
||||
"message": "组创建成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 批量创建
|
||||
|
||||
### 批量创建服务器
|
||||
|
||||
```http
|
||||
POST /api/servers/bulk
|
||||
```
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"name": "dev-server-1",
|
||||
"command": "python",
|
||||
"args": ["-m", "mcp_server"],
|
||||
"env": { "ENV": "development" }
|
||||
},
|
||||
{
|
||||
"name": "dev-server-2",
|
||||
"command": "node",
|
||||
"args": ["server.js"],
|
||||
"env": { "ENV": "development" }
|
||||
}
|
||||
],
|
||||
"options": {
|
||||
"skipExisting": true,
|
||||
"validateAll": true,
|
||||
"startAfterCreate": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应 (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"created": [
|
||||
{
|
||||
"id": "server-1",
|
||||
"name": "dev-server-1",
|
||||
"status": "created"
|
||||
},
|
||||
{
|
||||
"id": "server-2",
|
||||
"name": "dev-server-2",
|
||||
"status": "created"
|
||||
}
|
||||
],
|
||||
"skipped": [],
|
||||
"failed": [],
|
||||
"summary": {
|
||||
"total": 2,
|
||||
"created": 2,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"message": "批量创建完成，成功创建 2 个服务器"
|
||||
}
|
||||
```
|
||||
|
||||
## 验证
|
||||
|
||||
### 预验证创建请求
|
||||
|
||||
在实际创建资源之前验证请求：
|
||||
|
||||
```http
|
||||
POST /api/servers/validate
|
||||
```
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "test-server",
|
||||
"command": "invalid-command",
|
||||
"args": []
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"data": {
|
||||
"valid": false,
|
||||
"errors": [
|
||||
{
|
||||
"field": "command",
|
||||
"message": "命令 'invalid-command' 不存在或无法执行"
|
||||
}
|
||||
],
|
||||
"warnings": [
|
||||
{
|
||||
"field": "args",
|
||||
"message": "参数数组为空，服务器可能无法正常启动"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
有关更多 API 端点信息，请参阅 [获取资源](/zh/api-reference/endpoint/get)、[删除资源](/zh/api-reference/endpoint/delete) 和 [WebHooks](/zh/api-reference/endpoint/webhook) 文档。
|
||||
@@ -1,303 +0,0 @@
|
||||
---
|
||||
title: 删除资源 API
|
||||
description: 删除各种资源的 API 端点，包括服务器、组和配置等
|
||||
---
|
||||
|
||||
# 删除资源 API
|
||||
|
||||
本文档描述了用于删除各种资源的 API 端点。
|
||||
|
||||
## 删除 MCP 服务器
|
||||
|
||||
删除指定的 MCP 服务器配置。
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
DELETE /api/servers/{id}
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数名 | 类型 | 位置 | 必需 | 描述 |
|
||||
| ------ | ------ | ---- | ---- | ------------------ |
|
||||
| id | string | path | 是 | 服务器的唯一标识符 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X DELETE \
|
||||
'https://api.mcphub.io/api/servers/mcp-server-123' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN' \
|
||||
-H 'Content-Type: application/json'
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
#### 成功响应 (204 No Content)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "服务器已成功删除",
|
||||
"data": {
|
||||
"id": "mcp-server-123",
|
||||
"deletedAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
**404 Not Found**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "SERVER_NOT_FOUND",
|
||||
"message": "指定的服务器不存在",
|
||||
"details": {
|
||||
"serverId": "mcp-server-123"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**409 Conflict**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "SERVER_IN_USE",
|
||||
"message": "服务器正在使用中，无法删除",
|
||||
"details": {
|
||||
"activeConnections": 5,
|
||||
"associatedGroups": ["group-1", "group-2"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 删除服务器组
|
||||
|
||||
删除指定的服务器组。
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
DELETE /api/groups/{id}
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数名 | 类型 | 位置 | 必需 | 描述 |
|
||||
| ------ | ------- | ----- | ---- | ------------------------------ |
|
||||
| id | string | path | 是 | 组的唯一标识符 |
|
||||
| force | boolean | query | 否 | 是否强制删除（包含服务器的组） |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X DELETE \
|
||||
'https://api.mcphub.io/api/groups/production-group?force=true' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN' \
|
||||
-H 'Content-Type: application/json'
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
#### 成功响应 (204 No Content)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "服务器组已成功删除",
|
||||
"data": {
|
||||
"id": "production-group",
|
||||
"deletedServers": ["server-1", "server-2"],
|
||||
"deletedAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 删除配置项
|
||||
|
||||
删除指定的配置项。
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
DELETE /api/config/{key}
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数名 | 类型 | 位置 | 必需 | 描述 |
|
||||
| ------ | ------ | ---- | ---- | -------- |
|
||||
| key | string | path | 是 | 配置键名 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X DELETE \
|
||||
'https://api.mcphub.io/api/config/custom-setting' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN'
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
#### 成功响应 (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "配置项已删除",
|
||||
"data": {
|
||||
"key": "custom-setting",
|
||||
"previousValue": "old-value",
|
||||
"deletedAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 批量删除
|
||||
|
||||
### 批量删除服务器
|
||||
|
||||
删除多个 MCP 服务器。
|
||||
|
||||
#### 端点
|
||||
|
||||
```http
|
||||
DELETE /api/servers/batch
|
||||
```
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"serverIds": ["server-1", "server-2", "server-3"],
|
||||
"force": false
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "批量删除完成",
|
||||
"data": {
|
||||
"deleted": ["server-1", "server-3"],
|
||||
"failed": [
|
||||
{
|
||||
"id": "server-2",
|
||||
"reason": "服务器正在使用中"
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"total": 3,
|
||||
"deleted": 2,
|
||||
"failed": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 软删除 vs 硬删除
|
||||
|
||||
### 软删除
|
||||
|
||||
默认情况下，MCPHub 使用软删除机制：
|
||||
|
||||
- 资源被标记为已删除但保留在数据库中
|
||||
- 可以通过恢复 API 恢复删除的资源
|
||||
- 删除的资源在列表 API 中默认不显示
|
||||
|
||||
### 硬删除
|
||||
|
||||
使用 `permanent=true` 参数执行硬删除：
|
||||
|
||||
```bash
|
||||
curl -X DELETE \
|
||||
'https://api.mcphub.io/api/servers/mcp-server-123?permanent=true' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN'
|
||||
```
|
||||
|
||||
<Warning>硬删除操作不可逆，请谨慎使用。</Warning>
|
||||
|
||||
## 权限要求
|
||||
|
||||
| 操作 | 所需权限 |
|
||||
| ---------- | ------------------------ |
|
||||
| 删除服务器 | `servers:delete` |
|
||||
| 删除组 | `groups:delete` |
|
||||
| 删除配置 | `config:delete` |
|
||||
| 硬删除 | `admin:permanent_delete` |
|
||||
|
||||
## 错误代码
|
||||
|
||||
| 错误代码 | HTTP 状态码 | 描述 |
|
||||
| -------------------------- | ----------- | ---------------- |
|
||||
| `RESOURCE_NOT_FOUND` | 404 | 资源不存在 |
|
||||
| `RESOURCE_IN_USE` | 409 | 资源正在使用中 |
|
||||
| `INSUFFICIENT_PERMISSIONS` | 403 | 权限不足 |
|
||||
| `VALIDATION_ERROR` | 400 | 请求参数验证失败 |
|
||||
| `INTERNAL_ERROR` | 500 | 服务器内部错误 |
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 删除前检查
|
||||
|
||||
在删除资源前，建议先检查资源的使用情况：
|
||||
|
||||
```bash
|
||||
# 检查服务器使用情况
|
||||
curl -X GET \
|
||||
'https://api.mcphub.io/api/servers/mcp-server-123/usage' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN'
|
||||
```
|
||||
|
||||
### 2. 备份重要数据
|
||||
|
||||
对于重要资源，建议在删除前进行备份：
|
||||
|
||||
```bash
|
||||
# 导出服务器配置
|
||||
curl -X GET \
|
||||
'https://api.mcphub.io/api/servers/mcp-server-123/export' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN' \
|
||||
> server-backup.json
|
||||
```
|
||||
|
||||
### 3. 使用事务删除
|
||||
|
||||
对于复杂的删除操作，使用事务确保数据一致性：
|
||||
|
||||
```json
|
||||
{
|
||||
"transaction": true,
|
||||
"operations": [
|
||||
{
|
||||
"type": "delete",
|
||||
"resource": "server",
|
||||
"id": "server-1"
|
||||
},
|
||||
{
|
||||
"type": "delete",
|
||||
"resource": "group",
|
||||
"id": "group-1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 恢复删除的资源
|
||||
|
||||
软删除的资源可以通过恢复 API 恢复：
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
'https://api.mcphub.io/api/servers/mcp-server-123/restore' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN'
|
||||
```
|
||||
@@ -1,607 +0,0 @@
|
||||
---
|
||||
title: '获取资源'
|
||||
description: '查询和检索 MCP 服务器、用户和组信息'
|
||||
---
|
||||
|
||||
## 获取服务器列表
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/servers
|
||||
```
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数 | 类型 | 描述 | 示例 |
|
||||
| ---------------- | ------- | ------------------------------- | ---------------------------- |
|
||||
| `page` | integer | 页码（从 1 开始） | `?page=2` |
|
||||
| `limit` | integer | 每页记录数（默认 20，最大 100） | `?limit=50` |
|
||||
| `sort` | string | 排序字段 | `?sort=name` |
|
||||
| `order` | string | 排序顺序（asc/desc） | `?order=desc` |
|
||||
| `status` | string | 过滤服务器状态 | `?status=running` |
|
||||
| `search` | string | 搜索服务器名称或描述 | `?search=python` |
|
||||
| `group` | string | 过滤所属组 | `?group=dev-team` |
|
||||
| `tags` | string | 过滤标签（逗号分隔） | `?tags=python,production` |
|
||||
| `enabled` | boolean | 过滤启用状态 | `?enabled=true` |
|
||||
| `created_after` | string | 创建时间起始 | `?created_after=2024-01-01` |
|
||||
| `created_before` | string | 创建时间结束 | `?created_before=2024-01-31` |
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"id": "server-abc123",
|
||||
"name": "文件系统服务器",
|
||||
"status": "running",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
|
||||
"env": {
|
||||
"NODE_ENV": "production"
|
||||
},
|
||||
"cwd": "/app",
|
||||
"pid": 12345,
|
||||
"uptime": 3600000,
|
||||
"enabled": true,
|
||||
"description": "提供文件系统访问的 MCP 服务器",
|
||||
"tags": ["filesystem", "production"],
|
||||
"health": {
|
||||
"status": "healthy",
|
||||
"lastCheck": "2024-01-01T12:00:00Z",
|
||||
"responseTime": "45ms"
|
||||
},
|
||||
"resources": {
|
||||
"memory": {
|
||||
"used": "128MB",
|
||||
"limit": "512MB",
|
||||
"percentage": 25
|
||||
},
|
||||
"cpu": {
|
||||
"used": "15%",
|
||||
"limit": "50%"
|
||||
}
|
||||
},
|
||||
"stats": {
|
||||
"totalRequests": 1523,
|
||||
"errorCount": 2,
|
||||
"avgResponseTime": "234ms"
|
||||
},
|
||||
"lastRestart": "2024-01-01T08:00:00Z",
|
||||
"createdAt": "2024-01-01T00:00:00Z",
|
||||
"updatedAt": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 45,
|
||||
"pages": 3,
|
||||
"hasNext": true,
|
||||
"hasPrev": false
|
||||
},
|
||||
"filters": {
|
||||
"status": "running",
|
||||
"totalFiltered": 12
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# 获取运行中的服务器，按名称排序
|
||||
curl -X GET "http://localhost:3000/api/servers?status=running&sort=name&order=asc" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 搜索包含 "python" 的服务器
|
||||
curl -X GET "http://localhost:3000/api/servers?search=python&limit=10" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 获取开发团队的服务器
|
||||
curl -X GET "http://localhost:3000/api/servers?group=dev-team" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## 获取服务器详情
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/servers/{serverId}
|
||||
```
|
||||
|
||||
### 路径参数
|
||||
|
||||
- `serverId` (string): 服务器唯一标识符
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
| --------------- | ------ | ----------------------------------------------- |
|
||||
| `include` | string | 包含额外信息（逗号分隔）：`logs,metrics,events` |
|
||||
| `metrics_range` | string | 指标时间范围：`1h`, `24h`, `7d` |
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "server-abc123",
|
||||
"name": "文件系统服务器",
|
||||
"status": "running",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
|
||||
"env": {
|
||||
"NODE_ENV": "production",
|
||||
"DEBUG": "mcp:*"
|
||||
},
|
||||
"cwd": "/app",
|
||||
"pid": 12345,
|
||||
"uptime": 3600000,
|
||||
"enabled": true,
|
||||
"description": "提供文件系统访问的 MCP 服务器",
|
||||
"tags": ["filesystem", "production"],
|
||||
"healthCheck": {
|
||||
"enabled": true,
|
||||
"interval": 30000,
|
||||
"timeout": 5000,
|
||||
"retries": 3,
|
||||
"endpoint": "/health",
|
||||
"status": "healthy",
|
||||
"lastCheck": "2024-01-01T12:00:00Z",
|
||||
"responseTime": "45ms",
|
||||
"consecutiveFailures": 0
|
||||
},
|
||||
"resources": {
|
||||
"memory": {
|
||||
"used": "128MB",
|
||||
"limit": "512MB",
|
||||
"warning": "400MB",
|
||||
"percentage": 25
|
||||
},
|
||||
"cpu": {
|
||||
"used": "15%",
|
||||
"limit": "50%",
|
||||
"cores": 4
|
||||
},
|
||||
"network": {
|
||||
"bytesIn": "1.2GB",
|
||||
"bytesOut": "890MB"
|
||||
}
|
||||
},
|
||||
"stats": {
|
||||
"totalRequests": 1523,
|
||||
"successfulRequests": 1521,
|
||||
"errorCount": 2,
|
||||
"avgResponseTime": "234ms",
|
||||
"p95ResponseTime": "450ms",
|
||||
"requestsPerMinute": 25,
|
||||
"lastError": {
|
||||
"timestamp": "2024-01-01T11:30:00Z",
|
||||
"message": "Temporary connection timeout",
|
||||
"count": 1
|
||||
}
|
||||
},
|
||||
"capabilities": [
|
||||
{
|
||||
"type": "tool",
|
||||
"name": "read_file",
|
||||
"description": "读取文件内容",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "tool",
|
||||
"name": "write_file",
|
||||
"description": "写入文件内容",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": { "type": "string" },
|
||||
"content": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"groups": [
|
||||
{
|
||||
"id": "dev-team",
|
||||
"name": "开发团队",
|
||||
"permissions": ["read", "write", "execute"]
|
||||
}
|
||||
],
|
||||
"events": [
|
||||
{
|
||||
"id": "event-123",
|
||||
"type": "started",
|
||||
"timestamp": "2024-01-01T08:00:00Z",
|
||||
"message": "服务器启动成功",
|
||||
"metadata": {
|
||||
"pid": 12345,
|
||||
"startupTime": "2.3s"
|
||||
}
|
||||
}
|
||||
],
|
||||
"lastRestart": "2024-01-01T08:00:00Z",
|
||||
"createdAt": "2024-01-01T00:00:00Z",
|
||||
"updatedAt": "2024-01-01T12:00:00Z",
|
||||
"createdBy": "admin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# 获取服务器基本信息
|
||||
curl -X GET "http://localhost:3000/api/servers/server-abc123" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 获取服务器详情包含日志和指标
|
||||
curl -X GET "http://localhost:3000/api/servers/server-abc123?include=logs,metrics&metrics_range=24h" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## 获取服务器状态
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/servers/{serverId}/status
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"serverId": "server-abc123",
|
||||
"status": "running",
|
||||
"health": "healthy",
|
||||
"pid": 12345,
|
||||
"uptime": 3600000,
|
||||
"startedAt": "2024-01-01T08:00:00Z",
|
||||
"lastHealthCheck": "2024-01-01T12:00:00Z",
|
||||
"resources": {
|
||||
"memory": {
|
||||
"rss": 134217728,
|
||||
"heapTotal": 67108864,
|
||||
"heapUsed": 45088768,
|
||||
"external": 8388608
|
||||
},
|
||||
"cpu": {
|
||||
"user": 1000000,
|
||||
"system": 500000,
|
||||
"percentage": 15.5
|
||||
}
|
||||
},
|
||||
"connections": {
|
||||
"active": 5,
|
||||
"total": 127
|
||||
},
|
||||
"performance": {
|
||||
"requestsPerSecond": 12.5,
|
||||
"avgResponseTime": "234ms",
|
||||
"errorRate": "0.1%"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 获取服务器日志
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/servers/{serverId}/logs
|
||||
```
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
| -------- | ------- | ---------------------------------------------- |
|
||||
| `level` | string | 日志级别过滤：`error`, `warn`, `info`, `debug` |
|
||||
| `limit` | integer | 返回日志条数（默认 100，最大 1000） |
|
||||
| `since` | string | 开始时间（ISO 8601 格式） |
|
||||
| `until` | string | 结束时间（ISO 8601 格式） |
|
||||
| `follow` | boolean | 实时跟踪日志流 |
|
||||
| `search` | string | 搜索日志内容 |
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"logs": [
|
||||
{
|
||||
"id": "log-123",
|
||||
"timestamp": "2024-01-01T12:00:00Z",
|
||||
"level": "info",
|
||||
"message": "处理请求: read_file",
|
||||
"source": "mcp-server",
|
||||
"metadata": {
|
||||
"requestId": "req-456",
|
||||
"userId": "user-789",
|
||||
"duration": "45ms"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "log-124",
|
||||
"timestamp": "2024-01-01T12:00:05Z",
|
||||
"level": "error",
|
||||
"message": "文件不存在: /nonexistent/file.txt",
|
||||
"source": "filesystem",
|
||||
"metadata": {
|
||||
"requestId": "req-457",
|
||||
"path": "/nonexistent/file.txt",
|
||||
"error": "ENOENT"
|
||||
}
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"limit": 100,
|
||||
"total": 1523,
|
||||
"hasMore": true,
|
||||
"nextCursor": "cursor-abc123"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 实时日志流
|
||||
|
||||
```bash
|
||||
# 实时跟踪日志
|
||||
curl -X GET "http://localhost:3000/api/servers/server-abc123/logs?follow=true" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
## 获取服务器指标
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/servers/{serverId}/metrics
|
||||
```
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
| ------------- | ------ | ------------------------------------------- |
|
||||
| `timeRange` | string | 时间范围：`1h`, `24h`, `7d`, `30d` |
|
||||
| `granularity` | string | 数据粒度：`1m`, `5m`, `1h`, `1d` |
|
||||
| `metrics` | string | 指定指标（逗号分隔）：`cpu,memory,requests` |
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"timeRange": "1h",
|
||||
"granularity": "5m",
|
||||
"metrics": {
|
||||
"cpu": {
|
||||
"data": [
|
||||
{ "timestamp": "2024-01-01T11:00:00Z", "value": 12.5 },
|
||||
{ "timestamp": "2024-01-01T11:05:00Z", "value": 15.2 }
|
||||
],
|
||||
"summary": {
|
||||
"avg": 13.8,
|
||||
"min": 8.1,
|
||||
"max": 18.5,
|
||||
"current": 15.2
|
||||
}
|
||||
},
|
||||
"memory": {
|
||||
"data": [
|
||||
{ "timestamp": "2024-01-01T11:00:00Z", "value": 125 },
|
||||
{ "timestamp": "2024-01-01T11:05:00Z", "value": 128 }
|
||||
],
|
||||
"summary": {
|
||||
"avg": 126.5,
|
||||
"min": 120,
|
||||
"max": 135,
|
||||
"current": 128
|
||||
}
|
||||
},
|
||||
"requests": {
|
||||
"data": [
|
||||
{ "timestamp": "2024-01-01T11:00:00Z", "value": 45 },
|
||||
{ "timestamp": "2024-01-01T11:05:00Z", "value": 52 }
|
||||
],
|
||||
"summary": {
|
||||
"total": 2847,
|
||||
"avg": 48.5,
|
||||
"peak": 67
|
||||
}
|
||||
},
|
||||
"responseTime": {
|
||||
"data": [
|
||||
{ "timestamp": "2024-01-01T11:00:00Z", "avg": 230, "p95": 450 },
|
||||
{ "timestamp": "2024-01-01T11:05:00Z", "avg": 245, "p95": 480 }
|
||||
],
|
||||
"summary": {
|
||||
"avgResponseTime": "237ms",
|
||||
"p95ResponseTime": "465ms"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 获取用户列表
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/users
|
||||
```
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
| ------------------ | ------- | ---------------- |
|
||||
| `role` | string | 过滤用户角色 |
|
||||
| `group` | string | 过滤所属组 |
|
||||
| `enabled` | boolean | 过滤启用状态 |
|
||||
| `search` | string | 搜索用户名或邮箱 |
|
||||
| `last_login_after` | string | 最后登录时间起始 |
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"id": "user-abc123",
|
||||
"username": "zhangsan",
|
||||
"email": "zhangsan@example.com",
|
||||
"role": "user",
|
||||
"enabled": true,
|
||||
"profile": {
|
||||
"firstName": "张",
|
||||
"lastName": "三",
|
||||
"fullName": "张三",
|
||||
"department": "开发部",
|
||||
"title": "软件工程师"
|
||||
},
|
||||
"groups": [
|
||||
{
|
||||
"id": "dev-team",
|
||||
"name": "开发团队",
|
||||
"role": "member"
|
||||
}
|
||||
],
|
||||
"stats": {
|
||||
"totalSessions": 45,
|
||||
"totalRequests": 1234,
|
||||
"lastRequestAt": "2024-01-01T11:30:00Z"
|
||||
},
|
||||
"lastLoginAt": "2024-01-01T08:00:00Z",
|
||||
"createdAt": "2023-12-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 89,
|
||||
"pages": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 获取组列表
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/groups
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"id": "group-abc123",
|
||||
"name": "dev-team",
|
||||
"displayName": "开发团队",
|
||||
"description": "前端和后端开发人员",
|
||||
"memberCount": 12,
|
||||
"serverCount": 8,
|
||||
"parentGroup": null,
|
||||
"children": [],
|
||||
"permissions": {
|
||||
"servers": ["read", "write", "execute"],
|
||||
"tools": ["read", "execute"]
|
||||
},
|
||||
"quotas": {
|
||||
"requests": {
|
||||
"used": 750,
|
||||
"limit": 1000
|
||||
}
|
||||
},
|
||||
"createdAt": "2023-12-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 搜索
|
||||
|
||||
### 全局搜索
|
||||
|
||||
```http
|
||||
GET /api/search
|
||||
```
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
| ------- | ------- | ---------------------------------------------- |
|
||||
| `q` | string | 搜索关键词 |
|
||||
| `type` | string | 资源类型：`servers`, `users`, `groups`, `logs` |
|
||||
| `limit` | integer | 每种类型的最大结果数 |
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"query": "python",
|
||||
"results": {
|
||||
"servers": [
|
||||
{
|
||||
"id": "server-1",
|
||||
"name": "Python MCP Server",
|
||||
"type": "server",
|
||||
"relevance": 0.95
|
||||
}
|
||||
],
|
||||
"users": [],
|
||||
"groups": [
|
||||
{
|
||||
"id": "python-devs",
|
||||
"name": "Python 开发者",
|
||||
"type": "group",
|
||||
"relevance": 0.8
|
||||
}
|
||||
],
|
||||
"logs": [
|
||||
{
|
||||
"id": "log-123",
|
||||
"message": "Starting Python server...",
|
||||
"type": "log",
|
||||
"relevance": 0.7
|
||||
}
|
||||
]
|
||||
},
|
||||
"total": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
有关更多信息，请参阅 [创建资源](/zh/api-reference/endpoint/create)、[删除资源](/zh/api-reference/endpoint/delete) 和 [WebHooks](/zh/api-reference/endpoint/webhook) 文档。
|
||||
@@ -1,615 +0,0 @@
|
||||
---
|
||||
title: WebHooks API
|
||||
description: 配置和管理 WebHook 事件通知的完整指南
|
||||
---
|
||||
|
||||
# WebHooks API
|
||||
|
||||
WebHooks 允许 MCPHub 在特定事件发生时向您的应用程序发送实时通知。
|
||||
|
||||
## 概述
|
||||
|
||||
MCPHub WebHooks 系统支持以下功能：
|
||||
|
||||
- 实时事件通知
|
||||
- 自定义过滤器
|
||||
- 重试机制
|
||||
- 签名验证
|
||||
- 批量事件处理
|
||||
|
||||
## 支持的事件类型
|
||||
|
||||
| 事件类型 | 描述 |
|
||||
| ----------------------- | -------------- |
|
||||
| `server.created` | MCP 服务器创建 |
|
||||
| `server.updated` | MCP 服务器更新 |
|
||||
| `server.deleted` | MCP 服务器删除 |
|
||||
| `server.status_changed` | 服务器状态变更 |
|
||||
| `group.created` | 服务器组创建 |
|
||||
| `group.updated` | 服务器组更新 |
|
||||
| `group.deleted` | 服务器组删除 |
|
||||
| `user.login` | 用户登录 |
|
||||
| `user.logout` | 用户登出 |
|
||||
| `config.changed` | 配置变更 |
|
||||
| `system.error` | 系统错误 |
|
||||
|
||||
## 创建 WebHook
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
POST /api/webhooks
|
||||
```
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://your-app.com/webhook",
|
||||
"events": ["server.created", "server.status_changed"],
|
||||
"secret": "your-webhook-secret",
|
||||
"active": true,
|
||||
"config": {
|
||||
"contentType": "application/json",
|
||||
"insecureSsl": false,
|
||||
"retryCount": 3,
|
||||
"timeout": 30
|
||||
},
|
||||
"filters": {
|
||||
"serverGroups": ["production", "staging"],
|
||||
"serverTypes": ["ai-assistant", "data-processor"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "webhook-123",
|
||||
"url": "https://your-app.com/webhook",
|
||||
"events": ["server.created", "server.status_changed"],
|
||||
"active": true,
|
||||
"secret": "your-webhook-secret",
|
||||
"config": {
|
||||
"contentType": "application/json",
|
||||
"insecureSsl": false,
|
||||
"retryCount": 3,
|
||||
"timeout": 30
|
||||
},
|
||||
"filters": {
|
||||
"serverGroups": ["production", "staging"],
|
||||
"serverTypes": ["ai-assistant", "data-processor"]
|
||||
},
|
||||
"createdAt": "2024-01-15T10:30:00Z",
|
||||
"updatedAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 获取 WebHook 列表
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/webhooks
|
||||
```
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
| ------ | ------- | -------------------- |
|
||||
| page | integer | 页码（默认：1） |
|
||||
| limit | integer | 每页数量（默认：20） |
|
||||
| active | boolean | 过滤活跃状态 |
|
||||
| event | string | 过滤事件类型 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X GET \
|
||||
'https://api.mcphub.io/api/webhooks?active=true&limit=10' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN'
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"webhooks": [
|
||||
{
|
||||
"id": "webhook-123",
|
||||
"url": "https://your-app.com/webhook",
|
||||
"events": ["server.created", "server.status_changed"],
|
||||
"active": true,
|
||||
"lastDelivery": "2024-01-15T09:30:00Z",
|
||||
"deliveryCount": 145,
|
||||
"failureCount": 2,
|
||||
"createdAt": "2024-01-10T10:30:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 10,
|
||||
"total": 25,
|
||||
"pages": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 获取单个 WebHook
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/webhooks/{id}
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "webhook-123",
|
||||
"url": "https://your-app.com/webhook",
|
||||
"events": ["server.created", "server.status_changed"],
|
||||
"active": true,
|
||||
"secret": "your-webhook-secret",
|
||||
"config": {
|
||||
"contentType": "application/json",
|
||||
"insecureSsl": false,
|
||||
"retryCount": 3,
|
||||
"timeout": 30
|
||||
},
|
||||
"filters": {
|
||||
"serverGroups": ["production", "staging"],
|
||||
"serverTypes": ["ai-assistant", "data-processor"]
|
||||
},
|
||||
"stats": {
|
||||
"totalDeliveries": 145,
|
||||
"successfulDeliveries": 143,
|
||||
"failedDeliveries": 2,
|
||||
"lastDelivery": "2024-01-15T09:30:00Z",
|
||||
"lastSuccess": "2024-01-15T09:30:00Z",
|
||||
"lastFailure": "2024-01-14T15:20:00Z"
|
||||
},
|
||||
"createdAt": "2024-01-10T10:30:00Z",
|
||||
"updatedAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 更新 WebHook
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
PUT /api/webhooks/{id}
|
||||
```
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://your-app.com/new-webhook",
|
||||
"events": ["server.created", "server.updated", "server.deleted"],
|
||||
"active": true,
|
||||
"config": {
|
||||
"retryCount": 5,
|
||||
"timeout": 45
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 删除 WebHook
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
DELETE /api/webhooks/{id}
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "WebHook 已成功删除"
|
||||
}
|
||||
```
|
||||
|
||||
## WebHook 事件格式
|
||||
|
||||
### 基本结构
|
||||
|
||||
所有 WebHook 事件都遵循以下基本结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "event-123",
|
||||
"type": "server.created",
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"version": "1.0",
|
||||
"data": {
|
||||
// 事件特定数据
|
||||
},
|
||||
"metadata": {
|
||||
"source": "mcphub",
|
||||
"environment": "production",
|
||||
"triggeredBy": "user-456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 服务器事件示例
|
||||
|
||||
#### server.created
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "event-123",
|
||||
"type": "server.created",
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"version": "1.0",
|
||||
"data": {
|
||||
"server": {
|
||||
"id": "mcp-server-123",
|
||||
"name": "AI Assistant Server",
|
||||
"type": "ai-assistant",
|
||||
"endpoint": "https://ai-assistant.example.com",
|
||||
"group": "production",
|
||||
"status": "active",
|
||||
"capabilities": ["chat", "completion"],
|
||||
"createdAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
},
|
||||
"metadata": {
|
||||
"source": "mcphub",
|
||||
"environment": "production",
|
||||
"triggeredBy": "user-456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### server.status_changed
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "event-124",
|
||||
"type": "server.status_changed",
|
||||
"timestamp": "2024-01-15T11:30:00Z",
|
||||
"version": "1.0",
|
||||
"data": {
|
||||
"server": {
|
||||
"id": "mcp-server-123",
|
||||
"name": "AI Assistant Server",
|
||||
"previousStatus": "active",
|
||||
"currentStatus": "inactive",
|
||||
"reason": "Health check failed",
|
||||
"lastHealthCheck": "2024-01-15T11:25:00Z"
|
||||
}
|
||||
},
|
||||
"metadata": {
|
||||
"source": "mcphub",
|
||||
"environment": "production",
|
||||
"triggeredBy": "system"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 签名验证
|
||||
|
||||
MCPHub 使用 HMAC-SHA256 签名来验证 WebHook 的真实性。
|
||||
|
||||
### 签名生成
|
||||
|
||||
签名在 `X-MCPHub-Signature-256` 头中发送：
|
||||
|
||||
```
|
||||
X-MCPHub-Signature-256: sha256=5757107ea39eca8e35d1e8...
|
||||
```
|
||||
|
||||
### 验证示例
|
||||
|
||||
#### Node.js
|
||||
|
||||
```javascript
|
||||
const crypto = require('crypto');
|
||||
|
||||
function verifySignature(payload, signature, secret) {
|
||||
const expectedSignature = crypto
|
||||
.createHmac('sha256', secret)
|
||||
.update(payload, 'utf8')
|
||||
.digest('hex');
|
||||
|
||||
const actualSignature = signature.replace('sha256=', '');
|
||||
|
||||
return crypto.timingSafeEqual(
|
||||
Buffer.from(expectedSignature, 'hex'),
|
||||
Buffer.from(actualSignature, 'hex'),
|
||||
);
|
||||
}
|
||||
|
||||
// Express.js 中间件示例
|
||||
app.use('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
|
||||
const signature = req.headers['x-mcphub-signature-256'];
|
||||
const payload = req.body;
|
||||
|
||||
if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
|
||||
return res.status(401).send('Unauthorized');
|
||||
}
|
||||
|
||||
// 处理 WebHook 事件
|
||||
const event = JSON.parse(payload);
|
||||
console.log('收到事件:', event.type);
|
||||
|
||||
res.status(200).send('OK');
|
||||
});
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
```python
|
||||
import hmac
|
||||
import hashlib
|
||||
|
||||
def verify_signature(payload, signature, secret):
|
||||
expected_signature = hmac.new(
|
||||
secret.encode('utf-8'),
|
||||
payload,
|
||||
hashlib.sha256
|
||||
).hexdigest()
|
||||
|
||||
actual_signature = signature.replace('sha256=', '')
|
||||
|
||||
return hmac.compare_digest(expected_signature, actual_signature)
|
||||
|
||||
# Flask 示例
|
||||
from flask import Flask, request, jsonify
|
||||
import json
|
||||
|
||||
app = Flask(__name__)
|
||||
|
||||
@app.route('/webhook', methods=['POST'])
|
||||
def webhook():
|
||||
signature = request.headers.get('X-MCPHub-Signature-256')
|
||||
payload = request.get_data()
|
||||
|
||||
if not verify_signature(payload, signature, 'your-webhook-secret'):
|
||||
return jsonify({'error': 'Unauthorized'}), 401
|
||||
|
||||
event = json.loads(payload)
|
||||
print(f'收到事件: {event["type"]}')
|
||||
|
||||
return jsonify({'status': 'success'}), 200
|
||||
```
|
||||
|
||||
## 重试机制
|
||||
|
||||
MCPHub 对失败的 WebHook 交付实施指数退避重试：
|
||||
|
||||
- **重试次数**: 可配置（默认 3 次）
|
||||
- **重试间隔**: 2^n 秒（n 为重试次数）
|
||||
- **最大间隔**: 300 秒（5 分钟）
|
||||
- **超时设置**: 可配置（默认 30 秒）
|
||||
|
||||
### 重试时间表
|
||||
|
||||
| 尝试次数 | 延迟时间 |
|
||||
| -------- | -------- |
|
||||
| 1 | 立即 |
|
||||
| 2 | 2 秒 |
|
||||
| 3 | 4 秒 |
|
||||
| 4 | 8 秒 |
|
||||
| 5 | 16 秒 |
|
||||
|
||||
## 获取交付历史
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
GET /api/webhooks/{id}/deliveries
|
||||
```
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
| ---------- | ------- | ------------------------------------ |
|
||||
| page | integer | 页码 |
|
||||
| limit | integer | 每页数量 |
|
||||
| status | string | 过滤状态（success, failed, pending） |
|
||||
| event_type | string | 过滤事件类型 |
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"deliveries": [
|
||||
{
|
||||
"id": "delivery-123",
|
||||
"eventId": "event-123",
|
||||
"eventType": "server.created",
|
||||
"url": "https://your-app.com/webhook",
|
||||
"status": "success",
|
||||
"responseCode": 200,
|
||||
"responseTime": 145,
|
||||
"attempts": 1,
|
||||
"deliveredAt": "2024-01-15T10:30:15Z",
|
||||
"nextRetry": null
|
||||
},
|
||||
{
|
||||
"id": "delivery-124",
|
||||
"eventId": "event-124",
|
||||
"eventType": "server.status_changed",
|
||||
"url": "https://your-app.com/webhook",
|
||||
"status": "failed",
|
||||
"responseCode": 500,
|
||||
"responseTime": 30000,
|
||||
"attempts": 3,
|
||||
"error": "Connection timeout",
|
||||
"deliveredAt": null,
|
||||
"nextRetry": "2024-01-15T11:45:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 145,
|
||||
"pages": 8
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 测试 WebHook
|
||||
|
||||
### 端点
|
||||
|
||||
```http
|
||||
POST /api/webhooks/{id}/test
|
||||
```
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "server.created",
|
||||
"customData": {
|
||||
"test": true,
|
||||
"message": "这是一个测试事件"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"deliveryId": "delivery-test-123",
|
||||
"status": "delivered",
|
||||
"responseCode": 200,
|
||||
"responseTime": 124,
|
||||
"sentAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 幂等性处理
|
||||
|
||||
确保您的 WebHook 端点能够处理重复事件：
|
||||
|
||||
```javascript
|
||||
const processedEvents = new Set();
|
||||
|
||||
app.post('/webhook', (req, res) => {
|
||||
const event = req.body;
|
||||
|
||||
// 检查事件是否已处理
|
||||
if (processedEvents.has(event.id)) {
|
||||
return res.status(200).send('Already processed');
|
||||
}
|
||||
|
||||
// 处理事件
|
||||
processEvent(event);
|
||||
|
||||
// 记录已处理的事件
|
||||
processedEvents.add(event.id);
|
||||
|
||||
res.status(200).send('OK');
|
||||
});
|
||||
```
|
||||
|
||||
### 2. 异步处理
|
||||
|
||||
对于复杂的处理逻辑，使用异步处理避免阻塞：
|
||||
|
||||
```javascript
|
||||
app.post('/webhook', async (req, res) => {
|
||||
const event = req.body;
|
||||
|
||||
// 立即响应
|
||||
res.status(200).send('OK');
|
||||
|
||||
// 异步处理事件
|
||||
setImmediate(() => {
|
||||
processEventAsync(event);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 3. 错误处理
|
||||
|
||||
实施适当的错误处理和日志记录：
|
||||
|
||||
```javascript
|
||||
app.post('/webhook', (req, res) => {
|
||||
try {
|
||||
const event = req.body;
|
||||
processEvent(event);
|
||||
res.status(200).send('OK');
|
||||
} catch (error) {
|
||||
console.error('WebHook 处理错误:', error);
|
||||
res.status(500).send('Internal Server Error');
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 4. 监控和告警
|
||||
|
||||
监控 WebHook 的交付状态：
|
||||
|
||||
```bash
|
||||
# 检查失败的交付
|
||||
curl -X GET \
|
||||
'https://api.mcphub.io/api/webhooks/webhook-123/deliveries?status=failed' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN'
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **签名验证失败**
|
||||
|
||||
- 检查密钥是否正确
|
||||
- 确保使用原始请求体进行验证
|
||||
- 验证 HMAC 计算实现
|
||||
|
||||
2. **超时错误**
|
||||
|
||||
- 增加 WebHook 超时设置
|
||||
- 优化端点响应时间
|
||||
- 使用异步处理
|
||||
|
||||
3. **重复事件**
|
||||
- 实施幂等性检查
|
||||
- 使用事件 ID 去重
|
||||
- 记录处理状态
|
||||
|
||||
### 调试工具
|
||||
|
||||
使用 MCPHub 提供的调试工具：
|
||||
|
||||
```bash
|
||||
# 查看最近的交付日志
|
||||
curl -X GET \
|
||||
'https://api.mcphub.io/api/webhooks/webhook-123/deliveries?limit=5' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN'
|
||||
|
||||
# 重新发送失败的事件
|
||||
curl -X POST \
|
||||
'https://api.mcphub.io/api/webhooks/delivery-124/redeliver' \
|
||||
-H 'Authorization: Bearer YOUR_API_TOKEN'
|
||||
```
|
||||
212
docs/zh/api-reference/groups.mdx
Normal file
212
docs/zh/api-reference/groups.mdx
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
title: "群组"
|
||||
description: "管理服务器群组以组织和路由请求。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card title="GET /api/groups" href="#get-all-groups">获取所有群组的列表。</Card>
|
||||
<Card title="POST /api/groups" href="#create-a-new-group">创建一个新群组。</Card>
|
||||
<Card title="GET /api/groups/:id" href="#get-a-group">获取特定群组的详细信息。</Card>
|
||||
<Card title="PUT /api/groups/:id" href="#update-a-group">更新现有群组。</Card>
|
||||
<Card title="DELETE /api/groups/:id" href="#delete-a-group">删除一个群组。</Card>
|
||||
<Card title="POST /api/groups/:id/servers" href="#add-server-to-group">将服务器添加到群组。</Card>
|
||||
<Card title="DELETE /api/groups/:id/servers/:serverName" href="#remove-server-from-group">从群组中删除服务器。</Card>
|
||||
<Card title="PUT /api/groups/:id/servers/batch" href="#batch-update-group-servers">批量更新群组中的服务器。</Card>
|
||||
<Card title="GET /api/groups/:id/server-configs" href="#get-group-server-configs">获取群组中详细的服务器配置。</Card>
|
||||
<Card title="PUT /api/groups/:id/server-configs/:serverName/tools" href="#update-group-server-tools">更新群组中服务器的工具选择。</Card>
|
||||
|
||||
---
|
||||
|
||||
### 获取所有群组
|
||||
|
||||
检索所有服务器群组的列表。
|
||||
|
||||
- **端点**: `/api/groups`
|
||||
- **方法**: `GET`
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": "group-1",
|
||||
"name": "我的群组",
|
||||
"description": "服务器的集合。",
|
||||
"servers": ["server1", "server2"],
|
||||
"owner": "admin"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 创建一个新群组
|
||||
|
||||
创建一个新的服务器群组。
|
||||
|
||||
- **端点**: `/api/groups`
|
||||
- **方法**: `POST`
|
||||
- **正文**:
|
||||
- `name` (string, 必填): 群组的名称。
|
||||
- `description` (string, 可选): 群组的描述。
|
||||
- `servers` (array of strings, 可选): 要包含在群组中的服务器名称列表。
|
||||
- **请求示例**:
|
||||
```json
|
||||
{
|
||||
"name": "我的新群组",
|
||||
"description": "新群组的描述",
|
||||
"servers": ["server1", "server2"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 获取一个群组
|
||||
|
||||
通过 ID 或名称检索特定群组的详细信息。
|
||||
|
||||
- **端点**: `/api/groups/:id`
|
||||
- **方法**: `GET`
|
||||
- **参数**:
|
||||
- `:id` (string, 必填): 群组的 ID 或名称。
|
||||
|
||||
---
|
||||
|
||||
### 更新一个群组
|
||||
|
||||
更新现有群组的名称、描述或服务器列表。
|
||||
|
||||
- **端点**: `/api/groups/:id`
|
||||
- **方法**: `PUT`
|
||||
- **参数**:
|
||||
- `:id` (string, 必填): 要更新的群组的 ID 或名称。
|
||||
- **正文**:
|
||||
- `name` (string, 可选): 群组的新名称。
|
||||
- `description` (string, 可选): 群组的新描述。
|
||||
- `servers` (array, 可选): 群组的新服务器列表。格式请参阅 [批量更新群组服务器](#batch-update-group-servers)。
|
||||
- **请求示例**:
|
||||
```json
|
||||
{
|
||||
"name": "更新后的群组名称",
|
||||
"description": "更新后的描述"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 删除一个群组
|
||||
|
||||
通过 ID 或名称删除一个群组。
|
||||
|
||||
- **端点**: `/api/groups/:id`
|
||||
- **方法**: `DELETE`
|
||||
- **参数**:
|
||||
- `:id` (string, 必填): 要删除的群组的 ID 或名称。
|
||||
|
||||
---
|
||||
|
||||
### 将服务器添加到群组
|
||||
|
||||
将单个服务器添加到群组。
|
||||
|
||||
- **端点**: `/api/groups/:id/servers`
|
||||
- **方法**: `POST`
|
||||
- **参数**:
|
||||
- `:id` (string, 必填): 群组的 ID 或名称。
|
||||
- **正文**:
|
||||
- `serverName` (string, 必填): 要添加的服务器的名称。
|
||||
- **请求示例**:
|
||||
```json
|
||||
{
|
||||
"serverName": "my-server"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 从群组中删除服务器
|
||||
|
||||
从群组中删除单个服务器。
|
||||
|
||||
- **端点**: `/api/groups/:id/servers/:serverName`
|
||||
- **方法**: `DELETE`
|
||||
- **参数**:
|
||||
- `:id` (string, 必填): 群组的 ID 或名称。
|
||||
- `:serverName` (string, 必填): 要删除的服务器的名称。
|
||||
|
||||
---
|
||||
|
||||
### 批量更新群组服务器
|
||||
|
||||
用新的列表替换群组中的所有服务器。该列表可以是简单的字符串或详细的配置对象。
|
||||
|
||||
- **端点**: `/api/groups/:id/servers/batch`
|
||||
- **方法**: `PUT`
|
||||
- **参数**:
|
||||
- `:id` (string, 必填): 群组的 ID 或名称。
|
||||
- **正文**:
|
||||
- `servers` (array, 必填): 服务器名称（字符串）或服务器配置对象的数组。
|
||||
- **请求示例 (简单)**:
|
||||
```json
|
||||
{
|
||||
"servers": ["server1", "server2"]
|
||||
}
|
||||
```
|
||||
- **请求示例 (详细)**:
|
||||
```json
|
||||
{
|
||||
"servers": [
|
||||
{ "name": "server1", "tools": "all" },
|
||||
{ "name": "server2", "tools": ["toolA", "toolB"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 获取群组服务器配置
|
||||
|
||||
检索群组内所有服务器的详细配置，包括启用了哪些工具。
|
||||
|
||||
- **端点**: `/api/groups/:id/server-configs`
|
||||
- **方法**: `GET`
|
||||
- **参数**:
|
||||
- `:id` (string, 必填): 群组的 ID 或名称。
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"name": "server1",
|
||||
"tools": "all"
|
||||
},
|
||||
{
|
||||
"name": "server2",
|
||||
"tools": ["toolA", "toolB"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 更新群组服务器工具
|
||||
|
||||
更新群组内特定服务器的工具选择。
|
||||
|
||||
- **端点**: `/api/groups/:id/server-configs/:serverName/tools`
|
||||
- **方法**: `PUT`
|
||||
- **参数**:
|
||||
- `:id` (string, 必填): 群组的 ID 或名称。
|
||||
- `:serverName` (string, 必填): 要更新的服务器的名称。
|
||||
- **正文**:
|
||||
- `tools` (string or array of strings, 必填): 字符串 `"all"` 表示启用所有工具，或一个工具名称数组以指定启用哪些工具。
|
||||
- **请求示例**:
|
||||
```json
|
||||
{
|
||||
"tools": ["toolA", "toolC"]
|
||||
}
|
||||
```
|
||||
@@ -1,717 +1,13 @@
|
||||
---
|
||||
title: 'API 参考'
|
||||
description: 'MCPHub REST API 完整参考文档'
|
||||
title: "介绍"
|
||||
description: "欢迎来到 MCPHub API 文档。"
|
||||
---
|
||||
|
||||
## 概述
|
||||
MCPHub API 提供了一整套端点来管理您的 MCP 服务器、群组、用户等。该 API 分为两个主要类别：
|
||||
|
||||
MCPHub 提供全面的 REST API，用于管理 MCP 服务器、用户、组和监控。所有 API 端点都需要身份验证，并支持 JSON 格式的请求和响应。
|
||||
- **MCP 端点**: 这些是与您的 MCP 服务器交互的主要端点。它们提供了一个统一的界面，用于向您的服务器发送请求并实时接收响应。
|
||||
- **管理 API**: 这些端点用于管理 MCPHub 实例本身。这包括管理服务器、群组、用户和系统设置。
|
||||
|
||||
## 基础信息
|
||||
所有 API 端点都在 `/api` 路径下可用。例如，获取所有服务器的端点是 `/api/servers`。
|
||||
|
||||
### 基础 URL
|
||||
|
||||
```
|
||||
https://your-mcphub-instance.com/api
|
||||
```
|
||||
|
||||
### 身份验证
|
||||
|
||||
所有 API 请求都需要身份验证。支持以下方法：
|
||||
|
||||
#### JWT 令牌认证
|
||||
|
||||
```bash
|
||||
curl -X GET https://api.mcphub.com/servers \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
#### API 密钥认证
|
||||
|
||||
```bash
|
||||
curl -X GET https://api.mcphub.com/servers \
|
||||
-H "X-API-Key: YOUR_API_KEY"
|
||||
```
|
||||
|
||||
### 请求格式
|
||||
|
||||
- **Content-Type**: `application/json`
|
||||
- **Accept**: `application/json`
|
||||
- **User-Agent**: 建议包含您的应用程序名称和版本
|
||||
|
||||
### 响应格式
|
||||
|
||||
所有响应都采用 JSON 格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
// 响应数据
|
||||
},
|
||||
"message": "操作成功",
|
||||
"timestamp": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
错误响应格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "请求数据无效",
|
||||
"details": {
|
||||
"field": "name",
|
||||
"reason": "名称不能为空"
|
||||
}
|
||||
},
|
||||
"timestamp": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 状态码
|
||||
|
||||
| 状态码 | 说明 |
|
||||
| ------ | -------------------- |
|
||||
| 200 | 请求成功 |
|
||||
| 201 | 资源创建成功 |
|
||||
| 204 | 请求成功，无返回内容 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未授权访问 |
|
||||
| 403 | 权限不足 |
|
||||
| 404 | 资源不存在 |
|
||||
| 409 | 资源冲突 |
|
||||
| 422 | 请求数据验证失败 |
|
||||
| 429 | 请求频率超限 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 分页
|
||||
|
||||
支持分页的端点使用以下参数：
|
||||
|
||||
- `page`: 页码（从 1 开始）
|
||||
- `limit`: 每页记录数（默认 20，最大 100）
|
||||
- `sort`: 排序字段
|
||||
- `order`: 排序顺序（`asc` 或 `desc`）
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.mcphub.com/servers?page=2&limit=50&sort=name&order=asc" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
分页响应格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"items": [...],
|
||||
"pagination": {
|
||||
"page": 2,
|
||||
"limit": 50,
|
||||
"total": 234,
|
||||
"pages": 5,
|
||||
"hasNext": true,
|
||||
"hasPrev": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 过滤和搜索
|
||||
|
||||
支持过滤的端点可以使用以下参数：
|
||||
|
||||
- `search`: 全文搜索
|
||||
- `filter[field]`: 字段过滤
|
||||
- `status`: 状态过滤
|
||||
- `created_after`: 创建时间筛选
|
||||
- `created_before`: 创建时间筛选
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.mcphub.com/servers?search=python&filter[status]=running&created_after=2024-01-01" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## API 端点
|
||||
|
||||
### 服务器管理
|
||||
|
||||
#### 获取服务器列表
|
||||
|
||||
```http
|
||||
GET /api/servers
|
||||
```
|
||||
|
||||
参数：
|
||||
|
||||
- `status` (可选): 过滤服务器状态 (`running`, `stopped`, `error`)
|
||||
- `group` (可选): 过滤所属组
|
||||
- `search` (可选): 搜索服务器名称或描述
|
||||
|
||||
示例响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"id": "server-1",
|
||||
"name": "文件系统服务器",
|
||||
"status": "running",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
|
||||
"env": {
|
||||
"NODE_ENV": "production"
|
||||
},
|
||||
"cwd": "/app",
|
||||
"pid": 12345,
|
||||
"uptime": 3600000,
|
||||
"lastRestart": "2024-01-01T12:00:00Z",
|
||||
"createdAt": "2024-01-01T10:00:00Z",
|
||||
"updatedAt": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 创建服务器
|
||||
|
||||
```http
|
||||
POST /api/servers
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "新服务器",
|
||||
"command": "python",
|
||||
"args": ["-m", "mcp_server"],
|
||||
"env": {
|
||||
"API_KEY": "your-api-key",
|
||||
"LOG_LEVEL": "INFO"
|
||||
},
|
||||
"cwd": "/app/python-server",
|
||||
"enabled": true,
|
||||
"description": "Python MCP 服务器",
|
||||
"tags": ["python", "production"]
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取服务器详情
|
||||
|
||||
```http
|
||||
GET /api/servers/{serverId}
|
||||
```
|
||||
|
||||
#### 更新服务器
|
||||
|
||||
```http
|
||||
PUT /api/servers/{serverId}
|
||||
```
|
||||
|
||||
#### 删除服务器
|
||||
|
||||
```http
|
||||
DELETE /api/servers/{serverId}
|
||||
```
|
||||
|
||||
#### 启动服务器
|
||||
|
||||
```http
|
||||
POST /api/servers/{serverId}/start
|
||||
```
|
||||
|
||||
#### 停止服务器
|
||||
|
||||
```http
|
||||
POST /api/servers/{serverId}/stop
|
||||
```
|
||||
|
||||
请求体（可选）：
|
||||
|
||||
```json
|
||||
{
|
||||
"graceful": true,
|
||||
"timeout": 30000
|
||||
}
|
||||
```
|
||||
|
||||
#### 重启服务器
|
||||
|
||||
```http
|
||||
POST /api/servers/{serverId}/restart
|
||||
```
|
||||
|
||||
#### 获取服务器日志
|
||||
|
||||
```http
|
||||
GET /api/servers/{serverId}/logs
|
||||
```
|
||||
|
||||
参数：
|
||||
|
||||
- `level` (可选): 日志级别过滤
|
||||
- `limit` (可选): 返回日志条数
|
||||
- `since` (可选): 开始时间
|
||||
- `follow` (可选): 实时跟踪日志
|
||||
|
||||
### 用户管理
|
||||
|
||||
#### 获取用户列表
|
||||
|
||||
```http
|
||||
GET /api/users
|
||||
```
|
||||
|
||||
#### 创建用户
|
||||
|
||||
```http
|
||||
POST /api/users
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "newuser",
|
||||
"email": "user@example.com",
|
||||
"password": "securepassword",
|
||||
"role": "user",
|
||||
"groups": ["dev-team"],
|
||||
"profile": {
|
||||
"firstName": "张",
|
||||
"lastName": "三",
|
||||
"department": "开发部"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取用户详情
|
||||
|
||||
```http
|
||||
GET /api/users/{userId}
|
||||
```
|
||||
|
||||
#### 更新用户
|
||||
|
||||
```http
|
||||
PUT /api/users/{userId}
|
||||
```
|
||||
|
||||
#### 删除用户
|
||||
|
||||
```http
|
||||
DELETE /api/users/{userId}
|
||||
```
|
||||
|
||||
### 组管理
|
||||
|
||||
#### 获取组列表
|
||||
|
||||
```http
|
||||
GET /api/groups
|
||||
```
|
||||
|
||||
#### 创建组
|
||||
|
||||
```http
|
||||
POST /api/groups
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "dev-team",
|
||||
"displayName": "开发团队",
|
||||
"description": "前端和后端开发人员",
|
||||
"parentGroup": null,
|
||||
"permissions": {
|
||||
"servers": ["read", "write", "execute"],
|
||||
"tools": ["read", "execute"]
|
||||
},
|
||||
"settings": {
|
||||
"autoAssign": false,
|
||||
"maxMembers": 50,
|
||||
"requireApproval": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 添加用户到组
|
||||
|
||||
```http
|
||||
POST /api/groups/{groupId}/members
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"userId": "user123",
|
||||
"role": "member"
|
||||
}
|
||||
```
|
||||
|
||||
#### 从组中移除用户
|
||||
|
||||
```http
|
||||
DELETE /api/groups/{groupId}/members/{userId}
|
||||
```
|
||||
|
||||
#### 分配服务器到组
|
||||
|
||||
```http
|
||||
POST /api/groups/{groupId}/servers
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"serverId": "server-1",
|
||||
"permissions": ["read", "write", "execute"]
|
||||
}
|
||||
```
|
||||
|
||||
### 身份验证
|
||||
|
||||
#### 登录
|
||||
|
||||
```http
|
||||
POST /api/auth/login
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "password",
|
||||
"mfaCode": "123456"
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"refreshToken": "refresh_token_here",
|
||||
"expiresIn": 86400,
|
||||
"user": {
|
||||
"id": "user123",
|
||||
"username": "admin",
|
||||
"role": "admin",
|
||||
"permissions": ["*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 刷新令牌
|
||||
|
||||
```http
|
||||
POST /api/auth/refresh
|
||||
```
|
||||
|
||||
#### 注销
|
||||
|
||||
```http
|
||||
POST /api/auth/logout
|
||||
```
|
||||
|
||||
#### 验证令牌
|
||||
|
||||
```http
|
||||
GET /api/auth/verify
|
||||
```
|
||||
|
||||
### 监控
|
||||
|
||||
#### 获取系统状态
|
||||
|
||||
```http
|
||||
GET /api/monitoring/status
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"system": {
|
||||
"uptime": 86400,
|
||||
"version": "2.1.0",
|
||||
"nodeVersion": "18.17.0"
|
||||
},
|
||||
"servers": {
|
||||
"total": 12,
|
||||
"running": 10,
|
||||
"stopped": 1,
|
||||
"error": 1
|
||||
},
|
||||
"performance": {
|
||||
"requestsPerMinute": 85,
|
||||
"avgResponseTime": "245ms",
|
||||
"errorRate": "0.3%"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取性能指标
|
||||
|
||||
```http
|
||||
GET /api/monitoring/metrics
|
||||
```
|
||||
|
||||
参数：
|
||||
|
||||
- `timeRange`: 时间范围 (`1h`, `24h`, `7d`, `30d`)
|
||||
- `granularity`: 数据粒度 (`1m`, `5m`, `1h`, `1d`)
|
||||
- `metrics`: 指定指标名称（逗号分隔）
|
||||
|
||||
#### 获取日志
|
||||
|
||||
```http
|
||||
GET /api/monitoring/logs
|
||||
```
|
||||
|
||||
参数：
|
||||
|
||||
- `level`: 日志级别
|
||||
- `source`: 日志源
|
||||
- `limit`: 返回条数
|
||||
- `since`: 开始时间
|
||||
- `until`: 结束时间
|
||||
|
||||
### 配置管理
|
||||
|
||||
#### 获取系统配置
|
||||
|
||||
```http
|
||||
GET /api/config
|
||||
```
|
||||
|
||||
#### 更新系统配置
|
||||
|
||||
```http
|
||||
PUT /api/config
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"smtp": {
|
||||
"host": "smtp.example.com",
|
||||
"port": 587,
|
||||
"secure": false,
|
||||
"auth": {
|
||||
"user": "noreply@example.com",
|
||||
"pass": "password"
|
||||
}
|
||||
},
|
||||
"notifications": {
|
||||
"email": true,
|
||||
"slack": true,
|
||||
"webhook": "https://hooks.example.com/notifications"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## WebSocket API
|
||||
|
||||
MCPHub 支持 WebSocket 连接以获取实时更新。
|
||||
|
||||
### 连接
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('wss://api.mcphub.com/ws');
|
||||
ws.onopen = function () {
|
||||
// 发送认证消息
|
||||
ws.send(
|
||||
JSON.stringify({
|
||||
type: 'auth',
|
||||
token: 'YOUR_JWT_TOKEN',
|
||||
}),
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### 订阅事件
|
||||
|
||||
```javascript
|
||||
// 订阅服务器状态更新
|
||||
ws.send(
|
||||
JSON.stringify({
|
||||
type: 'subscribe',
|
||||
channel: 'server-status',
|
||||
filters: {
|
||||
serverId: 'server-1',
|
||||
},
|
||||
}),
|
||||
);
|
||||
|
||||
// 订阅系统监控
|
||||
ws.send(
|
||||
JSON.stringify({
|
||||
type: 'subscribe',
|
||||
channel: 'monitoring',
|
||||
metrics: ['cpu', 'memory', 'requests'],
|
||||
}),
|
||||
);
|
||||
```
|
||||
|
||||
### 事件类型
|
||||
|
||||
- `server-status`: 服务器状态变化
|
||||
- `server-logs`: 实时日志流
|
||||
- `monitoring`: 系统监控指标
|
||||
- `alerts`: 系统警报
|
||||
- `user-activity`: 用户活动事件
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 错误代码
|
||||
|
||||
| 错误代码 | 描述 |
|
||||
| ----------------------- | -------------- |
|
||||
| `INVALID_REQUEST` | 请求格式无效 |
|
||||
| `AUTHENTICATION_FAILED` | 身份验证失败 |
|
||||
| `AUTHORIZATION_FAILED` | 权限不足 |
|
||||
| `RESOURCE_NOT_FOUND` | 资源不存在 |
|
||||
| `RESOURCE_CONFLICT` | 资源冲突 |
|
||||
| `VALIDATION_ERROR` | 数据验证失败 |
|
||||
| `RATE_LIMIT_EXCEEDED` | 请求频率超限 |
|
||||
| `SERVER_ERROR` | 服务器内部错误 |
|
||||
|
||||
### 错误处理示例
|
||||
|
||||
```javascript
|
||||
async function handleApiRequest() {
|
||||
try {
|
||||
const response = await fetch('/api/servers', {
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
});
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
if (!data.success) {
|
||||
switch (data.error.code) {
|
||||
case 'AUTHENTICATION_FAILED':
|
||||
// 重新登录
|
||||
redirectToLogin();
|
||||
break;
|
||||
case 'RATE_LIMIT_EXCEEDED':
|
||||
// 延迟重试
|
||||
setTimeout(() => handleApiRequest(), 5000);
|
||||
break;
|
||||
default:
|
||||
// 显示错误消息
|
||||
showError(data.error.message);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
// 处理成功响应
|
||||
handleSuccessResponse(data.data);
|
||||
} catch (error) {
|
||||
// 处理网络错误
|
||||
console.error('网络请求失败:', error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 速率限制
|
||||
|
||||
API 实施速率限制以防止滥用：
|
||||
|
||||
- **默认限制**: 每分钟 100 请求
|
||||
- **认证用户**: 每分钟 1000 请求
|
||||
- **管理员**: 每分钟 5000 请求
|
||||
|
||||
响应头包含速率限制信息：
|
||||
|
||||
```
|
||||
X-RateLimit-Limit: 1000
|
||||
X-RateLimit-Remaining: 999
|
||||
X-RateLimit-Reset: 1609459200
|
||||
```
|
||||
|
||||
## SDK 和客户端库
|
||||
|
||||
### JavaScript/Node.js
|
||||
|
||||
```bash
|
||||
npm install @mcphub/sdk
|
||||
```
|
||||
|
||||
```javascript
|
||||
import { MCPHubClient } from '@mcphub/sdk';
|
||||
|
||||
const client = new MCPHubClient({
|
||||
baseURL: 'https://api.mcphub.com',
|
||||
token: 'YOUR_JWT_TOKEN',
|
||||
});
|
||||
|
||||
// 获取服务器列表
|
||||
const servers = await client.servers.list();
|
||||
|
||||
// 创建服务器
|
||||
const newServer = await client.servers.create({
|
||||
name: '新服务器',
|
||||
command: 'python',
|
||||
args: ['-m', 'mcp_server'],
|
||||
});
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```bash
|
||||
pip install mcphub-sdk
|
||||
```
|
||||
|
||||
```python
|
||||
from mcphub_sdk import MCPHubClient
|
||||
|
||||
client = MCPHubClient(
|
||||
base_url='https://api.mcphub.com',
|
||||
token='YOUR_JWT_TOKEN'
|
||||
)
|
||||
|
||||
# 获取服务器列表
|
||||
servers = client.servers.list()
|
||||
|
||||
# 创建服务器
|
||||
new_server = client.servers.create(
|
||||
name='新服务器',
|
||||
command='python',
|
||||
args=['-m', 'mcp_server']
|
||||
)
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **使用 HTTPS**: 始终通过 HTTPS 访问 API
|
||||
2. **安全存储令牌**: 不要在客户端代码中硬编码令牌
|
||||
3. **处理错误**: 实施适当的错误处理和重试逻辑
|
||||
4. **遵守速率限制**: 监控速率限制并实施退避策略
|
||||
5. **使用分页**: 对于大数据集使用分页参数
|
||||
6. **缓存响应**: 适当缓存 API 响应以减少请求
|
||||
7. **版本控制**: 使用 API 版本号以确保兼容性
|
||||
|
||||
有关更多信息，请参阅我们的 [SDK 文档](https://docs.mcphub.com/sdk) 和 [示例代码](https://github.com/mcphub/examples)。
|
||||
大多数管理 API 端点都需要身份验证。有关更多详细信息，请参阅[身份验证](/api-reference/auth)部分。
|
||||
81
docs/zh/api-reference/logs.mdx
Normal file
81
docs/zh/api-reference/logs.mdx
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: "日志"
|
||||
description: "访问和管理服务器日志。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="GET /api/logs"
|
||||
href="#get-all-logs"
|
||||
>
|
||||
获取所有日志。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="DELETE /api/logs"
|
||||
href="#clear-logs"
|
||||
>
|
||||
清除所有日志。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/logs/stream"
|
||||
href="#stream-logs"
|
||||
>
|
||||
实时流式传输日志。
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### 获取所有日志
|
||||
|
||||
检索所有存储的日志。
|
||||
|
||||
- **端点**: `/api/logs`
|
||||
- **方法**: `GET`
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"timestamp": "2023-10-27T10:00:00.000Z",
|
||||
"level": "info",
|
||||
"message": "服务器成功启动。",
|
||||
"service": "system"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 清除日志
|
||||
|
||||
删除所有存储的日志。
|
||||
|
||||
- **端点**: `/api/logs`
|
||||
- **方法**: `DELETE`
|
||||
- **成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "日志清除成功"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 流式传输日志
|
||||
|
||||
使用服务器发送事件 (SSE) 实时流式传输日志。连接将保持打开状态，新的日志条目将在发生时发送。
|
||||
|
||||
- **端点**: `/api/logs/stream`
|
||||
- **方法**: `GET`
|
||||
- **响应格式**: 该流发送带有包含 JSON 对象的 `data` 字段的事件。第一个事件的 `type` 为 `initial`，包含所有历史日志。后续事件的 `type` 为 `log`，包含单个新日志条目。
|
||||
|
||||
- **事件示例**:
|
||||
```
|
||||
data: {"type":"log","log":{"timestamp":"2023-10-27T10:00:05.000Z","level":"debug","message":"正在处理 /api/some-endpoint 的请求","service":"mcp-server"}}
|
||||
```
|
||||
33
docs/zh/api-reference/mcp-http.mdx
Normal file
33
docs/zh/api-reference/mcp-http.mdx
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "MCP HTTP 端点"
|
||||
description: "使用统一的 HTTP 端点连接到您的 MCP 服务器。"
|
||||
---
|
||||
|
||||
MCPHub 为您的所有 MCP 服务器提供统一的可流式 HTTP 接口。这使您可以向任何配置的 MCP 服务器发送请求并实时接收响应。
|
||||
|
||||
### 统一端点
|
||||
|
||||
此端点提供对所有已启用的 MCP 服务器的访问。
|
||||
|
||||
- **端点**: `http://localhost:3000/mcp`
|
||||
- **方法**: `POST`
|
||||
|
||||
### 特定群组的端点
|
||||
|
||||
要定向访问特定的服务器群组，请使用基于群组的 HTTP 端点。
|
||||
|
||||
- **端点**: `http://localhost:3000/mcp/{group}`
|
||||
- **方法**: `POST`
|
||||
- **参数**:
|
||||
- `{group}`: 群组的 ID 或名称。
|
||||
|
||||
### 特定服务器的端点
|
||||
|
||||
要直接访问单个服务器，请使用特定于服务器的 HTTP 端点。
|
||||
|
||||
- **端点**: `http://localhost:3000/mcp/{server}`
|
||||
- **方法**: `POST`
|
||||
- **参数**:
|
||||
- `{server}`: 服务器的名称。
|
||||
|
||||
> **注意**: 如果服务器名称和群组名称相同，则群组将优先。
|
||||
25
docs/zh/api-reference/mcp-sse.mdx
Normal file
25
docs/zh/api-reference/mcp-sse.mdx
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "MCP SSE 端点 (已弃用)"
|
||||
description: "使用 SSE 端点连接到您的 MCP 服务器。"
|
||||
---
|
||||
|
||||
SSE 端点已弃用，并将在未来版本中删除。请改用 [MCP HTTP 端点](/api-reference/mcp-http)。
|
||||
|
||||
### 统一端点
|
||||
|
||||
- **端点**: `http://localhost:3000/sse`
|
||||
- **方法**: `GET`
|
||||
|
||||
### 特定群组的端点
|
||||
|
||||
- **端点**: `http://localhost:3000/sse/{group}`
|
||||
- **方法**: `GET`
|
||||
- **参数**:
|
||||
- `{group}`: 群组的 ID 或名称。
|
||||
|
||||
### 特定服务器的端点
|
||||
|
||||
- **端点**: `http://localhost:3000/sse/{server}`
|
||||
- **方法**: `GET`
|
||||
- **参数**:
|
||||
- `{server}`: 服务器的名称。
|
||||
209
docs/zh/api-reference/servers.mdx
Normal file
209
docs/zh/api-reference/servers.mdx
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
title: "服务器"
|
||||
description: "管理您的 MCP 服务器。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="GET /api/servers"
|
||||
href="#get-all-servers"
|
||||
>
|
||||
获取所有 MCP 服务器的列表。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/servers"
|
||||
href="#create-a-new-server"
|
||||
>
|
||||
创建一个新的 MCP 服务器。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/servers/:name"
|
||||
href="#update-a-server"
|
||||
>
|
||||
更新现有的 MCP 服务器。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="DELETE /api/servers/:name"
|
||||
href="#delete-a-server"
|
||||
>
|
||||
删除一个 MCP 服务器。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/servers/:name/toggle"
|
||||
href="#toggle-a-server"
|
||||
>
|
||||
切换服务器的启用状态。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/servers/:serverName/tools/:toolName/toggle"
|
||||
href="#toggle-a-tool"
|
||||
>
|
||||
切换工具的启用状态。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/servers/:serverName/tools/:toolName/description"
|
||||
href="#update-tool-description"
|
||||
>
|
||||
更新工具的描述。
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### 获取所有服务器
|
||||
|
||||
检索所有已配置的 MCP 服务器的列表，包括其状态和可用工具。
|
||||
|
||||
- **端点**: `/api/servers`
|
||||
- **方法**: `GET`
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"name": "example-server",
|
||||
"status": "connected",
|
||||
"tools": [
|
||||
{
|
||||
"name": "tool1",
|
||||
"description": "工具1的描述"
|
||||
}
|
||||
],
|
||||
"config": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["server.js"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 创建一个新服务器
|
||||
|
||||
将一个新的 MCP 服务器添加到配置中。
|
||||
|
||||
- **端点**: `/api/servers`
|
||||
- **方法**: `POST`
|
||||
- **正文**:
|
||||
```json
|
||||
{
|
||||
"name": "my-new-server",
|
||||
"config": {
|
||||
"type": "stdio",
|
||||
"command": "python",
|
||||
"args": ["-u", "my_script.py"],
|
||||
"owner": "admin"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `name` (string, 必填): 服务器的唯一名称。
|
||||
- `config` (object, 必填): 服务器配置对象。
|
||||
- `type` (string): `stdio`、`sse`、`streamable-http` 或 `openapi`。
|
||||
- `command` (string): `stdio` 类型要执行的命令。
|
||||
- `args` (array of strings): 命令的参数。
|
||||
- `url` (string): `sse`、`streamable-http` 或 `openapi` 类型的 URL。
|
||||
- `openapi` (object): OpenAPI 配置。
|
||||
- `url` (string): OpenAPI 模式的 URL。
|
||||
- `schema` (object): OpenAPI 模式对象本身。
|
||||
- `headers` (object): `sse`、`streamable-http` 和 `openapi` 类型请求要发送的标头。
|
||||
- `keepAliveInterval` (number): `sse` 类型的保持活动间隔（毫秒）。默认为 60000。
|
||||
- `owner` (string): 服务器的所有者。默认为当前用户或“admin”。
|
||||
|
||||
---
|
||||
|
||||
### 更新一个服务器
|
||||
|
||||
更新现有 MCP 服务器的配置。
|
||||
|
||||
- **端点**: `/api/servers/:name`
|
||||
- **方法**: `PUT`
|
||||
- **参数**:
|
||||
- `:name` (string, 必填): 要更新的服务器的名称。
|
||||
- **正文**:
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": ["new_server.js"]
|
||||
}
|
||||
}
|
||||
```
|
||||
- `config` (object, 必填): 更新后的服务器配置对象。详情请参阅“创建一个新服务器”。
|
||||
|
||||
---
|
||||
|
||||
### 删除一个服务器
|
||||
|
||||
从配置中删除一个 MCP 服务器。
|
||||
|
||||
- **端点**: `/api/servers/:name`
|
||||
- **方法**: `DELETE`
|
||||
- **参数**:
|
||||
- `:name` (string, 必填): 要删除的服务器的名称。
|
||||
|
||||
---
|
||||
|
||||
### 切换一个服务器
|
||||
|
||||
启用或禁用一个 MCP 服务器。
|
||||
|
||||
- **端点**: `/api/servers/:name/toggle`
|
||||
- **方法**: `POST`
|
||||
- **参数**:
|
||||
- `:name` (string, 必填): 要切换的服务器的名称。
|
||||
- **正文**:
|
||||
```json
|
||||
{
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
- `enabled` (boolean, 必填): `true` 启用服务器，`false` 禁用服务器。
|
||||
|
||||
---
|
||||
|
||||
### 切换一个工具
|
||||
|
||||
启用或禁用服务器上的特定工具。
|
||||
|
||||
- **端点**: `/api/servers/:serverName/tools/:toolName/toggle`
|
||||
- **方法**: `POST`
|
||||
- **参数**:
|
||||
- `:serverName` (string, 必填): 服务器的名称。
|
||||
- `:toolName` (string, 必填): 工具的名称。
|
||||
- **正文**:
|
||||
```json
|
||||
{
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
- `enabled` (boolean, 必填): `true` 启用工具，`false` 禁用工具。
|
||||
|
||||
---
|
||||
|
||||
### 更新工具描述
|
||||
|
||||
更新特定工具的描述。
|
||||
|
||||
- **端点**: `/api/servers/:serverName/tools/:toolName/description`
|
||||
- **方法**: `PUT`
|
||||
- **参数**:
|
||||
- `:serverName` (string, 必填): 服务器的名称。
|
||||
- `:toolName` (string, 必填): 工具的名称。
|
||||
- **正文**:
|
||||
```json
|
||||
{
|
||||
"description": "新的工具描述"
|
||||
}
|
||||
```
|
||||
- `description` (string, 必填): 工具的新描述。
|
||||
29
docs/zh/api-reference/smart-routing.mdx
Normal file
29
docs/zh/api-reference/smart-routing.mdx
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "智能路由"
|
||||
description: "使用向量语义搜索进行智能工具发现。"
|
||||
---
|
||||
|
||||
智能路由是 MCPHub 的智能工具发现系统，它使用向量语义搜索来自动为任何给定任务找到最相关的工具。
|
||||
|
||||
### HTTP 端点
|
||||
|
||||
- **端点**: `http://localhost:3000/mcp/$smart`
|
||||
- **方法**: `POST`
|
||||
|
||||
### SSE 端点 (已弃用)
|
||||
|
||||
- **端点**: `http://localhost:3000/sse/$smart`
|
||||
- **方法**: `GET`
|
||||
|
||||
### 工作原理
|
||||
|
||||
1. **工具索引**: 所有 MCP 工具都会自动转换为向量嵌入并存储在带有 pgvector 的 PostgreSQL 中。
|
||||
2. **语义搜索**: 用户查询被转换为向量，并使用余弦相似度与工具嵌入进行匹配。
|
||||
3. **智能过滤**: 动态阈值可确保相关结果而无噪音。
|
||||
4. **精确执行**: 找到的工具可以通过适当的参数验证直接执行。
|
||||
|
||||
### 设置要求
|
||||
|
||||
- 带有 pgvector 扩展的 PostgreSQL
|
||||
- OpenAI API 密钥（或兼容的嵌入服务）
|
||||
- 在 MCPHub 设置中启用智能路由
|
||||
Reference in New Issue
Block a user