跳到主要内容

MCP工具调用系统

GeniSpace 智能体支持强大的MCP（Model Context Protocol）工具调用系统，能够通过内置工具和外部MCP服务器扩展智能体的能力边界。本指南详细介绍MCP工具的配置、使用和管理方法。

MCP工具概述​

什么是MCP工具​

MCP（Model Context Protocol）工具是一种标准化的接口协议，允许智能体调用外部功能和服务。GeniSpace实现了完整的MCP工具生态系统，包括：

  • 内置工具：通过平台工具提供的标准化工具
  • 外部工具：通过MCP服务器提供的第三方工具
  • 智能路由：自动识别和路由到正确的工具服务器

工具分类​

内置工具​

  • 来源：平台内置工具系统
  • 类型：HTML渲染、图表生成、表格展示等
  • 调用方式：通过mcp-server统一接口
  • 缓存策略：10分钟TTL，基于会话+智能体
  • 权限控制：可通过配置启用或禁用

平台算子工具​

  • 来源：平台算子系统和用户自定义算子
  • 调用方式：通过mcp-server统一接口
  • 命名规范：operator_identifier_method_identifier
  • 缓存策略：10分钟TTL，基于会话+智能体
  • 权限控制：支持全部算子或指定算子选择
  • 特点：
    • 显示算子详细信息（名称、标识符、描述）
    • 展示算子支持的方法列表
    • 区分自定义算子和系统算子

平台任务工具​

  • 来源：平台任务系统
  • 调用方式：智能体可以创建和执行任务
  • 任务类型：SCHEDULED（定时任务）、EVENT（事件任务）、MANUAL（手动任务）
  • 权限控制：支持全部任务或指定任务选择
  • 特点：
    • 显示任务名称、类型、描述
    • 智能体可以将任务作为工具调用
    • 支持任务编排和执行

平台数据源工具​

  • 来源：平台数据源系统
  • 调用方式：智能体可以直接查询和操作数据源
  • 操作类型：READ（读取）、CREATE（创建）、UPDATE（更新）、DELETE（删除）
  • 权限控制：支持全部数据源或指定数据源选择
  • 特点：
    • 显示数据源名称、操作类型、描述
    • 显示关联的数据库信息
    • 智能体可以执行SQL查询和数据操作

外部工具（MCP服务器工具）​

  • 来源：外部MCP服务器
  • 调用方式：直接调用外部MCP服务
  • 命名规范：由服务器定义
  • 缓存策略：5分钟TTL，全局共享
  • 扩展性：支持任意数量的外部服务器

MCP工具配置​

基础配置​

在智能体配置页面的"MCP工具"部分进行配置：

1. 启用MCP工具​

☑️ 启用MCP工具调用
  • 控制智能体是否可以使用MCP工具
  • 禁用后智能体将无法调用任何工具

2. 内置工具配置​

☑️ 启用内置工具
  • 控制是否启用平台内置的工具
  • 包括数据库查询、邮件发送、文件处理等

3. 算子选择策略​

○ 不使用工具 - 禁用所有算子访问
○ 全部算子 - 使用用户有权限的所有算子
○ 指定算子 - 仅使用选中的特定算子

指定算子选择：

  • 可以精确控制智能体可以使用的算子
  • 支持多选，适用于专业化场景
  • 显示算子名称、标识符、描述和方法列表
  • 区分自定义算子和系统算子
  • 有助于提高安全性和专业性

4. 任务选择策略​

○ 不使用任务 - 禁用所有任务访问
○ 全部任务 - 智能体可以创建和执行任何任务
○ 指定任务 - 仅限使用选中的任务

指定任务选择：

  • 控制智能体可以创建和执行的任务
  • 显示任务名称、类型（SCHEDULED/EVENT/MANUAL）、描述
  • 适用于有特定业务流程的场景
  • 防止智能体执行不相关的任务

5. 数据源选择策略​

○ 不使用数据源 - 禁用所有数据源访问
○ 全部数据源 - 智能体可以访问所有数据源
○ 指定数据源 - 仅限使用选中的数据源

指定数据源选择：

  • 控制智能体可以访问的数据源
  • 显示数据源名称、操作类型（READ/CREATE/UPDATE/DELETE）、描述
  • 显示关联的数据库信息
  • 适用于需要限制数据访问范围的场景
  • 提高数据安全性

外部MCP服务器配置​

添加外部服务器​

{
  "name": "自定义工具服务器",
  "endpoint": "https://your-mcp-server.com",
  "apiKey": "your-api-key",
  "description": "提供特定领域的专业工具",
  "tools": ["tool1", "tool2", "tool3"]
}

