| --- |
| 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: |
| -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) 文档。 |
|
|
