mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
418 lines
9.3 KiB
Plaintext
418 lines
9.3 KiB
Plaintext
---
|
||
title: '服务器管理'
|
||
description: '通过热插拔配置集中管理多个 MCP 服务器'
|
||
---
|
||
|
||
## 概述
|
||
|
||
MCPHub 的服务器管理系统允许您从单个仪表板集中配置、监控和控制多个 MCP（模型上下文协议）服务器。所有更改都会实时应用，无需重启服务器。
|
||
|
||
## 添加 MCP 服务器
|
||
|
||
### 通过仪表板
|
||
|
||
1. **访问仪表板**: 导航到 `http://localhost:3000` 并登录
|
||
2. **点击"添加服务器"**: 位于服务器部分
|
||
3. **填写服务器详细信息**:
|
||
- **名称**: 服务器的唯一标识符
|
||
- **命令**: 可执行命令（例如 `npx`、`uvx`、`python`）
|
||
- **参数**: 命令参数数组
|
||
- **环境变量**: 环境设置的键值对
|
||
- **工作目录**: 命令的可选工作目录
|
||
|
||
### 通过配置文件
|
||
|
||
编辑您的 `mcp_settings.json` 文件：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"server-name": {
|
||
"command": "command-to-run",
|
||
"args": ["arg1", "arg2"],
|
||
"env": {
|
||
"API_KEY": "your-api-key",
|
||
"CONFIG_VALUE": "some-value"
|
||
},
|
||
"cwd": "/optional/working/directory"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 通过 API
|
||
|
||
使用 REST API 以编程方式添加服务器：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/servers \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-d '{
|
||
"name": "fetch-server",
|
||
"command": "uvx",
|
||
"args": ["mcp-server-fetch"],
|
||
"env": {}
|
||
}'
|
||
```
|
||
|
||
## 流行的 MCP 服务器示例
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="Web 抓取服务器">
|
||
提供网页抓取和 HTTP 请求功能：
|
||
|
||
```json
|
||
{
|
||
"fetch": {
|
||
"command": "uvx",
|
||
"args": ["mcp-server-fetch"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**可用工具:**
|
||
- `fetch`: 发起 HTTP 请求
|
||
- `fetch_html`: 抓取网页
|
||
- `fetch_json`: 从 API 获取 JSON 数据
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Playwright 浏览器自动化">
|
||
用于网页交互的浏览器自动化：
|
||
|
||
```json
|
||
{
|
||
"playwright": {
|
||
"command": "npx",
|
||
"args": ["@playwright/mcp@latest", "--headless"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**可用工具:**
|
||
- `playwright_navigate`: 导航到网页
|
||
- `playwright_screenshot`: 截取屏幕截图
|
||
- `playwright_click`: 点击元素
|
||
- `playwright_fill`: 填写表单
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="文件系统操作">
|
||
文件和目录管理：
|
||
|
||
```json
|
||
{
|
||
"filesystem": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**可用工具:**
|
||
- `read_file`: 读取文件内容
|
||
- `write_file`: 写入文件
|
||
- `create_directory`: 创建目录
|
||
- `list_directory`: 列出目录内容
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="SQLite 数据库">
|
||
数据库操作：
|
||
|
||
```json
|
||
{
|
||
"sqlite": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**可用工具:**
|
||
- `execute_query`: 执行 SQL 查询
|
||
- `describe_tables`: 获取表结构
|
||
- `create_table`: 创建新表
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Slack 集成">
|
||
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`: 获取线程消息
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="GitHub 集成">
|
||
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`: 创建拉取请求
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Google Drive">
|
||
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`: 创建新文件
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="高德地图（中国）">
|
||
中国地图和位置服务：
|
||
|
||
```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`: 将坐标转换为地址
|
||
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
## 服务器生命周期管理
|
||
|
||
### 启动服务器
|
||
|
||
服务器会在以下情况下自动启动：
|
||
|
||
- MCPHub 启动时
|
||
- 通过仪表板或 API 添加服务器时
|
||
- 服务器配置更新时
|
||
- 手动重启已停止的服务器时
|
||
|
||
### 停止服务器
|
||
|
||
您可以通过以下方式停止服务器：
|
||
|
||
- **通过仪表板**: 切换服务器状态开关
|
||
- **通过 API**: 发送 POST 请求到 `/api/servers/{name}/toggle`
|
||
- **自动停止**: 服务器崩溃或遇到错误时会自动停止
|
||
|
||
### 重启服务器
|
||
|
||
服务器会在以下情况下自动重启：
|
||
|
||
- 配置更改时
|
||
- 环境变量更新后
|
||
- 通过仪表板或 API 手动触发时
|
||
|
||
## 服务器状态监控
|
||
|
||
### 状态指示器
|
||
|
||
每个服务器都显示状态指示器：
|
||
|
||
- 🟢 **运行中**: 服务器处于活动状态并响应
|
||
- 🟡 **启动中**: 服务器正在初始化
|
||
- 🔴 **已停止**: 服务器未运行
|
||
- ⚠️ **错误**: 服务器遇到错误
|
||
|
||
### 实时日志
|
||
|
||
实时查看服务器日志：
|
||
|
||
1. **仪表板日志**: 点击服务器查看其日志
|
||
2. **API 日志**: 通过 `/api/logs` 端点访问日志
|
||
3. **流式日志**: 通过 WebSocket 订阅日志流
|
||
|
||
### 健康检查
|
||
|
||
MCPHub 自动执行健康检查：
|
||
|
||
- **初始化检查**: 验证服务器成功启动
|
||
- **工具发现**: 确认检测到可用工具
|
||
- **响应检查**: 测试服务器响应性
|
||
- **资源监控**: 跟踪 CPU 和内存使用情况
|
||
|
||
## 配置管理
|
||
|
||
### 环境变量
|
||
|
||
服务器可以使用环境变量进行配置：
|
||
|
||
```json
|
||
{
|
||
"server-name": {
|
||
"command": "python",
|
||
"args": ["server.py"],
|
||
"env": {
|
||
"API_KEY": "${YOUR_API_KEY}",
|
||
"DEBUG": "true",
|
||
"MAX_CONNECTIONS": "10"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**环境变量展开:**
|
||
|
||
- `${VAR_NAME}`: 展开为环境变量值
|
||
- `${VAR_NAME:-default}`: 如果变量未设置则使用默认值
|
||
- `${VAR_NAME:+value}`: 如果变量已设置则使用指定值
|
||
|
||
### 命令变体
|
||
|
||
指定服务器命令的不同方式：
|
||
|
||
<Tabs>
|
||
<Tab title="npm/npx">
|
||
```json
|
||
{
|
||
"npm-server": {
|
||
"command": "npx",
|
||
"args": ["-y", "package-name", "--option", "value"]
|
||
}
|
||
}
|
||
```
|
||
</Tab>
|
||
|
||
<Tab title="Python/uvx">
|
||
```json
|
||
{
|
||
"python-server": {
|
||
"command": "uvx",
|
||
"args": ["package-name", "--config", "config.json"]
|
||
}
|
||
}
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## 高级功能
|
||
|
||
### 热重载
|
||
|
||
MCPHub 支持服务器配置的热重载：
|
||
|
||
1. **仪表板更新**: 立即应用通过 Web 界面进行的更改
|
||
2. **API 更新**: 通过 REST API 调用进行实时更新
|
||
3. **零停机时间**: 优雅的服务器重启，不影响其他服务器
|
||
|
||
## 故障排除
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="服务器无法启动">
|
||
**检查以下项目:**
|
||
- 命令在 PATH 中可用
|
||
- 已设置所有必需的环境变量
|
||
- 工作目录存在且可访问
|
||
- 网络端口未被阻塞
|
||
- 依赖项已安装
|
||
|
||
**调试步骤:**
|
||
1. 在仪表板中检查服务器日志
|
||
2. 在终端中手动测试命令
|
||
3. 验证环境变量展开
|
||
4. 检查文件权限
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="服务器持续崩溃">
|
||
**常见原因:**
|
||
- 无效的配置参数
|
||
- 缺少 API 密钥或凭据
|
||
- 超出资源限制
|
||
- 依赖项冲突
|
||
|
||
**解决方案:**
|
||
1. 查看服务器日志中的错误消息
|
||
2. 使用最小配置进行测试
|
||
3. 验证所有凭据和 API 密钥
|
||
4. 检查系统资源可用性
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="工具未显示">
|
||
**可能的问题:**
|
||
- 服务器未完全初始化
|
||
- 工具发现超时
|
||
- 通信协议不匹配
|
||
- 服务器报告错误
|
||
|
||
**调试步骤:**
|
||
1. 等待服务器初始化完成
|
||
2. 检查服务器日志中的工具注册消息
|
||
3. 测试与服务器的直接通信
|
||
4. 验证 MCP 协议兼容性
|
||
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
## 下一步
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="分组管理" icon="users" href="/zh/features/group-management">
|
||
将服务器组织成逻辑分组
|
||
</Card>
|
||
<Card title="智能路由" icon="route" href="/zh/features/smart-routing">
|
||
设置 AI 驱动的工具发现
|
||
</Card>
|
||
<Card title="API 参考" icon="code" href="/zh/api-reference/servers">
|
||
服务器管理 API 文档
|
||
</Card>
|
||
<Card title="配置指南" icon="cog" href="/zh/configuration/mcp-settings">
|
||
详细配置选项
|
||
</Card>
|
||
</CardGroup>
|