配置参数说明：

  • name：服务器显示名称
  • endpoint：MCP服务器API端点
  • apiKey：访问密钥（可选）
  • description：服务器功能描述
  • tools：可用工具列表

智能工具路由系统​

工具来源映射​

GeniSpace采用智能路由架构，自动构建工具来源映射表：

{
  "tool_name": {
    "type": "builtin|external",
    "server_name": "mcp-server|custom-server"
  }
}

路由策略​

自动路由（推荐）​

// 智能体会自动选择最合适的工具
await execute_tool("query_database", parameters, "auto");

指定类型路由​

// 强制使用内置工具
await execute_tool("query_database", parameters, "builtin");

// 强制使用外部工具
await execute_tool("custom_analysis", parameters, "external");

回退机制​

当智能路由失败时，系统会启用回退机制：

  1. 首先尝试内置工具
  2. 然后尝试外部工具
  3. 返回详细的错误信息

工具分析与执行​

智能工具分析​

系统使用大语言模型分析用户输入，决定是否需要使用工具：

分析因素​

  • 用户意图：分析用户的真实需求
  • 可用工具：检查当前可用的工具列表
  • 上下文信息：利用知识库和搜索结果
  • 执行历史：避免重复执行相同工具
  • 角色定义：基于智能体的专业角色

分析流程​

用户输入 → 意图识别 → 工具匹配 → 参数生成 → 执行决策

工具执行过程​

1. 参数验证​

  • 检查必需参数是否完整
  • 验证参数类型和格式
  • 应用默认值和约束条件

2. 权限检查​

  • 验证用户对工具的访问权限
  • 检查团队级别的工具配置
  • 确保符合安全策略

3. 工具调用​

  • 根据工具类型选择调用方式
  • 传递完整的上下文信息
  • 记录执行过程和结果

4. 结果处理​

  • 解析工具返回的结果
  • 生成执行摘要
  • 更新工具执行历史

错误恢复机制​

当工具执行失败时，系统提供智能错误恢复：

错误分析​

  • 解析错误类型和原因
  • 分析原始参数的问题
  • 提供参数修正建议

自动重试​

  • 基于错误信息重新生成参数
  • 智能调整工具调用策略
  • 提供详细的重试原因

错误类型处理​

  • 参数错误：重新分析和生成参数
  • 权限错误：检查访问配置
  • 网络错误：尝试重新连接
  • 业务错误：根据错误信息调整策略

缓存与性能优化​

多层缓存架构​

内置工具缓存​

  • TTL：10分钟（5-10分钟范围）
  • 键策略：{session_id}:{agent_id}
  • 存储内容：工具列表和元数据
  • 适用场景：工具相对稳定

外部工具缓存​

  • TTL：5分钟（2-5分钟范围）
  • 键策略：external_tools（全局）
  • 存储内容：外部服务器工具列表
  • 适用场景：外部工具可能变化频繁

会话缓存​

  • TTL：30分钟
  • 键策略：{team_id}:{user_id}:{agent_id}
  • 存储内容：MCP会话ID
  • 适用场景：维持会话状态

缓存管理​

自动过期​

// 缓存自动检查过期时间
{
  "data": tools_list,
  "expires_at": timestamp
}

手动清除​

// 清除特定智能体的缓存
clear_cache_for_agent(agent_id);

// 清除所有缓存
clear_cache("all");

// 清除特定类型缓存
clear_cache("builtin|external|sessions");

缓存统计​

{
  "builtin_tools": {"total": 15, "expired": 2, "valid": 13},
  "external_tools": {"total": 8, "expired": 0, "valid": 8},
  "sessions": {"total": 5, "expired": 1, "valid": 4}
}

显示插件系统​

插件概述​

智能体支持强大的显示插件系统，用于自定义工具输出结果的渲染方式：

  • 本地插件：内置在系统中的插件，如报销申请、差旅费用等
  • 远程插件：通过URL动态加载的独立插件项目
  • 自动发现：支持插件自动发现和注册
  • 热加载：开发模式下支持插件热重载

插件类型​

本地插件​

  • 位置：内置在聊天系统中
  • 加载方式：自动加载，无需配置
  • 示例：报销申请插件、差旅费用插件、URL重定向插件、Iframe嵌入插件

远程插件​

  • 加载方式：通过HTTP URL动态加载
  • 部署位置：GitHub Pages、CDN、自建服务器、企业内网
  • 优势：
    • 无需重新发布聊天系统
    • 独立版本管理
    • 支持企业自定义
    • 可部署到内网环境

插件配置​

在智能体配置中，可以通过以下方式配置显示插件：

  1. 自动加载：工具输出中包含插件URL时自动加载
  2. 手动加载：通过API手动加载远程插件
  3. 插件白名单：配置允许加载的插件URL

