fix: simplify server status labels in English and Chinese locales (#128)

This commit is contained in:
samanhappy
2025-05-28 18:20:43 +08:00
committed by GitHub
parent 39b69bf550
commit e019c9e8b3
9 changed files with 355 additions and 22 deletions

View File

@@ -18,7 +18,7 @@ MCPHub makes it easy to manage and scale multiple MCP (Model Context Protocol) s
## 🔧 Quick Start ## 🔧 Quick Start
### Optional Configuration ### Configuration
Create a `mcp_settings.json` file to customize your server settings: Create a `mcp_settings.json` file to customize your server settings:
@@ -96,6 +96,31 @@ This endpoint provides a unified streamable HTTP interface for all your MCP serv
- Easily integrate with various AI clients and tools - Easily integrate with various AI clients and tools
- Use the same endpoint for all servers, simplifying your integration process - Use the same endpoint for all servers, simplifying your integration process
**Smart Routing (Experimental)**:
Smart Routing is MCPHub's intelligent tool discovery system that uses vector semantic search to automatically find the most relevant tools for any given task.
```
http://localhost:3000/mcp/$smart
```
**How it Works:**
1. **Tool Indexing**: All MCP tools are automatically converted to vector embeddings and stored in PostgreSQL with pgvector
2. **Semantic Search**: User queries are converted to vectors and matched against tool embeddings using cosine similarity
3. **Intelligent Filtering**: Dynamic thresholds ensure relevant results without noise
4. **Precise Execution**: Found tools can be directly executed with proper parameter validation
**Setup Requirements:**
![Smart Routing](assets/smart-routing.png)
To enable Smart Routing, you need:
- PostgreSQL with pgvector extension
- OpenAI API key (or compatible embedding service)
- Enable Smart Routing in MCPHub settings
**Group-Specific Endpoints (Recommended)**: **Group-Specific Endpoints (Recommended)**:
![Group Management](assets/group.png) ![Group Management](assets/group.png)
@@ -131,6 +156,12 @@ Connect AI clients (e.g., Claude Desktop, Cursor, DeepChat, etc.) via:
http://localhost:3000/sse http://localhost:3000/sse
``` ```
For smart routing, use:
```
http://localhost:3000/sse/$smart
```
For targeted access to specific server groups, use the group-based SSE endpoint: For targeted access to specific server groups, use the group-based SSE endpoint:
``` ```

View File

@@ -18,7 +18,7 @@ MCPHub 通过将多个 MCPModel Context Protocol服务器组织为灵活
## 🔧 快速开始 ## 🔧 快速开始
### 可选配置 ### 配置
通过创建 `mcp_settings.json` 自定义服务器设置: 通过创建 `mcp_settings.json` 自定义服务器设置:
@@ -96,6 +96,31 @@ http://localhost:3000/mcp
- 轻松与各种 AI 客户端和工具集成 - 轻松与各种 AI 客户端和工具集成
- 对所有服务器使用相同的端点,简化集成过程 - 对所有服务器使用相同的端点,简化集成过程
**智能路由(实验性功能)**
智能路由是 MCPHub 的智能工具发现系统,使用向量语义搜索自动为任何给定任务找到最相关的工具。
```
http://localhost:3000/mcp/$smart
```
**工作原理:**
1. **工具索引**:所有 MCP 工具自动转换为向量嵌入并存储在 PostgreSQL 与 pgvector 中
2. **语义搜索**:用户查询转换为向量并使用余弦相似度与工具嵌入匹配
3. **智能筛选**:动态阈值确保相关结果且无噪声
4. **精确执行**:找到的工具可以直接执行并进行适当的参数验证
**设置要求:**
![智能路由](assets/smart-routing.zh.png)
为了启用智能路由,您需要:
- 支持 pgvector 扩展的 PostgreSQL
- OpenAI API 密钥(或兼容的嵌入服务)
- 在 MCPHub 设置中启用智能路由
**基于分组的 HTTP 端点(推荐)** **基于分组的 HTTP 端点(推荐)**
![分组](assets/group.zh.png) ![分组](assets/group.zh.png)
要针对特定服务器分组进行访问,请使用基于分组的 HTTP 端点: 要针对特定服务器分组进行访问,请使用基于分组的 HTTP 端点:
@@ -131,6 +156,12 @@ http://localhost:3000/mcp/{server}
http://localhost:3000/sse http://localhost:3000/sse
``` ```
要启用智能路由,请使用:
```
http://localhost:3000/sse/$smart
```
要针对特定服务器分组进行访问,请使用基于分组的 SSE 端点: 要针对特定服务器分组进行访问,请使用基于分组的 SSE 端点:
``` ```

BIN
assets/smart-routing.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

BIN
assets/smart-routing.zh.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

271
doc/smart-routing.md Normal file
View File

@@ -0,0 +1,271 @@
# 智能工具发现精准调用MCPHub 智能路由重新定义 AI 工具选择
## 概述
在现代 AI 应用中,随着 MCP 服务器数量的快速增长和工具种类的日益丰富如何从数百个可用工具中快速找到最适合当前任务的工具成为了一个日益突出的挑战。传统方式下AI 助手要么被迫处理所有可用工具的庞大列表,导致 token 消耗激增和响应延迟要么依赖开发者手动分组缺乏灵活性和智能化。MCPHub 的智能路由功能基于向量语义搜索技术,实现了自然语言驱动的工具发现与精准推荐,让 AI 助手能够像人类专家一样,根据任务描述智能地选择最合适的工具组合,大幅提升工作效率和用户体验。
## 智能路由是什么
### 技术原理
智能路由是 MCPHub 的核心创新功能,它基于现代向量语义搜索技术,将每个 MCP 工具的描述、参数和功能特征转换为高维向量表示。当用户提出任务需求时,系统将需求同样转换为向量,通过计算向量间的余弦相似度,快速定位最相关的工具集合。这种方法不依赖精确的关键词匹配,而是理解语义层面的相关性,能够处理自然语言的模糊性和多样性。
### 核心组件
**向量嵌入引擎**:支持 OpenAI text-embedding-3-small、BGE-M3 等多种主流嵌入模型,将工具描述转换为 1536 维或 1024 维向量表示,捕获工具功能的语义特征。
**PostgreSQL + pgvector 数据库**:采用业界领先的向量数据库解决方案,支持高效的向量索引和相似度搜索,能够在毫秒级时间内从大量工具中找到最相关的候选。
**动态阈值算法**根据查询复杂度和具体程度自动调整相似度阈值确保既不遗漏相关工具也不引入无关噪声。简单查询使用较低阈值0.2获得更多样化结果具体查询使用较高阈值0.4)确保精确匹配。
**两步工作流**`search_tools` 负责工具发现,`call_tool` 负责工具执行,清晰分离发现和执行逻辑,提供更好的可控性和调试体验。
## 为什么要使用智能路由
### 1. 解决工具选择的认知负荷
- **信息过载问题**:当 MCP 服务器数量超过 10 个、工具总数超过 100 个时AI 助手面临严重的信息过载,难以在合理时间内做出最优选择。
- **智能路由优势**:通过语义搜索将候选工具缩减到 5-10 个最相关的选项,让 AI 助手能够专注于理解和使用最合适的工具,而不是被迫处理庞大的工具清单。
### 2. 大幅降低 Token 消耗
- **传统方式的成本**:向 AI 模型传递完整的工具列表会消耗大量 token特别是当工具描述详细时单次请求可能消耗数千 token。
- **智能路由的效益**:只传递最相关的工具信息,通常可以将工具相关的 token 消耗降低 70-90%,显著减少 API 调用成本,特别是在频繁交互的场景中。
### 3. 提升工具使用的准确性
- **语义理解能力**:智能路由能够理解"图片处理"、"数据分析"、"文档转换"等抽象概念,将其映射到具体的工具实现,避免了传统关键词匹配的局限性。
- **上下文感知**:考虑工具的输入输出模式和使用场景,推荐最适合当前任务流程的工具组合。
![智能路由工作原理](../assets/smart-routing-flow.png)
## 如何使用智能路由
### 配置智能路由
#### 1. 数据库配置
智能路由需要 PostgreSQL 数据库支持 pgvector 扩展:
```bash
# 使用 Docker 快速启动支持 pgvector 的 PostgreSQL
docker run --name mcphub-postgres \
-e POSTGRES_DB=mcphub \
-e POSTGRES_USER=mcphub \
-e POSTGRES_PASSWORD=your_password \
-p 5432:5432 \
-d pgvector/pgvector:pg16
```
#### 2. 在 MCPHub 控制台配置智能路由
访问 MCPHub 设置页面http://localhost:3000/settings在"智能路由配置"部分填写:
- **数据库 URL**`postgresql://mcphub:your_password@localhost:5432/mcphub`
- **OpenAI API Key**:您的 OpenAI API 密钥
- **API Base URL**:可选,默认为 `https://api.openai.com/v1`
- **嵌入模型**:推荐使用 `text-embedding-3-small`1536 维,性价比最佳)
![智能路由配置界面](../assets/smart-routing-config.png)
#### 3. 启用智能路由
配置完成后,开启"启用智能路由"开关。系统将自动:
- 为所有已连接的 MCP 服务器工具生成向量嵌入
- 建立向量索引以支持快速搜索
- 在后续新增工具时自动更新向量数据库
### 智能工具发现的使用方式
启用智能路由后MCPHub 会自动提供两个核心工具:
#### search_tools - 智能工具搜索
```typescript
// 使用示例
{
"name": "search_tools",
"arguments": {
"query": "help me process images and resize them", // 自然语言查询
"limit": 10 // 返回结果数量
}
}
```
**查询策略建议**
- **宽泛查询**:使用较高的 limit20-30如"数据处理工具"
- **精确查询**:使用较低的 limit5-10如"将 PNG 图片转换为 WebP 格式"
- **分步查询**:复杂任务可以分解为多个具体查询
#### call_tool - 精准工具执行
```typescript
// 使用示例
{
"name": "call_tool",
"arguments": {
"toolName": "image_resize", // 从 search_tools 结果中获取的工具名
"arguments": { // 根据工具的 inputSchema 提供参数
"input_path": "/path/to/image.png",
"width": 800,
"height": 600
}
}
}
```
### 实际应用场景演示
#### 场景 1图像处理工作流
```markdown
用户请求:我需要批量处理一些产品图片,调整大小并转换格式
AI 工作流:
1. search_tools("image processing batch resize convert format")
→ 返回image_batch_processor, format_converter, image_optimizer
2. call_tool("image_batch_processor", {...})
→ 执行批量图像处理
```
#### 场景 2数据分析任务
```markdown
用户请求:分析这个 CSV 文件的销售数据,生成可视化图表
AI 工作流:
1. search_tools("CSV data analysis visualization charts")
→ 返回csv_analyzer, chart_generator, statistics_calculator
2. call_tool("csv_analyzer", {"file_path": "sales.csv"})
3. call_tool("chart_generator", {"data": analysis_result})
```
#### 场景 3文档处理流水线
```markdown
用户请求:将 Word 文档转换为 PDF然后提取其中的文本内容
AI 工作流:
1. search_tools("document conversion Word to PDF")
→ 返回doc_converter, pdf_generator
2. call_tool("doc_converter", {"input": "document.docx", "output_format": "pdf"})
3. search_tools("PDF text extraction")
→ 返回pdf_text_extractor, ocr_processor
4. call_tool("pdf_text_extractor", {"pdf_path": "document.pdf"})
```
### 高级配置选项
#### 多模型支持
智能路由支持多种嵌入模型,可根据需求选择:
```json
{
"embeddingModel": "text-embedding-3-small", // OpenAI1536维平衡性能和成本
"embeddingModel": "text-embedding-3-large", // OpenAI3072维最高精度
"embeddingModel": "bge-m3" // 开源模型1024维支持多语言
}
```
#### 自定义 API 端点
支持使用自建的嵌入服务或其他 OpenAI 兼容的 API
```json
{
"openaiApiBaseUrl": "https://your-api-endpoint.com/v1",
"openaiApiKey": "your-custom-api-key"
}
```
## 性能优化与最佳实践
### 查询优化策略
**分层查询**:对于复杂任务,使用从宽泛到具体的查询策略:
```
1. 宽泛查询:"文档处理工具" (limit: 20)
2. 具体查询:"PDF 转 Word 转换器" (limit: 5)
```
**上下文相关性**:在查询中包含任务上下文信息:
```
search_tools("为电商网站批量压缩产品图片")
较好search_tools("图片压缩工具")
```
**动态调整**:根据返回结果质量动态调整查询词和限制数量。
### 数据库性能调优
**索引优化**:智能路由自动创建最优的向量索引:
```sql
CREATE INDEX idx_vector_embeddings_embedding
ON vector_embeddings USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
```
**内存配置**:对于大规模部署,建议增加 PostgreSQL 内存配置:
```
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 64MB
```
### 监控与调试
**相似度阈值监控**:观察搜索结果的相似度分数,调整阈值以获得最佳效果。
**查询效果分析**:定期检查常用查询的返回结果,优化工具描述以提高搜索准确性。
## 智能路由的技术优势
### 语义理解能力
与传统的关键词匹配相比,智能路由能够理解:
- **同义词和近义词**"图片"和"图像"、"转换"和"变换"
- **上下层级概念**"数据可视化"包含"图表生成"、"统计图绘制"等
- **任务意图推理**"我要做一个数据报告"自动关联数据分析、图表生成、文档创建等工具
### 多语言支持
智能路由支持中英文混合查询,能够处理:
```
search_tools("图片 resize 和 format conversion")
search_tools("将文档转换为 PDF 格式")
search_tools("image processing and 格式转换")
```
### 容错能力
具备一定的容错能力,能够处理:
- 拼写错误:自动纠正常见拼写错误
- 模糊描述:从不完整的描述中推导完整意图
- 领域术语:理解特定领域的专业术语
## 结语
MCPHub 的智能路由功能代表着 MCP 生态系统向智能化方向发展的重要一步。通过引入向量语义搜索技术,它不仅解决了工具数量激增带来的选择困难,更为 AI 助手提供了类似人类专家的工具发现和选择能力。
随着 MCP 服务器生态的不断丰富,智能路由将成为连接用户需求与丰富工具资源的关键桥梁。它让开发者无需担心工具管理的复杂性,让用户享受到更加智能和高效的 AI 助手体验。
未来,我们还将继续优化智能路由的算法,引入更多先进的 AI 技术,如基于强化学习的工具推荐、多模态工具理解等,为 MCP 生态系统注入更强的智能化动力。
智能路由不仅仅是一个技术功能,更是 MCPHub 对于"让 AI 工具使用变得简单而智能"这一愿景的具体实现。在这个工具爆炸的时代,智能路由让我们重新定义了 AI 与工具的交互方式。
项目地址https://github.com/samanhappy/mcphub
![智能路由架构图](../assets/smart-routing-architecture.png)

