深入mcp.el源码:JSON-RPC通信、process filter与SSE事件解析的实现原理
深入mcp.el源码:JSON-RPC通信、process filter与SSE事件解析的实现原理
mcp.el 是一个运行在 Emacs 内部的 MCP(Model Context Protocol)客户端,能够连接本地 stdio 服务器和远程 SSE 服务器,并调用其 tools、prompts、resources。本文以 mcp.el 的 1400 多行源码为主线,拆解它的三大核心实现:JSON-RPC 消息收发、process filter 数据接收循环、以及最棘手的 SSE 事件流解析,帮助你理解一个 Emacs MCP 客户端是如何从零搭建的。
一、项目全貌:三个类撑起整个客户端
mcp.el 的架构建立在 Emacs 社区的 jsonrpc 包之上,核心是三层层类继承:
mcp-process-connection—— 继承自jsonrpc-process-connection,负责存放连接状态、服务器能力(capabilities)、tools 列表、回调函数等mcp-http-process-connection—— 面向远程 HTTP/SSE 服务器,额外记录 host、port、tls、session-id 等mcp-stdio-process-connection—— 面向本地子进程(如npx @modelcontextprotocol/server-filesystem)
类定义见 mcp.el。这个设计让上层业务代码(调用工具、拉取 prompts)完全不用关心底层是管道还是网络,只需要统一的 connection 对象。
连接入口是 mcp-connect-server:如果配置里是 :command,就用 make-process 启动子进程(stdio 模式);如果配置里是 :url,就解析出 host/port/path 后创建一个"空"进程占位,走 HTTP 流程。连接对象最终被存入全局哈希表 mcp-server-connections,供后续按名字取用。
二、JSON-RPC 发送端:一个方法适配两种传输
所有出站消息都汇聚到一个方法重写——jsonrpc-connection-send。它先判断消息类型(有 :id 是请求、只有 :method 是通知、有 :result 是回复),再序列化为 JSON,最后按连接类型分叉:
stdio 分支只有一行:process-send-string 把 JSON 加上 \r\n 写入子进程的标准输入。
http 分支则相当丰富:
- 用 Emacs 内置的
url-retrieve发起POST,携带Content-Type: application/json、Mcp-Session-Id、Authorization: Bearer等请求头 - 在响应回调里用 mcp--parse-http-header 解析响应头
- 如果状态码是 4xx,说明服务器是旧版 SSE 服务器,于是标记
sse并转入 SSE 连接流程 - 如果是
application/json直接解析为消息;如果是text/event-stream则按data:前缀逐行提取
这就是为什么 mcp.el 能同时兼容新版 HTTP 服务器和旧版 SSE 服务器——判断逻辑完全基于响应内容,而不是提前探测。
三、process filter:接收端的"心跳"
Emacs 通过 process filter 回调把子进程/网络流的新数据交给用户代码。mcp.el 把它注册在 initialize-instance 钩子 里,真正的实现是 mcp--process-filter,约 160 行,是整个项目最核心的函数。它按顺序做了五件事:
1. 防重入保护
开头用一个 mcp--in-process-filter 变量检测重入:如果 jsonrpc-connection-receive 触发的用户回调里又调用了 process-send-string,可能造成消息丢失(源码注释里引用了 bug#60088)。此时直接 run-at-time 0 把自己重新排进定时器,跳过本次递归。
2. 维护"挂起缓冲"
每个进程用 process-put 关联一个 *mcp-xxx-jsonrpc-pending* 缓冲(缓冲区创建逻辑)。stdio 模式下新数据追加进去后整体读取——因为管道可能把一条 JSON 截断成两半,必须等完整消息才能解析。
3. 按传输类型切分数据块
- stdio:分隔符是
\n,每块就是一条 JSON - 普通 http:
"\n\n" - SSE:
"\r\n\r\n"
切分逻辑在 mcp.el。
4. 容错地解析 JSON
每块数据用 json-parse-string 解析并转成 plist。这里有个巧妙细节:捕获 json-end-of-file 错误时,把数据写回挂起缓冲、留待下次数据到达再拼(mcp.el)——这就是处理网络半包的完整方案。
5. 用定时器派发消息
解析出的消息不直接处理,而是逐条创建一个"立即触发"的 timer,异步调用 jsonrpc-connection-receive(mcp.el)。这样把"收数据"和"处理消息"解耦,避免了在 filter 内做耗时操作卡住事件循环。
四、SSE 事件解析:十六进制长度计数的妙用
SSE 服务器是 mcp.el 里最复杂的场景。建立连接的 mcp--connect-sse 没有用 url-retrieve,而是用 open-network-stream 打开 TCP/TLS 流后手工拼写了一条完整的 HTTP GET 请求(带 Accept: text/event-stream 头)——因为 SSE 是长连接,url-retrieve 的一次性请求模型并不合适。
之后数据流回到 mcp--process-filter 的 http 分支(mcp.el),按事件类型分别处理:
| 事件类型 | 处理方式 |
|---|---|
endpoint |
从 data 里用正则提取 /message?sessionId=... 路径,存入连接对象,随即触发 initialize 握手 |
message |
按十六进制 data-size 计算剩余字节,做跨帧重组 |
: ping |
识别为 ping 事件,直接忽略(保持连接保活) |
message 事件的处理是整个解析器的精华:SSE 的 data 字段开头是一个十六进制数字,表示这条 JSON-RPC 消息的总字节数。mcp.el 用 string-to-number ... 16 把它转成十进制,再与已收到的字节数相减得到 rest-size(mcp.el):
rest-size <= 0:消息完整,直接 push 进解析队列rest-size > 0:把已收到的部分写入挂起缓冲,记录jsonrpc-message-rest-size,等下一个 data 块到达时继续累加,直到计数归零才拼出完整 JSON
这个"十六进制长度计数 + 剩余字节追踪"的方案,让 mcp.el 能正确处理被 TCP 流切碎的大消息,而不依赖任何不稳定的边界假设。
五、握手流程:从 initialize 到工具列表
SSE 的 endpoint 事件(或 stdio 进程就绪后)会触发 mcp--send-initial-message,完成 MCP 协议的完整握手:
- 发送
initialize请求,声明协议版本(2025-03-26优先,见 mcp--support-versions)和客户端能力roots/listChanged - 校验服务器返回的
protocolVersion是否在支持列表中,不支持则直接断开 - 发送
notifications/initialized通知 - 延迟
mcp-server-wait-initial-time(默认 2 秒)后,按服务器声明的能力依次拉取:prompts → tools → resources → resource templates - 把状态置为
connected,逐个触发用户回调
超时控制也在这里:initialize 请求带了 mcp-server-start-time(默认 60 秒)超时,超时回调对 SSE 连接做了特殊豁免(见 mcp--initialize-message)。
六、上手体验与源码地图
如果你想实际跑起来,安装只需满足 Emacs 30+ 并配置 mcp-hub-servers,具体用法参考 Readme.org。配合 mcp-hub.el 可以打开一个可视化管理界面,对配置的所有服务器执行启动/停止/重启(其启动入口 mcp-hub--start-server 本质上是带回调包装的 mcp-connect-server)。
最后给出一份按主题划分的源码地图,方便二次开发时快速定位:
| 主题 | 位置 |
|---|---|
| 连接类定义 | mcp.el#L93-L184 |
| 连接入口 | mcp.el#L758-L891 |
| JSON-RPC 发送 | mcp.el#L244-L364 |
| process filter 主体 | mcp.el#L369-L535 |
| SSE 建连 | mcp.el#L537-L588 |
| SSE 事件解析 | mcp.el#L413-L479 |
| initialize 握手 | mcp.el#L685-L750 |
| 工具调用封装 | mcp.el#L974-L1024 |
七、小结
mcp.el 用不到 1500 行 Elisp 实现了完整的 MCP 客户端,其可借鉴的设计点非常清晰:
- 用 CLOS 类继承抽象传输差异,业务层只面对统一的 connection 对象
- process filter 中用挂起缓冲 + 十六进制长度计数优雅地解决 TCP 半包问题
- 防重入 + 定时器派发保证了事件循环的健壮性
- 基于响应内容的 SSE 自动降级让它能兼容新旧两代服务器
理解了这几块,你基本上就掌握了在 Emacs 里构建任意长连接协议客户端的通用套路。