MCP-Go项目中Streamable HTTP传输层的心跳协议兼容性问题分析

在MCP-Go项目的开发过程中，我们发现了一个关于Streamable HTTP传输层与TypeScript客户端兼容性的重要问题。这个问题涉及到MCP协议中一个基础但关键的部分——心跳机制(Ping)的实现差异。

问题背景

MCP协议作为一种跨语言通信协议，其稳定性依赖于各个传输层实现的一致性。在0.30.1版本的mcp-go中，Streamable HTTP传输层与SSE(Server-Sent Events)传输层在心跳消息处理上存在不一致性，这导致了与TypeScript客户端(如MCP Inspector和Cursor)的兼容性问题。

技术细节分析

问题的核心在于心跳消息的ID字段处理上：

1. SSE传输层：正确实现了心跳消息的ID字段，每次发送Ping时都会包含一个递增的ID值
2. Streamable HTTP传输层：发送的心跳消息中缺少ID字段，导致该字段值为null

这种差异违反了MCP协议的一个重要原则——请求消息必须包含有效ID。在TypeScript客户端的实现中，通过Zod验证库严格校验了请求ID的格式：

export const RequestIdSchema = z.union([z.string(), z.number().int()]);

这个验证规则明确要求ID必须是字符串或整型数字，不接受null值。当Streamable HTTP传输层发送不带ID的心跳消息时，客户端验证失败，导致连接中断。

影响范围

该问题主要影响以下场景：

1. 使用Streamable HTTP作为传输层的Go服务端
2. 使用严格类型校验的TypeScript客户端
3. 依赖心跳机制维持长连接的应用程序

在实际应用中，这会导致客户端频繁重连，影响用户体验和系统稳定性。

解决方案

从技术实现角度来看，解决方案需要确保：

1. ID生成机制：Streamable HTTP传输层需要维护与SSE传输层类似的ID生成器
2. 会话状态管理：每个会话需要跟踪最后使用的ID值
3. 消息构造一致性：所有类型的请求消息(包括心跳)都应遵循相同的结构规范

具体实现可参考SSE传输层的做法，在发送Ping消息时使用下一个可用ID值：

func (s *SSEServer) sendPing(session *session) {
    session.mu.Lock()
    defer session.mu.Unlock()
    
    session.lastID++
    pingMsg := &protocol.Envelope{
        Id:   fmt.Sprintf("%d", session.lastID),
        Method: protocol.MethodPing,
    }
    // 发送消息...
}

最佳实践建议

为了避免类似问题，在实现MCP协议时建议：

1. 统一消息结构：所有传输层实现应使用相同的消息构造逻辑
2. 共享基础组件：将ID生成器等公共功能提取为共享模块
3. 跨语言测试：在协议变更时进行全面的跨语言兼容性测试
4. 文档规范：明确记录每个字段的必选/可选状态及格式要求

总结

这个案例展示了在实现跨语言协议时细节一致性的重要性。即使是看似简单的心跳消息，其格式差异也可能导致严重的兼容性问题。通过分析这个问题，我们不仅解决了当前的技术障碍，也为MCP协议的长期健康发展提供了有价值的实践经验。