消息怎样被读取和处理

适用范围: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:

  1. 调用方给请求分配 ID,在客户端登记一个 PendingRequest,然后通过传输发送。stdio 会在发送锁保护下写入服务器的 stdin;HTTP 会在调用方的执行体上发起一个 POST。
  2. 服务端读循环取到请求,运行入站过滤器,登记请求上下文,再把请求交给 BoundedWorkExecutor。读循环随即继续读下一条消息。
  3. 一个普通请求 worker 执行工具。默认最多 32 个 worker,另可排队 128 个请求;队列满时立即返回 JSON-RPC ServerError,消息是 MCP server is busy。
  4. 工具完成后,RequestContext 发送结果。stdio 用发送锁保证 JSON-RPC 消息不交错;HTTP 把结果写到这个 POST 自己的响应队列。
  5. 客户端读循环按 ID 找到 PendingRequest,调用完成通知。等待的调用方醒来并取得结果。唤醒本身不执行工具或通知回调。

subscriptions/listen 不占普通请求队列:它有独立的并发名额,默认 16 个。名额用完也立即返回 busy。HTTP 的每个请求有自己的 POST transport,因此不同 POST 使用相同 JSON-RPC ID 不会被误当成同一个在途请求。

一次通知怎么走

例如服务端收到一个已注册用户回调的通知:

  1. stdio 通知由 run() 从入站队列读取。HTTP 通知由对应的 HTTP POST 宿主线程接收,先经过同一条入站过滤器链;过滤器调用用锁串行化。
  2. notifications/cancelled 的内部取消动作立即执行,不排队等用户回调。HTTP 2026-07-28 没有跨 POST 的会话关联;独立 HTTP 取消 POST 不能仅凭请求 ID 安全取消另一个 POST。
  3. 服务端对用户注册的通知处理器取快照,并尝试放入 SerialWorkExecutor。客户端收到通知时也按同样方式将用户回调放入自己的 SerialWorkExecutor。
  4. 每侧各有一个通知 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。