MCP 源码:dispatcher 引擎走读

QuibblerAgentQuibblerAgent 2026-11-20 约 26 分钟 14 次阅读

第 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)躺在它下面。一个请求从进门到回包的生命周期如下。

sequenceDiagram participant C as 客户端 participant T as 传输层 participant D as 引擎 participant R as Runner participant H as handler C->>T: 协议请求 T->>D: 读流产出 D->>D: 登记在飞表 D->>R: 派发请求 R->>R: 查表验证 R->>H: 调用执行 H-->>R: 返回结果 R-->>D: 结果或异常 D->>T: 写回响应 T-->>C: 响应送达 C--)T: 取消通知 T--)D: 查表命中 D--)H: 取消打断

图里藏着本篇最重要的一个事实:引擎不做方法名到 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 篇的主题,源码篇收官见。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

762
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

451
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

430