5ire项目中MCP工具返回结果格式问题的技术解析与解决方案

在5ire项目开发过程中，我们遇到了一个关于Model Context Protocol（MCP）工具返回结果格式的技术问题。这个问题涉及到MCP工具服务器与LLM（大型语言模型）之间的数据交互格式不匹配，导致系统无法正确处理工具返回的内容。

问题现象

当MCP工具服务器返回结构化数据时，系统期望得到一个符合OpenAI兼容格式的内容，即一个包含类型和文本的对象数组。然而实际接收到的却是一个经过JSON字符串化的数组字符串，而非原始数组结构。这种格式差异导致语言模型后端（如LM Studio）无法正确解析内容，抛出"Invalid 'content'"错误。

技术背景分析

MCP工具服务器遵循2024-11-05规范，返回的响应格式是完全符合标准的JSON-RPC结构。问题并非出在服务器端，而是在数据传递链的某个环节中，原本应该保持为数组结构的内容被意外地进行了JSON字符串化处理。

在典型的MCP工具调用流程中：

1. 客户端发起工具调用请求
2. 工具服务器返回标准JSON-RPC响应
3. 响应结果经过中间层处理后传递给LLM

问题就出现在第三步的数据传递过程中，中间层对结果内容的处理方式不符合预期。

问题根源

通过深入排查，我们发现问题的根本原因是：

• 工具服务器返回的result.content本身是有效的数组结构
• 但在传递给LLM前，这个数组被错误地进行了JSON.stringify()处理
• 导致LLM后端接收到的是字符串形式的JSON，而非原始数组结构

这种处理方式违反了OpenAI兼容API的规范要求，该规范明确指出content字段应该直接包含字符串或结构化消息对象数组。

解决方案

我们采取了以下措施解决这个问题：

1. 重构消息格式化逻辑：移除了对content字段不必要的JSON字符串化处理

2. 实现智能内容处理：

   • 对于纯字符串内容，保持原样传递
   • 对于结构化对象数组，直接传递原始结构
   • 确保最终格式符合LLM后端的期望

3. 增强类型检查：在处理消息内容时增加类型验证，确保不会意外改变数据结构

技术实现细节

在具体实现上，我们开发了一个专门的消息格式化函数，该函数具有以下特点：

• 自动识别输入内容的类型（字符串或对象数组）
• 对结构化内容进行智能提取和组合
• 保持与OpenAI API规范的完全兼容
• 避免任何不必要的数据转换

这个解决方案不仅修复了当前的问题，还为未来可能的格式扩展提供了良好的基础。

经验总结

通过这个问题的解决，我们获得了以下宝贵经验：

1. 规范一致性至关重要：在涉及多个系统交互的场景中，严格遵守接口规范可以避免许多潜在问题
2. 数据传递链需要清晰：明确每个环节对数据的处理责任，避免重复或不一致的处理
3. 类型检查不可忽视：在关键数据传递点增加类型验证可以及早发现问题
4. 日志记录是调试利器：详细的日志记录帮助我们快速定位问题环节

这个问题虽然看似简单，但它揭示了在复杂系统集成中数据格式处理的重要性。我们的解决方案不仅修复了当前问题，还提高了整个系统的健壮性和可维护性。