From 35012f99fc7399bd8e7ff3417b4694a21c79606d Mon Sep 17 00:00:00 2001 From: samanhappy Date: Sun, 10 Aug 2025 12:52:54 +0800 Subject: [PATCH] refine docs --- docs/configuration/mcp-settings.mdx | 95 +-- docs/docs.json | 54 +- docs/features/group-management.mdx | 40 +- docs/features/server-management.mdx | 24 +- docs/features/smart-routing.mdx | 20 +- docs/index.mdx | 12 +- docs/installation.mdx | 23 +- docs/logo/dark.svg | 48 +- docs/logo/light.svg | 48 +- docs/quickstart.mdx | 10 +- docs/zh/features/group-management.mdx | 1016 ++++++++++++------------ docs/zh/features/server-management.mdx | 691 +++++++--------- docs/zh/features/smart-routing.mdx | 930 +++++++--------------- docs/zh/index.mdx | 18 +- docs/zh/installation.mdx | 570 +++++++++++++ docs/zh/quickstart.mdx | 388 ++++----- 16 files changed, 1985 insertions(+), 2002 deletions(-) create mode 100644 docs/zh/installation.mdx diff --git a/docs/configuration/mcp-settings.mdx b/docs/configuration/mcp-settings.mdx index f85e694..49cc9c6 100644 --- a/docs/configuration/mcp-settings.mdx +++ b/docs/configuration/mcp-settings.mdx @@ -27,10 +27,7 @@ MCPHub uses several configuration files: "args": ["arg1", "arg2"], "env": { "ENV_VAR": "value" - }, - "cwd": "/working/directory", - "timeout": 30000, - "restart": true + } } } } @@ -50,8 +47,7 @@ MCPHub uses several configuration files: }, "playwright": { "command": "npx", - "args": ["@playwright/mcp@latest", "--headless"], - "timeout": 60000 + "args": ["@playwright/mcp@latest", "--headless"] }, "slack": { "command": "npx", @@ -79,12 +75,6 @@ MCPHub uses several configuration files: | Field | Type | Default | Description | | -------------- | ------- | --------------- | --------------------------- | | `env` | object | `{}` | Environment variables | -| `cwd` | string | `process.cwd()` | Working directory | -| `timeout` | number | `30000` | Startup timeout (ms) | -| `restart` | boolean | `true` | Auto-restart on failure | -| `maxRestarts` | number | `5` | Maximum restart attempts | -| `restartDelay` | number | `5000` | Delay between restarts (ms) | -| `stdio` | string | `pipe` | stdio configuration | ## Common MCP Server Examples @@ -262,42 +252,14 @@ MCPHub supports environment variable substitution using `${VAR_NAME}` syntax: "args": ["-m", "api_server"], "env": { "API_KEY": "${API_KEY}", - "API_URL": "${API_BASE_URL}/v1", - "DEBUG": "${NODE_ENV:development}" + "API_URL": "${API_BASE_URL}/v1" } } } } ``` -Default values can be specified with `${VAR_NAME:default}`: - -```json -{ - "timeout": "${MCP_TIMEOUT:30000}", - "maxRestarts": "${MCP_MAX_RESTARTS:5}" -} -``` - -### Conditional Configuration - -Use different configurations based on environment: - -```json -{ - "mcpServers": { - "database": { - "command": "python", - "args": ["-m", "db_server"], - "env": { - "DB_URL": "${NODE_ENV:development == 'production' ? DATABASE_URL : DEV_DATABASE_URL}" - } - } - } -} -``` - -### Custom Server Scripts +{/* ### Custom Server Scripts #### Local Python Server @@ -373,7 +335,7 @@ Complement `mcp_settings.json` with server metadata: } } } -``` +``` */} ## Group Management @@ -385,25 +347,18 @@ Complement `mcp_settings.json` with server metadata: "production": { "name": "Production Tools", "description": "Stable production servers", - "servers": ["fetch", "slack", "github"], - "access": "authenticated", - "rateLimit": { - "requestsPerMinute": 100, - "burstLimit": 20 - } + "servers": ["fetch", "slack", "github"] }, "experimental": { "name": "Experimental Features", "description": "Beta and experimental servers", - "servers": ["experimental-ai", "beta-search"], - "access": "admin", - "enabled": false + "servers": ["experimental-ai", "beta-search"] } } } ``` -### Access Control +{/* ### Access Control | Access Level | Description | | --------------- | -------------------------- | @@ -422,9 +377,9 @@ MCPHub supports hot reloading of configurations: # Reload configurations without restart curl -X POST http://localhost:3000/api/admin/reload-config \ -H "Authorization: Bearer your-admin-token" -``` +``` */} -### Configuration Validation +{/* ### Configuration Validation MCPHub validates configurations on startup and reload: @@ -436,7 +391,7 @@ MCPHub validates configurations on startup and reload: "requireDocumentation": true } } -``` +``` */} ## Best Practices @@ -453,7 +408,7 @@ MCPHub validates configurations on startup and reload: } ``` -2. **Limit server permissions**: +{/* 2. **Limit server permissions**: ```json { "filesystem": { @@ -464,9 +419,9 @@ MCPHub validates configurations on startup and reload: } } } - ``` + ``` */} -### Performance +{/* ### Performance 1. **Set appropriate timeouts**: @@ -486,9 +441,9 @@ MCPHub validates configurations on startup and reload: "MEMORY_LIMIT": "512MB" } } - ``` + ``` */} -### Monitoring +{/* ### Monitoring 1. **Enable health checks**: @@ -510,9 +465,9 @@ MCPHub validates configurations on startup and reload: "LOG_FORMAT": "json" } } - ``` + ``` */} -## Troubleshooting +{/* ## Troubleshooting ### Common Issues @@ -521,9 +476,9 @@ MCPHub validates configurations on startup and reload: ```bash # Test command manually uvx mcp-server-fetch -``` +``` */} -**Environment variables not found**: Verify `.env` file +{/* **Environment variables not found**: Verify `.env` file ```bash # Check environment @@ -535,9 +490,9 @@ printenv | grep API_KEY ```bash # Verify executable permissions ls -la /path/to/server -``` +``` */} -### Debug Configuration +{/* ### Debug Configuration Enable debug mode for detailed logging: @@ -550,8 +505,8 @@ Enable debug mode for detailed logging: "logStartup": true } } -``` - +``` */} +{/* ### Validation Errors Common validation errors and solutions: @@ -559,6 +514,6 @@ Common validation errors and solutions: 1. **Missing required fields**: Add `command` and `args` 2. **Invalid timeout**: Use number, not string 3. **Environment variable not found**: Check `.env` file -4. **Command not found**: Verify installation and PATH +4. **Command not found**: Verify installation and PATH */} This comprehensive guide covers all aspects of configuring MCP servers in MCPHub for various use cases and environments. diff --git a/docs/docs.json b/docs/docs.json index a763e25..380dc08 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -27,27 +27,16 @@ "pages": [ "features/server-management", "features/group-management", - "features/smart-routing", - "features/authentication", - "features/monitoring" + "features/smart-routing" ] }, { "group": "Configuration", "pages": [ "configuration/mcp-settings", - "configuration/environment-variables", "configuration/docker-setup", "configuration/nginx" ] - }, - { - "group": "Development", - "pages": [ - "development/getting-started", - "development/architecture", - "development/contributing" - ] } ] }, @@ -67,51 +56,16 @@ "pages": [ "zh/features/server-management", "zh/features/group-management", - "zh/features/smart-routing", - "zh/features/authentication", - "zh/features/monitoring" + "zh/features/smart-routing" ] }, { "group": "配置指南", "pages": [ "zh/configuration/mcp-settings", - "zh/configuration/environment-variables", "zh/configuration/docker-setup", "zh/configuration/nginx" ] - }, - { - "group": "开发指南", - "pages": [ - "zh/development/getting-started", - "zh/development/architecture", - "zh/development/contributing" - ] - } - ] - }, - { - "tab": "API Reference", - "groups": [ - { - "group": "MCP Endpoints", - "pages": [ - "api-reference/introduction", - "api-reference/mcp-http", - "api-reference/mcp-sse", - "api-reference/smart-routing" - ] - }, - { - "group": "Management API", - "pages": [ - "api-reference/servers", - "api-reference/groups", - "api-reference/auth", - "api-reference/logs", - "api-reference/config" - ] } ] } @@ -144,13 +98,13 @@ "links": [ { "label": "Demo", - "href": "http://localhost:3000" + "href": "https://demo.mcphubx.com" } ], "primary": { "type": "button", "label": "Get Started", - "href": "https://docs.hubmcp.dev/quickstart" + "href": "https://docs.mcphubx.com/quickstart" } }, "footer": { diff --git a/docs/features/group-management.mdx b/docs/features/group-management.mdx index d3e60c9..6ad0959 100644 --- a/docs/features/group-management.mdx +++ b/docs/features/group-management.mdx @@ -30,9 +30,6 @@ Groups are named collections of MCP servers that can be accessed through dedicat 3. **Fill Group Details**: - **Name**: Unique identifier for the group - - **Display Name**: Human-readable name - - **Description**: Purpose and contents of the group - - **Access Level**: Public, Private, or Restricted 4. **Add Servers**: Select servers to include in the group @@ -46,14 +43,11 @@ curl -X POST http://localhost:3000/api/groups \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{ "name": "web-automation", - "displayName": "Web Automation Tools", - "description": "Browser automation and web scraping tools", - "servers": ["playwright", "fetch"], - "accessLevel": "public" + "servers": ["playwright", "fetch"] }' ``` -### Via Configuration File +{/* ### Via Configuration File Define groups in your `mcp_settings.json`: @@ -66,20 +60,16 @@ Define groups in your `mcp_settings.json`: }, "groups": { "web-tools": { - "displayName": "Web Tools", - "description": "Web scraping and browser automation", + "name": "web", "servers": ["fetch", "playwright"], - "accessLevel": "public" }, "communication": { - "displayName": "Communication Tools", - "description": "Messaging and collaboration tools", + "name": "communication", "servers": ["slack"], - "accessLevel": "private" } } } -``` +``` */} ## Group Types and Use Cases @@ -177,7 +167,7 @@ Define groups in your `mcp_settings.json`: -## Group Access Control +{/* ## Group Access Control ### Access Levels @@ -254,7 +244,7 @@ curl -X DELETE http://localhost:3000/api/groups/web-tools/members/user123 \ # List group members curl http://localhost:3000/api/groups/web-tools/members \ -H "Authorization: Bearer YOUR_JWT_TOKEN" -``` +``` */} ## Group Endpoints @@ -346,7 +336,7 @@ Response will only include tools from `fetch` and `playwright` servers. -### Batch Server Updates +{/* ### Batch Server Updates Update multiple servers at once: @@ -357,9 +347,9 @@ curl -X PUT http://localhost:3000/api/groups/web-tools/servers \ -d '{ "servers": ["fetch", "playwright", "selenium"] }' -``` +``` */} -## Group Monitoring +{/* ## Group Monitoring ### Group Status @@ -393,9 +383,9 @@ Metrics include: - Request count by tool - Response times - Error rates -- User activity +- User activity */} -## Advanced Group Features +{/* ## Advanced Group Features ### Nested Groups @@ -474,7 +464,7 @@ Define policies for group behavior: } } } -``` +``` */} ## Best Practices @@ -494,7 +484,7 @@ Define policies for group behavior: **Use Descriptive Names**: Choose names that clearly indicate the group's purpose and contents. -### Security Considerations +{/* ### Security Considerations **Principle of Least Privilege**: Only give users access to groups they actually need. @@ -507,7 +497,7 @@ Define policies for group behavior: **Regular Access Reviews**: Periodically review group memberships and remove unnecessary access. - + */} ### Performance Optimization diff --git a/docs/features/server-management.mdx b/docs/features/server-management.mdx index c1fd98d..2ba018f 100644 --- a/docs/features/server-management.mdx +++ b/docs/features/server-management.mdx @@ -311,7 +311,7 @@ Servers can use environment variables for configuration: - `${VAR_NAME:-default}`: Uses default if variable not set - `${VAR_NAME:+value}`: Uses value if variable is set -### Working Directory +{/* ### Working Directory Set the working directory for server execution: @@ -323,7 +323,7 @@ Set the working directory for server execution: "cwd": "/path/to/server/directory" } } -``` +``` */} ### Command Variations @@ -352,7 +352,7 @@ Different ways to specify server commands: ``` - + {/* ```json { "direct-python": { @@ -373,7 +373,7 @@ Different ways to specify server commands: } } ``` - + */} ## Advanced Features @@ -382,12 +382,12 @@ Different ways to specify server commands: MCPHub supports hot reloading of server configurations: -1. **Config File Changes**: Automatically detects changes to `mcp_settings.json` -2. **Dashboard Updates**: Immediately applies changes made through the web interface -3. **API Updates**: Real-time updates via REST API calls -4. **Zero Downtime**: Graceful server restarts without affecting other servers +{/* 1. **Config File Changes**: Automatically detects changes to `mcp_settings.json` */} +1. **Dashboard Updates**: Immediately applies changes made through the web interface +2. **API Updates**: Real-time updates via REST API calls +3. **Zero Downtime**: Graceful server restarts without affecting other servers -### Resource Limits +{/* ### Resource Limits Control server resource usage: @@ -403,9 +403,9 @@ Control server resource usage: } } } -``` +``` */} -### Dependency Management +{/* ### Dependency Management Handle server dependencies: @@ -439,7 +439,7 @@ Handle server dependencies: ``` - + */} ## Troubleshooting diff --git a/docs/features/smart-routing.mdx b/docs/features/smart-routing.mdx index d7aa935..702893c 100644 --- a/docs/features/smart-routing.mdx +++ b/docs/features/smart-routing.mdx @@ -55,7 +55,7 @@ Smart Routing requires additional setup compared to basic MCPHub usage: 2. **Embedding Service**: OpenAI API or compatible service 3. **Environment Configuration**: Proper configuration variables -### Quick Setup +{/* ### Quick Setup @@ -265,7 +265,7 @@ EMBEDDING_BATCH_SIZE=100 ``` - + */} ## Using Smart Routing @@ -287,7 +287,7 @@ Access Smart Routing through the special `$smart` endpoint: -### Basic Usage +{/* ### Basic Usage Connect your AI client to the Smart Routing endpoint and make natural language requests: @@ -330,9 +330,9 @@ Response: ] } } -``` +``` */} -### Advanced Queries +{/* ### Advanced Queries Smart Routing supports various query types: @@ -405,9 +405,9 @@ Smart Routing supports various query types: }' ``` - + */} -### Tool Execution +{/* ### Tool Execution Once Smart Routing finds relevant tools, you can execute them directly: @@ -426,9 +426,9 @@ curl -X POST http://localhost:3000/mcp/$smart \ } } }' -``` +``` */} -## Performance Optimization +{/* ## Performance Optimization ### Embedding Cache @@ -585,7 +585,7 @@ curl -X POST http://localhost:3000/api/smart-routing/feedback \ "successful": true, "comments": "Perfect tool for the task" }' -``` +``` */} ## Troubleshooting diff --git a/docs/index.mdx b/docs/index.mdx index 141acc6..f5a12a9 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,10 +1,10 @@ --- -title: MCPHub Documentation +title: MCPHub description: 'The Unified Hub for Model Context Protocol (MCP) Servers' --- -Hero Light -Hero Dark +{/* Hero Light +Hero Dark */} # Welcome to MCPHub @@ -16,12 +16,12 @@ MCPHub makes it easy to manage and scale multiple MCP (Model Context Protocol) s Centrally manage multiple MCP servers with hot-swappable configuration - - AI-powered tool discovery using vector semantic search - Organize servers into logical groups for streamlined access control + + AI-powered tool discovery using vector semantic search + Monitor server status and performance from a unified dashboard diff --git a/docs/installation.mdx b/docs/installation.mdx index cae64f4..17538fa 100644 --- a/docs/installation.mdx +++ b/docs/installation.mdx @@ -72,7 +72,6 @@ Optional for Smart Routing: -p 3000:3000 \ -e PORT=3000 \ -e BASE_PATH="" \ - -e REQUEST_TIMEOUT=60000 \ samanhappy/mcphub:latest ``` @@ -144,12 +143,9 @@ Optional for Smart Routing: # Run with custom port PORT=8080 mcphub - - # Run with custom config path - MCP_SETTINGS_PATH=/path/to/mcp_settings.json mcphub ``` - #### 3. Local Installation + {/* #### 3. Local Installation You can also install MCPHub locally in a project: @@ -170,8 +166,7 @@ Optional for Smart Routing: # Run MCPHub ./start.sh - ``` - + ``` */} @@ -419,7 +414,7 @@ Smart Routing provides AI-powered tool discovery using vector semantic search. -### Environment Configuration +{/* ### Environment Configuration Set the following environment variables: @@ -435,13 +430,13 @@ EMBEDDING_MODEL=text-embedding-3-small # Optional: Enable smart routing ENABLE_SMART_ROUTING=true -``` +``` */} ## Verification After installation, verify MCPHub is working: -### 1. Health Check +{/* ### 1. Health Check ```bash curl http://localhost:3000/api/health @@ -455,9 +450,9 @@ Expected response: "version": "x.x.x", "uptime": 123 } -``` +``` */} -### 2. Dashboard Access +### Dashboard Access Open your browser and navigate to: @@ -465,7 +460,7 @@ Open your browser and navigate to: http://localhost:3000 ``` -### 3. API Test +{/* ### 3. API Test ```bash curl -X POST http://localhost:3000/mcp \ @@ -476,7 +471,7 @@ curl -X POST http://localhost:3000/mcp \ "method": "tools/list", "params": {} }' -``` +``` */} ## Troubleshooting diff --git a/docs/logo/dark.svg b/docs/logo/dark.svg index 8b343cd..fba0b6b 100644 --- a/docs/logo/dark.svg +++ b/docs/logo/dark.svg @@ -1,21 +1,27 @@ - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + MCPHub + + + + \ No newline at end of file diff --git a/docs/logo/light.svg b/docs/logo/light.svg index 03e62bf..fba0b6b 100644 --- a/docs/logo/light.svg +++ b/docs/logo/light.svg @@ -1,21 +1,27 @@ - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + MCPHub + + + + \ No newline at end of file diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index a763507..a2b0f56 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -106,12 +106,10 @@ Once your servers are configured, connect your AI clients using MCPHub endpoints Access all configured MCP servers: ``` http://localhost:3000/mcp ``` - Access servers in a specific group: ``` http://localhost:3000/mcp/{group - name} - ``` + Access servers in a specific group: ``` http://localhost:3000/mcp/{groupName} ``` - Access a single server: ``` http://localhost:3000/mcp/{server - name} - ``` + Access a single server: ``` http://localhost:3000/mcp/{serverName} ``` Use AI-powered tool discovery: ``` http://localhost:3000/mcp/$smart ``` @@ -172,7 +170,7 @@ Here are some popular MCP servers you can add: -## Verification +{/* ## Verification Test your setup by making a simple request: @@ -187,7 +185,7 @@ curl -X POST http://localhost:3000/mcp \ }' ``` -You should receive a list of available tools from your configured MCP servers. +You should receive a list of available tools from your configured MCP servers. */} ## Next Steps diff --git a/docs/zh/features/group-management.mdx b/docs/zh/features/group-management.mdx index c430b82..dab3a01 100644 --- a/docs/zh/features/group-management.mdx +++ b/docs/zh/features/group-management.mdx @@ -1,567 +1,573 @@ --- -title: '组管理' -description: '组织用户和服务器为逻辑组，实现高效的访问控制' +title: '分组管理' +description: '将服务器组织成逻辑组以简化访问控制' --- ## 概述 -MCPHub 的组管理系统允许您将用户和服务器组织成逻辑组，从而简化权限管理和访问控制。组提供了一种灵活的方式来管理大规模部署中的资源。 +MCPHub 的分组管理功能允许您根据功能、用例或访问要求将 MCP 服务器组织成逻辑集合。这使您能够对不同的 AI 客户端和用户可用的工具进行精细控制。 -## 创建组 +## 核心概念 + +### 什么是分组？ + +分组是可通过专用端点访问的 MCP 服务器的命名集合。AI 客户端可以连接到特定分组以仅访问相关工具，而不是一次性连接到所有服务器。 + +### 分组的优势 + +- **聚焦工具访问**: AI 客户端只看到与其用例相关的工具 +- **更好的性能**: 减少工具发现开销 +- **增强安全性**: 限制对敏感工具的访问 +- **改进组织**: 功能的逻辑分离 +- **简化管理**: 更容易一起管理相关服务器 + +## 创建分组 ### 通过仪表板 -1. **导航到组部分**: 在主仪表板中点击"组" -2. **点击"创建组"**: 开始组创建流程 -3. **填写组详细信息**: - - **组名**: 唯一的组标识符 - - **显示名称**: 用户友好的组名称 - - **描述**: 组的目的和范围 - - **父组**: 可选的层次结构 +1. **导航到分组部分**: 在主导航中点击"分组" +2. **点击"创建分组"**: 开始分组创建流程 +3. **填写分组详细信息**: + + - **名称**: 分组的唯一标识符 + +4. **添加服务器**: 选择要包含在分组中的服务器 ### 通过 API +以编程方式创建分组： + ```bash curl -X POST http://localhost:3000/api/groups \ -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{ - "name": "development-team", - "displayName": "开发团队", - "description": "前端和后端开发人员", - "parentGroup": null, - "settings": { - "autoAssign": false, - "maxMembers": 50, - "requireApproval": true - } + "name": "web-automation", + "servers": ["playwright", "fetch"] }' ``` -### 通过配置文件 +{/* ### 通过配置文件 -在 `groups.json` 中定义组： +在您的 `mcp_settings.json` 中定义分组： ```json { + "mcpServers": { + "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }, + "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }, + "slack": { "command": "npx", "args": ["@modelcontextprotocol/server-slack"] } + }, "groups": { - "dev-team": { - "displayName": "开发团队", - "description": "应用程序开发人员", - "permissions": { - "servers": ["read", "write", "execute"], - "tools": ["read", "execute"], - "logs": ["read"] - }, + "web-tools": { + "name": "web", + "servers": ["fetch", "playwright"], + }, + "communication": { + "name": "communication", + "servers": ["slack"], + } + } +} +``` */} + +## 分组类型和用例 + + + + **用途**: 浏览器自动化和网页抓取 + + **服务器**: + - `playwright`: 浏览器自动化 + - `fetch`: HTTP 请求和网页抓取 + - `selenium`: 替代浏览器自动化 + + **用例**: + - 自动化测试 + - 数据收集 + - 网页监控 + - 内容分析 + + **端点**: `http://localhost:3000/mcp/web-automation` + + + + + **用途**: 数据操作和分析 + + **服务器**: + - `sqlite`: 数据库操作 + - `filesystem`: 文件操作 + - `spreadsheet`: Excel/CSV 处理 + + **用例**: + - 数据分析 + - 报告生成 + - 文件处理 + - 数据库查询 + + **端点**: `http://localhost:3000/mcp/data-processing` + + + + + **用途**: 消息传递和协作 + + **服务器**: + - `slack`: Slack 集成 + - `discord`: Discord 机器人 + - `email`: 邮件发送 + - `sms`: 短信通知 + + **用例**: + - 团队通知 + - 客户沟通 + - 警报系统 + - 社交媒体管理 + + **端点**: `http://localhost:3000/mcp/communication` + + + + + **用途**: 软件开发工具 + + **服务器**: + - `github`: GitHub 操作 + - `gitlab`: GitLab 集成 + - `docker`: 容器管理 + - `kubernetes`: K8s 操作 + + **用例**: + - 代码部署 + - 仓库管理 + - CI/CD 操作 + - 基础设施管理 + + **端点**: `http://localhost:3000/mcp/development` + + + + + **用途**: 机器学习和 AI 工具 + + **服务器**: + - `openai`: OpenAI API 集成 + - `huggingface`: Hugging Face 模型 + - `vector-db`: 向量数据库操作 + + **用例**: + - 模型推理 + - 数据嵌入 + - 自然语言处理 + - 计算机视觉 + + **端点**: `http://localhost:3000/mcp/ai-ml` + + + + +{/* ## 分组访问控制 + +### 访问级别 + + + + **公开分组**: + - 所有认证用户都可访问 + - 无需额外权限 + - 在分组列表中可见 + - 默认访问级别 + + ```json + { + "name": "public-tools", + "accessLevel": "public", + "servers": ["fetch", "calculator"] + } + ``` + + + + + **私有分组**: + - 仅对分组成员可见 + - 需要明确的用户分配 + - 在公开列表中隐藏 + - 管理员控制成员身份 + + ```json + { + "name": "internal-tools", + "accessLevel": "private", "members": ["user1", "user2"], - "servers": ["dev-server-1", "dev-server-2"] - }, - "qa-team": { - "displayName": "质量保证团队", - "description": "测试和质量保证", - "permissions": { - "servers": ["read", "execute"], - "tools": ["read", "execute"], - "logs": ["read"] - }, - "members": ["qa1", "qa2"], - "servers": ["test-server", "staging-server"] + "servers": ["internal-api", "database"] } - } -} + ``` + + + + + **受限分组**: + - 基于角色的访问控制 + - 需要特定权限 + - 启用审计日志 + - 限时访问 + + ```json + { + "name": "admin-tools", + "accessLevel": "restricted", + "requiredRoles": ["admin", "operator"], + "servers": ["system-control", "user-management"] + } + ``` + + + + +### 用户管理 + +将用户分配给分组： + +```bash +# 添加用户到分组 +curl -X POST http://localhost:3000/api/groups/web-tools/members \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -d '{"userId": "user123"}' + +# 从分组中移除用户 +curl -X DELETE http://localhost:3000/api/groups/web-tools/members/user123 \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" + +# 列出分组成员 +curl http://localhost:3000/api/groups/web-tools/members \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` */} + +## 分组端点 + +### 访问分组 + +每个分组都有自己的 MCP 端点： + + + + ``` + http://localhost:3000/mcp/{group-name} + ``` + + 示例： + - `http://localhost:3000/mcp/web-tools` + - `http://localhost:3000/mcp/data-processing` + - `http://localhost:3000/mcp/communication` + + + + + ``` + http://localhost:3000/sse/{group-name} + ``` + + 示例： + - `http://localhost:3000/sse/web-tools` + - `http://localhost:3000/sse/data-processing` + - `http://localhost:3000/sse/communication` + + + + +### 分组工具发现 + +当连接到分组端点时，AI 客户端将只看到该分组内服务器的工具： + +```bash +# 列出 web-tools 分组中的工具 +curl -X POST http://localhost:3000/mcp/web-tools \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/list", + "params": {} + }' ``` -## 组层次结构 +响应将只包含来自 `fetch` 和 `playwright` 服务器的工具。 -### 嵌套组 +## 动态分组管理 -创建组层次结构以实现更好的组织： +### 向分组添加服务器 + + + + 1. 在仪表板中导航到分组 + 2. 点击"管理服务器" + 3. 选择要添加的其他服务器 + 4. 点击"保存更改" + + + + ```bash + curl -X POST http://localhost:3000/api/groups/web-tools/servers \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -d '{"serverId": "new-server"}' + ``` + + + +### 从分组中移除服务器 + + + + 1. 在仪表板中导航到分组 + 2. 点击"管理服务器" + 3. 取消选择要移除的服务器 + 4. 点击"保存更改" + + + + ```bash + curl -X DELETE http://localhost:3000/api/groups/web-tools/servers/server-name \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" + ``` + + + +{/* ### 批量服务器更新 + +一次更新多个服务器： + +```bash +curl -X PUT http://localhost:3000/api/groups/web-tools/servers \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -d '{ + "servers": ["fetch", "playwright", "selenium"] + }' +``` */} + +{/* ## 分组监控 + +### 分组状态 + +监控分组健康状况和活动： + +```bash +# 获取分组状态 +curl http://localhost:3000/api/groups/web-tools/status \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +响应包括： + +- 活跃服务器数量 +- 工具数量 +- 活跃连接 +- 最近活动 + +### 分组分析 + +跟踪分组使用情况： + +```bash +# 获取分组分析 +curl http://localhost:3000/api/groups/web-tools/analytics \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +指标包括： + +- 按工具分类的请求计数 +- 响应时间 +- 错误率 +- 用户活动 */} + +{/* ## 高级分组功能 + +### 嵌套分组 + +创建层次化分组结构： ```json { "groups": { - "engineering": { - "displayName": "工程部", - "description": "所有工程团队", - "children": ["frontend", "backend", "devops"] + "development": { + "displayName": "开发工具", + "subGroups": ["frontend-dev", "backend-dev", "devops"] }, - "frontend": { - "displayName": "前端团队", - "parent": "engineering", - "servers": ["frontend-dev", "frontend-staging"] + "frontend-dev": { + "displayName": "前端开发", + "servers": ["playwright", "webpack-server"], + "parent": "development" }, - "backend": { - "displayName": "后端团队", - "parent": "engineering", - "servers": ["api-server", "database-server"] - }, - "devops": { - "displayName": "运维团队", - "parent": "engineering", - "servers": ["monitoring", "deployment"] + "backend-dev": { + "displayName": "后端开发", + "servers": ["database", "api-server"], + "parent": "development" } } } ``` -### 继承权限 +### 分组模板 -子组从父组继承权限： +使用模板快速创建分组： -```bash -# 检查继承的权限 -curl -X GET http://localhost:3000/api/groups/frontend/permissions?inherited=true \ - -H "Authorization: Bearer $TOKEN" +```json +{ + "groupTemplates": { + "web-project": { + "description": "标准 Web 项目工具集", + "servers": ["fetch", "playwright", "filesystem"], + "accessLevel": "public" + }, + "data-science": { + "description": "数据科学和 ML 工具", + "servers": ["python-tools", "jupyter", "vector-db"], + "accessLevel": "private" + } + } +} ``` -## 用户管理 - -### 添加用户到组 +应用模板： ```bash -# 添加单个用户 -curl -X POST http://localhost:3000/api/groups/dev-team/members \ +curl -X POST http://localhost:3000/api/groups/from-template \ -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{ - "userId": "user123", - "role": "member" - }' - -# 批量添加用户 -curl -X POST http://localhost:3000/api/groups/dev-team/members/bulk \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "users": [ - {"userId": "user1", "role": "member"}, - {"userId": "user2", "role": "admin"}, - {"userId": "user3", "role": "member"} - ] + "name": "my-web-project", + "template": "web-project", + "displayName": "我的 Web 项目工具" }' ``` -### 用户角色 +### 分组策略 -每个组内支持不同的用户角色： +定义分组行为策略： -- **组管理员**: 完整的组管理权限 -- **成员**: 标准组访问权限 -- **查看者**: 只读访问权限 -- **访客**: 有限的临时访问权限 - -### 移除用户 - -```bash -# 从组中移除用户 -curl -X DELETE http://localhost:3000/api/groups/dev-team/members/user123 \ - -H "Authorization: Bearer $TOKEN" -``` - -## 服务器分配 - -### 分配服务器到组 - -```bash -# 分配单个服务器 -curl -X POST http://localhost:3000/api/groups/dev-team/servers \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "serverId": "my-server", - "permissions": ["read", "write", "execute"] - }' - -# 批量分配服务器 -curl -X POST http://localhost:3000/api/groups/dev-team/servers/bulk \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "servers": [ - { - "serverId": "server1", - "permissions": ["read", "write"] +```json +{ + "groupPolicies": { + "web-tools": { + "maxConcurrentConnections": 10, + "requestTimeout": 30000, + "rateLimiting": { + "requestsPerMinute": 100, + "burstLimit": 20 }, - { - "serverId": "server2", - "permissions": ["read", "execute"] - } - ] - }' -``` - -### 服务器权限级别 - -为每个组-服务器对定义细粒度权限： - -```json -{ - "serverId": "my-server", - "permissions": { - "execute": { - "allowed": true, - "tools": ["filesystem", "web-search"], - "restrictions": { - "maxRequests": 100, - "timeWindow": "1h" - } - }, - "configure": { - "allowed": false - }, - "logs": { - "allowed": true, - "level": ["info", "warn", "error"] + "allowedOrigins": ["localhost", "myapp.com"] } } } -``` - -## 权限管理 - -### 组权限模型 - -```json -{ - "groupId": "dev-team", - "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": 50 - } - }, - "monitoring": { - "viewLogs": true, - "viewMetrics": true, - "exportData": false - }, - "administration": { - "manageUsers": false, - "manageServers": true, - "manageGroups": false - } - } -} -``` - -### 动态权限 - -基于条件的动态权限： - -```json -{ - "permissions": { - "servers": { - "execute": { - "condition": "time.hour >= 9 && time.hour <= 17", - "message": "服务器执行仅在工作时间内允许" - } - }, - "tools": { - "filesystem": { - "write": { - "condition": "user.role === 'admin' || group.name === 'senior-devs'", - "message": "写入权限需要管理员或高级开发者角色" - } - } - } - } -} -``` - -## 配额管理 - -### 设置组配额 - -```bash -curl -X PUT http://localhost:3000/api/groups/dev-team/quotas \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "requests": { - "daily": 1000, - "monthly": 30000 - }, - "storage": { - "maxSize": "10GB", - "retention": "30d" - }, - "compute": { - "maxConcurrentRequests": 10, - "maxExecutionTime": "5m" - } - }' -``` - -### 监控配额使用 - -```bash -# 获取当前配额使用情况 -curl -X GET http://localhost:3000/api/groups/dev-team/quotas/usage \ - -H "Authorization: Bearer $TOKEN" -``` - -响应示例： - -```json -{ - "groupId": "dev-team", - "period": "2024-01-01T00:00:00Z", - "usage": { - "requests": { - "used": 750, - "limit": 1000, - "remaining": 250 - }, - "storage": { - "used": "7.2GB", - "limit": "10GB", - "remaining": "2.8GB" - }, - "compute": { - "currentConcurrent": 3, - "maxConcurrent": 10, - "avgExecutionTime": "2m 15s" - } - } -} -``` - -## 组策略 - -### 定义组策略 - -```json -{ - "groupId": "dev-team", - "policies": { - "security": { - "requireMFA": false, - "sessionTimeout": "8h", - "ipWhitelist": ["192.168.1.0/24", "10.0.0.0/8"] - }, - "usage": { - "allowWeekendAccess": true, - "restrictHolidays": false, - "maxSessionDuration": "12h" - }, - "data": { - "encryptionRequired": true, - "dataRetention": "90d", - "exportAllowed": false - } - } -} -``` - -### 策略继承 - -```bash -# 应用策略模板 -curl -X POST http://localhost:3000/api/groups/dev-team/policies/apply \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "template": "development-team-template", - "overrides": { - "security.sessionTimeout": "4h" - } - }' -``` - -## 自动化组管理 - -### 自动用户分配 - -基于属性自动分配用户： - -```json -{ - "autoAssignment": { - "enabled": true, - "rules": [ - { - "condition": "user.department === '开发'", - "action": { - "addToGroup": "dev-team", - "role": "member" - } - }, - { - "condition": "user.title.includes('高级')", - "action": { - "addToGroup": "senior-devs", - "role": "admin" - } - } - ] - } -} -``` - -### 定时任务 - -```bash -# 创建定时清理任务 -curl -X POST http://localhost:3000/api/groups/dev-team/jobs \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "name": "cleanup-inactive-users", - "schedule": "0 2 * * *", - "action": "removeInactiveUsers", - "params": { - "inactiveDays": 30 - } - }' -``` - -## 组通知 - -### 配置通知 - -```json -{ - "groupId": "dev-team", - "notifications": { - "channels": { - "email": { - "enabled": true, - "recipients": ["team-lead@company.com"] - }, - "slack": { - "enabled": true, - "webhook": "https://hooks.slack.com/...", - "channel": "#dev-team" - } - }, - "events": ["userJoined", "userLeft", "serverAdded", "quotaExceeded", "securityAlert"] - } -} -``` - -### 发送组通知 - -```bash -curl -X POST http://localhost:3000/api/groups/dev-team/notifications \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "type": "announcement", - "title": "维护通知", - "message": "服务器将在今晚 10 点进行维护", - "priority": "high", - "channels": ["email", "slack"] - }' -``` - -## 组分析 - -### 使用统计 - -```bash -# 获取组使用统计 -curl -X GET http://localhost:3000/api/groups/dev-team/analytics \ - -H "Authorization: Bearer $TOKEN" -``` - -响应示例： - -```json -{ - "groupId": "dev-team", - "period": "30d", - "stats": { - "activeUsers": 12, - "totalRequests": 15750, - "avgResponseTime": "250ms", - "errorRate": "0.5%", - "mostUsedTools": [ - { "name": "filesystem", "usage": 8500 }, - { "name": "web-search", "usage": 4200 }, - { "name": "database", "usage": 3050 } - ], - "peakUsageHours": [9, 10, 14, 15, 16] - } -} -``` - -### 生成报告 - -```bash -# 生成月度报告 -curl -X POST http://localhost:3000/api/groups/dev-team/reports \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "type": "monthly", - "format": "pdf", - "includeDetails": true, - "recipients": ["manager@company.com"] - }' -``` - -## 故障排除 - -### 常见问题 - -1. **用户无法访问组资源** - - ```bash - # 检查用户组成员身份 - curl -X GET http://localhost:3000/api/users/user123/groups \ - -H "Authorization: Bearer $TOKEN" - ``` - -2. **权限配置错误** - - ```bash - # 验证权限设置 - curl -X GET http://localhost:3000/api/groups/dev-team/permissions/validate \ - -H "Authorization: Bearer $TOKEN" - ``` - -3. **配额超限** - ```bash - # 检查配额状态 - curl -X GET http://localhost:3000/api/groups/dev-team/quotas/status \ - -H "Authorization: Bearer $TOKEN" - ``` - -### 调试组权限 - -启用权限调试： - -```bash -# 调试用户权限 -curl -X GET http://localhost:3000/api/debug/permissions \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "userId": "user123", - "resource": "server:my-server", - "action": "execute" - }' -``` +``` */} ## 最佳实践 -1. **组织结构**: 使用层次化组结构镜像您的组织架构 -2. **权限最小化**: 只授予执行任务所需的最小权限 -3. **定期审核**: 定期审核组成员身份和权限 -4. **自动化**: 使用自动化规则减少手动管理开销 -5. **监控**: 设置监控和警报以跟踪组活动 +### 分组组织 -有关更多信息，请参阅 [身份认证与安全](/zh/features/authentication) 和 [监控](/zh/features/monitoring) 文档。 + + **按用例组织**: 根据用户想要完成的任务来组织服务器分组，而不仅仅是技术相似性。 + + + + **保持分组聚焦**: 避免创建包含太多不同工具的分组。更小、更聚焦的分组更有用。 + + + + **使用描述性名称**: 选择能清楚表明分组目的和内容的名称。 + + +{/* ### 安全考虑 + + + **最小权限原则**: 只给用户访问他们实际需要的分组。 + + + + **敏感工具隔离**: 将敏感工具保存在具有适当访问控制的受限分组中。 + + + + **定期访问审查**: 定期审查分组成员身份并移除不必要的访问权限。 + */} + +### 性能优化 + + + **平衡分组大小**: 非常大的分组可能导致工具发现较慢。考虑拆分为更小的分组。 + + + + **监控使用情况**: 使用分析来识别哪些分组被大量使用并相应优化。 + + +## 故障排除 + + + + **检查：** + - 用户具有适当权限 + - 分组存在且处于活跃状态 + - 分组中的服务器正在运行 + - 网络连接 + + **解决方案：** + 1. 验证用户分组成员身份 + 2. 检查分组配置 + 3. 测试单个服务器连接 + 4. 查看访问日志 + + + + + **可能原因：** + - 服务器未正确添加到分组 + - 服务器未运行 + - 工具发现失败 + - 缓存问题 + + **调试步骤：** + 1. 验证服务器在分组配置中 + 2. 检查服务器状态 + 3. 强制刷新工具发现 + 4. 清除分组缓存 + + + + + **常见问题：** + - 分组中服务器过多 + - 服务器响应慢 + - 网络延迟 + - 资源约束 + + **优化方案：** + 1. 拆分大型分组 + 2. 监控服务器性能 + 3. 实施请求缓存 + 4. 使用连接池 + + + + +## 下一步 + + + + 跨分组的 AI 驱动工具发现 + + + 用户管理和访问控制 + + + 完整的分组管理 API + + + 高级分组配置选项 + + diff --git a/docs/zh/features/server-management.mdx b/docs/zh/features/server-management.mdx index 31ae1d8..2c22bb6 100644 --- a/docs/zh/features/server-management.mdx +++ b/docs/zh/features/server-management.mdx @@ -49,448 +49,369 @@ curl -X POST http://localhost:3000/api/servers \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{ - "name": "my-server", - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"], - "env": { - "NODE_ENV": "production" - }, - "cwd": "/app" + "name": "fetch-server", + "command": "uvx", + "args": ["mcp-server-fetch"], + "env": {} }' ``` -## 服务器配置 +## 流行的 MCP 服务器示例 -### 通用配置选项 + + + 提供网页抓取和 HTTP 请求功能： -```json -{ - "name": "filesystem-server", - "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 -} -``` + ```json + { + "fetch": { + "command": "uvx", + "args": ["mcp-server-fetch"] + } + } + ``` -### Python 服务器示例 + **可用工具:** + - `fetch`: 发起 HTTP 请求 + - `fetch_html`: 抓取网页 + - `fetch_json`: 从 API 获取 JSON 数据 -```json -{ - "name": "python-server", - "command": "python", - "args": ["-m", "mcp_server", "--config", "config.json"], - "env": { - "PYTHONPATH": "/app/python", - "API_KEY": "${API_KEY}", - "LOG_LEVEL": "INFO" - }, - "cwd": "/app/python-server" -} -``` + -### Node.js 服务器示例 + + 用于网页交互的浏览器自动化： -```json -{ - "name": "node-server", - "command": "node", - "args": ["server.js", "--port", "3001"], - "env": { - "NODE_ENV": "production", - "PORT": "3001", - "DATABASE_URL": "${DATABASE_URL}" - }, - "cwd": "/app/node-server" -} -``` + ```json + { + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest", "--headless"] + } + } + ``` + + **可用工具:** + - `playwright_navigate`: 导航到网页 + - `playwright_screenshot`: 截取屏幕截图 + - `playwright_click`: 点击元素 + - `playwright_fill`: 填写表单 + + + + + 文件和目录管理： + + ```json + { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"] + } + } + ``` + + **可用工具:** + - `read_file`: 读取文件内容 + - `write_file`: 写入文件 + - `create_directory`: 创建目录 + - `list_directory`: 列出目录内容 + + + + + 数据库操作： + + ```json + { + "sqlite": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"] + } + } + ``` + + **可用工具:** + - `execute_query`: 执行 SQL 查询 + - `describe_tables`: 获取表结构 + - `create_table`: 创建新表 + + + + + Slack 工作空间集成： + + ```json + { + "slack": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-slack"], + "env": { + "SLACK_BOT_TOKEN": "xoxb-your-bot-token", + "SLACK_TEAM_ID": "T1234567890" + } + } + } + ``` + + **可用工具:** + - `send_slack_message`: 发送消息到频道 + - `list_slack_channels`: 列出可用频道 + - `get_slack_thread`: 获取线程消息 + + + + + GitHub 仓库操作： + + ```json + { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token" + } + } + } + ``` + + **可用工具:** + - `create_or_update_file`: 创建/更新仓库文件 + - `search_repositories`: 搜索 GitHub 仓库 + - `create_issue`: 创建问题 + - `create_pull_request`: 创建拉取请求 + + + + + Google Drive 文件操作： + + ```json + { + "gdrive": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-gdrive"], + "env": { + "GDRIVE_CLIENT_ID": "your-client-id", + "GDRIVE_CLIENT_SECRET": "your-client-secret", + "GDRIVE_REDIRECT_URI": "your-redirect-uri" + } + } + } + ``` + + **可用工具:** + - `gdrive_search`: 搜索文件和文件夹 + - `gdrive_read`: 读取文件内容 + - `gdrive_create`: 创建新文件 + + + + + 中国地图和位置服务： + + ```json + { + "amap": { + "command": "npx", + "args": ["-y", "@amap/amap-maps-mcp-server"], + "env": { + "AMAP_MAPS_API_KEY": "your-api-key" + } + } + } + ``` + + **可用工具:** + - `search_location`: 搜索位置 + - `get_directions`: 获取路线指引 + - `reverse_geocode`: 将坐标转换为地址 + + + ## 服务器生命周期管理 ### 启动服务器 -```bash -# 启动特定服务器 -curl -X POST http://localhost:3000/api/servers/my-server/start \ - -H "Authorization: Bearer $TOKEN" +服务器会在以下情况下自动启动： -# 启动所有服务器 -curl -X POST http://localhost:3000/api/servers/start-all \ - -H "Authorization: Bearer $TOKEN" -``` +- MCPHub 启动时 +- 通过仪表板或 API 添加服务器时 +- 服务器配置更新时 +- 手动重启已停止的服务器时 ### 停止服务器 -```bash -# 停止特定服务器 -curl -X POST http://localhost:3000/api/servers/my-server/stop \ - -H "Authorization: Bearer $TOKEN" +您可以通过以下方式停止服务器： -# 优雅停止（等待当前请求完成） -curl -X POST http://localhost:3000/api/servers/my-server/stop \ - -H "Authorization: Bearer $TOKEN" \ - -d '{"graceful": true, "timeout": 30000}' -``` +- **通过仪表板**: 切换服务器状态开关 +- **通过 API**: 发送 POST 请求到 `/api/servers/{name}/toggle` +- **自动停止**: 服务器崩溃或遇到错误时会自动停止 ### 重启服务器 -```bash -# 重启服务器 -curl -X POST http://localhost:3000/api/servers/my-server/restart \ - -H "Authorization: Bearer $TOKEN" -``` +服务器会在以下情况下自动重启： -## 热配置重载 - -### 更新服务器配置 - -无需重启即可更新配置： - -```bash -curl -X PUT http://localhost:3000/api/servers/my-server/config \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "env": { - "DEBUG": "mcp:verbose", - "NEW_SETTING": "value" - }, - "args": ["--verbose", "--new-flag"] - }' -``` - -### 批量配置更新 - -```bash -curl -X PUT http://localhost:3000/api/servers/bulk-update \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "servers": ["server1", "server2"], - "config": { - "env": { - "LOG_LEVEL": "DEBUG" - } - } - }' -``` +- 配置更改时 +- 环境变量更新后 +- 通过仪表板或 API 手动触发时 ## 服务器状态监控 -### 检查服务器状态 +### 状态指示器 -```bash -# 获取所有服务器状态 -curl -X GET http://localhost:3000/api/servers/status \ - -H "Authorization: Bearer $TOKEN" +每个服务器都显示状态指示器： -# 获取特定服务器状态 -curl -X GET http://localhost:3000/api/servers/my-server/status \ - -H "Authorization: Bearer $TOKEN" -``` +- 🟢 **运行中**: 服务器处于活动状态并响应 +- 🟡 **启动中**: 服务器正在初始化 +- 🔴 **已停止**: 服务器未运行 +- ⚠️ **错误**: 服务器遇到错误 -响应示例： +### 实时日志 -```json -{ - "name": "my-server", - "status": "running", - "pid": 12345, - "uptime": 3600000, - "memory": { - "rss": 123456789, - "heapTotal": 98765432, - "heapUsed": 87654321 - }, - "cpu": { - "user": 1000000, - "system": 500000 - }, - "lastRestart": "2024-01-01T12:00:00.000Z" -} -``` +实时查看服务器日志： + +1. **仪表板日志**: 点击服务器查看其日志 +2. **API 日志**: 通过 `/api/logs` 端点访问日志 +3. **流式日志**: 通过 WebSocket 订阅日志流 ### 健康检查 -配置自动健康检查： +MCPHub 自动执行健康检查： + +- **初始化检查**: 验证服务器成功启动 +- **工具发现**: 确认检测到可用工具 +- **响应检查**: 测试服务器响应性 +- **资源监控**: 跟踪 CPU 和内存使用情况 + +## 配置管理 + +### 环境变量 + +服务器可以使用环境变量进行配置： ```json { - "name": "my-server", - "command": "node", - "args": ["server.js"], - "healthCheck": { - "enabled": true, - "interval": 30000, - "timeout": 5000, - "retries": 3, - "endpoint": "/health", - "expectedStatus": 200 - } -} -``` - -## 负载均衡 - -### 配置多实例 - -```json -{ - "name": "load-balanced-server", - "instances": 3, - "command": "node", - "args": ["server.js"], - "loadBalancer": { - "strategy": "round-robin", - "healthCheck": true, - "stickySession": false - }, - "env": { - "PORT": "${PORT}" - } -} -``` - -### 负载均衡策略 - -- **round-robin**: 轮询分发请求 -- **least-connections**: 分发到连接数最少的实例 -- **weighted**: 基于权重分发 -- **ip-hash**: 基于客户端 IP 的一致性哈希 - -## 资源限制 - -### 设置资源限制 - -```json -{ - "name": "resource-limited-server", - "command": "python", - "args": ["server.py"], - "resources": { - "memory": { - "limit": "512MB", - "warning": "400MB" - }, - "cpu": { - "limit": "50%", - "priority": "normal" - }, - "processes": { - "max": 10 + "server-name": { + "command": "python", + "args": ["server.py"], + "env": { + "API_KEY": "${YOUR_API_KEY}", + "DEBUG": "true", + "MAX_CONNECTIONS": "10" } } } ``` -### 监控资源使用 +**环境变量展开:** -```bash -# 获取资源使用统计 -curl -X GET http://localhost:3000/api/servers/my-server/resources \ - -H "Authorization: Bearer $TOKEN" -``` +- `${VAR_NAME}`: 展开为环境变量值 +- `${VAR_NAME:-default}`: 如果变量未设置则使用默认值 +- `${VAR_NAME:+value}`: 如果变量已设置则使用指定值 -## 日志管理 +### 命令变体 -### 配置日志记录 +指定服务器命令的不同方式： -```json -{ - "name": "my-server", - "command": "node", - "args": ["server.js"], - "logging": { - "level": "info", - "file": "/var/log/mcphub/my-server.log", - "maxSize": "100MB", - "maxFiles": 5, - "rotate": true, - "format": "json" - } -} -``` - -### 查看日志 - -```bash -# 获取实时日志 -curl -X GET http://localhost:3000/api/servers/my-server/logs \ - -H "Authorization: Bearer $TOKEN" - -# 获取带过滤器的日志 -curl -X GET "http://localhost:3000/api/servers/my-server/logs?level=error&limit=100" \ - -H "Authorization: Bearer $TOKEN" -``` - -## 环境变量管理 - -### 动态环境变量 - -```json -{ - "name": "dynamic-server", - "command": "python", - "args": ["server.py"], - "env": { - "API_KEY": "${secrets:api_key}", - "DATABASE_URL": "${vault:db_url}", - "CURRENT_TIME": "${time:iso}", - "SERVER_ID": "${server:id}", - "HOSTNAME": "${system:hostname}" - } -} -``` - -### 环境变量模板 - -支持的模板变量： - -- `${secrets:key}`: 从密钥存储获取 -- `${vault:path}`: 从 Vault 获取 -- `${env:VAR}`: 从系统环境变量获取 -- `${time:format}`: 当前时间戳 -- `${server:property}`: 服务器属性 -- `${system:property}`: 系统属性 - -## 服务发现 - -### 自动服务发现 - -```json -{ - "serviceDiscovery": { - "enabled": true, - "provider": "consul", - "config": { - "host": "localhost", - "port": 8500, - "serviceName": "mcp-server", - "tags": ["mcp", "ai", "api"] - } - } -} -``` - -### 注册服务 - -```bash -# 手动注册服务 -curl -X POST http://localhost:3000/api/servers/my-server/register \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "service": { - "name": "my-mcp-service", - "tags": ["mcp", "production"], - "port": 3001, - "check": { - "http": "http://localhost:3001/health", - "interval": "30s" + + + ```json + { + "npm-server": { + "command": "npx", + "args": ["-y", "package-name", "--option", "value"] } } - }' -``` + ``` + + + + ```json + { + "python-server": { + "command": "uvx", + "args": ["package-name", "--config", "config.json"] + } + } + ``` + + + +## 高级功能 + +### 热重载 + +MCPHub 支持服务器配置的热重载： + +1. **仪表板更新**: 立即应用通过 Web 界面进行的更改 +2. **API 更新**: 通过 REST API 调用进行实时更新 +3. **零停机时间**: 优雅的服务器重启，不影响其他服务器 ## 故障排除 -### 常见问题 + + + **检查以下项目:** + - 命令在 PATH 中可用 + - 已设置所有必需的环境变量 + - 工作目录存在且可访问 + - 网络端口未被阻塞 + - 依赖项已安装 -1. **服务器启动失败** + **调试步骤:** + 1. 在仪表板中检查服务器日志 + 2. 在终端中手动测试命令 + 3. 验证环境变量展开 + 4. 检查文件权限 - ```bash - # 检查服务器日志 - curl -X GET http://localhost:3000/api/servers/my-server/logs?level=error \ - -H "Authorization: Bearer $TOKEN" - ``` + -2. **配置无效** + + **常见原因:** + - 无效的配置参数 + - 缺少 API 密钥或凭据 + - 超出资源限制 + - 依赖项冲突 - ```bash - # 验证配置 - curl -X POST http://localhost:3000/api/servers/validate \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d @server-config.json - ``` + **解决方案:** + 1. 查看服务器日志中的错误消息 + 2. 使用最小配置进行测试 + 3. 验证所有凭据和 API 密钥 + 4. 检查系统资源可用性 -3. **性能问题** - ```bash - # 获取性能指标 - curl -X GET http://localhost:3000/api/servers/my-server/metrics \ - -H "Authorization: Bearer $TOKEN" - ``` + -### 调试模式 + + **可能的问题:** + - 服务器未完全初始化 + - 工具发现超时 + - 通信协议不匹配 + - 服务器报告错误 -启用详细调试： + **调试步骤:** + 1. 等待服务器初始化完成 + 2. 检查服务器日志中的工具注册消息 + 3. 测试与服务器的直接通信 + 4. 验证 MCP 协议兼容性 -```json -{ - "name": "debug-server", - "command": "node", - "args": ["--inspect=0.0.0.0:9229", "server.js"], - "env": { - "DEBUG": "*", - "LOG_LEVEL": "debug", - "NODE_ENV": "development" - }, - "debugging": { - "enabled": true, - "port": 9229, - "breakOnStart": false - } -} -``` + + -## 高级配置 +## 下一步 -### 自定义钩子 - -```json -{ - "name": "hooked-server", - "command": "node", - "args": ["server.js"], - "hooks": { - "beforeStart": ["./scripts/setup.sh"], - "afterStart": ["./scripts/notify.sh"], - "beforeStop": ["./scripts/cleanup.sh"], - "onError": ["./scripts/alert.sh"] - } -} -``` - -### 配置模板 - -```json -{ - "templates": { - "python-server": { - "command": "python", - "args": ["-m", "mcp_server"], - "env": { - "PYTHONPATH": "/app/python", - "LOG_LEVEL": "INFO" - } - } - }, - "servers": { - "my-python-server": { - "extends": "python-server", - "args": ["-m", "mcp_server", "--config", "custom.json"], - "env": { - "API_KEY": "custom-key" - } - } - } -} -``` - -有关更多配置选项，请参阅 [MCP 设置配置](/zh/configuration/mcp-settings) 和 [环境变量](/zh/configuration/environment-variables) 文档。 + + + 将服务器组织成逻辑分组 + + + 设置 AI 驱动的工具发现 + + + 服务器管理 API 文档 + + + 详细配置选项 + + diff --git a/docs/zh/features/smart-routing.mdx b/docs/zh/features/smart-routing.mdx index e3c8c47..1758fd1 100644 --- a/docs/zh/features/smart-routing.mdx +++ b/docs/zh/features/smart-routing.mdx @@ -1,691 +1,367 @@ --- title: '智能路由' -description: '自动负载均衡和请求路由到最佳的 MCP 服务器实例' +description: '使用向量语义搜索的 AI 工具发现系统' --- ## 概述 -MCPHub 的智能路由系统自动将传入请求路由到最适合的 MCP 服务器实例。系统考虑服务器负载、响应时间、功能可用性和业务规则来做出路由决策。 +智能路由是 MCPHub 的智能工具发现系统，它使用向量语义搜索来自动找到与任何给定任务最相关的工具。AI 客户端无需手动指定使用哪些工具，只需描述他们想要完成的任务，智能路由就会识别并提供对最合适工具的访问。 -## 路由策略 +## 智能路由的工作原理 -### 轮询路由 +### 1. 工具索引 -最简单的路由策略，按顺序分发请求： +当服务器启动时，智能路由会自动： -```json -{ - "routing": { - "strategy": "round-robin", - "targets": [ - { - "serverId": "server-1", - "weight": 1, - "enabled": true - }, - { - "serverId": "server-2", - "weight": 1, - "enabled": true - }, - { - "serverId": "server-3", - "weight": 1, - "enabled": true - } - ] - } -} -``` +- 从 MCP 服务器发现所有可用工具 +- 提取工具元数据（名称、描述、参数） +- 将工具信息转换为向量嵌入 +- 使用 pgvector 将嵌入存储在 PostgreSQL 中 -### 加权轮询 +### 2. 语义搜索 -基于服务器容量分配不同权重： +当进行查询时： -```json -{ - "routing": { - "strategy": "weighted-round-robin", - "targets": [ - { - "serverId": "high-performance-server", - "weight": 3, - "specs": { - "cpu": "8 cores", - "memory": "32GB" - } - }, - { - "serverId": "standard-server-1", - "weight": 2, - "specs": { - "cpu": "4 cores", - "memory": "16GB" - } - }, - { - "serverId": "standard-server-2", - "weight": 1, - "specs": { - "cpu": "2 cores", - "memory": "8GB" - } - } - ] - } -} -``` +- 用户查询被转换为向量嵌入 +- 相似性搜索使用余弦相似度找到匹配的工具 +- 动态阈值过滤掉不相关的结果 +- 结果按相关性得分排序 -### 最少连接数 +### 3. 智能过滤 -将请求路由到当前连接数最少的服务器： +智能路由应用多个过滤器： -```json -{ - "routing": { - "strategy": "least-connections", - "balancingMode": "dynamic", - "healthCheck": { - "enabled": true, - "interval": 10000 - } - } -} -``` +- **相关性阈值**：只返回高于相似性阈值的工具 +- **上下文感知**：考虑对话上下文 +- **工具可用性**：确保工具当前可访问 +- **权限过滤**：尊重用户访问权限 -### 基于响应时间 +### 4. 工具执行 -路由到响应时间最短的服务器： +找到的工具可以直接执行： -```json -{ - "routing": { - "strategy": "fastest-response", - "metrics": { - "measurementWindow": "5m", - "sampleSize": 100, - "excludeSlowRequests": true, - "slowRequestThreshold": "5s" - } - } -} -``` +- 参数验证确保正确的工具使用 +- 错误处理提供有用的反馈 +- 响应格式保持一致性 +- 日志记录跟踪工具使用情况进行分析 -## 基于功能的路由 +## 前置条件 -### 工具特定路由 +智能路由需要比基础 MCPHub 使用更多的设置： -根据请求的工具类型路由到专门的服务器： +### 必需组件 -```json -{ - "routing": { - "strategy": "capability-based", - "rules": [ - { - "condition": { - "tool": "filesystem" - }, - "targets": ["filesystem-server-1", "filesystem-server-2"], - "strategy": "least-connections" - }, - { - "condition": { - "tool": "web-search" - }, - "targets": ["search-server-1", "search-server-2"], - "strategy": "round-robin" - }, - { - "condition": { - "tool": "database" - }, - "targets": ["db-server"], - "strategy": "single" - } - ], - "fallback": { - "targets": ["general-server-1", "general-server-2"], - "strategy": "round-robin" - } - } -} -``` +1. **带有 pgvector 的 PostgreSQL**：用于嵌入存储的向量数据库 +2. **嵌入服务**：OpenAI API 或兼容服务 +3. **环境配置**：正确的配置变量 -### 内容感知路由 +## 使用智能路由 -基于请求内容进行智能路由： +### 智能路由端点 -```json -{ - "routing": { - "strategy": "content-aware", - "rules": [ - { - "condition": { - "content.language": "python" - }, - "targets": ["python-specialized-server"], - "reason": "Python代码分析专用服务器" - }, - { - "condition": { - "content.size": "> 1MB" - }, - "targets": ["high-memory-server"], - "reason": "大文件处理专用服务器" - }, - { - "condition": { - "content.type": "image" - }, - "targets": ["image-processing-server"], - "reason": "图像处理专用服务器" - } - ] - } -} -``` +通过特殊的 `$smart` 端点访问智能路由： -## 地理位置路由 + + + ``` + http://localhost:3000/mcp/$smart + ``` + -### 基于客户端位置 + + ``` + http://localhost:3000/sse/$smart + ``` + + -根据客户端地理位置路由到最近的服务器： +{/* ## 性能优化 -```json -{ - "routing": { - "strategy": "geo-location", - "regions": [ - { - "name": "北美", - "countries": ["US", "CA", "MX"], - "servers": ["us-east-1", "us-west-1", "ca-central-1"], - "strategy": "least-latency" - }, - { - "name": "欧洲", - "countries": ["DE", "FR", "UK", "NL"], - "servers": ["eu-west-1", "eu-central-1"], - "strategy": "round-robin" - }, - { - "name": "亚太", - "countries": ["CN", "JP", "KR", "SG"], - "servers": ["ap-southeast-1", "ap-northeast-1"], - "strategy": "fastest-response" - } - ], - "fallback": { - "servers": ["global-server-1"], - "strategy": "single" - } - } -} -``` +### 嵌入缓存 -### 延迟优化 +智能路由缓存嵌入以提高性能： ```bash -# 配置延迟监控 -curl -X PUT http://localhost:3000/api/routing/latency-config \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ +# 配置缓存设置 +EMBEDDING_CACHE_TTL=3600 # 缓存 1 小时 +EMBEDDING_CACHE_SIZE=10000 # 最多缓存 10k 个嵌入 +EMBEDDING_CACHE_CLEANUP=300 # 每 5 分钟清理一次 +``` + +### 批处理 + +工具批量索引以提高效率： + +```bash +# 嵌入生成的批大小 +EMBEDDING_BATCH_SIZE=100 + +# 并发嵌入请求 +EMBEDDING_CONCURRENCY=5 + +# 索引更新频率 +INDEX_UPDATE_INTERVAL=3600 # 每小时重新索引 +``` + +### 数据库优化 + +为向量操作优化 PostgreSQL： + +```sql +-- 创建索引以获得更好的性能 +CREATE INDEX ON tool_embeddings USING hnsw (embedding vector_cosine_ops); + +-- 调整 PostgreSQL 设置 +ALTER SYSTEM SET shared_preload_libraries = 'vector'; +ALTER SYSTEM SET max_connections = 200; +ALTER SYSTEM SET shared_buffers = '256MB'; +ALTER SYSTEM SET effective_cache_size = '1GB'; +``` + +## 监控和分析 + +### 智能路由指标 + +监控智能路由性能： + +```bash +# 获取智能路由统计信息 +curl http://localhost:3000/api/smart-routing/stats \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +响应包括： + +- 查询计数和频率 +- 平均响应时间 +- 嵌入缓存命中率 +- 最受欢迎的工具 +- 查询模式 + +### 工具使用分析 + +跟踪哪些工具被发现和使用： + +```bash +# 获取工具使用分析 +curl http://localhost:3000/api/smart-routing/analytics \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +指标包括： + +- 工具发现率 +- 执行成功率 +- 用户满意度评分 +- 查询到执行的转换率 + +### 性能监控 + +监控系统性能： + +```bash +# 数据库性能 +curl http://localhost:3000/api/smart-routing/db-stats \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" + +# 嵌入服务状态 +curl http://localhost:3000/api/smart-routing/embedding-stats \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +## 高级功能 + +### 自定义嵌入 + +使用自定义嵌入模型： + +```bash +# Hugging Face 模型 +EMBEDDING_SERVICE=huggingface +HUGGINGFACE_MODEL=sentence-transformers/all-MiniLM-L6-v2 +HUGGINGFACE_API_KEY=your_api_key + +# 本地嵌入服务 +EMBEDDING_SERVICE=local +EMBEDDING_SERVICE_URL=http://localhost:8080/embeddings +``` + +### 查询增强 + +增强查询以获得更好的结果： + +```json +{ + "queryEnhancement": { "enabled": true, - "measurementInterval": 30000, - "regions": [ - {"id": "us-east", "endpoint": "ping.us-east.example.com"}, - {"id": "eu-west", "endpoint": "ping.eu-west.example.com"}, - {"id": "ap-southeast", "endpoint": "ping.ap-southeast.example.com"} - ], - "routing": { - "preferLowLatency": true, - "maxLatencyThreshold": "200ms", - "fallbackOnTimeout": true - } - }' -``` - -## 负载感知路由 - -### 实时负载监控 - -```json -{ - "routing": { - "strategy": "load-aware", - "loadMetrics": { - "cpu": { - "threshold": 80, - "weight": 0.4 - }, - "memory": { - "threshold": 85, - "weight": 0.3 - }, - "connections": { - "threshold": 1000, - "weight": 0.2 - }, - "responseTime": { - "threshold": "2s", - "weight": 0.1 - } - }, - "adaptation": { - "enabled": true, - "adjustmentInterval": 60000, - "emergencyThreshold": 95 - } + "expandAcronyms": true, + "addSynonyms": true, + "contextualExpansion": true } } ``` -### 预测性负载均衡 +### 结果过滤 + +基于条件过滤结果： ```json { - "routing": { - "strategy": "predictive", - "prediction": { - "algorithm": "linear-regression", - "trainingWindow": "7d", - "predictionHorizon": "1h", - "factors": ["historical_load", "time_of_day", "day_of_week", "seasonal_patterns"] - }, - "adaptation": { - "preemptiveScaling": true, - "scaleUpThreshold": 70, - "scaleDownThreshold": 30 - } + "resultFiltering": { + "minRelevanceScore": 0.7, + "maxResults": 10, + "preferredServers": ["fetch", "playwright"], + "excludeServers": ["deprecated-server"] } } ``` -## 故障转移和恢复 +### 反馈学习 -### 自动故障转移 - -```json -{ - "routing": { - "strategy": "high-availability", - "failover": { - "enabled": true, - "detection": { - "healthCheckFailures": 3, - "timeoutThreshold": "10s", - "checkInterval": 5000 - }, - "recovery": { - "automaticRecovery": true, - "recoveryChecks": 5, - "recoveryInterval": 30000 - } - }, - "clusters": [ - { - "name": "primary", - "servers": ["server-1", "server-2"], - "priority": 1 - }, - { - "name": "secondary", - "servers": ["backup-server-1", "backup-server-2"], - "priority": 2 - } - ] - } -} -``` - -### 断路器模式 - -```json -{ - "routing": { - "circuitBreaker": { - "enabled": true, - "failureThreshold": 10, - "timeWindow": 60000, - "halfOpenRetries": 3, - "fallback": { - "type": "cached-response", - "ttl": 300000 - } - } - } -} -``` - -## 会话亲和性 - -### 粘性会话 - -保持用户会话与特定服务器的关联： - -```json -{ - "routing": { - "strategy": "session-affinity", - "affinity": { - "type": "cookie", - "cookieName": "mcphub-server-id", - "ttl": 3600000, - "fallbackOnUnavailable": true - }, - "sessionStore": { - "type": "redis", - "config": { - "host": "localhost", - "port": 6379, - "db": 1 - } - } - } -} -``` - -### 基于用户 ID 的路由 - -```json -{ - "routing": { - "strategy": "user-based", - "userRouting": { - "algorithm": "consistent-hashing", - "hashFunction": "sha256", - "virtualNodes": 100, - "replicationFactor": 2 - } - } -} -``` - -## 动态路由配置 - -### 运行时配置更新 +基于用户反馈改进结果： ```bash -# 更新路由配置 -curl -X PUT http://localhost:3000/api/routing/config \ +# 对搜索结果提供反馈 +curl -X POST http://localhost:3000/api/smart-routing/feedback \ -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{ - "strategy": "weighted-round-robin", - "weights": { - "server-1": 3, - "server-2": 2, - "server-3": 1 - }, - "applyImmediately": true + "queryId": "search-123", + "toolName": "fetch_html", + "rating": 5, + "successful": true, + "comments": "完美适合这个任务的工具" }' -``` - -### A/B 测试路由 - -```json -{ - "routing": { - "strategy": "ab-testing", - "experiments": [ - { - "name": "new-algorithm-test", - "enabled": true, - "trafficSplit": { - "control": 70, - "variant": 30 - }, - "rules": { - "control": { - "strategy": "round-robin", - "servers": ["stable-server-1", "stable-server-2"] - }, - "variant": { - "strategy": "ai-optimized", - "servers": ["experimental-server-1"] - } - }, - "metrics": ["response_time", "error_rate", "user_satisfaction"] - } - ] - } -} -``` - -## 路由分析和监控 - -### 实时路由指标 - -```bash -# 获取路由统计 -curl -X GET http://localhost:3000/api/routing/metrics \ - -H "Authorization: Bearer $TOKEN" -``` - -响应示例： - -```json -{ - "timestamp": "2024-01-01T12:00:00Z", - "totalRequests": 15420, - "routingDistribution": { - "server-1": { "requests": 6168, "percentage": 40 }, - "server-2": { "requests": 4626, "percentage": 30 }, - "server-3": { "requests": 3084, "percentage": 20 }, - "backup-server": { "requests": 1542, "percentage": 10 } - }, - "performance": { - "avgResponseTime": "245ms", - "p95ResponseTime": "580ms", - "errorRate": "0.3%" - }, - "failovers": { - "total": 2, - "byServer": { - "server-2": 1, - "server-3": 1 - } - } -} -``` - -### 路由决策日志 - -```bash -# 启用路由决策日志 -curl -X PUT http://localhost:3000/api/routing/logging \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "enabled": true, - "level": "info", - "includeDecisionFactors": true, - "sampleRate": 0.1 - }' -``` - -## 自定义路由规则 - -### 基于业务逻辑的路由 - -```json -{ - "routing": { - "strategy": "custom-rules", - "rules": [ - { - "name": "premium-users", - "priority": 1, - "condition": "user.tier === 'premium'", - "action": { - "targetServers": ["premium-server-1", "premium-server-2"], - "strategy": "least-connections", - "qos": { - "maxResponseTime": "1s", - "priority": "high" - } - } - }, - { - "name": "high-volume-requests", - "priority": 2, - "condition": "request.size > 10MB", - "action": { - "targetServers": ["high-capacity-server"], - "strategy": "single", - "timeout": "60s" - } - }, - { - "name": "batch-processing", - "priority": 3, - "condition": "request.type === 'batch'", - "action": { - "targetServers": ["batch-server-1", "batch-server-2"], - "strategy": "queue-based", - "queueConfig": { - "maxSize": 1000, - "timeout": "5m" - } - } - } - ] - } -} -``` - -### JavaScript 路由函数 - -```javascript -// 自定义路由函数 -function customRouting(request, servers, metrics) { - const { user, content, timestamp } = request; - - // 工作时间优先使用高性能服务器 - const isBusinessHours = - new Date(timestamp).getHours() >= 9 && new Date(timestamp).getHours() <= 17; - - if (isBusinessHours && user.priority === 'high') { - return servers.filter((s) => s.tags.includes('high-performance')); - } - - // 基于内容类型的特殊路由 - if (content.type === 'code-analysis') { - return servers.filter((s) => s.capabilities.includes('code-analysis')); - } - - // 默认负载均衡 - return servers.sort((a, b) => a.currentLoad - b.currentLoad); -} -``` - -## 路由优化 - -### 机器学习优化 - -```json -{ - "routing": { - "strategy": "ml-optimized", - "mlConfig": { - "algorithm": "reinforcement-learning", - "rewardFunction": "response_time_weighted", - "trainingData": { - "features": [ - "server_load", - "response_time_history", - "request_complexity", - "user_pattern", - "time_of_day" - ], - "targetMetric": "overall_satisfaction" - }, - "updateFrequency": "hourly", - "explorationRate": 0.1 - } - } -} -``` - -### 缓存感知路由 - -```json -{ - "routing": { - "strategy": "cache-aware", - "caching": { - "enabled": true, - "levels": [ - { - "type": "local", - "ttl": 300, - "maxSize": "100MB" - }, - { - "type": "distributed", - "provider": "redis", - "ttl": 3600, - "maxSize": "1GB" - } - ], - "routing": { - "preferCachedServers": true, - "cacheHitBonus": 0.3, - "cacheMissThreshold": 0.8 - } - } - } -} -``` +``` */} ## 故障排除 -### 路由调试 + + + **症状：** + - 智能路由不可用 + - 数据库连接错误 + - 嵌入存储失败 -```bash -# 调试特定请求的路由决策 -curl -X POST http://localhost:3000/api/routing/debug \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "request": { - "userId": "user123", - "tool": "filesystem", - "content": {"type": "read", "path": "/data/file.txt"} - }, - "traceRoute": true - }' -``` + **解决方案：** + 1. 验证 PostgreSQL 是否正在运行 + 2. 检查 DATABASE_URL 格式 + 3. 确保安装了 pgvector 扩展 + 4. 手动测试连接： + ```bash + psql $DATABASE_URL -c "SELECT 1;" + ``` -### 路由性能分析 + -```bash -# 获取路由性能报告 -curl -X GET http://localhost:3000/api/routing/performance \ - -H "Authorization: Bearer $TOKEN" \ - -G -d "timeRange=1h" -d "detailed=true" -``` + + **症状：** + - 工具索引失败 + - 查询处理错误 + - API 速率限制错误 -### 常见问题 + **解决方案：** + 1. 验证 API 密钥有效性 + 2. 检查网络连接 + 3. 监控速率限制 + 4. 测试嵌入服务： + ```bash + curl -X POST https://api.openai.com/v1/embeddings \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"input": "test", "model": "text-embedding-3-small"}' + ``` -1. **不均匀的负载分布** + - - 检查服务器权重配置 - - 验证健康检查设置 - - 分析请求模式 + + **症状：** + - 返回不相关的工具 + - 相关性得分低 + - 缺少预期的工具 -2. **频繁的故障转移** + **解决方案：** + 1. 调整相似性阈值 + 2. 使用更好的描述重新索引工具 + 3. 使用更具体的查询 + 4. 检查工具元数据质量 + ```bash + # 重新索引所有工具 + curl -X POST http://localhost:3000/api/smart-routing/reindex \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" + ``` - - 调整健康检查阈值 - - 检查网络连接稳定性 - - 优化服务器资源 + -3. **路由延迟过高** - - 简化路由规则 - - 优化路由算法 - - 使用缓存加速决策 + + **症状：** + - 查询响应缓慢 + - 数据库负载高 + - 内存使用激增 -有关更多信息，请参阅 [监控](/zh/features/monitoring) 和 [服务器管理](/zh/features/server-management) 文档。 + **解决方案：** + 1. 优化数据库配置 + 2. 增加缓存大小 + 3. 减少批处理大小 + 4. 监控系统资源 + ```bash + # 检查系统性能 + curl http://localhost:3000/api/smart-routing/performance \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" + ``` + + + + +## 最佳实践 + +### 查询编写 + + + **要具体描述**：在查询中使用具体、描述性的语言以获得更好的工具匹配。 + + + + **包含上下文**：提供有关您的任务或领域的相关上下文以获得更准确的结果。 + + +**使用自然语言**：像向人类描述任务一样编写查询。 + +### 工具描述 + + + **质量元数据**：确保 MCP 服务器提供高质量的工具描述和元数据。 + + +**定期更新**：随着功能的发展保持工具描述的最新状态。 + + + **一致的命名**：在工具和服务器中使用一致的命名约定。 + + +### 系统维护 + +**定期重新索引**：定期重新索引工具以确保嵌入质量。 + +**监控性能**：跟踪查询模式并根据使用情况进行优化。 + + + **更新模型**：随着新嵌入模型的出现，考虑更新到更新的模型。 + + +## 下一步 + + + + 用户管理和访问控制 + + + 系统监控和分析 + + + 完整的智能路由 API 文档 + + + 高级配置选项 + + diff --git a/docs/zh/index.mdx b/docs/zh/index.mdx index a392401..463917e 100644 --- a/docs/zh/index.mdx +++ b/docs/zh/index.mdx @@ -1,23 +1,21 @@ --- -title: '欢迎使用 MCPHub' -description: 'MCPHub 是一个强大的 Model Context Protocol (MCP) 服务器管理平台，提供智能路由、负载均衡和实时监控功能' +title: '欢迎使用' +description: 'MCPHub 是一个强大的 Model Context Protocol (MCP) 服务器管理平台，提供分组管理、智能路由和实时监控等功能' --- -MCPHub Hero Light -MCPHub Hero Dark +{/* MCPHub Hero Light +MCPHub Hero Dark */} ## 什么是 MCPHub？ -MCPHub 是一个现代化的 Model Context Protocol (MCP) 服务器管理平台，旨在简化 AI 模型服务的部署、管理和监控。通过智能路由和负载均衡技术，MCPHub 帮助您构建高可用、可扩展的 AI 服务架构。 +MCPHub 是一个现代化的 Model Context Protocol (MCP) 服务器管理平台，旨在简化 AI 模型服务的部署、管理和监控。通过分组管理和智能路由技术，MCPHub 帮助您构建高可用、可扩展的 AI 服务架构。 ### 核心功能 -- **🚀 智能路由** - 基于负载、延迟和健康状态的智能请求分发 -- **⚖️ 负载均衡** - 多种负载均衡策略，确保最优性能 +- **🏗️ 分组管理** - 灵活的服务器分组和配置管理 +- **🚀 智能路由** - 基于语义检索的智能路由分发 - **📊 实时监控** - 全面的性能指标和健康检查 -- **🔐 安全认证** - 企业级身份认证和访问控制 -- **🏗️ 服务器组管理** - 灵活的服务器分组和配置管理 -- **🔄 故障转移** - 自动故障检测和流量切换 +- **🔐 安全认证** - 身份认证和访问控制 ## 快速开始 diff --git a/docs/zh/installation.mdx b/docs/zh/installation.mdx new file mode 100644 index 0000000..e1685c5 --- /dev/null +++ b/docs/zh/installation.mdx @@ -0,0 +1,570 @@ +--- +title: '安装指南' +description: '各种平台的详细安装说明' +--- + +## 先决条件 + +在安装 MCPHub 之前，请确保您具备以下先决条件： + +- **Node.js** 18+ (用于本地开发) +- **Docker** (推荐用于生产环境) +- **pnpm** (用于本地开发) + +智能路由的可选要求： + +- **PostgreSQL** 带 pgvector 扩展 +- **OpenAI API Key** 或兼容的嵌入服务 + +## 安装方法 + + + + ### Docker 安装 + + Docker 是在生产环境中部署 MCPHub 的推荐方式。 + + #### 1. 基础安装 + + ```bash + # 拉取最新镜像 + docker pull samanhappy/mcphub:latest + + # 使用默认设置运行 + docker run -d \ + --name mcphub \ + -p 3000:3000 \ + samanhappy/mcphub:latest + ``` + + #### 2. 使用自定义配置 + + ```bash + # 创建您的配置文件 + cat > mcp_settings.json << 'EOF' + { + "mcpServers": { + "fetch": { + "command": "uvx", + "args": ["mcp-server-fetch"] + }, + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest", "--headless"] + } + } + } + EOF + + # 使用挂载的配置运行 + docker run -d \ + --name mcphub \ + -p 3000:3000 \ + -v $(pwd)/mcp_settings.json:/app/mcp_settings.json \ + samanhappy/mcphub:latest + ``` + + #### 3. 使用环境变量 + + ```bash + docker run -d \ + --name mcphub \ + -p 3000:3000 \ + -e PORT=3000 \ + -e BASE_PATH="" \ + samanhappy/mcphub:latest + ``` + + #### 4. Docker Compose + + 创建 `docker-compose.yml` 文件： + + ```yaml + version: '3.8' + services: + mcphub: + image: samanhappy/mcphub:latest + ports: + - "3000:3000" + volumes: + - ./mcp_settings.json:/app/mcp_settings.json + environment: + - PORT=3000 + - BASE_PATH="" + - REQUEST_TIMEOUT=60000 + restart: unless-stopped + + # 可选：用于智能路由的 PostgreSQL + postgres: + image: pgvector/pgvector:pg16 + environment: + POSTGRES_DB: mcphub + POSTGRES_USER: mcphub + POSTGRES_PASSWORD: mcphub_password + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "5432:5432" + + volumes: + postgres_data: + ``` + + 运行命令： + ```bash + docker-compose up -d + ``` + + + + + ### npm 包安装 + + 将 MCPHub 安装为全局 npm 包： + + #### 1. 全局安装 + + ```bash + # 全局安装 + npm install -g @samanhappy/mcphub + + # 或使用 yarn + yarn global add @samanhappy/mcphub + + # 或使用 pnpm + pnpm add -g @samanhappy/mcphub + ``` + + #### 2. 运行 MCPHub + + ```bash + # 使用默认设置运行 + mcphub + + # 使用自定义端口运行 + PORT=8080 mcphub + ``` + + {/* #### 3. 本地安装 + + 您也可以在项目中本地安装 MCPHub： + + ```bash + # 创建新目录 + mkdir my-mcphub + cd my-mcphub + + # 初始化 package.json + npm init -y + + # 本地安装 MCPHub + npm install @samanhappy/mcphub + + # 创建启动脚本 + echo '#!/bin/bash\nnpx mcphub' > start.sh + chmod +x start.sh + + # 运行 MCPHub + ./start.sh + ``` */} + + + + ### 本地开发环境设置 + + 用于开发、自定义或贡献： + + #### 1. 克隆仓库 + + ```bash + # 克隆仓库 + git clone https://github.com/samanhappy/mcphub.git + cd mcphub + ``` + + #### 2. 安装依赖 + + ```bash + # 使用 pnpm 安装依赖（推荐） + pnpm install + + # 或使用 npm + npm install + + # 或使用 yarn + yarn install + ``` + + #### 3. 开发模式 + + ```bash + # 在开发模式下同时启动后端和前端 + pnpm dev + + # 这将启动： + # - 后端在 http://localhost:3001 + # - 前端在 http://localhost:5173 + # - 前端代理 API 调用到后端 + ``` + + #### 4. 生产构建 + + ```bash + # 构建后端和前端 + pnpm build + + # 启动生产服务器 + pnpm start + ``` + + #### 5. 开发脚本 + + ```bash + # 仅后端（用于 API 开发） + pnpm backend:dev + + # 仅前端（当后端单独运行时） + pnpm frontend:dev + + # 运行测试 + pnpm test + + # 代码检查 + pnpm lint + + # 代码格式化 + pnpm format + ``` + + + 在 Windows 上，您可能需要分别运行后端和前端： + ```bash + # 终端 1：后端 + pnpm backend:dev + + # 终端 2：前端 + pnpm frontend:dev + ``` + + + + + + ### Kubernetes 部署 + + 使用这些清单在 Kubernetes 上部署 MCPHub： + + #### 1. 设置的 ConfigMap + + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: mcphub-config + data: + mcp_settings.json: | + { + "mcpServers": { + "fetch": { + "command": "uvx", + "args": ["mcp-server-fetch"] + }, + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest", "--headless"] + } + } + } + ``` + + #### 2. 部署 + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: mcphub + spec: + replicas: 1 + selector: + matchLabels: + app: mcphub + template: + metadata: + labels: + app: mcphub + spec: + containers: + - name: mcphub + image: samanhappy/mcphub:latest + ports: + - containerPort: 3000 + env: + - name: PORT + value: "3000" + volumeMounts: + - name: config + mountPath: /app/mcp_settings.json + subPath: mcp_settings.json + volumes: + - name: config + configMap: + name: mcphub-config + ``` + + #### 3. 服务 + + ```yaml + apiVersion: v1 + kind: Service + metadata: + name: mcphub-service + spec: + selector: + app: mcphub + ports: + - port: 80 + targetPort: 3000 + type: ClusterIP + ``` + + #### 4. Ingress (可选) + + ```yaml + apiVersion: networking.k8s.io/v1 + kind: Ingress + metadata: + name: mcphub-ingress + annotations: + nginx.ingress.kubernetes.io/proxy-buffering: "off" + spec: + rules: + - host: mcphub.yourdomain.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: mcphub-service + port: + number: 80 + ``` + + 部署命令： + ```bash + kubectl apply -f mcphub-configmap.yaml + kubectl apply -f mcphub-deployment.yaml + kubectl apply -f mcphub-service.yaml + kubectl apply -f mcphub-ingress.yaml + ``` + + + + +## 智能路由设置 (可选) + +智能路由使用向量语义搜索提供 AI 驱动的工具发现。 + +### 先决条件 + +1. **PostgreSQL 带 pgvector 扩展** +2. **OpenAI API Key** (或兼容的嵌入服务) + +### 数据库设置 + + + + ```bash + # 运行带 pgvector 的 PostgreSQL + docker run -d \ + --name mcphub-postgres \ + -e POSTGRES_DB=mcphub \ + -e POSTGRES_USER=mcphub \ + -e POSTGRES_PASSWORD=your_password \ + -p 5432:5432 \ + pgvector/pgvector:pg16 + ``` + + + + 如果您有现有的 PostgreSQL 实例： + + ```sql + -- 连接到您的 PostgreSQL 实例 + -- 创建数据库 + CREATE DATABASE mcphub; + + -- 连接到 mcphub 数据库 + \c mcphub; + + -- 启用 pgvector 扩展 + CREATE EXTENSION IF NOT EXISTS vector; + ``` + + + + + 对于云提供商（AWS RDS、Google Cloud SQL 等）： + + 1. 在您的云提供商控制台中启用 pgvector 扩展 + 2. 创建名为 `mcphub` 的数据库 + 3. 记下连接详细信息 + + + + +{/* ### 环境配置 + +设置以下环境变量： + +```bash +# 数据库连接 +DATABASE_URL=postgresql://mcphub:your_password@localhost:5432/mcphub + +# 用于嵌入的 OpenAI API +OPENAI_API_KEY=your_openai_api_key + +# 可选：自定义嵌入模型 +EMBEDDING_MODEL=text-embedding-3-small + +# 可选：启用智能路由 +ENABLE_SMART_ROUTING=true +``` */} + +## 验证 + +安装后，验证 MCPHub 是否正常工作： + +{/* ### 1. 健康检查 + +```bash +curl http://localhost:3000/api/health +``` + +预期响应： + +```json +{ + "status": "ok", + "version": "x.x.x", + "uptime": 123 +} +``` */} + +### 控制台访问 + +打开浏览器并导航到： + +``` +http://localhost:3000 +``` + +{/* ### 3. API 测试 + +```bash +curl -X POST http://localhost:3000/mcp \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/list", + "params": {} + }' +``` */} + +## 故障排除 + + + + **端口已被使用：** + ```bash + # 检查是什么在使用端口 3000 + lsof -i :3000 + + # 使用不同的端口 + docker run -p 8080:3000 samanhappy/mcphub + ``` + + **容器无法启动：** + ```bash + # 检查容器日志 + docker logs mcphub + + # 交互式运行以进行调试 + docker run -it --rm samanhappy/mcphub /bin/bash + ``` + + + + + **权限错误：** + ```bash + # 使用 npx 而不是全局安装 + npx @samanhappy/mcphub + + # 或修复 npm 权限 + npm config set prefix ~/.npm-global + export PATH=~/.npm-global/bin:$PATH + ``` + + **Node 版本问题：** + ```bash + # 检查 Node 版本 + node --version + + # 使用 nvm 安装 Node 18+ + nvm install 18 + nvm use 18 + ``` + + + + + **无法访问控制台：** + - 检查 MCPHub 是否在运行：`ps aux | grep mcphub` + - 验证端口绑定：`netstat -tlnp | grep 3000` + - 检查防火墙设置 + - 尝试通过 `127.0.0.1:3000` 而不是 `localhost:3000` 访问 + + **AI 客户端无法连接：** + - 确保端点 URL 正确 + - 检查 MCPHub 是否在代理后面 + - 验证 Kubernetes/Docker 环境中的网络策略 + + + + + **数据库连接失败：** + ```bash + # 测试数据库连接 + psql $DATABASE_URL -c "SELECT 1;" + + # 检查是否安装了 pgvector + psql $DATABASE_URL -c "CREATE EXTENSION IF NOT EXISTS vector;" + ``` + + **嵌入服务错误：** + - 验证 OpenAI API 密钥是否有效 + - 检查互联网连接 + - 监控速率限制 + + + + +## 下一步 + + + + 配置您的 MCP 服务器和设置 + + + 5分钟内启动并运行 + + + 了解如何管理您的 MCP 服务器 + + + 探索完整的 API 文档 + + diff --git a/docs/zh/quickstart.mdx b/docs/zh/quickstart.mdx index ae39719..ca39f66 100644 --- a/docs/zh/quickstart.mdx +++ b/docs/zh/quickstart.mdx @@ -1,304 +1,212 @@ --- -title: '快速开始' -description: '5 分钟内部署 MCPHub 并连接您的第一个 MCP 服务器' +title: '快速开始指南' +description: '5 分钟内运行 MCPHub' --- -## 欢迎使用 MCPHub！ +## 安装 -本指南将帮助您在 5 分钟内完成 MCPHub 的部署和配置，并连接您的第一个 MCP 服务器。 - -## 前提条件 - -在开始之前，请确保您的系统满足以下要求： - - - - - **操作系统**: Linux、macOS 或 Windows - - **内存**: 最少 2GB RAM（推荐 4GB+） - - **存储**: 至少 1GB 可用空间 - - **网络**: 稳定的互联网连接 - - - - - **Node.js**: 18.0+ 版本 - - **Docker**: 最新版本（可选，用于容器化部署） - - **Git**: 用于代码管理 - - 检查版本： - ```bash - node --version # 应该 >= 18.0.0 - npm --version # 应该 >= 8.0.0 - docker --version # 可选 - ``` - - - -## 安装 MCPHub - -### 方式一：使用 npm（推荐） - - - - 首先安装 MCPHub 命令行工具： + + + 使用 Docker 是最快的开始方式： ```bash - npm install -g @mcphub/cli + # 使用默认配置运行 + docker run -p 3000:3000 samanhappy/mcphub ``` - 验证安装： + 或者挂载自定义配置： + ```bash - mcphub --version + # 使用自定义 MCP 设置运行 + docker run -p 3000:3000 \ + -v $(pwd)/mcp_settings.json:/app/mcp_settings.json \ + samanhappy/mcphub ``` - - - - 创建一个新的 MCPHub 项目： + + + 用于开发或自定义： ```bash - # 创建项目 - mcphub init my-mcphub-project - cd my-mcphub-project + # 克隆仓库 + git clone https://github.com/samanhappy/mcphub.git + cd mcphub # 安装依赖 - npm install + pnpm install + + # 启动开发服务器 + pnpm dev ``` - + 这会同时启动后端（端口 3001）和前端（端口 5173）的开发模式。 - - 复制并编辑环境变量文件： + + + 将 MCPHub 安装为全局包： ```bash - cp .env.example .env + # 全局安装 + npm install -g @samanhappy/mcphub + + # 运行 MCPHub + mcphub ``` - 编辑 `.env` 文件，设置基本配置： - ```bash - # 服务器配置 - PORT=3000 - NODE_ENV=development + + - # 数据库配置（使用内置 SQLite） - DATABASE_URL=sqlite:./data/mcphub.db +## 初始设置 - # JWT 密钥（请更改为安全的随机字符串） - JWT_SECRET=your-super-secret-jwt-key-change-me +### 1. 访问控制面板 - # 管理员账户 - ADMIN_EMAIL=admin@example.com - ADMIN_PASSWORD=admin123 - ``` +打开浏览器并导航到： - - - -### 方式二：使用 Docker - - - - 使用 Docker Compose 一键部署： - - ```bash - # 下载配置文件 - curl -O https://raw.githubusercontent.com/mcphub/mcphub/main/docker-compose.yml - - # 启动服务 - docker-compose up -d - ``` - - 或者直接运行 Docker 容器： - ```bash - docker run -d \ - --name mcphub \ - -p 3000:3000 \ - -e NODE_ENV=production \ - -e JWT_SECRET=your-secret-key \ - mcphub/server:latest - ``` - - - - -## 启动 MCPHub - -### 开发模式启动 - -```bash -# 初始化数据库 -npm run db:setup - -# 启动开发服务器 -npm run dev +``` +http://localhost:3000 ``` -### 生产模式启动 +### 2. 登录 -```bash -# 构建应用 -npm run build +使用默认凭据： -# 启动生产服务器 -npm start -``` - -开发模式下，MCPHub 会在 `http://localhost:3000` 启动，并具有热重载功能。 - -## 首次访问和配置 - -### 1. 访问管理界面 - -打开浏览器，访问 `http://localhost:3000`，您将看到 MCPHub 的欢迎页面。 - -### 2. 登录管理员账户 - -使用您在 `.env` 文件中设置的管理员凭据登录： - -- **邮箱**: `admin@example.com` +- **用户名**: `admin` - **密码**: `admin123` -首次登录后，请立即更改默认密码以确保安全！ +为了安全起见，请在首次登录后立即更改这些默认凭据。 -### 3. 完成初始配置 +### 3. 配置您的第一个 MCP 服务器 -登录后，系统会引导您完成初始配置： +1. 在控制面板中点击 **"添加服务器"** +2. 输入服务器详细信息： + - **名称**: 唯一标识符（例如 `fetch`） + - **命令**: 可执行命令（`uvx`） + - **参数**: 命令参数（`["mcp-server-fetch"]`） + - **环境**: 任何所需的环境变量 -1. **更改管理员密码** -2. **设置组织信息** -3. **配置基本设置** +fetch 服务器的示例配置： -## 添加您的第一个 MCP 服务器 - -### 1. 准备 MCP 服务器 - -如果您还没有 MCP 服务器，可以使用我们的示例服务器进行测试： - -```bash -# 克隆示例服务器 -git clone https://github.com/mcphub/example-mcp-server.git -cd example-mcp-server - -# 安装依赖并启动 -npm install -npm start +```json +{ + "name": "fetch", + "command": "uvx", + "args": ["mcp-server-fetch"], + "env": {} +} ``` -示例服务器将在 `http://localhost:3001` 启动。 +## 基本使用 -### 2. 在 MCPHub 中添加服务器 +### 连接 AI 客户端 -在 MCPHub 管理界面中： +一旦配置了服务器，使用 MCPHub 端点连接您的 AI 客户端： -1. 点击 **"添加服务器"** 按钮 -2. 填写服务器信息： - ``` - 名称: Example MCP Server - 端点: http://localhost:3001 - 描述: 示例 MCP 服务器用于测试 - ``` -3. 选择功能类型（如：chat、completion、analysis） -4. 点击 **"测试连接"** 验证服务器可达性 -5. 点击 **"保存"** 完成添加 + + + 访问所有已配置的 MCP 服务器：``` http://localhost:3000/mcp ``` + + + 访问特定组中的服务器：``` http://localhost:3000/mcp/{groupName} ``` + + + 访问单个服务器：``` http://localhost:3000/mcp/{serverName} ``` + + + 使用 AI 驱动的工具发现：``` http://localhost:3000/mcp/$smart ``` + 智能路由需要使用 pgvector 的 PostgreSQL 和 OpenAI API 密钥。 + + -### 3. 验证服务器状态 +### 示例：添加热门 MCP 服务器 -添加成功后，您应该能在服务器列表中看到新添加的服务器，状态显示为 **"活跃"**（绿色）。 +以下是一些您可以添加的热门 MCP 服务器： -## 测试路由功能 - -### 发送测试请求 - -使用 cURL 或其他 HTTP 客户端测试路由功能： - -```bash -# 发送聊天请求 -curl -X POST http://localhost:3000/api/chat \ - -H "Content-Type: application/json" \ - -d '{ - "messages": [ - { - "role": "user", - "content": "Hello, this is a test message!" + + + ```json + { + "name": "fetch", + "command": "uvx", + "args": ["mcp-server-fetch"] + } + ``` + + + + ```json + { + "name": "playwright", + "command": "npx", + "args": ["@playwright/mcp@latest", "--headless"] + } + ``` + + + + ```json + { + "name": "amap", + "command": "npx", + "args": ["-y", "@amap/amap-maps-mcp-server"], + "env": { + "AMAP_MAPS_API_KEY": "your-api-key-here" } - ] - }' -``` - -### 查看请求日志 - -在 MCPHub 管理界面的 **"监控"** 页面中，您可以实时查看： - -- 请求数量和响应时间 -- 服务器健康状态 -- 错误日志和统计 + } + ``` + + + + ```json + { + "name": "slack", + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-slack"], + "env": { + "SLACK_BOT_TOKEN": "your-bot-token", + "SLACK_TEAM_ID": "your-team-id" + } + } + ``` + + ## 后续步骤 -恭喜！您已经成功部署了 MCPHub 并添加了第一个 MCP 服务器。接下来您可以： - - - 学习如何配置智能路由和负载均衡策略 + + 学习高级服务器配置和管理 - - 了解服务器管理的高级功能 + + 将服务器组织成逻辑组 - - 配置性能监控和告警通知 + + 设置 AI 驱动的工具发现 - - 将 MCPHub 集成到您的应用程序中 + + 探索完整的 API 文档 -## 常见问题 +## 故障排除 - - **可能原因**： - - 服务器地址错误或服务器未启动 - - 防火墙阻止连接 - - 网络配置问题 - - **解决方案**： - 1. 验证服务器是否正在运行：`curl http://localhost:3001/health` - 2. 检查防火墙设置 - 3. 确认网络连接正常 - + + - 检查 MCP 服务器命令是否在您的 PATH 中可访问 + - 验证环境变量是否正确设置 + - 检查 MCPHub 日志以获取详细错误信息 - - **可能原因**： - - 健康检查失败 - - 服务器响应超时 - - 服务器崩溃或重启 - - **解决方案**： - 1. 检查服务器日志 - 2. 调整健康检查间隔 - 3. 重启服务器进程 - + + - 确保 MCPHub 在正确的端口上运行 + - 检查防火墙设置 + - 验证端点 URL 格式 - - **解决方案**： - ```bash - # 重置管理员密码 - npm run reset-admin-password - ``` - 或者删除数据库文件重新初始化： - ```bash - rm data/mcphub.db - npm run db:setup - ``` + + - 验证凭据是否正确 + - 检查 JWT 令牌是否有效 + - 尝试清除浏览器缓存和 cookie -## 获取帮助 - -如果您在设置过程中遇到问题： - -- 📖 查看 [完整文档](/zh/development/getting-started) -- 🐛 在 [GitHub](https://github.com/mcphub/mcphub/issues) 上报告问题 -- 💬 加入 [Discord 社区](https://discord.gg/mcphub) 获取实时帮助 -- 📧 发送邮件至 support@mcphub.io +需要更多帮助？加入我们的 [Discord 社区](https://discord.gg/qMKNsn5Q) 获取支持！