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.
|
||||
Reference in New Issue
Block a user