Spring AI 1.0.0-SNAPSHOT 与 MCP 0.10.0-SNAPSHOT 集成问题分析

在 Spring AI 1.0.0-SNAPSHOT 版本与 Model Context Protocol (MCP) 0.10.0-SNAPSHOT 版本的集成过程中，开发者遇到了一个值得注意的兼容性问题。本文将深入分析该问题的表现、原因以及解决方案。

问题现象

当开发者尝试使用 Spring AI 1.0.0-SNAPSHOT 与 MCP 0.10.0-SNAPSHOT 进行集成时，系统抛出了"Failed to wait for the message endpoint"错误。具体表现为：

1. 在初始化 MCP 客户端时失败
2. 后续操作无法正常执行
3. 系统日志中显示 JSON 解析异常，提示"Unrecognized token 'Failed'"

值得注意的是，同样的代码在 MCP 0.9.0 版本中可以正常运行，这表明问题与版本升级有关。

错误分析

从技术层面来看，错误的核心在于 JSON 解析失败。系统尝试解析一个预期为 JSON 格式的响应时，却收到了以"Failed"开头的非标准响应内容。这种错误通常发生在以下几种情况：

1. 服务端返回了错误信息而非预期的 JSON 数据
2. 客户端与服务端版本不兼容
3. 通信协议或数据格式发生了变化

在堆栈跟踪中，我们可以看到错误起源于 VertexAiGeminiChatModel 类的 jsonToStruct 方法，这表明问题发生在 AI 模型处理 MCP 服务返回的数据时。

根本原因

经过深入排查，发现问题并非直接由 Spring AI 或 MCP 的代码变更引起，而是由 Maven 本地仓库(.m2)中的依赖冲突导致。具体表现为：

1. 本地仓库中同时存在多个版本的 MCP SDK
2. 构建系统错误地混合了不同版本的依赖
3. 1.0.0-SNAPSHOT 版本与其他版本产生了冲突

这种依赖冲突在从里程碑版本(如 M7 到 M8)升级时也曾出现过，表明这是一个需要特别注意的升级陷阱。

解决方案

解决此问题的步骤如下：

1. 清理本地 Maven 仓库中与 MCP 相关的缓存：

   • 删除 ~/.m2/repository/io/modelcontextprotocol 目录

2. 确保项目配置中只声明了一个明确的 MCP 版本

3. 执行干净的构建：

   • mvn clean install

4. 验证所有依赖版本的一致性

最佳实践建议

为了避免类似问题，建议开发者在进行版本升级时：

1. 定期清理本地仓库，特别是在切换版本时
2. 使用依赖树分析工具检查冲突
3. 在升级前仔细阅读版本变更说明
4. 考虑使用依赖管理工具锁定版本
5. 在持续集成环境中配置干净的构建环境

总结

Spring AI 与 MCP 的集成问题提醒我们，在快速迭代的开源项目中，依赖管理是一个需要特别关注的方面。通过理解问题的本质并采取适当的预防措施，开发者可以更顺利地完成版本升级和系统集成工作。记住，当遇到看似莫名其妙的兼容性问题时，检查依赖冲突往往是一个好的起点。