diff --git a/README.md b/README.md index c125ac6..c1b44cf 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,11 @@ MCPHub makes it easy to manage and scale multiple MCP (Model Context Protocol) s ![Dashboard Preview](assets/dashboard.png) +## 🌐 Live Demo & Docs + +- **Documentation**: [docs.mcphubx.com](https://docs.mcphubx.com/) +- **Demo Environment**: [demo.mcphubx.com](https://demo.mcphubx.com/) + ## 🚀 Features - **Broadened MCP Server Support**: Seamlessly integrate any MCP server with minimal configuration. diff --git a/README.zh.md b/README.zh.md index 0c7d32d..0fc72b9 100644 --- a/README.zh.md +++ b/README.zh.md @@ -6,6 +6,11 @@ MCPHub 通过将多个 MCP（Model Context Protocol）服务器组织为灵活 ![控制面板预览](assets/dashboard.zh.png) +## 🌐 在线文档与演示 + +- **文档地址**: [docs.mcphubx.com](https://docs.mcphubx.com/) +- **演示环境**: [demo.mcphubx.com](https://demo.mcphubx.com/) + ## 🚀 功能亮点 - **广泛的 MCP 服务器支持**：无缝集成任何 MCP 服务器，配置简单。 diff --git a/docs/api-reference/auth.mdx b/docs/api-reference/auth.mdx new file mode 100644 index 0000000..1fa8f8f --- /dev/null +++ b/docs/api-reference/auth.mdx @@ -0,0 +1,147 @@ +--- +title: "Authentication" +description: "Manage users and authentication." +--- + +import { Card, Cards } from 'mintlify'; + + + Log in to get a JWT token. + + + + Register a new user. + + + + Get the currently authenticated user. + + + + Change the password for the current user. + + +--- + +### 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" + } + ``` diff --git a/docs/api-reference/config.mdx b/docs/api-reference/config.mdx new file mode 100644 index 0000000..93ca3d7 --- /dev/null +++ b/docs/api-reference/config.mdx @@ -0,0 +1,111 @@ +--- +title: "Config" +description: "Manage and retrieve system-wide configurations." +--- + +import { Card, Cards } from 'mintlify'; + +Update the main system configuration. +Get all system settings, including servers and groups. +Get public runtime configuration for the frontend. +Get public configuration to check for auth skip. + +--- + +### 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": {} + } + } + ``` diff --git a/docs/api-reference/endpoint/create.mdx b/docs/api-reference/endpoint/create.mdx deleted file mode 100644 index 5689f1b..0000000 --- a/docs/api-reference/endpoint/create.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Create Plant' -openapi: 'POST /plants' ---- diff --git a/docs/api-reference/endpoint/delete.mdx b/docs/api-reference/endpoint/delete.mdx deleted file mode 100644 index 657dfc8..0000000 --- a/docs/api-reference/endpoint/delete.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Delete Plant' -openapi: 'DELETE /plants/{id}' ---- diff --git a/docs/api-reference/endpoint/get.mdx b/docs/api-reference/endpoint/get.mdx deleted file mode 100644 index 56aa09e..0000000 --- a/docs/api-reference/endpoint/get.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Get Plants' -openapi: 'GET /plants' ---- diff --git a/docs/api-reference/endpoint/webhook.mdx b/docs/api-reference/endpoint/webhook.mdx deleted file mode 100644 index 3291340..0000000 --- a/docs/api-reference/endpoint/webhook.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'New Plant' -openapi: 'WEBHOOK /plant/webhook' ---- diff --git a/docs/api-reference/groups.mdx b/docs/api-reference/groups.mdx new file mode 100644 index 0000000..b975002 --- /dev/null +++ b/docs/api-reference/groups.mdx @@ -0,0 +1,212 @@ +--- +title: "Groups" +description: "Manage server groups to organize and route requests." +--- + +import { Card, Cards } from 'mintlify'; + +Get a list of all groups. +Create a new group. +Get details of a specific group. +Update an existing group. +Delete a group. +Add a server to a group. +Remove a server from a group. +Batch update servers in a group. +Get detailed server configurations in a group. +Update tool selection for a server in a group. + +--- + +### 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"] + } + ``` diff --git a/docs/api-reference/introduction.mdx b/docs/api-reference/introduction.mdx index c835b78..296bc74 100644 --- a/docs/api-reference/introduction.mdx +++ b/docs/api-reference/introduction.mdx @@ -1,33 +1,13 @@ --- -title: 'Introduction' -description: 'Example section for showcasing API endpoints' +title: "Introduction" +description: "Welcome to the MCPHub API documentation." --- - - If you're not looking to build API reference documentation, you can delete - this section by removing the api-reference folder. - +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`. - - View the OpenAPI specification file - - -## 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. \ No newline at end of file diff --git a/docs/api-reference/logs.mdx b/docs/api-reference/logs.mdx new file mode 100644 index 0000000..a2b60b8 --- /dev/null +++ b/docs/api-reference/logs.mdx @@ -0,0 +1,81 @@ +--- +title: "Logs" +description: "Access and manage server logs." +--- + +import { Card, Cards } from 'mintlify'; + + + Get all logs. + + + + Clear all logs. + + + + Stream logs in real-time. + + +--- + +### 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"}} + ``` diff --git a/docs/api-reference/mcp-http.mdx b/docs/api-reference/mcp-http.mdx new file mode 100644 index 0000000..ee62fd8 --- /dev/null +++ b/docs/api-reference/mcp-http.mdx @@ -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. diff --git a/docs/api-reference/mcp-sse.mdx b/docs/api-reference/mcp-sse.mdx new file mode 100644 index 0000000..c2c16b4 --- /dev/null +++ b/docs/api-reference/mcp-sse.mdx @@ -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. diff --git a/docs/api-reference/servers.mdx b/docs/api-reference/servers.mdx new file mode 100644 index 0000000..eb2bc43 --- /dev/null +++ b/docs/api-reference/servers.mdx @@ -0,0 +1,209 @@ +--- +title: "Servers" +description: "Manage your MCP servers." +--- + +import { Card, Cards } from 'mintlify'; + + + Get a list of all MCP servers. + + + + Create a new MCP server. + + + + Update an existing MCP server. + + + + Delete an MCP server. + + + + Toggle the enabled state of a server. + + + + Toggle the enabled state of a tool. + + + + Update the description of a tool. + + +--- + +### 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. diff --git a/docs/api-reference/smart-routing.mdx b/docs/api-reference/smart-routing.mdx new file mode 100644 index 0000000..a6b4b7f --- /dev/null +++ b/docs/api-reference/smart-routing.mdx @@ -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 diff --git a/docs/docs.json b/docs/docs.json index d4fba32..ead9557 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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": { diff --git a/docs/zh/api-reference/auth.mdx b/docs/zh/api-reference/auth.mdx new file mode 100644 index 0000000..6ed5b0a --- /dev/null +++ b/docs/zh/api-reference/auth.mdx @@ -0,0 +1,147 @@ +--- +title: "身份验证" +description: "管理用户和身份验证。" +--- + +import { Card, Cards } from 'mintlify'; + + + 登录以获取 JWT 令牌。 + + + + 注册一个新用户。 + + + + 获取当前已验证的用户。 + + + + 更改当前用户的密码。 + + +--- + +### 登录 + +验证用户身份并返回 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": "密码更新成功" + } + ``` diff --git a/docs/zh/api-reference/config.mdx b/docs/zh/api-reference/config.mdx new file mode 100644 index 0000000..39d7eb1 --- /dev/null +++ b/docs/zh/api-reference/config.mdx @@ -0,0 +1,111 @@ +--- +title: "配置" +description: "管理和检索系统级配置。" +--- + +import { Card, Cards } from 'mintlify'; + +更新主系统配置。 +获取所有系统设置，包括服务器和群组。 +获取前端的公共运行时配置。 +获取公共配置以检查是否跳过身份验证。 + +--- + +### 更新系统配置 + +更新系统配置的各个部分。您只需提供要更新部分的键。 + +- **端点**: `/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": {} + } + } + ``` diff --git a/docs/zh/api-reference/endpoint/create.mdx b/docs/zh/api-reference/endpoint/create.mdx deleted file mode 100644 index 1998710..0000000 --- a/docs/zh/api-reference/endpoint/create.mdx +++ /dev/null @@ -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) 文档。 diff --git a/docs/zh/api-reference/endpoint/delete.mdx b/docs/zh/api-reference/endpoint/delete.mdx deleted file mode 100644 index 51aa07a..0000000 --- a/docs/zh/api-reference/endpoint/delete.mdx +++ /dev/null @@ -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' -``` - -硬删除操作不可逆，请谨慎使用。 - -## 权限要求 - -| 操作 | 所需权限 | -| ---------- | ------------------------ | -| 删除服务器 | `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' -``` diff --git a/docs/zh/api-reference/endpoint/get.mdx b/docs/zh/api-reference/endpoint/get.mdx deleted file mode 100644 index da0e527..0000000 --- a/docs/zh/api-reference/endpoint/get.mdx +++ /dev/null @@ -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) 文档。 diff --git a/docs/zh/api-reference/endpoint/webhook.mdx b/docs/zh/api-reference/endpoint/webhook.mdx deleted file mode 100644 index a38b4c9..0000000 --- a/docs/zh/api-reference/endpoint/webhook.mdx +++ /dev/null @@ -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' -``` diff --git a/docs/zh/api-reference/groups.mdx b/docs/zh/api-reference/groups.mdx new file mode 100644 index 0000000..f123491 --- /dev/null +++ b/docs/zh/api-reference/groups.mdx @@ -0,0 +1,212 @@ +--- +title: "群组" +description: "管理服务器群组以组织和路由请求。" +--- + +import { Card, Cards } from 'mintlify'; + +获取所有群组的列表。 +创建一个新群组。 +获取特定群组的详细信息。 +更新现有群组。 +删除一个群组。 +将服务器添加到群组。 +从群组中删除服务器。 +批量更新群组中的服务器。 +获取群组中详细的服务器配置。 +更新群组中服务器的工具选择。 + +--- + +### 获取所有群组 + +检索所有服务器群组的列表。 + +- **端点**: `/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"] + } + ``` diff --git a/docs/zh/api-reference/introduction.mdx b/docs/zh/api-reference/introduction.mdx index a488d22..6f27376 100644 --- a/docs/zh/api-reference/introduction.mdx +++ b/docs/zh/api-reference/introduction.mdx @@ -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)部分。 \ No newline at end of file diff --git a/docs/zh/api-reference/logs.mdx b/docs/zh/api-reference/logs.mdx new file mode 100644 index 0000000..e46b695 --- /dev/null +++ b/docs/zh/api-reference/logs.mdx @@ -0,0 +1,81 @@ +--- +title: "日志" +description: "访问和管理服务器日志。" +--- + +import { Card, Cards } from 'mintlify'; + + + 获取所有日志。 + + + + 清除所有日志。 + + + + 实时流式传输日志。 + + +--- + +### 获取所有日志 + +检索所有存储的日志。 + +- **端点**: `/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"}} + ``` diff --git a/docs/zh/api-reference/mcp-http.mdx b/docs/zh/api-reference/mcp-http.mdx new file mode 100644 index 0000000..c7c39d1 --- /dev/null +++ b/docs/zh/api-reference/mcp-http.mdx @@ -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}`: 服务器的名称。 + +> **注意**: 如果服务器名称和群组名称相同，则群组将优先。 diff --git a/docs/zh/api-reference/mcp-sse.mdx b/docs/zh/api-reference/mcp-sse.mdx new file mode 100644 index 0000000..827a790 --- /dev/null +++ b/docs/zh/api-reference/mcp-sse.mdx @@ -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}`: 服务器的名称。 diff --git a/docs/zh/api-reference/servers.mdx b/docs/zh/api-reference/servers.mdx new file mode 100644 index 0000000..4e383b5 --- /dev/null +++ b/docs/zh/api-reference/servers.mdx @@ -0,0 +1,209 @@ +--- +title: "服务器" +description: "管理您的 MCP 服务器。" +--- + +import { Card, Cards } from 'mintlify'; + + + 获取所有 MCP 服务器的列表。 + + + + 创建一个新的 MCP 服务器。 + + + + 更新现有的 MCP 服务器。 + + + + 删除一个 MCP 服务器。 + + + + 切换服务器的启用状态。 + + + + 切换工具的启用状态。 + + + + 更新工具的描述。 + + +--- + +### 获取所有服务器 + +检索所有已配置的 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, 必填): 工具的新描述。 diff --git a/docs/zh/api-reference/smart-routing.mdx b/docs/zh/api-reference/smart-routing.mdx new file mode 100644 index 0000000..4f93d27 --- /dev/null +++ b/docs/zh/api-reference/smart-routing.mdx @@ -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 设置中启用智能路由