第 8 篇读完了 wire 模型层:mcp-types 包用 pydantic 把 JSON-RPC 报文定义成一个个模型,请求、响应、通知、错误各有准确的形状。但模型只回答"线上长什么样",回答不了"谁在收、谁在调、超时了谁负责收场"。这些问题的答案在 SDK 的会话引擎里——v2 做了一件伤筋动骨的事:删掉陪伴整个 v1 时代的 BaseSession,换成一枚共享的 dispatcher 引擎。本篇是《MCP 协议与实现》第 9 篇、源码篇第 2 篇,继续以 mcp 2.3.0 源码为准(wheel 解包本地走读,写作时 2026 年 11 月),按"重写动机 → 引擎全景 → 派发核心 → 超时取消 → 双轨接入 → 通知分野 → 传输解耦 → 总结"组织全文。
1、为什么要重写会话层
先看被删掉的是什么。v1 的 BaseSession 住在 mcp/shared/session.py,客户端 ClientSession 与服务端 ServerSession 都继承它:驱动收流、把响应匹配回等待中的请求、分发通知、给出站请求计时,全套管道长在这一个会话基类上。能用,但三个问题越积越重。
其一,引擎与协议语义搅在一起:BaseSession 直接认识 notifications/cancelled 这类 MCP 消息,换传输、换端侧都得拖着整个基类走。其二,双端各自继承一份,管道逻辑重复,改一处容易漏一处。其三,进程内测试代价高——第 5 篇提过,v1 要手工调 create_connected_server_and_client_session 组装内存传输对,才能在 pytest 里直连一个 server。最要命的是超时与取消的语义:出站请求到点抛异常后引擎就撒手,对端不知道、继续白干;对端发来取消时,打断的主要是"等结果"的等待方,已经在跑的 handler 能否及时收手没有统一保证。
v2 的处理不是重构而是删除。在 python-sdk 2.3.0 的包里全文检索 BaseSession,零命中——连兼容别名都没留。顶替它的引擎在 mcp/shared/dispatcher.py,"会话"这个词从引擎层彻底消失了:dispatcher 不维护会话状态,只做进程内消息派发,MCP 语义全部上移,线格式全部下沉。
2、dispatcher 全景
引擎由三个类分层组成,位置与分工如下。
| 文件 | 类名 | 定位 |
|---|---|---|
mcp/shared/dispatcher.py |
Dispatcher |
引擎协议,只定义接口 |
mcp/shared/jsonrpc_dispatcher.py |
JSONRPCDispatcher |
生产实现,对接 JSON-RPC 线格式 |
mcp/shared/direct_dispatcher.py |
DirectDispatcher |
进程内直连,测试与内嵌用 |
Dispatcher 是个 Protocol,模块 docstring 把它的边界讲得很直白:把一条双工消息通道变成两样东西——出站 API 与入站泵。引擎刻意不感知 MCP:方法名是字符串,参数与结果是 dict[str, Any];MCP 类型层(请求模型、能力协商、Context)坐在它上面,线格式(JSON-RPC、进程内直连,docstring 甚至点名 gRPC)躺在它下面。一个请求从进门到回包的生命周期如下。
图里藏着本篇最重要的一个事实:引擎不做方法名到 handler 的查找。它把方法名原样交给上层传入的回调,查找发生在 ServerRunner 里(第 5 节展开)。引擎只负责"消息怎么流动",不负责"方法由谁服务"——这条边界是后面一切架构红利的来源。
3、派发核心走读
入站泵的骨架在 run():开一个 anyio 任务组,逐条读流、逐条派发,读完或出错后统一收场。核心节选如下(源码有删减,注释为笔者所加)。
async with self._write_stream: # LIFO:写流最后关,善后写还能落地
async with anyio.create_task_group() as tg:
self._tg = tg
task_status.started() # 此刻起出站 API 可用
try:
async with self._read_stream:
async for item in self._read_stream:
sender_ctx = getattr(self._read_stream, "last_context", None)
await self._dispatch(item, on_request, on_notify, sender_ctx)
self._fan_out_closed() # EOF:唤醒所有出站等待者
finally:
tg.cancel_scope.cancel() # 收场:取消全部在飞 handler
三条设计藏在里面:task_status.started() 让上层在引擎就绪后才发出站请求;读流结束后 _fan_out_closed 给每个等待响应的出站调用送上 CONNECTION_CLOSED,谁也不会干等;而 finally 里那记 tg.cancel_scope.cancel() 是收场兜底——连接没了,handler 跟着停,任务组的 join 不会吊死在早已无人认领的执行上。
每条消息进来先过 _dispatch 的类型分流,一小段 match 把四种 JSON-RPC 消息各归其位。
match msg:
case JSONRPCRequest():
await self._dispatch_request(msg, metadata, on_request, sender_ctx)
case JSONRPCNotification():
self._dispatch_notification(msg, metadata, on_notify, sender_ctx) # 同步
case JSONRPCResponse():
self._resolve_pending(msg.id, msg.result)
case JSONRPCError():
self._resolve_pending(msg.id, msg.error)
注意请求与通知的待遇差异:请求走 await,通知只是同步调用后立刻回到读循环。响应与错误则根本不进 handler——它们查 _pending 表找到等待者,用 send_nowait 把结果塞进内存通道,出站调用方就此醒来。id 归一化也在这里:coerce_request_id 把字符串化的 "7" 折叠回整数 7,两端对 id 的相关性判断共享同一套规则。
请求这一路的登记动作值得细看,节选如下。
dctx = _JSONRPCDispatchContext( # 请求级上下文:取消标志、进度令牌
transport=transport_ctx, _dispatcher=self,
_request_id=req.id, _progress_token=progress_token,
)
scope = anyio.CancelScope()
self._in_flight[coerce_request_id(req.id)] = _InFlight(scope=scope, dctx=dctx)
if req.method in self._inline_methods:
self._spawn(_run_inline, sender_ctx=sender_ctx)
await done.wait() # 内联方法停住读循环,保住顺序
else:
self._spawn(self._handle_request, req, dctx, scope, on_request, ...)
每个请求先在 _in_flight 在飞表里登记"取消域 + 上下文",这是后续取消通知能精准命中的索引。然后分两路:initialize 这类内联方法(runner 层传入了 inline_methods={"initialize"} 规则)虽然也 spawn 执行,但读循环会 await done.wait() 停住等它——握手必须按序完成;其余请求 spawn 后立刻回去读下一条,并发由任务组自然承载,慢请求不会阻塞快请求。
4、超时与取消的真清理
这是 v2 动机最足的一块,先看出站超时。实现既不是 asyncio.wait_for 也不是简单一刀切的 deadline,而是 mcp/shared/_request_clock.py 里的预算制时钟。
def pause(self) -> None:
if not self._pauses:
self._budget = self._scope.deadline - anyio.current_time()
self._scope.deadline = math.inf # 时钟停走,剩余预算先存起来
self._pauses += 1
def resume(self) -> None:
self._pauses -= 1
if not self._pauses:
self._scope.deadline = anyio.current_time() + self._budget
时钟骑在 anyio CancelScope 的 deadline 上(背景见 anyio 取消文档),但可以暂停:模块 docstring 一句话点题——请求的超时量的是对端,所以等人的时候时钟要停。一次工具调用中途去问用户(elicitation 或 MRTR 后续轮),等待人类的时段不烧预算,回来续上剩余额度接着算。时钟本体放在 ContextVar 里随执行上下文传播,深埋在传输层的代码也能找到"当前请求的时钟"。
超时之后的动作更见功力:引擎会补发一封 notifications/cancelled——这是 v1 没有的礼貌性取消(courtesy cancel)。v1 到点抛出超时异常就此结束,对端毫不知情继续干活;v2 的补发写操作走 shielded 路径并且自带 _ABANDON_WRITE_TIMEOUT 上限,挂死的传输也拖不垮取消路径。调用方主动取消同样补发,对端不白干。
入站方向的取消在通知拦截里,一瞥见真章。
if msg.method == "notifications/cancelled":
rid = cancelled_request_id_from_params(msg.params)
if rid is not None and (in_flight := self._in_flight.get(coerce_request_id(rid))) is not None:
in_flight.dctx.cancel_requested.set()
if self._peer_cancel_mode == "interrupt":
in_flight.scope.cancel() # 默认:直接打断 handler 的取消域
对端的取消通知先查在飞表,命中后按模式处理,两种模式如下。
| 模式 | 行为 |
|---|---|
| interrupt | 默认。取消 handler 的作用域,执行在下一个检查点被打断 |
| signal | 只置 cancel_requested 标志,handler 自行轮询决定何时收手 |
无论哪种模式,被取消的请求永不回答——规范要求不得再为它发送任何消息,引擎替 handler 兜住这条纪律。执行与写回的完整边界在 _handle_request,节选如下。
try:
with scope: # 对端取消就落在这个域上
result = await on_request(dctx, req.method, req.params)
dctx.close() # 同时从在飞表摘除
if not dctx.cancel_requested.is_set():
await self._write_result(req.id, result) # 正常路:写回结果
except Exception as e:
error = handler_exception_to_error_data(e) # 唯一的异常上线边界
if not dctx.cancel_requested.is_set():
await self._write_error(req.id, error)
if not answer_write_started:
await self._settle_unanswered(dctx) # 被取消:静默落定
这是全引擎唯一一处"异常变报文"的边界:handler 抛什么异常都在这里翻译成 JSONRPCError 写回,一个崩溃的 handler 只损失这一个请求。整个关闭流程的顺序也讲究——写流在任务组 join 之后才关闭,所以关闭时的善后写(礼貌取消、CONNECTION_CLOSED 兜底响应)仍然能落到线上。两代实现对照如下。
| 维度 | v1 的 BaseSession | v2 的 dispatcher |
|---|---|---|
| 架构位置 | 会话基类,双端各自继承 | 独立引擎,两端共享同一实现 |
| 出站超时 | 到点抛异常即结束 | 预算制时钟可暂停,超时后礼貌取消 |
| 入站取消 | 以打断等待方为主 | 取消域打断执行方,被取消者永不回答 |
| 异常边界 | 分散在各会话类 | 单一 exception-to-wire 边界 |
| 进程内直连 | 手工组装内存传输对 | DirectDispatcher 直接可用 |
5、双轨汇入同一张表
第 3 篇讲过 v2 是双轨 API:低层 Server 构造器传 handler(低层 Server 文档),高层 MCPServer 装饰器注册函数。源码走读到这里可以补上底牌——两条轨道殊途同归,落进同一张表。先看低层 Server 构造器做的事。
_spec_requests = [
("ping", types.RequestParams, on_ping),
("prompts/list", types.PaginatedRequestParams, on_list_prompts),
("resources/read", types.ReadResourceRequestParams, on_read_resource),
("tools/list", types.PaginatedRequestParams, on_list_tools),
("tools/call", types.CallToolRequestParams, on_call_tool),
# ……共 14 个规范方法
]
self._request_handlers.update({m: HandlerEntry(pt, h) for m, pt, h in _spec_requests if h is not None})
每个构造器参数展开成"方法名 →(参数模型, handler)"的条目,塞进 _request_handlers 字典。这张表的消费者是 mcp/server/runner.py 的 ServerRunner:它实现的 _on_request(dctx, method, params) 正是引擎回调的 on_request——查表、用参数模型做 pydantic 验证、过 middleware 链(OTel 中间件默认在场),最后调用 handler。而把 runner 接到引擎上的关键三行(自 runner.py 节选拼合)如下。
dispatcher = JSONRPCDispatcher(...)
connection = Connection.for_loop(dispatcher, session_id=session_id)
await dispatcher.run(runner.on_request, runner.on_notify, task_status=task_status)
高层那条轨道呢?v2 把 FastMCP 改名 MCPServer(旧路径 mcp.server.fastmcp 只剩一个 16 行的报错模块,指路迁移指南),它构造时同样要造一个低层 Server。
self._lowlevel_server = Server(
...,
on_list_tools=self._handle_list_tools, # 装饰器目录汇总成低层 handler
on_call_tool=self._handle_call_tool,
)
@mcp.tool() 注册的函数先进 MCPServer 自己的工具目录;tools/list 与 tools/call 到来时,_handle_list_tools、_handle_call_tool 负责从目录里现查现答。所以在引擎视角里根本不存在两条轨道——只有一张 _request_handlers 表、一个 ServerRunner、一枚 dispatcher。第 3 篇"高层翻译函数、低层直面方法"的表述,在源码里就是这层包含关系。
顺带为第 4 篇补一个底注:ServerSession 这个名字还在,但身份全变了——它不再是会话基类,而是内核为每个入站请求现造的请求级代理,handler 里的 ctx.session 拿到的就是它,服务端反向请求与通知都从它走。
6、通知与请求的分野
回到第 3 节埋的伏笔:请求 await,通知同步。差异不止于此,根源在于请求有回包义务,通知没有。通知不登记在飞表、没有取消域、没有超时,fire-and-forget,处理丢了就丢了。引擎自己拦截两张内部表相关的通知:notifications/cancelled 关联 _in_flight(第 4 节已读),notifications/progress 查 _pending 表找到出站请求挂的进度回调。进度回调的调用包了一层防御——_shielded_progress 包装器保证用户回调抛异常不会取消引擎的任务组,一个坏回调只损失这一条进度。
通知 handler 本体的调用同样有防御包装。
async def _wrapped(dctx, method, params):
try:
await fn(dctx, method, params)
except Exception:
logger.exception(...) # 通知 handler 崩溃只进日志
_contained_notify 的名字起得准确:把通知处理"兜住"。对照请求侧——handler 异常会变成 JSONRPCError 回给对端,调用方能感知失败;通知没有对端可回,异常只能进日志,但无论哪侧,单个 handler 的崩溃都伤不到连接本身,读循环照常转。另外上层还可传 on_notify_intercept:在派发给用户通知 handler 之前先过一道拦截器,消费掉的通知不再下沉——第 4 篇读过的"宿主截获"类机制的挂点就在这里。
7、传输无关的架构红利
整条走读下来会发现,引擎从头到尾没碰过 stdio 或 HTTP 的任何细节——它只见读写两条流,流的元素是 SessionMessage。传输层的全部职责是把字节变成流里的消息:stdio 拿子进程管道做流,Streamable HTTP 拿请求响应做流。想加一种新传输(docstring 点名的 gRPC 之类),实现两条流就能骑上整套派发、超时、取消、异常边界,引擎零改动。
有个精巧的细节值得单独讲:消息进城时引擎会尝试读取读流上的 last_context 属性——这是个鸭子类型约定,只有带上下文快照的 ContextReceiveStream 才有。HTTP 传输里,ASGI 中间件(认证、OTel)写在发送任务上的 contextvars,就这样跟着消息本身到达 handler:_spawn 用 sender_ctx.run(self._tg.start_soon, run) 把派发任务放进发送方的上下文里执行。进程边界的消息携带执行上下文,这是无状态内核下"每请求自描述"在工程侧的呼应。
最后是 DirectDispatcher 的位置。它实现了同一个 Dispatcher 协议,但线格式是进程内直调——没有 JSON 编解码、没有传输字节。第 5 篇的进程内三件套(Client(mcp) 内存直连)底层骑的就是它:测试要的是毫秒级往返与确定性行为,绕开线格式正合适;内嵌场景(把 server 当库用)同理。一个协议、三个实现、零 MCP 语义——引擎层的解耦到此闭环。
8、总结
v2 删掉 BaseSession 换成共享 dispatcher,不是为改而改:引擎与协议语义解耦(方法名只是字符串,查找上移到 ServerRunner 的方法表)、双端共享同一实现、超时从一刀切变成可暂停的预算制时钟、取消从"打断等待"升级为"取消域打断执行 + 礼貌取消 + 永不回答"、异常收敛到单一上线边界,传输层彻底退化为两条流。低层构造器与高层装饰器在第 5 节的源码里汇入同一张表,印证了第 3 篇的双轨叙述。对于排障与二次开发的读者,建议把引擎里的两张表当导航图:取消没生效查 _in_flight,方法没命中查 _request_handlers,超时行为异常先看时钟有没有被暂停。留三道练习:
- 把
peer_cancel_mode设为signal,长任务取消后从日志看 handler 是否跑完 - 通读
DirectDispatcher,列出它相对 JSON-RPC 实现跳过的步骤并逐一验证 - 给低层
Server手写on_list_tools,断点确认高层工具调用走的是同一张表
多轮往返的悬念还留着:MRTR(Multi Round-Trip Requests,见 SEP-2322)在引擎与 runner 层怎么落到 input_required 与 inputResponses 的重试循环,是第 10 篇的主题,源码篇收官见。

