map-client-vue/docs/MCP_TOOL_DEBUG_GUIDE.md

# MCP 工具调用调试指南

## 问题现象

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

但实际上：
- Server 端日志没有收到调用请求
- 内容没有真正发布

## 调试步骤

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

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

```javascript
// 应该看到：
🔍 [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 解析日志：

```javascript
// 应该看到：
🔧 [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. 检查工具调用收集

查找最终收集日志：

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

**如果看到 `没有检测到工具调用`**：
- 问题：工具调用数据没有被正确累积
- 检查：`toolCallsMap` 是否为空

### 4. 检查工具名称解析

查找工具执行详情：

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

**如果工具名称解析错误**：
- 检查：`split('__')` 逻辑
- 检查：是否有 `__` 分隔符

### 5. 检查 MCP 协议调用

查找 MCP 客户端日志：

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

**如果没有看到这个日志**：
- 问题：根本没有执行到 `MCPClientService.callTool`
- 原因：前面的步骤出错了

**如果看到调用失败**：
```javascript
❌ [MCPClientService.callTool] 工具调用失败
   - 工具名称: publish_content
   - 错误信息: Error: ...
```
- 检查错误信息
- 检查 MCP 服务器是否正常运行
- 检查参数格式是否正确

### 6. 检查服务器端日志

在 MCP Server 端查看：

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

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

## 常见问题排查

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

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

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

**可能原因**：
```typescript
// 错误处理中可能返回了假的成功结果
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

**解决方法**：
```typescript
// 确保 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 不存在
```

**排查**：
- 检查工具名称是否包含 `__` 前缀
- 检查解析后的工具名是否正确

**解决方法**：
```typescript
// 正确的解析逻辑
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 格式是否有效

**解决方法**：
```typescript
// 确保参数被正确解析
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