插件开发​

详细的插件开发指南请参考：

工具开发与集成​

内置工具开发​

工具规范​

  • 命名格式：{operator_id}_{method_id}
  • 参数定义：使用JSON Schema
  • 返回格式：标准化的MCP响应格式
  • 文档要求：详细的功能和参数说明

示例工具​

{
  "name": "database_query_sql",
  "description": "执行SQL查询获取数据库数据",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sql": {
        "type": "string",
        "description": "要执行的SQL查询语句"
      },
      "database": {
        "type": "string", 
        "description": "目标数据库名称"
      }
    },
    "required": ["sql"]
  }
}

外部MCP服务器开发​

标准MCP协议​

  • 实现标准的MCP接口规范
  • 支持工具列表查询
  • 提供工具执行接口
  • 返回标准化结果格式

服务器示例​

// 工具列表接口
GET /tools
{
  "tools": [
    {
      "name": "weather_query",
      "description": "查询天气信息",
      "parameters": {...}
    }
  ]
}

// 工具执行接口
POST /execute
{
  "tool": "weather_query",
  "parameters": {"city": "北京"}
}

API接口​

获取可用工具​

const tools = await fetch('/api/agents/mcp/tools', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Team-ID': team_id,
    'X-User-ID': user_id,
    'X-Agent-ID': agent_id
  }
});

执行工具​

const result = await fetch('/api/agents/mcp/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    toolName: 'database_query_sql',
    parameters: {sql: 'SELECT * FROM users LIMIT 10'},
    toolType: 'auto'
  })
});

清除工具缓存​

await fetch(`/api/agents/${agentId}/mcp/cache`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

最佳实践​

工具选择策略​

专业化智能体​

  • 算子选择：使用"指定算子"策略，只选择相关领域的算子
  • 任务选择：使用"指定任务"策略，限制可执行的任务类型
  • 数据源选择：使用"指定数据源"策略，限制可访问的数据源
  • 优势：提高响应准确性和专业性，增强安全性

通用智能体​

  • 算子选择：使用"全部算子"策略，提供广泛的功能覆盖
  • 任务选择：使用"全部任务"策略，允许执行任何任务
  • 数据源选择：使用"全部数据源"策略，允许访问所有数据源
  • 优势：适合多样化的任务需求，提供最大的灵活性

数据密集型智能体​

  • 算子选择：选择数据处理相关的算子
  • 数据源选择：使用"指定数据源"策略，选择需要的数据源
  • 任务选择：可选择数据同步、数据转换等任务
  • 优势：专注于数据处理和分析任务

任务编排智能体​

  • 任务选择：使用"指定任务"策略，选择需要编排的任务
  • 算子选择：选择任务执行所需的算子
  • 数据源选择：根据任务需求选择数据源
  • 优势：专注于任务编排和流程自动化

性能优化建议​

减少工具调用延迟​

  1. 合理配置缓存TTL：平衡数据新鲜度和性能
  2. 预热缓存：在智能体启动时预加载常用工具
  3. 批量操作：将多个相关操作合并为单次工具调用

提高工具执行成功率​

  1. 完善参数验证：在客户端进行初步参数检查
  2. 优化错误处理：提供清晰的错误信息和恢复建议
  3. 监控工具状态：定期检查外部服务器的可用性

安全考虑​

权限控制​

  • 严格限制工具访问权限
  • 定期审查工具使用情况
  • 实施最小权限原则

数据保护​

  • 避免在工具参数中传递敏感信息
  • 使用加密传输保护API通信
  • 记录和审计工具调用日志

故障排除​

常见问题​

工具列表为空​

原因：

  • MCP功能被禁用
  • 缓存过期或损坏
  • 权限配置错误

解决方案：

  1. 检查MCP配置是否启用
  2. 清除并重建缓存
  3. 验证用户权限设置

工具执行失败​

原因：

  • 参数格式错误
  • 权限不足
  • 外部服务不可用

解决方案：

  1. 检查参数是否符合工具要求
  2. 验证工具访问权限
  3. 测试外部服务器连接

性能问题​

原因：

  • 缓存命中率低
  • 外部服务响应慢
  • 工具调用频率过高

解决方案：

  1. 优化缓存策略
  2. 监控外部服务性能
  3. 实施调用频率限制

调试工具​

缓存统计​

// 获取详细的缓存统计信息
const stats = await getCacheStats();
console.log('缓存统计:', stats);

工具来源映射​

// 查看工具路由映射表
const mapping = await getToolSourceStats();
console.log('工具映射:', mapping);

执行日志​

// 检查工具执行历史
const history = await getToolExecutionHistory(agentId);
console.log('执行历史:', history);

下一步​

探索更多相关功能：

相关指南：