1. 为什么需要同时支持三种传输协议我最初接触 MCPModel Context Protocol时面临一个很现实的问题不同客户端生态对传输方式的要求完全是分裂的。有的客户端只认 stdio有的偏好 SSE而新的 streamable HTTP 又逐渐成为主流。如果为每种协议各写一套服务端代码重复率高得吓人维护成本更是灾难。于是我开始动手写一个框架核心目标只有一个同一套业务逻辑零修改地跑在三种协议之上。先说结论这件事的难点不在协议本身而在协议差异的抽象层设计。stdio、streamable HTTP、SSE 看似一致实际上各自有完全不同的连接模型、消息边界和生命周期语义。很多 MCP 服务实现只选了其中一种协议因为最简单但要“同时支持”必须在设计初期就把协议无关的中间层抽出来否则后面会越改越乱。我选择用 TypeScript 来实现一方面是对生态兼容好另一方面是类型系统能帮我提前锁死消息格式的边界。框架的分层大致是传输层负责与具体协议打交道会话层负责维护请求-响应关联与生命周期核心层只暴露纯逻辑接口比如“注册工具”“处理请求”“推送通知”。刚开始我觉得传输层是最难的部分后来发现恰恰相反。因为 MCP 的协议文档对消息格式定义得很死照着实现就行真正让人头疼的是工程上的抽层问题比如怎么让同一个请求处理器同时被 stdio 的 stdin 事件回调、SSE 的 message 事件回调、streamable HTTP 的 POST 请求体回调触发又不互相污染状态。2. 三种传输协议的核心差异拆解2.1 stdio子进程间的严格消息边界stdio 传输的本质是“客户端拉起一个子进程通过标准输入输出进行 JSON-RPC 消息交换”。它有一个硬性要求每次消息必须以单行 JSON 结尾也就是用换行符\n作为消息边界。这意味着如果你的日志输出跑到了 stdout直接就把协议破坏了。我踩过这个坑后来统一把所有日志强制走 stderr 或独立文件否则客户端那边报 parse error 你根本不知道发生了什么。stdio 的生命周期简单粗暴进程活着连接就在进程退出连接就断。所以它天然适合本地工具、CLI 集成这类场景。回调函数的签名其实就是两个一个处理输入data事件一个处理输出write方法。做框架的时候需要把这里的stdin抽象成一种“只读消息源”把stdout抽象成“只写消息槽”后续换传输层不用动核心逻辑。2.2 SSE单向通道与心跳的博弈SSEServer-Sent Events是单向的服务端可以向客户端持续推送但客户端要发消息得靠另一个普通 HTTP POST 通道。这个“一上一下”的组合在实现时很容易被忽略很多人只处理了服务端到客户端的推送忘了把客户端的 POST 请求体和 SSE 连接关联起来。实现的时候我维护了一个connections表用sessionId作为 key存对应的 SSE 响应流对象。客户端 POST 过来的请求解析后先找到对应的 SSE 流再通过它把响应推回去。关键是超时和心跳的处理如果没有在 30 秒内发心跳或注释帧很多代理服务器会直接掐断长连接。2.3 streamable HTTPMCP 协议的新基准Streamable HTTP 是新增的传输模式它把消息传输建立在标准 HTTP 之上支持包括流式响应在内的多种交互方式。相比 SSE它不依赖全局唯一的长期连接而是允许会话内的多个 HTTP 请求按需建立。这意味着可以用POST /mcp作为统一入口按 Header 中的MCP-Session-ID区分会话响应根据请求的需求决定是单条 JSON 还是流式数据块。实现这种模式最需要注意的一点是“幂等与会话状态”的平衡。因为 HTTP 是无状态的如果会话状态全部挂在服务端内存里一旦中间发生断连或轮询节点变化状态就丢了。框架内部需要做一个带过期时间的会话表同时允许客户端请求带上MCP-Session-ID来恢复上下文。2.4 三种协议的对比实验下面是我在本地用同一套“查询天气”工具跑出的实测对比参考价值在于帮你理解场景适配而不是绝对性能。传输方式连接模型适合场景主要开销备注stdio子进程存活期间持续通讯本地 CLI、桌面端集成进程启动成本消息边界靠换行符SSE单连长推送POST 短连接上行浏览器页面、管理面板长连接心跳与保活需要额外处理跨域streamable HTTP会话内多请求可流式响应跨网络服务、移动端会话恢复与超时管理官方当前推荐方向我实际测过同一套工具在三种协议下的表现功能完全一致但代码路径上 stdio 最干净streamable HTTP 的中间层最多。这不代表 streamable HTTP 不好它换来的是解耦和灵活性适合部署为独立服务。3. 框架核心架构与模块设计3.1 整体分层业务、会话与传输解耦先放一张我自己在用的分层仅用文字描述不画图顶层是业务注册层工具、资源、提示词的注册入口直接暴露给用户中间是调度内核层请求分发、派发到具体业务函数、响应组装底层是传输适配层stdio、SSE、streamable HTTP 三种实现互相独立全局贯穿的是协议消息模型统一使用 JSON-RPC 格式与传输方式无关这个分层的核心思想就一句话传输层决定“怎么收怎么发”会话层决定“消息属于谁”内核层只关心“消息是什么”。这也直接决定了后续加新协议比如未来的 WebSocket 或者 QUIC时原有业务代码可以完全不动。实现上用了一个TransportAdapter接口形态大概是interface TransportAdapter { start(): void stop(): void send(message: JSONRPCMessage): Promisevoid onMessage(callback: (message: JSONRPCMessage) void): void onClose(callback: () void): void }三个适配器各自实现这套接口内核只面向接口编程。接口设计上我斟酌了很久最小集合就这四个方法。send返回Promise是为了处理背压尤其是 streamable HTTP 的大流式响应时很重要的机制。3.2 会话管理器状态与请求的归属问题在 stdio 模式下一个进程就是一个会话变量存全局都行。但到了 SSE 和 streamable HTTP多个客户端会同时连接到同一个服务进程这时候必须引入“会话”概念。我的实现是这样的interface Session { id: string createdAt: number lastActiveAt: number transportType: stdio | sse | http metadata: Recordstring, unknown }统一由一个SessionManager负责创建、查找和过期清理。每次消息进来先看有没有会话 ID没有就新建一个有就去更新lastActiveAt。这里有个实际经验不要用Map存会话之后就不管了必须加定时器做无活动过期回收不然长时间运行的内存会越来越高。对于不兼容老协议的客户端直接把它当作新会话处理是最稳妥的。我原以为需要完全复现老数据结构才能向后兼容实际做下来发现协议升级比你想象的慢主动降级为“可用但非最优”的状态反而省事。3.3 工具注册与请求路由工具的注册方式封装成几个装饰器即可server.tool(get_weather, { city: string }, async ({ city }) { return { temperature: 25, unit: C } })关键是工具名和 JSON Schema 的校验。我在初始化阶段把每个工具注册进一个Mapstring, ToolHandler收到tools/call请求时先查工具是否存在再用 JSON Schema 校验参数最后调用业务函数把返回结果统一包成 MCP 规定的content数组格式。路由层面只有一个总入口dispatchMessage(message: JSONRPCMessage, session: Session)。它根据method字段做分发分发完之后统一处理响应。这部分的代码其实不复杂但却是最容易碰见“响应包多了一层”这种问题的地方。3.4 三种适配器的内部细节stdio 适配器import * as readline from readline const rl readline.createInterface({ input: process.stdin, crlfDelay: Infinity }) rl.on(line, (line) { if (!line.trim()) return const message JSON.parse(line) kernelDispatch(message) }) function sendToStdio(message: JSONRPCMessage) { process.stdout.write(JSON.stringify(message) \n) }这里crlfDelay: Infinity很关键它能让 readline 正确处理 Windows 下的\r\n换行否则跨平台跑起来会偶发半行解析错误。发送那边务必要保证一次写入完整 JSON 并且以换行结尾。SSE 适配器SSE 处理长连接我直接把响应对象存进会话上下文中function formatSSE(event: string, data: unknown): string { return event: ${event}\ndata: ${JSON.stringify(data)}\n\n } // 发送时 session.sseResponse.write(formatSSE(message, jsonRpcMessage))不要忘了第一握手时要发送event: endpoint消息把 POST 消息通道的 URL 告知客户端。客户端后续就是往那个 URL POST JSON-RPC 消息。streamable HTTP 适配器这部分会同时实现两条请求路径POST消息入口和 GET 流请求。因为客户端可能在初始请求就要求流式响应所以要把响应类型判断好是application/json直接返回还是用text/event-stream边发边写。我实现时参考了规范细节初始请求若带MCP-Protocol-Version头优先按新规范走没有的按兼容路径处理。4. 实操过程从零搭起这个多协议服务框架4.1 初始化项目与依赖我用了一个空目录开跑操作流程如下mkdir mcp-multi-transport cd mcp-multi-transport npm init -y npm install typescript types/node --save-dev npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext编译目标选 ES2022 是因为AbortController、ReadableStream这些 Web API 在 Node 18 都原生支持了不用额外装 polyfill。TypeScript 的配置文件里记得把strict打开MCP 消息的类型定义很多是可空联合类型不开严格模式容易写漏。4.2 协议消息模型定义我手写了核心类型定义没有完全依赖 SDK因为想验证自己对规范的理解。核心类型大概是export type JSONRPCMessage | { jsonrpc: 2.0; id: number | string; method: string; params?: unknown } | { jsonrpc: 2.0; id: number | string; result?: unknown; error?: { code: number; message: string } } | { jsonrpc: 2.0; method: string; params?: unknown } // 通知这里的联合类型是很重要的设计请求、响应、通知被区分开。通知是没有id的客户端不用回复。我在内核 dispatch 时会先判断有没有id有的话就是请求类处理完必须回一个同 id 的响应没 id 就当作通知只触发逻辑不返回任何东西。工具调用协议组合起来看起来很繁琐其实拆开就三类初始化握手、工具列表拉取、工具执行。订阅资源和提示词还有额外方法但核心流程一样。4.3 统一消息入口的实现我写了这样一个核心分发函数它被三种传输适配器共用async function handleMessage(raw: unknown, session: Session) { const message JSON.parse(raw as string) const response processMessage(message, session) if (response) { await session.transport.send(response) } }每个适配器的onMessage回调都调handleMessage每个适配器的send实现各不一样。这个函数是整个框架的中枢当初为我节省了大量重复逻辑。需要注意的点是processMessage 内部应该是异步安全的因为信息间可能交错到达我加了微任务队列来保证同一会话内消息串行处理。4.4 业务工具注册示例弄一个抛砖引玉的计算器工具server.tool( add, { a: number, b: number }, async ({ a, b }) { return { result: a b } } )实际去调用时MCP 客户端传来的参数顺序不一定是“平铺”的可能是嵌套结构。我建议注册工具时Schema 直接按嵌套 object 来定义而不是拆成多个顶层参数这样可以减少兼容问题。工具返回值如果复杂建议显式声明content数组中的type: text否则一些客户端解析不了。4.5 启动完整的服务端入口我最后做的事是把三个适配器放进同一个start()流程里const stdioAdapter createStdioAdapter() const sseAdapter createSSEAdapter({ port: 3001 }) const httpAdapter createStreamableHTTPAdapter({ port: 3002 }) await Promise.all([ stdioAdapter.start(), sseAdapter.start(), httpAdapter.start() ])注意 SSE 和 HTTP 如果选同一个端口需要用一个 HTTP 服务实例通过路径区分。分开用不同端口是为了防止路由冲突不过生产环境建议都走同一域名不同路径。stdio 的端口更特殊它不需要网络端口只监听进程的文件描述符所以启动它不需要等待端口可用。5. 开发中踩过的坑与排查过程5.1 line 事件把二进制或超大消息截断了stdin 如果一次写入超大 JSONreadline默认按行解析没问题但如果某一行特别长内存峰值会非常高而且如果中间混入二进制内容会直接乱码。后来我限制单条消息最大 10MB超出直接报错误响应防止恶意客户端拖垮进程。5.2 SSE 长连接被代理断开本地测没问题一挂到公网服务器上大约几十秒后连接就断了。我用curl -N测试能稳定复现后来发现根因是客户端没设Cache-Control: no-cache代理以为可以缓存响应直接把长连接关掉。实际修复响应头加Cache-Control: no-cache同时开启X-Accel-Buffering: nonginx 才不会缓冲 SSE 流。5.3 streamable HTTP 的 204 响应弄丢了消息体某些旧客户端要求初始化后返回具体版本信息但我为了“省流量”直接回了 204 No Content导致客户端直接报协议错误。后面改成了只回最基本的元信息并确保响应头带正确的MCP-Protocol-Version。5.4 stdio 的日志污染 stdout项目接了日志库默认输出到 stdout线上跑的时候客户端疯狂报解析失败。排查一整天之后才意识到stdio 协议下任何打印到 stdout 的内容都会进入协议数据流。最终的解决办法日志全部走stderr并用环境变量区分是否启用调试日志。框架里还可以加一层“协议流保护”在 build 阶段禁止向process.stdout写入非协议内容。5.5 会话 ID 生成时机我一开始在 streamable HTTP 的初始化请求里就生成会话 ID回传给客户端。但实际上客户端可能根本没有保存这个 ID之后每个请求都新建会话导致工具状态一直对不上。最终改成只有客户端明确发起初始化且我们返回会话 ID 之后才正式建立会话否则默认本请求结束时释放会话。5.6 工具错误信息的包装业务工具内部直接抛 Error如果原样传给客户端错误码是-32603不区分“参数错误”和“内部错误”。后来我在 dispatch 层包装了一层ToolExecutionError把参数校验错误映射为-32602内核错误映射为-32000附近的自定义码客户端定位问题就方便多了。6. 常见问题速查表现象根因解决方式stdio 模式下客户端报 invalid JSONstdout 被日志污染强制日志走 stderrSSE 连接频繁中断缺少心跳或代理缓冲设置 no-cache 和心跳间隔streamable HTTP 响应没有流式输出响应的 Content-Type 错误使用 text/event-stream 类型工具调用参数总是丢失默认值JSON Schema 没定义默认字段在 schema 里显式声明 default两个客户端互相串数据会话表作用域写错改成按传输连接隔离会话表消息积压导致响应超时没做背压控制在 send 里加队列限流初始化偶发 500会话表还没生成就被清理清理逻辑加最小存活时间请求 ID 重复客户端 bug 或代理重放框架内加 ID 去重窗口这表是我真实调试过程中沉淀出来的不是从文档抄来的。每一条背后都对应一次线上事故或白天的定位循环。7. 后续可能扩展的方向框架的第一版已经跑起来了实际使用中我又加了一些增强能力。一个是“传输降级”机制当客户端不支持 streamable HTTP 时自动退回 SSESSE 再不行就退回 stdio保证老客户端也能用同一套业务代码。另一个是“会话持久化”把我那个Session对象序列化到 Redis 或本地文件里这样服务重启后客户端用同一个会话 ID 还能继续操作。如果你打算长期用这个框架建议再加一个 mock 测试层把所有工具函数用一个假的 transport 包起来直接模拟客户端发起各种 JSON-RPC 请求验证响应结构。这套测试跑完三种协议同时回归的成本就会低很多。我个人现在最常用的用法其实是本地 CLI 工具和远程管理 API 共用一套内核写工具时只写一遍底下接三个适配器效果意外地好。尤其是团队协作时同事想快速验证某个工具可以直接起一个 stdio 实例而正式服务则跑在 HTTP 端口上互不影响。如果你也要做类似的多协议服务框架我的建议很直接先把消息模型和会话管理写对再去适配传输细节。传输这一层可以靠测试慢慢补但消息模型错了三个协议都会一样地错。这个顺序省下来的时间只多不少。
1. 为什么需要同时支持三种传输协议我最初接触 MCPModel Context Protocol时面临一个很现实的问题不同客户端生态对传输方式的要求完全是分裂的。有的客户端只认 stdio有的偏好 SSE而新的 streamable HTTP 又逐渐成为主流。如果为每种协议各写一套服务端代码重复率高得吓人维护成本更是灾难。于是我开始动手写一个框架核心目标只有一个同一套业务逻辑零修改地跑在三种协议之上。先说结论这件事的难点不在协议本身而在协议差异的抽象层设计。stdio、streamable HTTP、SSE 看似一致实际上各自有完全不同的连接模型、消息边界和生命周期语义。很多 MCP 服务实现只选了其中一种协议因为最简单但要“同时支持”必须在设计初期就把协议无关的中间层抽出来否则后面会越改越乱。我选择用 TypeScript 来实现一方面是对生态兼容好另一方面是类型系统能帮我提前锁死消息格式的边界。框架的分层大致是传输层负责与具体协议打交道会话层负责维护请求-响应关联与生命周期核心层只暴露纯逻辑接口比如“注册工具”“处理请求”“推送通知”。刚开始我觉得传输层是最难的部分后来发现恰恰相反。因为 MCP 的协议文档对消息格式定义得很死照着实现就行真正让人头疼的是工程上的抽层问题比如怎么让同一个请求处理器同时被 stdio 的 stdin 事件回调、SSE 的 message 事件回调、streamable HTTP 的 POST 请求体回调触发又不互相污染状态。2. 三种传输协议的核心差异拆解2.1 stdio子进程间的严格消息边界stdio 传输的本质是“客户端拉起一个子进程通过标准输入输出进行 JSON-RPC 消息交换”。它有一个硬性要求每次消息必须以单行 JSON 结尾也就是用换行符\n作为消息边界。这意味着如果你的日志输出跑到了 stdout直接就把协议破坏了。我踩过这个坑后来统一把所有日志强制走 stderr 或独立文件否则客户端那边报 parse error 你根本不知道发生了什么。stdio 的生命周期简单粗暴进程活着连接就在进程退出连接就断。所以它天然适合本地工具、CLI 集成这类场景。回调函数的签名其实就是两个一个处理输入data事件一个处理输出write方法。做框架的时候需要把这里的stdin抽象成一种“只读消息源”把stdout抽象成“只写消息槽”后续换传输层不用动核心逻辑。2.2 SSE单向通道与心跳的博弈SSEServer-Sent Events是单向的服务端可以向客户端持续推送但客户端要发消息得靠另一个普通 HTTP POST 通道。这个“一上一下”的组合在实现时很容易被忽略很多人只处理了服务端到客户端的推送忘了把客户端的 POST 请求体和 SSE 连接关联起来。实现的时候我维护了一个connections表用sessionId作为 key存对应的 SSE 响应流对象。客户端 POST 过来的请求解析后先找到对应的 SSE 流再通过它把响应推回去。关键是超时和心跳的处理如果没有在 30 秒内发心跳或注释帧很多代理服务器会直接掐断长连接。2.3 streamable HTTPMCP 协议的新基准Streamable HTTP 是新增的传输模式它把消息传输建立在标准 HTTP 之上支持包括流式响应在内的多种交互方式。相比 SSE它不依赖全局唯一的长期连接而是允许会话内的多个 HTTP 请求按需建立。这意味着可以用POST /mcp作为统一入口按 Header 中的MCP-Session-ID区分会话响应根据请求的需求决定是单条 JSON 还是流式数据块。实现这种模式最需要注意的一点是“幂等与会话状态”的平衡。因为 HTTP 是无状态的如果会话状态全部挂在服务端内存里一旦中间发生断连或轮询节点变化状态就丢了。框架内部需要做一个带过期时间的会话表同时允许客户端请求带上MCP-Session-ID来恢复上下文。2.4 三种协议的对比实验下面是我在本地用同一套“查询天气”工具跑出的实测对比参考价值在于帮你理解场景适配而不是绝对性能。传输方式连接模型适合场景主要开销备注stdio子进程存活期间持续通讯本地 CLI、桌面端集成进程启动成本消息边界靠换行符SSE单连长推送POST 短连接上行浏览器页面、管理面板长连接心跳与保活需要额外处理跨域streamable HTTP会话内多请求可流式响应跨网络服务、移动端会话恢复与超时管理官方当前推荐方向我实际测过同一套工具在三种协议下的表现功能完全一致但代码路径上 stdio 最干净streamable HTTP 的中间层最多。这不代表 streamable HTTP 不好它换来的是解耦和灵活性适合部署为独立服务。3. 框架核心架构与模块设计3.1 整体分层业务、会话与传输解耦先放一张我自己在用的分层仅用文字描述不画图顶层是业务注册层工具、资源、提示词的注册入口直接暴露给用户中间是调度内核层请求分发、派发到具体业务函数、响应组装底层是传输适配层stdio、SSE、streamable HTTP 三种实现互相独立全局贯穿的是协议消息模型统一使用 JSON-RPC 格式与传输方式无关这个分层的核心思想就一句话传输层决定“怎么收怎么发”会话层决定“消息属于谁”内核层只关心“消息是什么”。这也直接决定了后续加新协议比如未来的 WebSocket 或者 QUIC时原有业务代码可以完全不动。实现上用了一个TransportAdapter接口形态大概是interface TransportAdapter { start(): void stop(): void send(message: JSONRPCMessage): Promisevoid onMessage(callback: (message: JSONRPCMessage) void): void onClose(callback: () void): void }三个适配器各自实现这套接口内核只面向接口编程。接口设计上我斟酌了很久最小集合就这四个方法。send返回Promise是为了处理背压尤其是 streamable HTTP 的大流式响应时很重要的机制。3.2 会话管理器状态与请求的归属问题在 stdio 模式下一个进程就是一个会话变量存全局都行。但到了 SSE 和 streamable HTTP多个客户端会同时连接到同一个服务进程这时候必须引入“会话”概念。我的实现是这样的interface Session { id: string createdAt: number lastActiveAt: number transportType: stdio | sse | http metadata: Recordstring, unknown }统一由一个SessionManager负责创建、查找和过期清理。每次消息进来先看有没有会话 ID没有就新建一个有就去更新lastActiveAt。这里有个实际经验不要用Map存会话之后就不管了必须加定时器做无活动过期回收不然长时间运行的内存会越来越高。对于不兼容老协议的客户端直接把它当作新会话处理是最稳妥的。我原以为需要完全复现老数据结构才能向后兼容实际做下来发现协议升级比你想象的慢主动降级为“可用但非最优”的状态反而省事。3.3 工具注册与请求路由工具的注册方式封装成几个装饰器即可server.tool(get_weather, { city: string }, async ({ city }) { return { temperature: 25, unit: C } })关键是工具名和 JSON Schema 的校验。我在初始化阶段把每个工具注册进一个Mapstring, ToolHandler收到tools/call请求时先查工具是否存在再用 JSON Schema 校验参数最后调用业务函数把返回结果统一包成 MCP 规定的content数组格式。路由层面只有一个总入口dispatchMessage(message: JSONRPCMessage, session: Session)。它根据method字段做分发分发完之后统一处理响应。这部分的代码其实不复杂但却是最容易碰见“响应包多了一层”这种问题的地方。3.4 三种适配器的内部细节stdio 适配器import * as readline from readline const rl readline.createInterface({ input: process.stdin, crlfDelay: Infinity }) rl.on(line, (line) { if (!line.trim()) return const message JSON.parse(line) kernelDispatch(message) }) function sendToStdio(message: JSONRPCMessage) { process.stdout.write(JSON.stringify(message) \n) }这里crlfDelay: Infinity很关键它能让 readline 正确处理 Windows 下的\r\n换行否则跨平台跑起来会偶发半行解析错误。发送那边务必要保证一次写入完整 JSON 并且以换行结尾。SSE 适配器SSE 处理长连接我直接把响应对象存进会话上下文中function formatSSE(event: string, data: unknown): string { return event: ${event}\ndata: ${JSON.stringify(data)}\n\n } // 发送时 session.sseResponse.write(formatSSE(message, jsonRpcMessage))不要忘了第一握手时要发送event: endpoint消息把 POST 消息通道的 URL 告知客户端。客户端后续就是往那个 URL POST JSON-RPC 消息。streamable HTTP 适配器这部分会同时实现两条请求路径POST消息入口和 GET 流请求。因为客户端可能在初始请求就要求流式响应所以要把响应类型判断好是application/json直接返回还是用text/event-stream边发边写。我实现时参考了规范细节初始请求若带MCP-Protocol-Version头优先按新规范走没有的按兼容路径处理。4. 实操过程从零搭起这个多协议服务框架4.1 初始化项目与依赖我用了一个空目录开跑操作流程如下mkdir mcp-multi-transport cd mcp-multi-transport npm init -y npm install typescript types/node --save-dev npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext编译目标选 ES2022 是因为AbortController、ReadableStream这些 Web API 在 Node 18 都原生支持了不用额外装 polyfill。TypeScript 的配置文件里记得把strict打开MCP 消息的类型定义很多是可空联合类型不开严格模式容易写漏。4.2 协议消息模型定义我手写了核心类型定义没有完全依赖 SDK因为想验证自己对规范的理解。核心类型大概是export type JSONRPCMessage | { jsonrpc: 2.0; id: number | string; method: string; params?: unknown } | { jsonrpc: 2.0; id: number | string; result?: unknown; error?: { code: number; message: string } } | { jsonrpc: 2.0; method: string; params?: unknown } // 通知这里的联合类型是很重要的设计请求、响应、通知被区分开。通知是没有id的客户端不用回复。我在内核 dispatch 时会先判断有没有id有的话就是请求类处理完必须回一个同 id 的响应没 id 就当作通知只触发逻辑不返回任何东西。工具调用协议组合起来看起来很繁琐其实拆开就三类初始化握手、工具列表拉取、工具执行。订阅资源和提示词还有额外方法但核心流程一样。4.3 统一消息入口的实现我写了这样一个核心分发函数它被三种传输适配器共用async function handleMessage(raw: unknown, session: Session) { const message JSON.parse(raw as string) const response processMessage(message, session) if (response) { await session.transport.send(response) } }每个适配器的onMessage回调都调handleMessage每个适配器的send实现各不一样。这个函数是整个框架的中枢当初为我节省了大量重复逻辑。需要注意的点是processMessage 内部应该是异步安全的因为信息间可能交错到达我加了微任务队列来保证同一会话内消息串行处理。4.4 业务工具注册示例弄一个抛砖引玉的计算器工具server.tool( add, { a: number, b: number }, async ({ a, b }) { return { result: a b } } )实际去调用时MCP 客户端传来的参数顺序不一定是“平铺”的可能是嵌套结构。我建议注册工具时Schema 直接按嵌套 object 来定义而不是拆成多个顶层参数这样可以减少兼容问题。工具返回值如果复杂建议显式声明content数组中的type: text否则一些客户端解析不了。4.5 启动完整的服务端入口我最后做的事是把三个适配器放进同一个start()流程里const stdioAdapter createStdioAdapter() const sseAdapter createSSEAdapter({ port: 3001 }) const httpAdapter createStreamableHTTPAdapter({ port: 3002 }) await Promise.all([ stdioAdapter.start(), sseAdapter.start(), httpAdapter.start() ])注意 SSE 和 HTTP 如果选同一个端口需要用一个 HTTP 服务实例通过路径区分。分开用不同端口是为了防止路由冲突不过生产环境建议都走同一域名不同路径。stdio 的端口更特殊它不需要网络端口只监听进程的文件描述符所以启动它不需要等待端口可用。5. 开发中踩过的坑与排查过程5.1 line 事件把二进制或超大消息截断了stdin 如果一次写入超大 JSONreadline默认按行解析没问题但如果某一行特别长内存峰值会非常高而且如果中间混入二进制内容会直接乱码。后来我限制单条消息最大 10MB超出直接报错误响应防止恶意客户端拖垮进程。5.2 SSE 长连接被代理断开本地测没问题一挂到公网服务器上大约几十秒后连接就断了。我用curl -N测试能稳定复现后来发现根因是客户端没设Cache-Control: no-cache代理以为可以缓存响应直接把长连接关掉。实际修复响应头加Cache-Control: no-cache同时开启X-Accel-Buffering: nonginx 才不会缓冲 SSE 流。5.3 streamable HTTP 的 204 响应弄丢了消息体某些旧客户端要求初始化后返回具体版本信息但我为了“省流量”直接回了 204 No Content导致客户端直接报协议错误。后面改成了只回最基本的元信息并确保响应头带正确的MCP-Protocol-Version。5.4 stdio 的日志污染 stdout项目接了日志库默认输出到 stdout线上跑的时候客户端疯狂报解析失败。排查一整天之后才意识到stdio 协议下任何打印到 stdout 的内容都会进入协议数据流。最终的解决办法日志全部走stderr并用环境变量区分是否启用调试日志。框架里还可以加一层“协议流保护”在 build 阶段禁止向process.stdout写入非协议内容。5.5 会话 ID 生成时机我一开始在 streamable HTTP 的初始化请求里就生成会话 ID回传给客户端。但实际上客户端可能根本没有保存这个 ID之后每个请求都新建会话导致工具状态一直对不上。最终改成只有客户端明确发起初始化且我们返回会话 ID 之后才正式建立会话否则默认本请求结束时释放会话。5.6 工具错误信息的包装业务工具内部直接抛 Error如果原样传给客户端错误码是-32603不区分“参数错误”和“内部错误”。后来我在 dispatch 层包装了一层ToolExecutionError把参数校验错误映射为-32602内核错误映射为-32000附近的自定义码客户端定位问题就方便多了。6. 常见问题速查表现象根因解决方式stdio 模式下客户端报 invalid JSONstdout 被日志污染强制日志走 stderrSSE 连接频繁中断缺少心跳或代理缓冲设置 no-cache 和心跳间隔streamable HTTP 响应没有流式输出响应的 Content-Type 错误使用 text/event-stream 类型工具调用参数总是丢失默认值JSON Schema 没定义默认字段在 schema 里显式声明 default两个客户端互相串数据会话表作用域写错改成按传输连接隔离会话表消息积压导致响应超时没做背压控制在 send 里加队列限流初始化偶发 500会话表还没生成就被清理清理逻辑加最小存活时间请求 ID 重复客户端 bug 或代理重放框架内加 ID 去重窗口这表是我真实调试过程中沉淀出来的不是从文档抄来的。每一条背后都对应一次线上事故或白天的定位循环。7. 后续可能扩展的方向框架的第一版已经跑起来了实际使用中我又加了一些增强能力。一个是“传输降级”机制当客户端不支持 streamable HTTP 时自动退回 SSESSE 再不行就退回 stdio保证老客户端也能用同一套业务代码。另一个是“会话持久化”把我那个Session对象序列化到 Redis 或本地文件里这样服务重启后客户端用同一个会话 ID 还能继续操作。如果你打算长期用这个框架建议再加一个 mock 测试层把所有工具函数用一个假的 transport 包起来直接模拟客户端发起各种 JSON-RPC 请求验证响应结构。这套测试跑完三种协议同时回归的成本就会低很多。我个人现在最常用的用法其实是本地 CLI 工具和远程管理 API 共用一套内核写工具时只写一遍底下接三个适配器效果意外地好。尤其是团队协作时同事想快速验证某个工具可以直接起一个 stdio 实例而正式服务则跑在 HTTP 端口上互不影响。如果你也要做类似的多协议服务框架我的建议很直接先把消息模型和会话管理写对再去适配传输细节。传输这一层可以靠测试慢慢补但消息模型错了三个协议都会一样地错。这个顺序省下来的时间只多不少。
