mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
608 lines
14 KiB
Plaintext
608 lines
14 KiB
Plaintext
---
|
||
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) 文档。
|