ModelContextProtocol TypeScript SDK 中 Bun 运行时与 SSE 服务器传输的兼容性问题分析

背景介绍

在开发基于 Server-Sent Events (SSE) 的实时通信应用时，ModelContextProtocol TypeScript SDK 提供了一个 SSEServerTransport 类用于实现服务器端的事件推送功能。然而，当开发者尝试在 Bun 运行时环境下使用该功能时，遇到了连接无法建立的问题。

问题现象

开发者在使用 Bun 运行时运行基于 ModelContextProtocol TypeScript SDK 的 SSE 服务器时，发现客户端无法成功建立 SSE 连接。具体表现为：

1. 客户端连接请求一直处于挂起状态
2. 服务器端没有报告任何错误
3. 相同的代码在 Node.js 运行时下工作正常

问题根源

经过深入调查，发现问题源于 Bun 运行时对 SSE 实现的一个特殊行为：在 Windows 平台上，Bun 不会立即发送第一个 SSE 消息，而是会等待第二个消息被写入后才发送第一个消息。这种行为导致了客户端无法及时收到服务器端的初始握手消息，从而造成连接无法正常建立。

解决方案

针对这个问题，开发社区提出了几种解决方案：

1. 发送虚拟消息：在建立连接后立即发送一个虚拟的 SSE 事件消息，强制触发 Bun 的消息发送机制。

this.sseTransport = new SSEServerTransport(
  "/messages",
  res as unknown as ServerResponse<IncomingMessage>,
);
res.write('event: log\ndata: "dummy event for bun workaround"\n\n');

2. SDK 内部兼容处理：在 SSEServerTransport 类中增加对 Bun 运行时的特殊处理。

if (process.versions.bun) {
  this.res.write('event: log\ndata: bun runtime compatibility message\n\n');
}

3. 升级 Bun 运行时：在 Bun 1.2.6 版本中，这个问题已经得到修复。

技术原理

SSE 协议要求服务器在建立连接后立即发送特定格式的消息。在 Node.js 实现中，消息会被立即发送到客户端。而 Bun 的早期版本出于性能优化考虑，采用了缓冲机制，导致第一个消息的发送被延迟。

这种差异对于遵循标准 SSE 协议的客户端来说会造成兼容性问题，因为客户端通常会等待特定的初始消息来确认连接已建立。

最佳实践

对于需要在多个运行时环境下使用 ModelContextProtocol TypeScript SDK 的开发者，建议：

1. 优先考虑升级到 Bun 1.2.6 或更高版本
2. 如果必须使用早期 Bun 版本，应在代码中显式添加兼容性处理
3. 在跨平台开发时，特别注意 Windows 平台的特殊行为
4. 实现完善的日志记录，帮助快速诊断连接问题

总结

运行时环境的差异是跨平台开发中常见的问题来源。ModelContextProtocol TypeScript SDK 与 Bun 运行时的兼容性问题展示了底层实现细节对应用层协议的影响。通过理解问题本质和采用适当的解决方案，开发者可以确保 SSE 功能在各种环境下可靠工作。