深入mcp.el源码:JSON-RPC通信、process filter与SSE事件解析的实现原理

原创2026-11-17 23:54:491,973 阅读

深入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 分支则相当丰富:

  1. 用 Emacs 内置的 url-retrieve 发起 POST,携带 Content-Type: application/json、Mcp-Session-Id、Authorization: Bearer 等请求头
  2. 在响应回调里用 mcp--parse-http-header 解析响应头
  3. 如果状态码是 4xx,说明服务器是旧版 SSE 服务器,于是标记 sse 并转入 SSE 连接流程
  4. 如果是 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 协议的完整握手:

  1. 发送 initialize 请求,声明协议版本(2025-03-26 优先,见 mcp--support-versions)和客户端能力 roots/listChanged
  2. 校验服务器返回的 protocolVersion 是否在支持列表中,不支持则直接断开
  3. 发送 notifications/initialized 通知
  4. 延迟 mcp-server-wait-initial-time(默认 2 秒)后,按服务器声明的能力依次拉取:prompts → tools → resources → resource templates
  5. 把状态置为 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 里构建任意长连接协议客户端的通用套路。

登录后查看全文
mcp.el