Mofox-Core/docs/MCP_TOOLS_INTEGRATION.md

MCP工具集成完整指南

概述

MoFox Bot现在完全支持MCP (Model Context Protocol)，包括：

1. MCP SSE客户端 - 与支持MCP的LLM（如Claude）通信
2. MCP工具提供器 - 将MCP服务器的工具集成到Bot，让AI能够调用

架构说明

┌─────────────────────────────────────────┐
│        MoFox Bot AI系统                  │
│  ┌───────────────────────────────────┐  │
│  │  AI决策层 (ToolExecutor)         │  │
│  │  - 分析用户请求                   │  │
│  │  - 决定调用哪些工具               │  │
│  └───────────────┬───────────────────┘  │
│                  │                       │
│  ┌───────────────▼───────────────────┐  │
│  │  工具注册表 (ComponentRegistry)   │  │
│  │  - Bot内置工具                    │  │
│  │  - MCP动态工具 ✨                 │  │
│  └───────────────┬───────────────────┘  │
│                  │                       │
│  ┌───────────────▼───────────────────┐  │
│  │  MCP工具提供器插件                │  │
│  │  - 连接MCP服务器                  │  │
│  │  - 动态注册工具                   │  │
│  └───────────────┬───────────────────┘  │
└──────────────────┼───────────────────────┘
                   │
    ┌──────────────▼──────────────┐
    │     MCP连接器                │
    │  - tools/list               │
    │  - tools/call               │
    │  - resources/list (未来)   │
    └──────────────┬──────────────┘
                   │
    ┌──────────────▼──────────────┐
    │      MCP服务器               │
    │  - 文件系统工具              │
    │  - Git工具                  │
    │  - 数据库工具               │
    │  - 自定义工具...            │
    └─────────────────────────────┘

完整配置步骤

步骤1: 启动MCP服务器

首先你需要一个运行中的MCP服务器。这里以官方的文件系统MCP服务器为例：

# 安装MCP服务器（以filesystem为例）
npm install -g @modelcontextprotocol/server-filesystem

# 启动服务器
mcp-server-filesystem --port 3000 /path/to/allowed/directory

或使用其他MCP服务器：

• Git MCP: 提供Git操作工具
• 数据库MCP: 提供数据库查询工具
• 自定义MCP服务器: 你自己开发的MCP服务器

步骤2: 配置MCP工具提供器插件

编辑配置文件 config/plugins/mcp_tools_provider.toml：

[plugin]
enabled = true  # 启用插件

# 配置MCP服务器
[[mcp_servers]]
name = "filesystem"  # 服务器标识名
url = "http://localhost:3000"  # MCP服务器地址
api_key = ""  # API密钥（如果需要）
timeout = 30  # 超时时间
enabled = true  # 是否启用

# 可以配置多个MCP服务器
[[mcp_servers]]
name = "git"
url = "http://localhost:3001"
enabled = true

步骤3: 启动Bot

python bot.py

启动后，你会在日志中看到：

