Skip to main content

​
概述

智能路由是 MCPHub 的智能工具发现系统，它使用向量语义搜索来自动找到与任何给定任务最相关的工具。AI 客户端无需手动指定使用哪些工具，只需描述他们想要完成的任务，智能路由就会识别并提供对最合适工具的访问。

​
智能路由的工作原理

​
1. 工具索引

当服务器启动时，智能路由会自动：
  • 从 MCP 服务器发现所有可用工具
  • 提取工具元数据（名称、描述、参数）
  • 将工具信息转换为向量嵌入
  • 使用 pgvector 将嵌入存储在 PostgreSQL 中

​
2. 语义搜索

当进行查询时：
  • 用户查询被转换为向量嵌入
  • 相似性搜索使用余弦相似度找到匹配的工具
  • 动态阈值过滤掉不相关的结果
  • 结果按相关性得分排序

​
3. 智能过滤

智能路由应用多个过滤器：
  • 相关性阈值：只返回高于相似性阈值的工具
  • 上下文感知：考虑对话上下文
  • 工具可用性：确保工具当前可访问
  • 权限过滤：尊重用户访问权限

​
4. 工具执行

找到的工具可以直接执行：
  • 参数验证确保正确的工具使用
  • 错误处理提供有用的反馈
  • 响应格式保持一致性
  • 日志记录跟踪工具使用情况进行分析

​
前置条件

智能路由需要比基础 MCPHub 使用更多的设置：

​
必需组件

  1. 带有 pgvector 的 PostgreSQL：用于嵌入存储的向量数据库
  2. 嵌入服务：OpenAI API 或兼容服务
  3. 环境配置：正确的配置变量

​
使用智能路由

​
智能路由端点

通过特殊的 $smart 端点访问智能路由： 
# 搜索所有服务器
http://localhost:3000/mcp/$smart

# 在特定分组内搜索
http://localhost:3000/mcp/$smart/{group}

​
分组范围的智能路由

智能路由支持分组范围的搜索，允许您将工具发现限制在特定分组内的服务器：
将您的 AI 客户端连接到特定分组的智能路由端点：
http://localhost:3000/mcp/$smart/production
此端点只会搜索属于 “production” 分组的服务器中的工具。优势：
  • 聚焦结果：只返回相关服务器的工具
  • 更好的性能：减少搜索空间以加快查询速度
  • 环境隔离：将开发、预发布和生产工具分开
  • 访问控制：根据用户权限限制工具发现
当使用 $smart/{group} 时：
  1. 系统识别指定的分组
  2. 获取属于该分组的所有服务器
  3. 将工具搜索过滤到仅限那些服务器
  4. 返回限定在该分组服务器范围内的结果
如果分组不存在或没有服务器，搜索将不返回任何结果。

​
渐进式披露模式

渐进式披露是一个优化功能，可以减少使用智能路由时的 Token 消耗。启用后，工具发现工作流从 2 步变为 3 步。
默认情况下，智能路由在 search_tools 结果中返回完整的工具信息，包括完整的参数模式。当处理具有复杂输入模式的工具时，这会消耗大量 Token。渐进式披露 改变了这种行为：
  • search_tools 只返回工具名称和描述（最少信息）
  • 新的 describe_tool 端点按需提供完整的参数模式
  • call_tool 像以前一样执行工具
这种方法特别适用于：
  • 处理具有复杂模式的大量工具
  • Token 使用优化很重要的场景
  • AI 客户端需要浏览多个工具后再选择
通过设置页面或环境变量启用渐进式披露：通过设置界面：
  1. 导航到 设置 → 智能路由
  2. 启用”渐进式披露”开关
  3. 更改立即生效
通过环境变量：
SMART_ROUTING_PROGRESSIVE_DISCLOSURE=true
当渐进式披露禁用（默认）时，智能路由提供两个工具：工作流： search_tools → call_tool
工具用途
search_tools按查询查找工具，返回包含 inputSchema 的完整工具信息
call_tool使用提供的参数执行工具
这种模式更简单，但由于搜索结果中包含完整模式，会使用更多 Token。
当渐进式披露启用时，智能路由提供三个工具：工作流： search_tools → describe_tool → call_tool
工具用途
search_tools按查询查找工具，只返回名称和描述
describe_tool获取特定工具的完整模式（新增）
call_tool使用提供的参数执行工具
示例工作流：
  1. AI 使用查询 “文件操作” 调用 search_tools
  2. 结果显示工具名称和描述（最少 Token）
  3. AI 为特定工具调用 describe_tool 获取完整的 inputSchema
  4. AI 使用正确的参数调用 call_tool
这种模式通过仅在需要时获取完整模式来减少 Token 使用。
标准模式 search_tools 响应：
{
  "tools": [
    {
      "name": "read_file",
      "description": "读取文件内容",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "要读取的文件路径" },
          "encoding": { "type": "string", "default": "utf-8" }
        },
        "required": ["path"]
      }
    }
  ]
}
渐进式披露模式 search_tools 响应：
{
  "tools": [
    {
      "name": "read_file",
      "description": "读取文件内容"
    }
  ],
  "metadata": {
    "progressiveDisclosure": true,
    "guideline": "使用 describe_tool 获取完整的参数模式后再调用。"
  }
}
describe_tool 响应：
{
  "tool": {
    "name": "read_file",
    "description": "读取文件内容",
    "inputSchema": {
      "type": "object",
      "properties": {
        "path": { "type": "string", "description": "要读取的文件路径" },
        "encoding": { "type": "string", "default": "utf-8" }
      },
      "required": ["path"]
    }
  }
}

​
故障排除

症状：
  • 智能路由不可用
  • 数据库连接错误
  • 嵌入存储失败
解决方案：
  1. 验证 PostgreSQL 是否正在运行
  2. 检查 DB_URL 格式
  3. 确保安装了 pgvector 扩展
  4. 手动测试连接：
psql $DB_URL -c "SELECT 1;"
症状：
  • 工具索引失败
  • 查询处理错误
  • API 速率限制错误
解决方案：
  1. 验证 API 密钥有效性
  2. 检查网络连接
  3. 监控速率限制
  4. 测试嵌入服务：
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. 使用更好的描述重新索引工具
  3. 使用更具体的查询
  4. 检查工具元数据质量
# 重新索引所有工具
curl -X POST http://localhost:3000/api/smart-routing/reindex \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
症状：
  • 查询响应缓慢
  • 数据库负载高
  • 内存使用激增
解决方案：
  1. 优化数据库配置
  2. 增加缓存大小
  3. 减少批处理大小
  4. 监控系统资源
# 检查系统性能
curl http://localhost:3000/api/smart-routing/performance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
最佳实践

​
查询编写

要具体描述：在查询中使用具体、描述性的语言以获得更好的工具匹配。
包含上下文：提供有关您的任务或领域的相关上下文以获得更准确的结果。
使用自然语言：像向人类描述任务一样编写查询。

​
工具描述

质量元数据：确保 MCP 服务器提供高质量的工具描述和元数据。
定期更新：随着功能的发展保持工具描述的最新状态。
一致的命名：在工具和服务器中使用一致的命名约定。

​
系统维护

定期重新索引：定期重新索引工具以确保嵌入质量。
监控性能：跟踪查询模式并根据使用情况进行优化。
更新模型：随着新嵌入模型的出现，考虑更新到更新的模型。

​
下一步

身份验证

用户管理和访问控制

监控

系统监控和分析

API 参考

完整的智能路由 API 文档

配置

高级配置选项