消息怎样被读取和处理
适用范围:mcp/src 和 soulsoft_web_mcp/src,仅 MCP 2026-07-28。本文记录当前实现和这轮讨论确定的取舍。
仓颉的 spawn 创建语言线程,由运行时调度;下文说的 worker 是执行任务的语言线程,不等于固定占用一个操作系统线程。
先看结论
| 消息 | 谁先接收 | 谁做实际处理 | 读循环是否等待处理完成 |
|---|---|---|---|
服务端收到普通请求,例如 tools/call |
stdio/HTTP 传输入站队列,再由 McpServerImpl.run() 读取 |
有界请求 worker | 不等待 |
服务端收到 subscriptions/listen |
同上 | 独立的订阅任务,受并发名额限制 | 不等待 |
| 服务端收到通知 | stdio 由 run() 读取;HTTP 由该 POST 的宿主线程接收 |
内部取消立即处理;注册的用户回调由串行通知 worker 处理 | 不等待用户回调 |
| 客户端收到响应 | readLoop() |
按请求 ID 找到等待方并唤醒它 | 只做匹配和唤醒,不执行用户回调 |
| 客户端收到通知 | readLoop() |
内部取消立即处理;注册的用户回调由串行通知 worker 处理 | 不等待用户回调 |
readLoop() 和 run() 各只有一个入站读消费者。这样消息只被读取一次;慢工具和慢通知回调则在别处运行。通知回调可以同步发起新请求,因为读循环仍能继续读取新请求的响应。
请求与响应示意图
sequenceDiagram
participant Caller as 客户端调用方
participant ClientRead as 客户端 readLoop
participant ServerRead as 服务端 run 读循环
participant Worker as 请求 worker
participant Tool as 用户工具
Caller->>Caller: 登记请求 ID 和 PendingRequest
Caller->>ServerRead: 发送 tools/call
ServerRead->>Worker: 入队请求,继续读取下一条
Worker->>Tool: 调用工具
Tool-->>Worker: 返回结果
Worker-->>ClientRead: 发送 JSON-RPC 响应
ClientRead->>Caller: 按 ID 完成等待并唤醒
Caller->>Caller: 取得结果
图中的发送和接收之间还有传输层:stdio 走标准输入输出管道;HTTP 每个请求走自己的 POST。两种传输都由服务端 worker 处理工具,客户端读循环只负责匹配响应。
一次普通请求怎么走
例如客户端调用 tools/call:
- 调用方给请求分配 ID,在客户端登记一个
PendingRequest,然后通过传输发送。stdio 会在发送锁保护下写入服务器的 stdin;HTTP 会在调用方的执行体上发起一个 POST。 - 服务端读循环取到请求,运行入站过滤器,登记请求上下文,再把请求交给
BoundedWorkExecutor。读循环随即继续读下一条消息。 - 一个普通请求 worker 执行工具。默认最多 32 个 worker,另可排队 128 个请求;队列满时立即返回 JSON-RPC
ServerError,消息是MCP server is busy。 - 工具完成后,
RequestContext发送结果。stdio 用发送锁保证 JSON-RPC 消息不交错;HTTP 把结果写到这个 POST 自己的响应队列。 - 客户端读循环按 ID 找到
PendingRequest,调用完成通知。等待的调用方醒来并取得结果。唤醒本身不执行工具或通知回调。
subscriptions/listen 不占普通请求队列:它有独立的并发名额,默认 16 个。名额用完也立即返回 busy。HTTP 的每个请求有自己的 POST transport,因此不同 POST 使用相同 JSON-RPC ID 不会被误当成同一个在途请求。
一次通知怎么走
例如服务端收到一个已注册用户回调的通知:
- stdio 通知由
run()从入站队列读取。HTTP 通知由对应的 HTTP POST 宿主线程接收,先经过同一条入站过滤器链;过滤器调用用锁串行化。 notifications/cancelled的内部取消动作立即执行,不排队等用户回调。HTTP 2026-07-28 没有跨 POST 的会话关联;独立 HTTP 取消 POST 不能仅凭请求 ID 安全取消另一个 POST。- 服务端对用户注册的通知处理器取快照,并尝试放入
SerialWorkExecutor。客户端收到通知时也按同样方式将用户回调放入自己的SerialWorkExecutor。 - 每侧各有一个通知 worker,按入队顺序执行回调。回调抛出的异常会被隔离,不占住入站读循环。
通知队列容量是 256,入队不阻塞读循环。满载时不静默丢弃:客户端结束该连接并唤醒等待请求;stdio 服务端结束其唯一会话;HTTP 没有会话,该通知 POST 返回 HTTP 503 和 JSON-RPC ServerError,共享服务器继续处理其他请求。执行器会累计入队拒绝次数。HTTP 通知只有在准入成功后才返回 202。
flowchart LR
A[入站通知] --> B{传输方式}
B -->|stdio| C[服务端 run 读循环]
B -->|HTTP| D[该 POST 的宿主执行体]
C --> E[入站过滤器与分派]
D --> E
E --> F{取消通知?}
F -->|是| G[立即处理内部取消]
F -->|否| L{有用户回调?}
G --> L
L -->|是| H[尝试放入通知队列]
L -->|否| M[处理结束]
H -->|入队成功| I[单个通知 worker 按顺序调用回调]
H -->|队列满:stdio| J[结束该会话]
H -->|队列满:HTTP| K[该 POST 返回 503]
取消通知若没有注册用户回调,在内部取消完成后就结束,不会进入队列。客户端收到通知时也由单个通知 worker 执行用户回调;队列满则结束客户端连接。
HTTP 为什么多一个等待者
每个 HTTP 请求 POST 都创建一个 StreamableHttpPostTransport。服务端 worker 把响应或订阅通知送进该 POST 的出站队列;处理该 POST 的宿主执行体用 ChannelReader.read() 等待队列消息,再写入 JSON 或 SSE 响应流。队列容量为 64,满时发送方等待空位,最终响应不会因为队列满而被丢弃。
这里的 read() 由消息到达或队列完成唤醒,不再每 20 毫秒轮询。如果服务器关闭发生在请求尚未成功入队时,POST 立即得到传输关闭错误,stdx 和 Spire 适配层都返回 503。如果请求已入队、但关闭时尚未开始执行,worker 会取消请求上下文并关闭对应 POST 的响应队列,避免宿主执行体一直等不到结果。
HTTP 客户端的普通请求目前在调用方的执行体中同步发送并读取响应;长期订阅另派生 SSE 读取任务。HTTP/1.1 的 stdx 客户端连接池对同一主机设为 20;这是底层 HTTP 连接上限,不是 MCP 自建的 TCP 线程池,连接用满时 stdx 会报错。
队列满或关闭时会怎样
| 位置 | 默认容量 | 满载时 | 关闭时 |
|---|---|---|---|
| stdio/HTTP 服务端入站 | 256 | 写入方等待空位 | 唤醒读写等待者;新 POST 返回 503 |
| 普通请求执行器 | 128 排队,32 worker | 立即返回 busy | 停止接收新任务 |
| 长期订阅 | 16 个任务 | 立即返回 busy | 取消请求上下文 |
| 客户端和服务端的通知执行器 | 各 256 | 按上节所述明确拒绝 | 停止接收并唤醒 worker |
| 每个 HTTP POST 出站 | 64 | 发送方等待空位 | 唤醒等待响应的宿主执行体 |
| 客户端入站 | 256 | 传输读取方等待空位 | 唤醒客户端读循环 |
Channel 用一把锁保护队列状态。普通入队只唤醒一个等待读取者,普通出队只唤醒一个等待写入者;complete() 和 fail() 会唤醒所有等待者。容量包含数据和排队的非终止错误事件。队列完成后,读者先取完已有消息,再得到 None 或终止错误。
关闭、取消与超时
- 服务端
close()停止接收,关闭执行器和传输,并取消在途请求上下文。它不等待正在执行的用户工具结束;工具若需要尽早退出,应检查RequestContext.isCancelled。这轮讨论决定不增加任务排空。 - 客户端
close()会让全部等待中的请求失败并关闭传输。普通请求的响应等待默认 60 秒,可配置;subscriptions/listen默认不设该期限。 - 普通请求超时后只清理客户端本地等待项,不发送取消通知。这轮讨论决定暂不处理;超时并不保证服务端工具停止。
- HTTP 客户端断开后,服务端目前未收到可靠的远端断开信号;这轮讨论决定暂不处理。没有结果且 POST 通道未关闭时,HTTP 宿主执行体仍会等待。
这轮优化与保留项
已实施:通知用户回调离开读循环;响应按 ID 立即完成;普通请求和订阅各有限额;客户端等待有期限;流传输关闭状态与发送锁分开;OAuth 授权和刷新在状态锁外合并并发获取;HTTP 响应去掉 20 毫秒轮询;通知溢出按传输类型明确处理;关闭期间 HTTP POST 不再因投递失败而挂住;Channel 的逐项唤醒改为 notify()。
保留现状:HTTP 请求 busy 仍用 JSON-RPC ServerError 表达,HTTP 状态可能为 200;HTTP 客户端连接池固定 20;传输队列容量固定 256/64;已经阻塞的底层 stdio 写入能否被跨线程关闭打断,取决于底层流实现。
相关实现:src/common/channel.cj、src/common/serial_work_executor.cj、src/common/bounded_work_executor.cj、src/client/client.cj、src/server/mcp_server_impl.cj、src/server/streamable_http_post_transport.cj。