mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
Add missing API documentation for tool execution and management endpoints (#430)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: samanhappy <2755122+samanhappy@users.noreply.github.com>
This commit is contained in:
Copilot
@@ -60,6 +60,32 @@ Generates and returns the complete OpenAPI 3.0.3 specification for all connected
|
||||
Comma-separated list of server names to include
|
||||
</ParamField>
|
||||
|
||||
### Group/Server-Specific OpenAPI Specification
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
```bash GET /api/:name/openapi.json
|
||||
curl "http://localhost:3000/api/mygroup/openapi.json"
|
||||
```
|
||||
|
||||
```bash With Parameters
|
||||
curl "http://localhost:3000/api/myserver/openapi.json?title=My Server API&version=1.0.0"
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
Generates and returns the OpenAPI 3.0.3 specification for a specific group or server. If a group with the given name exists, it returns the specification for all servers in that group. Otherwise, it treats the name as a server name and returns the specification for that server only.
|
||||
|
||||
**Path Parameters:**
|
||||
|
||||
<ParamField path="name" type="string" required>
|
||||
Group ID/name or server name
|
||||
</ParamField>
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
Same as the main OpenAPI specification endpoint (title, description, version, serverUrl, includeDisabled).
|
||||
|
||||
### Available Servers
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
142
docs/api-reference/prompts.mdx
Normal file
142
docs/api-reference/prompts.mdx
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: "Prompts"
|
||||
description: "Manage and execute MCP prompts."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="POST /api/mcp/:serverName/prompts/:promptName"
|
||||
href="#get-a-prompt"
|
||||
>
|
||||
Execute a prompt on an MCP server.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/servers/:serverName/prompts/:promptName/toggle"
|
||||
href="#toggle-a-prompt"
|
||||
>
|
||||
Enable or disable a prompt.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/servers/:serverName/prompts/:promptName/description"
|
||||
href="#update-prompt-description"
|
||||
>
|
||||
Update the description of a prompt.
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### Get a Prompt
|
||||
|
||||
Execute a prompt on an MCP server and get the result.
|
||||
|
||||
- **Endpoint**: `/api/mcp/:serverName/prompts/:promptName`
|
||||
- **Method**: `POST`
|
||||
- **Authentication**: Required
|
||||
- **Parameters**:
|
||||
- `:serverName` (string, required): The name of the MCP server.
|
||||
- `:promptName` (string, required): The name of the prompt.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"arguments": {
|
||||
"arg1": "value1",
|
||||
"arg2": "value2"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `arguments` (object, optional): Arguments to pass to the prompt.
|
||||
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": {
|
||||
"type": "text",
|
||||
"text": "Prompt content"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example Request:**
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/api/mcp/myserver/prompts/code-review" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{
|
||||
"arguments": {
|
||||
"language": "typescript",
|
||||
"code": "const x = 1;"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Toggle a Prompt
|
||||
|
||||
Enable or disable a specific prompt on a server.
|
||||
|
||||
- **Endpoint**: `/api/servers/:serverName/prompts/:promptName/toggle`
|
||||
- **Method**: `POST`
|
||||
- **Authentication**: Required
|
||||
- **Parameters**:
|
||||
- `:serverName` (string, required): The name of the server.
|
||||
- `:promptName` (string, required): The name of the prompt.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
- `enabled` (boolean, required): `true` to enable the prompt, `false` to disable it.
|
||||
|
||||
**Example Request:**
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/api/servers/myserver/prompts/code-review/toggle" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{"enabled": false}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Update Prompt Description
|
||||
|
||||
Update the description of a specific prompt.
|
||||
|
||||
- **Endpoint**: `/api/servers/:serverName/prompts/:promptName/description`
|
||||
- **Method**: `PUT`
|
||||
- **Authentication**: Required
|
||||
- **Parameters**:
|
||||
- `:serverName` (string, required): The name of the server.
|
||||
- `:promptName` (string, required): The name of the prompt.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"description": "New prompt description"
|
||||
}
|
||||
```
|
||||
- `description` (string, required): The new description for the prompt.
|
||||
|
||||
**Example Request:**
|
||||
|
||||
```bash
|
||||
curl -X PUT "http://localhost:3000/api/servers/myserver/prompts/code-review/description" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{"description": "Review code for best practices and potential issues"}'
|
||||
```
|
||||
|
||||
**Note**: Prompts are templates that can be used to generate standardized requests to MCP servers. They are defined by the MCP server and can have arguments that are filled in when the prompt is executed.
|
||||
@@ -54,6 +54,20 @@ import { Card, Cards } from 'mintlify';
|
||||
Update the description of a tool.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/system-config"
|
||||
href="#update-system-config"
|
||||
>
|
||||
Update system configuration settings.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/settings"
|
||||
href="#get-settings"
|
||||
>
|
||||
Get all server settings and configurations.
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### Get All Servers
|
||||
@@ -207,3 +221,45 @@ Updates the description of a specific tool.
|
||||
}
|
||||
```
|
||||
- `description` (string, required): The new description for the tool.
|
||||
|
||||
---
|
||||
|
||||
### Update System Config
|
||||
|
||||
Updates the system-wide configuration settings.
|
||||
|
||||
- **Endpoint**: `/api/system-config`
|
||||
- **Method**: `PUT`
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"openaiApiKey": "sk-...",
|
||||
"openaiBaseUrl": "https://api.openai.com/v1",
|
||||
"modelName": "gpt-4",
|
||||
"temperature": 0.7,
|
||||
"maxTokens": 2048
|
||||
}
|
||||
```
|
||||
- All fields are optional. Only provided fields will be updated.
|
||||
|
||||
---
|
||||
|
||||
### Get Settings
|
||||
|
||||
Retrieves all server settings and configurations.
|
||||
|
||||
- **Endpoint**: `/api/settings`
|
||||
- **Method**: `GET`
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"servers": [...],
|
||||
"groups": [...],
|
||||
"systemConfig": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: For detailed prompt management, see the [Prompts API](/api-reference/prompts) documentation.
|
||||
|
||||
113
docs/api-reference/system.mdx
Normal file
113
docs/api-reference/system.mdx
Normal file
@@ -0,0 +1,113 @@
|
||||
---
|
||||
title: "System"
|
||||
description: "System and utility endpoints."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="GET /health"
|
||||
href="#health-check"
|
||||
>
|
||||
Check the health status of the MCPHub server.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /oauth/callback"
|
||||
href="#oauth-callback"
|
||||
>
|
||||
OAuth callback endpoint for authentication flows.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/dxt/upload"
|
||||
href="#upload-dxt-file"
|
||||
>
|
||||
Upload a DXT configuration file.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/mcp-settings/export"
|
||||
href="#export-mcp-settings"
|
||||
>
|
||||
Export MCP settings as JSON.
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### Health Check
|
||||
|
||||
Check the health status of the MCPHub server.
|
||||
|
||||
- **Endpoint**: `/health`
|
||||
- **Method**: `GET`
|
||||
- **Authentication**: Not required
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"timestamp": "2024-11-12T01:30:00.000Z",
|
||||
"uptime": 12345
|
||||
}
|
||||
```
|
||||
|
||||
**Example Request:**
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3000/health"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### OAuth Callback
|
||||
|
||||
OAuth callback endpoint for handling OAuth authentication flows. This endpoint is automatically called by OAuth providers after user authorization.
|
||||
|
||||
- **Endpoint**: `/oauth/callback`
|
||||
- **Method**: `GET`
|
||||
- **Authentication**: Not required (public callback URL)
|
||||
- **Query Parameters**: Varies by OAuth provider (typically includes `code`, `state`, etc.)
|
||||
|
||||
**Note**: This endpoint is used internally by MCPHub's OAuth integration and should not be called directly by clients.
|
||||
|
||||
---
|
||||
|
||||
### Upload DXT File
|
||||
|
||||
Upload a DXT (Desktop Extension) configuration file to import server configurations.
|
||||
|
||||
- **Endpoint**: `/api/dxt/upload`
|
||||
- **Method**: `POST`
|
||||
- **Authentication**: Required
|
||||
- **Content-Type**: `multipart/form-data`
|
||||
- **Body**:
|
||||
- `file` (file, required): The DXT configuration file to upload.
|
||||
|
||||
**Example Request:**
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/api/dxt/upload" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-F "file=@config.dxt"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Export MCP Settings
|
||||
|
||||
Export the current MCP settings configuration as a JSON file.
|
||||
|
||||
- **Endpoint**: `/api/mcp-settings/export`
|
||||
- **Method**: `GET`
|
||||
- **Authentication**: Required
|
||||
- **Response**: Returns the `mcp_settings.json` configuration file.
|
||||
|
||||
**Example Request:**
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3000/api/mcp-settings/export" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-o mcp_settings.json
|
||||
```
|
||||
|
||||
**Note**: This endpoint allows you to download a backup of your MCP settings, which can be used to restore or migrate your configuration.
|
||||
86
docs/api-reference/tools.mdx
Normal file
86
docs/api-reference/tools.mdx
Normal file
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: "Tools"
|
||||
description: "Execute MCP tools programmatically."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="POST /api/tools/call/:server"
|
||||
href="#call-a-tool"
|
||||
>
|
||||
Call a specific tool on an MCP server.
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### Call a Tool
|
||||
|
||||
Execute a specific tool on an MCP server with given arguments.
|
||||
|
||||
- **Endpoint**: `/api/tools/call/:server`
|
||||
- **Method**: `POST`
|
||||
- **Parameters**:
|
||||
- `:server` (string, required): The name of the MCP server.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"toolName": "tool-name",
|
||||
"arguments": {
|
||||
"param1": "value1",
|
||||
"param2": "value2"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `toolName` (string, required): The name of the tool to execute.
|
||||
- `arguments` (object, optional): The arguments to pass to the tool. Defaults to an empty object.
|
||||
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Tool execution result"
|
||||
}
|
||||
],
|
||||
"toolName": "tool-name",
|
||||
"arguments": {
|
||||
"param1": "value1",
|
||||
"param2": "value2"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example Request:**
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/api/tools/call/amap" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{
|
||||
"toolName": "amap-maps_weather",
|
||||
"arguments": {
|
||||
"city": "Beijing"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- The tool arguments are automatically converted to the proper types based on the tool's input schema.
|
||||
- Use the `x-session-id` header to maintain session state across multiple tool calls if needed.
|
||||
- This endpoint requires authentication.
|
||||
|
||||
---
|
||||
|
||||
### Alternative: OpenAPI Tool Execution
|
||||
|
||||
For OpenAPI-compatible tool execution without authentication, see the [OpenAPI Integration](/api-reference/openapi#tool-execution) documentation. The OpenAPI endpoints provide:
|
||||
|
||||
- **GET** `/api/tools/:serverName/:toolName` - For simple tools with query parameters
|
||||
- **POST** `/api/tools/:serverName/:toolName` - For complex tools with JSON body
|
||||
|
||||
These endpoints are designed for integration with OpenWebUI and other OpenAPI-compatible systems.
|
||||
195
docs/api-reference/users.mdx
Normal file
195
docs/api-reference/users.mdx
Normal file
@@ -0,0 +1,195 @@
|
||||
---
|
||||
title: "Users"
|
||||
description: "Manage users in MCPHub."
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="GET /api/users"
|
||||
href="#get-all-users"
|
||||
>
|
||||
Get a list of all users.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/users/:username"
|
||||
href="#get-a-user"
|
||||
>
|
||||
Get details of a specific user.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/users"
|
||||
href="#create-a-user"
|
||||
>
|
||||
Create a new user.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/users/:username"
|
||||
href="#update-a-user"
|
||||
>
|
||||
Update an existing user.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="DELETE /api/users/:username"
|
||||
href="#delete-a-user"
|
||||
>
|
||||
Delete a user.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/users-stats"
|
||||
href="#get-user-statistics"
|
||||
>
|
||||
Get statistics about users and their server access.
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### Get All Users
|
||||
|
||||
Retrieves a list of all users in the system.
|
||||
|
||||
- **Endpoint**: `/api/users`
|
||||
- **Method**: `GET`
|
||||
- **Authentication**: Required (Admin only)
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"username": "admin",
|
||||
"role": "admin",
|
||||
"servers": ["server1", "server2"],
|
||||
"groups": ["group1"]
|
||||
},
|
||||
{
|
||||
"username": "user1",
|
||||
"role": "user",
|
||||
"servers": ["server1"],
|
||||
"groups": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Get a User
|
||||
|
||||
Retrieves details of a specific user.
|
||||
|
||||
- **Endpoint**: `/api/users/:username`
|
||||
- **Method**: `GET`
|
||||
- **Authentication**: Required (Admin only)
|
||||
- **Parameters**:
|
||||
- `:username` (string, required): The username of the user.
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"username": "user1",
|
||||
"role": "user",
|
||||
"servers": ["server1", "server2"],
|
||||
"groups": ["group1"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Create a User
|
||||
|
||||
Creates a new user in the system.
|
||||
|
||||
- **Endpoint**: `/api/users`
|
||||
- **Method**: `POST`
|
||||
- **Authentication**: Required (Admin only)
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"username": "newuser",
|
||||
"password": "securepassword",
|
||||
"role": "user",
|
||||
"servers": ["server1"],
|
||||
"groups": ["group1"]
|
||||
}
|
||||
```
|
||||
- `username` (string, required): The username for the new user.
|
||||
- `password` (string, required): The password for the new user. Must be at least 6 characters.
|
||||
- `role` (string, optional): The role of the user. Either `"admin"` or `"user"`. Defaults to `"user"`.
|
||||
- `servers` (array of strings, optional): List of server names the user has access to.
|
||||
- `groups` (array of strings, optional): List of group IDs the user belongs to.
|
||||
|
||||
---
|
||||
|
||||
### Update a User
|
||||
|
||||
Updates an existing user's information.
|
||||
|
||||
- **Endpoint**: `/api/users/:username`
|
||||
- **Method**: `PUT`
|
||||
- **Authentication**: Required (Admin only)
|
||||
- **Parameters**:
|
||||
- `:username` (string, required): The username of the user to update.
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"password": "newpassword",
|
||||
"role": "admin",
|
||||
"servers": ["server1", "server2", "server3"],
|
||||
"groups": ["group1", "group2"]
|
||||
}
|
||||
```
|
||||
- `password` (string, optional): New password for the user.
|
||||
- `role` (string, optional): New role for the user.
|
||||
- `servers` (array of strings, optional): Updated list of accessible servers.
|
||||
- `groups` (array of strings, optional): Updated list of groups.
|
||||
|
||||
---
|
||||
|
||||
### Delete a User
|
||||
|
||||
Removes a user from the system.
|
||||
|
||||
- **Endpoint**: `/api/users/:username`
|
||||
- **Method**: `DELETE`
|
||||
- **Authentication**: Required (Admin only)
|
||||
- **Parameters**:
|
||||
- `:username` (string, required): The username of the user to delete.
|
||||
|
||||
---
|
||||
|
||||
### Get User Statistics
|
||||
|
||||
Retrieves statistics about users and their access to servers and groups.
|
||||
|
||||
- **Endpoint**: `/api/users-stats`
|
||||
- **Method**: `GET`
|
||||
- **Authentication**: Required (Admin only)
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"totalUsers": 5,
|
||||
"adminUsers": 1,
|
||||
"regularUsers": 4,
|
||||
"usersPerServer": {
|
||||
"server1": 3,
|
||||
"server2": 2
|
||||
},
|
||||
"usersPerGroup": {
|
||||
"group1": 2,
|
||||
"group2": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: All user management endpoints require admin authentication.
|
||||
@@ -96,9 +96,13 @@
|
||||
"pages": [
|
||||
"api-reference/servers",
|
||||
"api-reference/groups",
|
||||
"api-reference/users",
|
||||
"api-reference/tools",
|
||||
"api-reference/prompts",
|
||||
"api-reference/auth",
|
||||
"api-reference/logs",
|
||||
"api-reference/config"
|
||||
"api-reference/config",
|
||||
"api-reference/system"
|
||||
]
|
||||
}
|
||||
]
|
||||
@@ -126,9 +130,13 @@
|
||||
"pages": [
|
||||
"zh/api-reference/servers",
|
||||
"zh/api-reference/groups",
|
||||
"zh/api-reference/users",
|
||||
"zh/api-reference/tools",
|
||||
"zh/api-reference/prompts",
|
||||
"zh/api-reference/auth",
|
||||
"zh/api-reference/logs",
|
||||
"zh/api-reference/config"
|
||||
"zh/api-reference/config",
|
||||
"zh/api-reference/system"
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
@@ -60,6 +60,32 @@ curl "http://localhost:3000/api/openapi.json?title=我的 MCP API&version=2.0.0"
|
||||
要包含的服务器名称列表（逗号分隔）
|
||||
</ParamField>
|
||||
|
||||
### 组/服务器特定的 OpenAPI 规范
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
```bash GET /api/:name/openapi.json
|
||||
curl "http://localhost:3000/api/mygroup/openapi.json"
|
||||
```
|
||||
|
||||
```bash 带参数
|
||||
curl "http://localhost:3000/api/myserver/openapi.json?title=我的服务器 API&version=1.0.0"
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
为特定组或服务器生成并返回 OpenAPI 3.0.3 规范。如果存在具有给定名称的组，则返回该组中所有服务器的规范。否则，将名称视为服务器名称并仅返回该服务器的规范。
|
||||
|
||||
**路径参数：**
|
||||
|
||||
<ParamField path="name" type="string" required>
|
||||
组 ID/名称或服务器名称
|
||||
</ParamField>
|
||||
|
||||
**查询参数：**
|
||||
|
||||
与主 OpenAPI 规范端点相同（title、description、version、serverUrl、includeDisabled）。
|
||||
|
||||
### 可用服务器
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
142
docs/zh/api-reference/prompts.mdx
Normal file
142
docs/zh/api-reference/prompts.mdx
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: "提示词"
|
||||
description: "管理和执行 MCP 提示词。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="POST /api/mcp/:serverName/prompts/:promptName"
|
||||
href="#get-a-prompt"
|
||||
>
|
||||
在 MCP 服务器上执行提示词。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/servers/:serverName/prompts/:promptName/toggle"
|
||||
href="#toggle-a-prompt"
|
||||
>
|
||||
启用或禁用提示词。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/servers/:serverName/prompts/:promptName/description"
|
||||
href="#update-prompt-description"
|
||||
>
|
||||
更新提示词的描述。
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### 获取提示词
|
||||
|
||||
在 MCP 服务器上执行提示词并获取结果。
|
||||
|
||||
- **端点**: `/api/mcp/:serverName/prompts/:promptName`
|
||||
- **方法**: `POST`
|
||||
- **身份验证**: 必需
|
||||
- **参数**:
|
||||
- `:serverName` (字符串, 必需): MCP 服务器的名称。
|
||||
- `:promptName` (字符串, 必需): 提示词的名称。
|
||||
- **请求正文**:
|
||||
```json
|
||||
{
|
||||
"arguments": {
|
||||
"arg1": "value1",
|
||||
"arg2": "value2"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `arguments` (对象, 可选): 传递给提示词的参数。
|
||||
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": {
|
||||
"type": "text",
|
||||
"text": "提示词内容"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**请求示例：**
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/api/mcp/myserver/prompts/code-review" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{
|
||||
"arguments": {
|
||||
"language": "typescript",
|
||||
"code": "const x = 1;"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 切换提示词
|
||||
|
||||
启用或禁用服务器上的特定提示词。
|
||||
|
||||
- **端点**: `/api/servers/:serverName/prompts/:promptName/toggle`
|
||||
- **方法**: `POST`
|
||||
- **身份验证**: 必需
|
||||
- **参数**:
|
||||
- `:serverName` (字符串, 必需): 服务器的名称。
|
||||
- `:promptName` (字符串, 必需): 提示词的名称。
|
||||
- **请求正文**:
|
||||
```json
|
||||
{
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
- `enabled` (布尔值, 必需): `true` 启用提示词, `false` 禁用提示词。
|
||||
|
||||
**请求示例：**
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/api/servers/myserver/prompts/code-review/toggle" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{"enabled": false}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 更新提示词描述
|
||||
|
||||
更新特定提示词的描述。
|
||||
|
||||
- **端点**: `/api/servers/:serverName/prompts/:promptName/description`
|
||||
- **方法**: `PUT`
|
||||
- **身份验证**: 必需
|
||||
- **参数**:
|
||||
- `:serverName` (字符串, 必需): 服务器的名称。
|
||||
- `:promptName` (字符串, 必需): 提示词的名称。
|
||||
- **请求正文**:
|
||||
```json
|
||||
{
|
||||
"description": "新的提示词描述"
|
||||
}
|
||||
```
|
||||
- `description` (字符串, 必需): 提示词的新描述。
|
||||
|
||||
**请求示例：**
|
||||
|
||||
```bash
|
||||
curl -X PUT "http://localhost:3000/api/servers/myserver/prompts/code-review/description" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{"description": "审查代码的最佳实践和潜在问题"}'
|
||||
```
|
||||
|
||||
**注意**: 提示词是可用于生成标准化请求到 MCP 服务器的模板。它们由 MCP 服务器定义，并且可以具有在执行提示词时填充的参数。
|
||||
@@ -54,6 +54,20 @@ import { Card, Cards } from 'mintlify';
|
||||
更新工具的描述。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/system-config"
|
||||
href="#update-system-config"
|
||||
>
|
||||
更新系统配置设置。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/settings"
|
||||
href="#get-settings"
|
||||
>
|
||||
获取所有服务器设置和配置。
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### 获取所有服务器
|
||||
@@ -207,3 +221,45 @@ import { Card, Cards } from 'mintlify';
|
||||
}
|
||||
```
|
||||
- `description` (string, 必填): 工具的新描述。
|
||||
|
||||
---
|
||||
|
||||
### 更新系统配置
|
||||
|
||||
更新系统范围的配置设置。
|
||||
|
||||
- **端点**: `/api/system-config`
|
||||
- **方法**: `PUT`
|
||||
- **正文**:
|
||||
```json
|
||||
{
|
||||
"openaiApiKey": "sk-...",
|
||||
"openaiBaseUrl": "https://api.openai.com/v1",
|
||||
"modelName": "gpt-4",
|
||||
"temperature": 0.7,
|
||||
"maxTokens": 2048
|
||||
}
|
||||
```
|
||||
- 所有字段都是可选的。只有提供的字段会被更新。
|
||||
|
||||
---
|
||||
|
||||
### 获取设置
|
||||
|
||||
检索所有服务器设置和配置。
|
||||
|
||||
- **端点**: `/api/settings`
|
||||
- **方法**: `GET`
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"servers": [...],
|
||||
"groups": [...],
|
||||
"systemConfig": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**: 有关详细的提示词管理，请参阅 [提示词 API](/zh/api-reference/prompts) 文档。
|
||||
|
||||
113
docs/zh/api-reference/system.mdx
Normal file
113
docs/zh/api-reference/system.mdx
Normal file
@@ -0,0 +1,113 @@
|
||||
---
|
||||
title: "系统"
|
||||
description: "系统和实用程序端点。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="GET /health"
|
||||
href="#health-check"
|
||||
>
|
||||
检查 MCPHub 服务器的健康状态。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /oauth/callback"
|
||||
href="#oauth-callback"
|
||||
>
|
||||
用于身份验证流程的 OAuth 回调端点。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/dxt/upload"
|
||||
href="#upload-dxt-file"
|
||||
>
|
||||
上传 DXT 配置文件。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/mcp-settings/export"
|
||||
href="#export-mcp-settings"
|
||||
>
|
||||
将 MCP 设置导出为 JSON。
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### 健康检查
|
||||
|
||||
检查 MCPHub 服务器的健康状态。
|
||||
|
||||
- **端点**: `/health`
|
||||
- **方法**: `GET`
|
||||
- **身份验证**: 不需要
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"timestamp": "2024-11-12T01:30:00.000Z",
|
||||
"uptime": 12345
|
||||
}
|
||||
```
|
||||
|
||||
**请求示例：**
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3000/health"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### OAuth 回调
|
||||
|
||||
用于处理 OAuth 身份验证流程的 OAuth 回调端点。此端点在用户授权后由 OAuth 提供商自动调用。
|
||||
|
||||
- **端点**: `/oauth/callback`
|
||||
- **方法**: `GET`
|
||||
- **身份验证**: 不需要（公共回调 URL）
|
||||
- **查询参数**: 因 OAuth 提供商而异（通常包括 `code`、`state` 等）
|
||||
|
||||
**注意**: 此端点由 MCPHub 的 OAuth 集成内部使用，客户端不应直接调用。
|
||||
|
||||
---
|
||||
|
||||
### 上传 DXT 文件
|
||||
|
||||
上传 DXT（桌面扩展）配置文件以导入服务器配置。
|
||||
|
||||
- **端点**: `/api/dxt/upload`
|
||||
- **方法**: `POST`
|
||||
- **身份验证**: 必需
|
||||
- **Content-Type**: `multipart/form-data`
|
||||
- **正文**:
|
||||
- `file` (文件, 必需): 要上传的 DXT 配置文件。
|
||||
|
||||
**请求示例：**
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/api/dxt/upload" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-F "file=@config.dxt"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 导出 MCP 设置
|
||||
|
||||
将当前 MCP 设置配置导出为 JSON 文件。
|
||||
|
||||
- **端点**: `/api/mcp-settings/export`
|
||||
- **方法**: `GET`
|
||||
- **身份验证**: 必需
|
||||
- **响应**: 返回 `mcp_settings.json` 配置文件。
|
||||
|
||||
**请求示例：**
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3000/api/mcp-settings/export" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-o mcp_settings.json
|
||||
```
|
||||
|
||||
**注意**: 此端点允许您下载 MCP 设置的备份，可用于恢复或迁移您的配置。
|
||||
86
docs/zh/api-reference/tools.mdx
Normal file
86
docs/zh/api-reference/tools.mdx
Normal file
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: "工具"
|
||||
description: "以编程方式执行 MCP 工具。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="POST /api/tools/call/:server"
|
||||
href="#call-a-tool"
|
||||
>
|
||||
在 MCP 服务器上调用特定工具。
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### 调用工具
|
||||
|
||||
使用给定参数在 MCP 服务器上执行特定工具。
|
||||
|
||||
- **端点**: `/api/tools/call/:server`
|
||||
- **方法**: `POST`
|
||||
- **参数**:
|
||||
- `:server` (字符串, 必需): MCP 服务器的名称。
|
||||
- **请求正文**:
|
||||
```json
|
||||
{
|
||||
"toolName": "tool-name",
|
||||
"arguments": {
|
||||
"param1": "value1",
|
||||
"param2": "value2"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `toolName` (字符串, 必需): 要执行的工具名称。
|
||||
- `arguments` (对象, 可选): 传递给工具的参数。默认为空对象。
|
||||
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "工具执行结果"
|
||||
}
|
||||
],
|
||||
"toolName": "tool-name",
|
||||
"arguments": {
|
||||
"param1": "value1",
|
||||
"param2": "value2"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**请求示例：**
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/api/tools/call/amap" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{
|
||||
"toolName": "amap-maps_weather",
|
||||
"arguments": {
|
||||
"city": "Beijing"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
**注意事项：**
|
||||
- 工具参数会根据工具的输入模式自动转换为适当的类型。
|
||||
- 如果需要，可以使用 `x-session-id` 请求头在多个工具调用之间维护会话状态。
|
||||
- 此端点需要身份验证。
|
||||
|
||||
---
|
||||
|
||||
### 替代方案：OpenAPI 工具执行
|
||||
|
||||
有关无需身份验证的 OpenAPI 兼容工具执行，请参阅 [OpenAPI 集成](/api-reference/openapi#tool-execution) 文档。OpenAPI 端点提供：
|
||||
|
||||
- **GET** `/api/tools/:serverName/:toolName` - 用于带查询参数的简单工具
|
||||
- **POST** `/api/tools/:serverName/:toolName` - 用于带 JSON 正文的复杂工具
|
||||
|
||||
这些端点专为与 OpenWebUI 和其他 OpenAPI 兼容系统集成而设计。
|
||||
195
docs/zh/api-reference/users.mdx
Normal file
195
docs/zh/api-reference/users.mdx
Normal file
@@ -0,0 +1,195 @@
|
||||
---
|
||||
title: "用户"
|
||||
description: "在 MCPHub 中管理用户。"
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'mintlify';
|
||||
|
||||
<Card
|
||||
title="GET /api/users"
|
||||
href="#get-all-users"
|
||||
>
|
||||
获取所有用户的列表。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/users/:username"
|
||||
href="#get-a-user"
|
||||
>
|
||||
获取特定用户的详细信息。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="POST /api/users"
|
||||
href="#create-a-user"
|
||||
>
|
||||
创建新用户。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="PUT /api/users/:username"
|
||||
href="#update-a-user"
|
||||
>
|
||||
更新现有用户。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="DELETE /api/users/:username"
|
||||
href="#delete-a-user"
|
||||
>
|
||||
删除用户。
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GET /api/users-stats"
|
||||
href="#get-user-statistics"
|
||||
>
|
||||
获取有关用户及其服务器访问权限的统计信息。
|
||||
</Card>
|
||||
|
||||
---
|
||||
|
||||
### 获取所有用户
|
||||
|
||||
检索系统中所有用户的列表。
|
||||
|
||||
- **端点**: `/api/users`
|
||||
- **方法**: `GET`
|
||||
- **身份验证**: 必需（仅管理员）
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"username": "admin",
|
||||
"role": "admin",
|
||||
"servers": ["server1", "server2"],
|
||||
"groups": ["group1"]
|
||||
},
|
||||
{
|
||||
"username": "user1",
|
||||
"role": "user",
|
||||
"servers": ["server1"],
|
||||
"groups": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 获取用户
|
||||
|
||||
检索特定用户的详细信息。
|
||||
|
||||
- **端点**: `/api/users/:username`
|
||||
- **方法**: `GET`
|
||||
- **身份验证**: 必需（仅管理员）
|
||||
- **参数**:
|
||||
- `:username` (字符串, 必需): 用户的用户名。
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"username": "user1",
|
||||
"role": "user",
|
||||
"servers": ["server1", "server2"],
|
||||
"groups": ["group1"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 创建用户
|
||||
|
||||
在系统中创建新用户。
|
||||
|
||||
- **端点**: `/api/users`
|
||||
- **方法**: `POST`
|
||||
- **身份验证**: 必需（仅管理员）
|
||||
- **请求正文**:
|
||||
```json
|
||||
{
|
||||
"username": "newuser",
|
||||
"password": "securepassword",
|
||||
"role": "user",
|
||||
"servers": ["server1"],
|
||||
"groups": ["group1"]
|
||||
}
|
||||
```
|
||||
- `username` (字符串, 必需): 新用户的用户名。
|
||||
- `password` (字符串, 必需): 新用户的密码。至少 6 个字符。
|
||||
- `role` (字符串, 可选): 用户的角色。可以是 `"admin"` 或 `"user"`。默认为 `"user"`。
|
||||
- `servers` (字符串数组, 可选): 用户可以访问的服务器名称列表。
|
||||
- `groups` (字符串数组, 可选): 用户所属的组 ID 列表。
|
||||
|
||||
---
|
||||
|
||||
### 更新用户
|
||||
|
||||
更新现有用户的信息。
|
||||
|
||||
- **端点**: `/api/users/:username`
|
||||
- **方法**: `PUT`
|
||||
- **身份验证**: 必需（仅管理员）
|
||||
- **参数**:
|
||||
- `:username` (字符串, 必需): 要更新的用户的用户名。
|
||||
- **请求正文**:
|
||||
```json
|
||||
{
|
||||
"password": "newpassword",
|
||||
"role": "admin",
|
||||
"servers": ["server1", "server2", "server3"],
|
||||
"groups": ["group1", "group2"]
|
||||
}
|
||||
```
|
||||
- `password` (字符串, 可选): 用户的新密码。
|
||||
- `role` (字符串, 可选): 用户的新角色。
|
||||
- `servers` (字符串数组, 可选): 更新的可访问服务器列表。
|
||||
- `groups` (字符串数组, 可选): 更新的组列表。
|
||||
|
||||
---
|
||||
|
||||
### 删除用户
|
||||
|
||||
从系统中删除用户。
|
||||
|
||||
- **端点**: `/api/users/:username`
|
||||
- **方法**: `DELETE`
|
||||
- **身份验证**: 必需（仅管理员）
|
||||
- **参数**:
|
||||
- `:username` (字符串, 必需): 要删除的用户的用户名。
|
||||
|
||||
---
|
||||
|
||||
### 获取用户统计信息
|
||||
|
||||
检索有关用户及其对服务器和组的访问权限的统计信息。
|
||||
|
||||
- **端点**: `/api/users-stats`
|
||||
- **方法**: `GET`
|
||||
- **身份验证**: 必需（仅管理员）
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"totalUsers": 5,
|
||||
"adminUsers": 1,
|
||||
"regularUsers": 4,
|
||||
"usersPerServer": {
|
||||
"server1": 3,
|
||||
"server2": 2
|
||||
},
|
||||
"usersPerGroup": {
|
||||
"group1": 2,
|
||||
"group2": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**: 所有用户管理端点都需要管理员身份验证。
|
||||
Reference in New Issue
Block a user