View File

@@ -69,7 +69,7 @@ const AddServerForm = ({ onAdd }: AddServerFormProps) => {
<div> <div>
<button <button
onClick={toggleModal} onClick={toggleModal}
className="w-full bg-blue-500 hover:bg-blue-600 text-white font-medium py-2 px-4 rounded" className="w-full bg-blue-100 text-blue-800 rounded hover:bg-blue-200 py-2 px-4"
> >
{t('server.addServer')} {t('server.addServer')}
</button> </button>

View File

@@ -153,10 +153,10 @@
"pages": { "pages": {
"dashboard": { "dashboard": {
"title": "Dashboard", "title": "Dashboard",
"totalServers": "Total Servers", "totalServers": "Total",
"onlineServers": "Online Servers", "onlineServers": "Online",
"offlineServers": "Offline Servers", "offlineServers": "Offline",
"connectingServers": "Connecting Servers", "connectingServers": "Connecting",
"recentServers": "Recent Servers" "recentServers": "Recent Servers"
}, },
"servers": { "servers": {

View File

@@ -154,10 +154,10 @@
"pages": { "pages": {
"dashboard": { "dashboard": {
"title": "仪表盘", "title": "仪表盘",
"totalServers": "服务器总数", "totalServers": "总数",
"onlineServers": "在线服务器", "onlineServers": "在线",
"offlineServers": "离线服务器", "offlineServers": "离线",
"connectingServers": "连接中服务", "connectingServers": "连接中",
"recentServers": "最近的服务器" "recentServers": "最近的服务器"
}, },
"servers": { "servers": {
@@ -283,7 +283,7 @@
"installConfig": "安装配置", "installConfig": "安装配置",
"systemConfigUpdated": "系统配置更新成功", "systemConfigUpdated": "系统配置更新成功",
"enableSmartRouting": "启用智能路由", "enableSmartRouting": "启用智能路由",
"enableSmartRoutingDescription": "开启智能路由功能,根据输入自动搜索最合适的工具", "enableSmartRoutingDescription": "开启智能路由功能,根据输入自动搜索最合适的工具(使用 $smart 分组)",
"dbUrl": "PostgreSQL 连接地址(支持 pgvector", "dbUrl": "PostgreSQL 连接地址(支持 pgvector",
"dbUrlPlaceholder": "例如: postgresql://user:password@localhost:5432/dbname", "dbUrlPlaceholder": "例如: postgresql://user:password@localhost:5432/dbname",
"openaiApiBaseUrl": "OpenAI API 基础地址", "openaiApiBaseUrl": "OpenAI API 基础地址",

View File

@@ -10,16 +10,16 @@ import { useServerData } from '@/hooks/useServerData';
const ServersPage: React.FC = () => { const ServersPage: React.FC = () => {
const { t } = useTranslation(); const { t } = useTranslation();
const navigate = useNavigate(); const navigate = useNavigate();
const { const {
servers, servers,
error, error,
setError, setError,
isLoading, isLoading,
handleServerAdd, handleServerAdd,
handleServerEdit, handleServerEdit,
handleServerRemove, handleServerRemove,
handleServerToggle, handleServerToggle,
triggerRefresh triggerRefresh
} = useServerData(); } = useServerData();
const [editingServer, setEditingServer] = useState<Server | null>(null); const [editingServer, setEditingServer] = useState<Server | null>(null);
const [isRefreshing, setIsRefreshing] = useState(false); const [isRefreshing, setIsRefreshing] = useState(false);
@@ -54,7 +54,7 @@ const ServersPage: React.FC = () => {
<div className="flex space-x-4"> <div className="flex space-x-4">
<button <button
onClick={() => navigate('/market')} onClick={() => navigate('/market')}
className="px-4 py-2 bg-emerald-100 text-emerald-800 rounded hover:bg-emerald-200 flex items-center" className="px-4 py-2 bg-blue-100 text-blue-800 rounded hover:bg-blue-200 flex items-center"
> >
<svg xmlns="http://www.w3.org/2000/svg" className="h-4 w-4 mr-2" viewBox="0 0 20 20" fill="currentColor"> <svg xmlns="http://www.w3.org/2000/svg" className="h-4 w-4 mr-2" viewBox="0 0 20 20" fill="currentColor">
<path d="M3 1a1 1 0 000 2h1.22l.305 1.222a.997.997 0 00.01.042l1.358 5.43-.893.892C3.74 11.846 4.632 14 6.414 14H15a1 1 0 000-2H6.414l1-1H14a1 1 0 00.894-.553l3-6A1 1 0 0017 3H6.28l-.31-1.243A1 1 0 005 1H3z" /> <path d="M3 1a1 1 0 000 2h1.22l.305 1.222a.997.997 0 00.01.042l1.358 5.43-.893.892C3.74 11.846 4.632 14 6.414 14H15a1 1 0 000-2H6.414l1-1H14a1 1 0 00.894-.553l3-6A1 1 0 0017 3H6.28l-.31-1.243A1 1 0 005 1H3z" />