map-client-vue/docs/MCP_TOOL_DEBUG_GUIDE.md

MCP 工具调用调试指南

问题现象

用户界面显示工具调用成功：

🔧 正在调用工具: publish_content...
✅ 工具执行完成
🤖 正在生成回复...
已为您发布一篇仅自己可见的笔记，主题为《如何制作酸菜鱼》...

但实际上：

• Server 端日志没有收到调用请求
• 内容没有真正发布

调试步骤

1. 检查工具调用是否被触发

打开浏览器控制台（F12），查找以下关键日志：

// 应该看到：
🔍 [callModelStream] 检查工具调用: {
  hasData: true,
  hasToolCalls: true,
  toolCallsCount: 1,
  hasMcpServerId: true,
  mcpServerId: "xhs-sse",
  toolCalls: [...]
}

如果看到 toolCallsCount: 0 或 hasToolCalls: false：

• 问题：AI 模型没有返回工具调用
• 可能原因：
  1. 模型不支持 Function Calling
  2. System Prompt 没有正确注入
  3. 工具格式不正确

2. 检查 SSE 流中的工具调用

查找 SSE 解析日志：

// 应该看到：
🔧 [makeChatRequestStream] SSE检测到 tool_calls: [
  {
    index: 0,
    id: "call_abc123",
    type: "function",
    function: {
      name: "xiaohongshu__publish_content",
      arguments: "{\"title\":..."
    }
  }
]

