AG2项目中MCP客户端字符串转整型问题的分析与解决

问题背景

在AG2项目的开发过程中，开发团队发现MCP客户端在与本地SSE模式运行的MCP服务器交互时出现了一个类型转换问题。具体表现为：当客户端调用get_projects_for_workspace工具方法时，虽然参数workspace_gid以字符串形式传递，但在服务器端却被错误地转换为整型，导致验证失败。

问题现象

开发人员在使用AG2的MCP客户端连接本地MCP服务器时，尝试通过create_toolkit_and_run函数执行一系列Asana相关操作。在调用get_projects_for_workspace工具方法时，系统报错显示：

Error: Tool call failed: Error executing tool get_projects_for_workspace: 1 validation error for get_projects_for_workspaceArguments  
workspace_gid
  Input should be a valid string [type=string_type, input_value=232323423, input_type=int]

从日志中可以清楚地看到，虽然客户端发送的JSON-RPC请求中workspace_gid参数是以字符串形式('232323423')传递的，但在服务器端接收时却被转换为了整型(232323423)，这与服务器端参数类型定义(string)不匹配，导致验证失败。

技术分析

1. 参数传递流程：

   • 客户端构造JSON-RPC请求，其中workspace_gid明确以字符串形式传递
   • 请求通过SSE通道发送到服务器端
   • 服务器端接收并解析请求时，自动将数字形式的字符串转换为整型

2. 根本原因： 这个问题实际上源于fastmcp底层框架的一个已知问题。在JSON解析过程中，框架会自动将纯数字形式的字符串转换为数值类型，而忽略了参数定义的类型约束。

3. 临时解决方案： 开发人员发现可以通过修改服务器端的参数类型定义来临时解决这个问题。将workspace_gid参数的类型从str改为Union[str, int]，即同时接受字符串和整型输入，可以绕过这个类型转换问题。

解决方案建议

1. 长期解决方案：

   • 在fastmcp框架层面修复JSON解析时的自动类型转换逻辑
   • 确保框架能够尊重参数的类型定义，不进行自动类型转换
   • 或者提供明确的类型转换控制选项

2. 客户端适配方案：

   • 在客户端增加类型验证逻辑
   • 对于必须为字符串类型的参数，客户端可以主动添加引号或其他标识
   • 或者在发送请求前显式地进行类型转换

3. 服务器端防御性编程：

   • 对关键参数实现更灵活的类型处理
   • 在参数验证前增加类型转换逻辑
   • 提供更友好的错误提示信息

经验总结

这个问题展示了在分布式系统开发中类型系统一致性的重要性。特别是在跨语言、跨平台的RPC调用中，类型系统的差异可能导致难以预料的问题。开发团队应该：

1. 建立完善的类型验证机制
2. 在接口定义时考虑最大兼容性
3. 实现详细的日志记录以帮助诊断类似问题
4. 考虑使用Protocol Buffers等强类型序列化方案替代JSON

通过这个案例，我们也看到开源生态中上下游依赖可能带来的问题，提醒我们在技术选型时需要全面评估各个组件的兼容性和成熟度。