[INFO] MCP工具提供器插件启动中...
[INFO] 发现 1 个MCP服务器配置
[INFO] 正在连接MCP服务器: filesystem (http://localhost:3000)
[INFO] 从MCP服务器 'filesystem' 获取到 5 个工具
[INFO] ✓ 已注册MCP工具: filesystem_read_file
[INFO] ✓ 已注册MCP工具: filesystem_write_file
[INFO] ✓ 已注册MCP工具: filesystem_list_directory
...
[INFO] MCP工具提供器插件启动完成，共注册 5 个工具

步骤4: AI自动调用MCP工具

现在AI可以自动发现并调用这些工具！例如：

用户: "帮我读取项目根目录下的README.md文件"

AI决策过程:

1. 分析用户请求 → 需要读取文件
2. 查找可用工具 → 发现 filesystem_read_file
3. 调用工具 → filesystem_read_file(path="README.md")
4. 获取结果 → 文件内容
5. 生成回复 → "README.md的内容是..."

工具命名规则

MCP工具会自动添加服务器名前缀，避免冲突：

• 原始工具名: read_file
• 注册后: filesystem_read_file

如果有多个MCP服务器提供相同名称的工具，它们会被区分开：

• 服务器A: serverA_search
• 服务器B: serverB_search

配置示例

示例1: 本地文件操作

[[mcp_servers]]
name = "local_fs"
url = "http://localhost:3000"
enabled = true

可用工具:

• local_fs_read_file - 读取文件
• local_fs_write_file - 写入文件
• local_fs_list_directory - 列出目录

示例2: Git操作

[[mcp_servers]]
name = "git"
url = "http://localhost:3001"
enabled = true

可用工具:

• git_status - 查看Git状态
• git_commit - 提交更改
• git_log - 查看提交历史

示例3: 多服务器配置

[[mcp_servers]]
name = "filesystem"
url = "http://localhost:3000"
enabled = true

[[mcp_servers]]
name = "database"
url = "http://localhost:3002"
api_key = "db-secret-key"
enabled = true

[[mcp_servers]]
name = "api_tools"
url = "https://mcp.example.com"
api_key = "your-api-key"
timeout = 60
enabled = true

开发自定义MCP服务器

你可以开发自己的MCP服务器来提供自定义工具：

// 简单的MCP服务器示例 (Node.js)
const express = require('express');
const app = express();

app.use(express.json());

// 列出工具
app.post('/tools/list', (req, res) => {
  res.json({
    tools: [
      {
        name: 'custom_tool',
        description: '自定义工具描述',
        inputSchema: {
          type: 'object',
          properties: {
            param1: {
              type: 'string',
              description: '参数1'
            }
          },
          required: ['param1']
        }
      }
    ]
  });
});

// 执行工具
app.post('/tools/call', async (req, res) => {
  const { name, arguments: args } = req.body;
  
  if (name === 'custom_tool') {
    // 执行你的逻辑
    const result = await doSomething(args.param1);
    
    res.json({
      content: [
        {
          type: 'text',
          text: result
        }
      ]
    });
  }
});

app.listen(3000, () => {
  console.log('MCP服务器运行在 http://localhost:3000');
});

常见问题

Q: MCP服务器连接失败？

检查:

1. MCP服务器是否正在运行
2. URL配置是否正确
3. 防火墙是否阻止连接
4. 查看日志中的具体错误信息

Q: 工具注册成功但AI不调用？

原因:

• 工具描述不够清晰
• 参数定义不明确

解决: 在MCP服务器端优化工具的description和inputSchema

Q: 如何禁用某个MCP服务器？

在配置中设置：

[[mcp_servers]]
enabled = false  # 禁用

Q: 如何查看已注册的MCP工具？

查看启动日志，或在Bot运行时检查组件注册表。

MCP协议规范

MCP服务器必须实现以下端点：

1. POST /tools/list

列出所有可用工具

响应:

{
  "tools": [
    {
      "name": "tool_name",
      "description": "工具描述",
      "inputSchema": {
        "type": "object",
        "properties": { ... },
        "required": [...]
      }
    }
  ]
}

2. POST /tools/call

执行工具

请求:

{
  "name": "tool_name",
  "arguments": { ... }
}

响应:

{
  "content": [
    {
      "type": "text",
      "text": "执行结果"
    }
  ]
}

高级功能

动态刷新工具列表

工具列表默认缓存5分钟。如果MCP服务器更新了工具，Bot会自动在下次缓存过期后刷新。

错误处理

MCP工具调用失败时，会返回错误信息给AI，AI可以据此做出相应处理或提示用户。

性能优化

• 工具列表有缓存机制
• 支持并发工具调用
• 自动重试机制

相关文档

• MCP SSE使用指南
• MCP协议官方文档
• 插件开发文档

更新日志

v1.0.0 (2025-10-05)

• ✅ 完整的MCP工具集成
• ✅ 动态工具注册
• ✅ 多服务器支持
• ✅ 自动错误处理

---

集成状态: ✅ 生产就绪
版本: v1.0.0
更新时间: 2025-10-05