5ire项目中Gemini与MCP工具集成的JSON协议兼容性问题分析

问题背景

在5ire项目的0.9.9版本中，开发团队发现当用户尝试将MCP（多链协议）工具服务器与Google Gemini AI模型结合使用时，系统会抛出JSON协议相关的异常。具体表现为两种错误形态：

1. 当启用基础功能时出现"Invalid JSON payload received. Unknown name 'type'"错误
2. 在后续版本中又出现了关于enum类型校验的"only allowed for STRING type"错误

技术根源分析

经过项目维护者的深入排查，发现问题核心在于协议层的设计差异：

类型系统差异

Gemini API对JSON Schema的处理与OpenAI存在本质区别。在工具函数参数定义中：

• OpenAI允许灵活的类型声明方式
• Gemini则强制要求严格的类型匹配，特别是对于enum类型，必须显式声明为STRING类型

协议实现差异

错误信息中提到的"Proto field is not repeating"表明：

1. Gemini后端使用Protocol Buffers作为序列化协议
2. 其实现中对JSON到Proto的转换有严格的字段重复性校验
3. MCP工具生成的Schema直接沿用了OpenAI的宽松模式

解决方案

项目团队通过以下方式解决了该问题：

协议适配层

1. 增加了专门的Schema转换器
2. 对enum类型自动添加类型声明
3. 对参数结构进行递归校验和修正

版本兼容处理

1. 区分不同AI提供商的协议要求
2. 动态调整工具声明格式
3. 保留OpenAI的原始模式同时支持Gemini的严格模式

开发者建议

对于需要集成多AI平台工具的开发人员，建议：

1. 实现协议检测机制
2. 建立统一的中间表示层
3. 对每个平台实现特定的适配器
4. 特别注意enum类型的平台差异处理

经验总结

该案例典型地展示了在多AI平台集成过程中可能遇到的协议兼容性问题。5ire项目的解决方案为类似场景提供了很好的参考范式，特别是：

• 协议差异的早期识别
• 适配层的抽象设计
• 动态调整机制的重要性

这种架构思路对于构建支持多AI后端的应用系统具有普遍参考价值。