🔧 [makeChatRequestStream] 创建新工具调用 [0]: {...}
🔧 [makeChatRequestStream] 更新工具名 [0]: xiaohongshu__publish_content
🔧 [makeChatRequestStream] 累积参数 [0]: {"title":...

如果没有看到这些日志：

• 问题：SSE 流中没有 tool_calls 数据
• 可能原因：
  1. AI 服务商返回格式不标准
  2. SSE 解析逻辑有问题
  3. 模型真的没有决定调用工具

3. 检查工具调用收集

查找最终收集日志：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 [makeChatRequestStream] 最终收集到工具调用: 1 个
   工具 [0]: {
     id: "call_abc123",
     name: "xiaohongshu__publish_content",
     arguments: "{\"title\":\"🐟 超详细！...\",\"content\":\"...\",...}"
   }
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

如果看到 没有检测到工具调用：

• 问题：工具调用数据没有被正确累积
• 检查：toolCallsMap 是否为空

4. 检查工具名称解析

查找工具执行详情：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 [executeToolCalls] 工具调用详情:
   - 完整工具名: xiaohongshu__publish_content
   - 提取工具名: publish_content
   - MCP服务器ID: xhs-sse
   - 参数: {
       "title": "🐟 超详细！...",
       "content": "...",
       "tags": [...],
       "category": "美食"
     }
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

如果工具名称解析错误：

• 检查：split('__') 逻辑
• 检查：是否有 __ 分隔符

5. 检查 MCP 协议调用

查找 MCP 客户端日志：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 [MCPClientService.callTool] 准备调用工具
   - 服务器ID: xhs-sse
   - 工具名称: publish_content
   - 参数: {
       "title": "...",
       "content": "...",
       ...
     }
   - MCP协议调用: tools/call
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

如果没有看到这个日志：

• 问题：根本没有执行到 MCPClientService.callTool
• 原因：前面的步骤出错了

如果看到调用失败：

❌ [MCPClientService.callTool] 工具调用失败
   - 工具名称: publish_content
   - 错误信息: Error: ...

• 检查错误信息
• 检查 MCP 服务器是否正常运行
• 检查参数格式是否正确

6. 检查服务器端日志

在 MCP Server 端查看：

# 应该看到类似日志：
[INFO] 收到工具调用请求: publish_content
[INFO] 参数: {"title": "...", ...}
[INFO] 开始发布内容...
[INFO] 发布成功，返回结果

如果服务器端没有日志：

• 问题：请求根本没有到达服务器
• 可能原因：
  1. 连接已断开
  2. MCP 协议调用格式错误
  3. 传输层问题（HTTP/SSE）

常见问题排查

问题 1: 显示成功但没有实际调用

症状：

• UI 显示 ✅ 工具执行完成
• AI 返回友好的成功消息
• 但 Server 端没有收到请求

排查：

1. 检查浏览器控制台，查找 [MCPClientService.callTool] 日志
2. 如果没有这个日志，说明根本没有调用 MCP
3. 检查是否进入了错误处理分支（假成功）

可能原因：

// 错误处理中可能返回了假的成功结果
try {
  const result = await this.mcpClient.callTool(...)
  return result
} catch (error) {
  // 这里可能返回了假的成功对象
  return { success: true } // ❌ 错误！
}

问题 2: AI 没有调用工具

症状：

• 控制台显示 没有检测到工具调用
• AI 直接回答了问题，没有使用工具

排查：

1. 检查 System Prompt 是否正确注入
2. 检查工具列表是否正确传递给 AI
3. 检查 AI 模型是否支持 Function Calling

解决方法：

// 确保 System Prompt 被添加
if (tools.length > 0 && messages.length > 0 && messages[0].role !== 'system') {
  const systemPrompt = this.createSystemPromptWithTools(tools, mcpServerName)
  messages = [
    { role: 'system', content: systemPrompt },
    ...messages
  ]
}

// 确保工具被传递
await modelServiceManager.sendChatRequestStream(
  service.id,
  messages,
  selectedModel,
  onChunk,
  tools.length > 0 ? tools : undefined // ✅ 正确传递
)

问题 3: 工具名称格式错误

症状：

❌ 工具调用失败: 工具 xiaohongshu__publish_content 不存在

排查：

• 检查工具名称是否包含 __ 前缀
• 检查解析后的工具名是否正确

解决方法：

// 正确的解析逻辑
const fullFunctionName = "xiaohongshu__publish_content"
const toolName = fullFunctionName.includes('__') 
  ? fullFunctionName.split('__')[1]  // publish_content ✅
  : fullFunctionName

// 使用原始名称调用 MCP
await this.mcpClient.callTool(mcpServerId, toolName, functionArgs)

问题 4: 参数格式错误

症状：

❌ 工具调用失败: 参数格式不正确

排查：

1. 检查 functionArgs 是否正确解析
2. 检查 JSON 格式是否有效

解决方法：

// 确保参数被正确解析
const functionArgs = JSON.parse(toolCall.function.arguments)

// 打印参数查看
console.log('参数:', JSON.stringify(functionArgs, null, 2))

问题 5: MCP 服务器未连接

症状：

❌ 工具调用失败: 服务器 xhs-sse 未连接

排查：

1. 在 MCP 设置中检查服务器状态
2. 尝试重新连接
3. 检查服务器进程是否运行

解决方法：

1. 重启 MCP 服务器
2. 在 UI 中重新连接
3. 检查连接配置是否正确

调试流程图

用户发送消息
    ↓
[检查点 1] System Prompt 是否注入？
    ↓ Yes
[检查点 2] 工具列表是否传递给 AI？
    ↓ Yes
AI 处理并返回 SSE 流
    ↓
[检查点 3] SSE 流中是否有 tool_calls？
    ↓ Yes
[检查点 4] tool_calls 是否正确收集？
    ↓ Yes
[检查点 5] 工具名称是否正确解析？
    ↓ Yes
[检查点 6] MCP Client 是否调用？
    ↓ Yes
[检查点 7] MCP Server 是否收到请求？
    ↓ Yes
[检查点 8] MCP Server 是否返回结果？
    ↓ Yes
✅ 成功！

增强的日志输出

现在代码中已经添加了详细的日志，按顺序查找：

1. 工具收集阶段：

🔧 [makeChatRequestStream] SSE检测到 tool_calls
🔧 [makeChatRequestStream] 创建新工具调用
🔧 [makeChatRequestStream] 更新工具名
🔧 [makeChatRequestStream] 累积参数
🔧 [makeChatRequestStream] 最终收集到工具调用: X 个

2. 工具检查阶段：

🔍 [callModelStream] 检查工具调用
🔧 [callModelStream] 开始执行工具调用

3. 工具执行阶段：

🔧 [executeToolCalls] 工具调用详情
🔧 [MCPClientService.callTool] 准备调用工具
✅ [MCPClientService.callTool] 工具调用成功

下一步

如果通过上述调试仍然找不到问题，请：

1. 复制完整的控制台日志
2. 复制 MCP Server 端的日志
3. 提供以下信息：
   • 使用的 AI 模型
   • MCP 服务器类型
   • 连接方式（HTTP/SSE）
   • 完整的错误信息

---

更新时间: 2024-01-15
版本: v1.0.2+ Debug