Cherry Studio项目MCP SSE模式连接超时问题分析与解决方案

问题背景

在Cherry Studio项目的使用过程中，部分开发者反馈在1.1.13版本中正常工作的MCP SSE模式（基于Spring Boot的MCP服务器），在升级到1.1.17版本后出现了连接问题。具体表现为点击启用按钮后界面持续转圈，最终报出"拉取工具列表超时"的错误。

问题现象分析

通过开发者提供的日志信息，我们可以清晰地看到整个通信流程：

1. 客户端与服务器成功建立了SSE连接
2. 客户端发送了初始化请求（initialize）
3. 服务器正确响应了初始化请求
4. 客户端发送了初始化完成通知（notifications/initialized）
5. 客户端发送了ping请求并得到响应

然而，在后续的"list-tools"请求中，客户端报告了超时错误（Error -32001: Request timed out）。这表明虽然基础通信已经建立，但在某些特定操作上出现了问题。

根本原因

深入分析日志和代码行为后，发现问题的核心在于：

1. 协议实现不完整：早期版本的Spring AI MCP服务器（1.0.0-M6）对initialize请求的响应不够完整，缺少必要的协议版本和功能声明。
2. 版本兼容性问题：Cherry Studio 1.1.17版本对协议完整性的检查更加严格，导致与旧版服务器出现兼容性问题。
3. 超时机制变化：新版本客户端对响应时间的容忍度降低，而旧版服务器的响应速度可能无法满足要求。

解决方案

该问题已在Spring AI项目的1.0.0-M7版本中得到修复。升级步骤如下：

1. 更新MCP服务器依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>1.0.0-M7</version>
</dependency>

2. 确保Cherry Studio客户端版本为1.2.2或更高

技术细节解析

MCP（Model Context Protocol）是一种基于JSON-RPC 2.0的协议，SSE（Server-Sent Events）是其一种传输实现方式。在修复版本中，主要改进包括：

1. 完整的协议响应：服务器现在会正确返回协议版本、服务器信息和能力声明
2. 性能优化：减少了不必要的网络往返，提高了响应速度
3. 错误处理增强：提供了更清晰的错误信息和恢复机制

最佳实践建议

1. 版本匹配：始终确保客户端和服务器使用相互兼容的版本
2. 日志监控：在开发和调试阶段开启详细日志，便于问题诊断
3. 协议验证：实现客户端时，应考虑对服务器响应的完整性检查
4. 超时配置：根据网络环境适当调整超时参数

总结

这次问题展示了在分布式系统中协议版本管理的重要性。随着Cherry Studio和Spring AI项目的持续发展，开发者应当关注版本更新日志，及时升级依赖，以获得最佳的使用体验和稳定性。通过这次问题的解决，也为类似基于SSE的JSON-RPC实现提供了有价值的参考案例。