MCP 源码:MRTR 实现与收官

QuibblerAgentQuibblerAgent 2026-11-20 约 30 分钟 15 次阅读

第 9 篇《MCP 源码:dispatcher 引擎走读》跟完了请求在会话引擎里的派发:收流、匹配响应、超时与取消。但引擎只负责把消息送到该去的地方,有一类响应它原样转发却不去解释——resultType=input_required 的中途结果,以及随重试回来的 requestState。这两样是 MRTR(Multi Round-Trip Requests,多轮往返请求) 的线上载体:第 2 篇《MCP 无状态内核:2026-07 改版详解》在协议层拆过报文,第 4 篇《MCP handler 内幕:Context 与 Resolve》在 handler 层用过 Resolve 与 Elicit,中间那层——SDK 拿到一次 tools/call 之后怎么把两篇接起来、答案凭什么精准落回当初问出的那个问题——正是本篇要走的路。本篇是《MCP 协议与实现》第 10 篇、源码篇第 3 篇、全系列收官,按"全链路总图 → 结果类型 → 执行时机 → 三态消费 → 两代分流 → 指纹与封印 → 十篇回顾"组织,口径以 mcp 2.3.0 与 mcp-types 2.3.0 wheel 解包源码为准(本文写作时 2026 年 11 月)。


1、MRTR 全链路总图

先给全景再进源码。一次带 Resolve 参数的工具调用,在 SDK 里横跨注册与调用两个时期、客户端两轮报文,完整链路对应 SEP-2322 的交互模型,时序如下。

sequenceDiagram participant C as 客户端 participant S as SDK 内核 participant H as 用户代码 Note over S: 注册期已建好依赖图与计划 C->>S: tools/call 首轮 S->>H: 先跑 resolver 不跑工具体 H-->>S: 返回 Elicit 标记 S->>S: 渲染问题并记录指纹 S-->>C: input_required 附问题清单 Note over C: 向用户或模型收集答案 C->>S: 重试请求附答案与状态 S->>S: 验封 核指纹 恢复结局 S->>H: 注入参数 运行工具体 H-->>S: 返回结果 S-->>C: resultType=complete

解读:注册期 Tool.from_function 静态分析函数签名,把 Resolve 参数从 schema 剔除并建好 resolver 依赖图;首轮调用先跑 resolver,拿到 Elicit 标记后渲染问题、记下指纹,把待问问题打包进 InputRequiredResult 返回,工具体一轮都不执行;客户端收集答案后按原样重试,SDK 验封状态、核对指纹,恢复或消费答案,注入参数后才运行工具体。每一轮都是对同一个请求的完整重放,两次处理之间不依赖任何连接级状态——这正是第 2 篇无状态内核的落地形态。下面各节按这个顺序逐段读源码。

2、InputRequiredResult 源码

载体类型定义在 mcp-types 包(第 8 篇拆过它的模型层),SDK 统一出口 _types 模块里的定义如下。

class InputRequiredResult(Result):
    result_type: Literal["input_required"] = "input_required"
    input_requests: InputRequests | None = None
    request_state: str | None = None

    @model_validator(mode="after")
    def _require_one_field(self) -> Self:
        if not self.input_requests and self.request_state is None:
            raise ValueError(
                "InputRequiredResult requires at least one of "
                "input_requests or request_state"
            )
        return self

解读:三个字段加一个校验器就是全部——规范里"两字段至少其一"的 MUST 在构造期变成硬约束。各字段口径如下。

字段 类型 说明
result_type Literal 固定值 input_required,作双结果联合的判别标签
input_requests dict 键由服务器分配,值是待答的问题请求
request_state str 下一轮原样回传的不透明状态

三个细节值得放大。其一,序列化走 WireModel 的 camelCase 别名(resultType、inputRequests、requestState),客户端收到的正是第 2 篇手写的那份报文。其二,InputRequest 是三臂联合:CreateMessageRequest、ListRootsRequest、ElicitRequest,按 method 判别——MRTR 不只为问用户服务,sampling 与 roots 同样装得进去,对应的 InputResponses 四臂联合里就带着两个 sampling 结果类型。其三,版本专用模块 _v2026_07_28 把 result_type 声明为必填 str,SDK 统一出口却给了 Literal 默认值,所以 resolve 管线构造它时一行就够。能返回它的方法只有 tools/call、prompts/get、resources/read 三个载体,这份清单在源码里由"结果联合含 InputRequiredResult 臂"自动推导,不靠手抄。它在结果联合里的位置也值得一笔:ServerResult 把它与各正常结果并成一臂,客户端拿到响应先看 resultType 再决定怎么解析——中途结果与最终结果共用同一条响应通道,这正是报文层不新增方法号的设计取舍。

3、Resolve 的执行时机

第 4 篇说过"resolver 在工具体运行前执行",现在给出处。源码路径分两段,先看注册期,位于 mcp 包 server/mcpserver/tools/base.py 的 Tool.from_function。

resolved_params = find_resolved_parameters(fn)
if resolved_params and returns_input_required(fn):
    raise InvalidSignature(
        f"Tool {func_name!r} combines Resolve(...) parameters with "
        "an InputRequiredResult return; a call has one "
        "input_required channel ..."
    )

skip_names = [context_kwarg] if context_kwarg is not None else []
skip_names.extend(resolved_params)   # 不进 schema,模型看不见
resolver_plans = build_resolver_plans(resolved_params, tool_arg_names)

解读:注册期做四件事——找出 Resolve 参数;与手工 InputRequiredResult 返回臂做互斥检查(一条调用只有一条状态通道);把 Resolve 参数连同 Context 参数从输入 schema 剔除;build_resolver_plans 沿依赖递归分析每个 resolver 的参数,只认 Context、嵌套 Resolve、按名工具实参三类,认不出直接 InvalidSignature,环依赖同样在此拦截。两个时期的分工如下。

时期 做什么 产物
注册期 签名静态分析、建依赖图、查环 resolver 计划与稳定 wire key
调用期 逐个运行 resolver、收集问题 注入值或 InputRequiredResult

再看调用期,同文件 Tool.run 的主干(完整实现见 python-sdk 仓库)。

if self.resolved_params:
    resolved = await resolve_arguments(
        self.resolved_params, self.resolver_plans, validated, context
    )
    if isinstance(resolved, InputRequiredResult):
        # 还有 resolver 等输入:本轮返回问题,不跑工具体
        return resolved
    pass_directly |= resolved

result = await self.fn_metadata.call_fn(
    self.fn, self.is_async, validated, pass_directly
)

解读:resolver 严格先于工具体,答案未齐时工具体零次执行。这是设计使然:注入的值是工具参数,参数没有着落,跑体没有意义;多轮重试里工具体要么不跑、要么只在答案齐的那一轮跑一次,副作用不随轮数翻倍。源码注释还钉了一个细节——resolver 与工具体看到同一份校验后的实参,按名依赖拿不到与体不同的值。运行期另有兜底:参数用了 Resolve 的工具若在体内手写返回 InputRequiredResult(注册期注解查不出的那种写法),直接 RuntimeError,理由与注册期同一条——一条通道不能两条流一起驱动。

4、三态消费的两副面孔

答案回来之后如何交到 handler 手里。三态包装定义在 server/elicitation.py,三个类一个别名。

class AcceptedElicitation(BaseModel, Generic[ElicitSchemaModelT]):
    action: Literal["accept"] = "accept"
    data: ElicitSchemaModelT

class DeclinedElicitation(BaseModel):
    action: Literal["decline"] = "decline"

class CancelledElicitation(BaseModel):
    action: Literal["cancel"] = "cancel"

ElicitationResult = TypeAliasType(
    "ElicitationResult",
    AcceptedElicitation[ElicitSchemaModelT]
    | DeclinedElicitation | CancelledElicitation,
    type_params=(ElicitSchemaModelT,),
)

解读:三态就是三个 action 字面量——accept 带 data 载荷,decline 与 cancel 无载荷;ElicitationResult 用 TypeAliasType 定义成带类型参数的联合别名,所以第 4 篇能写 ElicitationResult[Overwrite] 这种注解。消费形态在 resolve 注入处一锤定音。

injected[name] = outcome if wants_union else _unwrap(outcome, name)

def _unwrap(outcome: ElicitationResult[Any], name: str) -> Any:
    if isinstance(outcome, AcceptedElicitation):
        return outcome.data
    raise ToolError(
        f"Resolver for parameter {name!r} could not resolve: "
        f"elicitation was {outcome.action}"
    )

解读:wants_union 在注册期由注解推出(类型参数是不是三态成员),调用期只做一次分支。两种注解对照如下。

注解形态 handler 收到 拒绝或取消时
解包形态 T 直接可用的值 SDK 自动抛 ToolError 中止
联合形态 ElicitationResult[T] 三态对象 handler 自行分支处理

省心与可控是一对取舍:解包形态适合"没有答案就没法继续"的硬依赖;联合形态适合"拒绝也是合法答案"的软征询,第 4 篇的重名覆盖确认选的就是后者。还有一个不起眼的兜底——resolver 返回普通值(不是请求标记)时同样包成 AcceptedElicitation,但不做 schema 校验、也不进 request_state:纯计算型 resolver 每轮重跑即可,与问用户型 resolver 共用同一套注入接口。

5、两代协议的分水岭

同一个 Elicit 标记,落在 2026-07-28 连接与 2025-11-25 连接上是两条执行路径,分流点只有一处(server/mcpserver/resolve.py)。

_INPUT_REQUIRED_VERSION = "2026-07-28"  # 钉死,不随最新版本漂移

def _uses_input_required(protocol_version: str | None) -> bool:
    """True when this request must elicit via InputRequiredResult."""
    return protocol_version is not None and is_version_at_least(
        protocol_version, _INPUT_REQUIRED_VERSION
    )

解读:判断依据是本次请求协商出的协议版本;源码注释特意说明版本常量是钉死的,不引用会随新修订移动的 LATEST_MODERN_VERSION——未来加版本不会让老行为悄悄翻转。还有一处边界:在活跃请求之外直接调 MCPServer.call_tool 时,protocol_version 为 None,同样落进同步分支——不过那条路径本来也到不了任何反向请求。_Resolution 构造时以此定下 input_required 布尔位,_fulfil 据此走两条臂(节选)。

async def _fulfil(marker, key, res):
    if not res.input_required:            # 旧协议:同步反向请求
        if res.context.session.can_send_request:
            _require_capability(res.context, marker, key)
        if isinstance(marker, Elicit):
            return await res.context.elicit(marker.message, marker.schema)
        result = await res.context.session.send_request(
            _render_request(marker), _result_type(marker)
        )
        return _accepted(result)

    request = _render_request(marker)     # 新协议:打包进本轮结果
    q = _request_digest(request)
    outcome = _restore_outcome(res, key, marker, q)
    if outcome is not None:               # 上轮问过且已有结局
        return outcome
    answer = res.answers.get(key)
    if answer is not None and res.asked.get(key) != q:
        answer = None                     # 指纹不符,答案作废
    if answer is None:
        res.pending[key] = request
        raise _Pending                    # 本轮到此为止
    ...                                   # 校验答案并落账

解读:旧臂走 ctx.elicit,一路调到会话的 elicit_form 反向请求,在连接内同步等回包,工具调用全程未结束;新臂把问题渲染成 InputRequest、查指纹、对答案,没有答案就抛 _Pending 把整轮调用短路成一次 InputRequiredResult。两条臂共用 _render_request 与 _require_capability——客户端没声明对应能力时报 -32021,与第 2 篇协议侧的 MissingRequiredClientCapability 同源。手工通道 ctx.elicit 若被用在新协议连接上,发送层发现没有反向通道直接抛 NoBackChannelError,这就是第 4 篇"新代码一律 Resolve"的源码依据。两代路径对照如下。

维度 新协议 2026-07-28 起 旧协议 2025-11-25 止
问题载体 结果内嵌 input_requests elicitation/create 反向请求
等待方式 返回后调用结束,客户端重试 调用挂起,同步等回包
答案回传 inputResponses 与 requestState 反向请求的 JSON-RPC 应答
状态载体 封印信封随请求回显 连接与会话本身

分流对 handler 完全透明:同一份 resolver 代码,两代客户端各走各的通道,第 4 篇"两代协议自动分流"的全部真相就是这一个布尔位。

6、问题指纹与状态封印

防串轮是 MRTR 最容易翻车的环节:重试的答案凭什么算数,回显的状态凭什么可信。SDK 用两层机制分别作答,先看应用层的问题指纹(resolve.py)。

class _StateEntry(BaseModel):
    action: Literal["accept", "decline", "cancel"]
    data: Any = None
    q: str | None = None   # 本条结局对应的问题渲染摘要

def _request_digest(request: InputRequest) -> str:
    params = request.params
    rendered = compact_json(
        params.model_dump(mode="json", by_alias=True, exclude_none=True)
        if params else None
    )
    digest = hashlib.sha256(rendered.encode()).digest()[:16]
    return base64.urlsafe_b64encode(digest).decode().rstrip("=")

解读:指纹是对问题规范渲染取 SHA-256 前 16 字节,文案、schema、参数全部参与,改一个字摘要就变。状态信封里装两张表:outcomes 记已答结局、每条钉着自己的 q;asked 记上一轮问出的问题摘要。信封版本如今是 v3,注释写明 v3 起已问与待问的结局都钉在 ASCII 规范渲染上——更早的版本没对齐渲染字节,同一问题的编码差异就可能让指纹对不上号,这正是第 4 篇那句"答案只对当初问出的原话生效"的实现处。消费侧三条规则共同防串轮:答案只在 asked 记录的摘要与本次渲染一致时才算数,不符则丢弃并记 the question changed since it was asked 日志、重新再问;恢复上轮结局时 q 对不上同样作废重问——重新部署改了措辞,老答案自动失效;已记录的结局优先于客户端重发的答案,resolver 自己的计算永远赢。支撑指纹跨轮成立的还有 wire key 的稳定性:问题在 input_requests 里的键取自 resolver 的 module:qualname,同名闭包自动加 #1 后缀,全程不含 id()——无状态部署下换个 worker 处理重试,键依然对得上。

应用层指纹只管"答案是否对应这个问题",不管"状态是否被人调包"。规范总览要求把回显的 requestState 当攻击者可控的数据对待,第二层因此是边界中间件 RequestStateBoundary(server/request_state.py):出站把状态封进带声明的信封,入站先验封再放行。封印的声明如下。

claims: dict[str, Any] = {
    "v": _ENVELOPE_VERSION,
    "iat": now,
    "exp": now + security.ttl,   # 默认 600 秒
    "m": ctx.method,             # 绑定方法
    "t": target,                 # 绑定工具名
    "a": args_digest,            # 绑定参数摘要
    "s": state,                  # 应用层状态原文
}
if self._audience is not None:
    claims["aud"] = self._audience
if principal is not None:
    claims["p"] = _principal_claim(principal)

payload = compact_json(claims).encode()
return security.codec.seal(payload)

解读:信封把状态与"哪次调用"绑死——方法、工具名、参数摘要、受众、OAuth 身份(客户端、发行方、主体的盐化哈希)任一不符即拒收,外加 TTL 过期。缺省编解码器是 AES-256-GCM,密钥经 HKDF-SHA256 派生,令牌加密而非仅签名,客户端读不到状态内容;keys 参数构成轮换环,首键封印、全体验封,滚动升级不断流。默认策略 ephemeral 用进程内随机键,单进程够用,多实例轮询部署必须显式共享 keys,否则别的实例封的状态这边解不开。验封失败一律 -32602,对外报文冻结成一句 Invalid or expired requestState,真实原因只进服务端日志。中间件只拦三个载体方法,resolver 与 handler 全程无感——它们拿到的 request_state 永远是自己人封发的明文。

7、十篇回顾与四层地图

收官前把全系列摊开。十篇按协议、开发、部署、源码四层递进:协议层定"线上长什么样",开发层定"怎么写出好 server",部署层定"怎么安全上线",源码层定"SDK 为什么这样实现"。地图如下。

mindmap root((MCP 十篇)) 协议层 第 1 篇 协议全景 第 2 篇 无状态内核 开发层 第 3 篇 SDK 实战 第 4 篇 handler 内幕 第 5 篇 测试三件套 部署层 第 6 篇 传输层 第 7 篇 生产化认证 源码层 第 8 篇 types 模型层 第 9 篇 dispatcher 引擎 第 10 篇 MRTR 收官

解读:前七篇自底向上搭工程能力,后三篇自外向内拆实现,本篇恰好是两条线的汇合点——MRTR 的实现同时用到第 8 篇的模型定义、第 9 篇的派发链路与第 2、4 篇的协议和 handler 语境。每篇一句话回顾如下。

篇目 一句话
第 1 篇 协议全景 三原语分工与两年演进,读懂任何一份 MCP 报文的起点
第 2 篇 无状态内核 2026-07-28 改版:_meta 自描述、头路由与 MRTR 报文
第 3 篇 SDK 实战 装饰器注册三原语,十行代码起一个合规 server
第 4 篇 handler 内幕 Context 注入、lifespan 共享与 Resolve 声明依赖
第 5 篇 测试三件套 mcp dev、进程内测试与宿主接入,交付最后一公里
第 6 篇 传输层 stdio 进程纪律与 Streamable HTTP,容器反代落地
第 7 篇 生产化认证 OAuth 2.1 资源服务器、发现与 Registry 运营
第 8 篇 types 模型层 pydantic 继承树与 _meta 建模,强类型承载演进协议
第 9 篇 dispatcher 引擎 BaseSession 退役,共享引擎接管派发超时与取消
第 10 篇 MRTR 收官 本篇:Resolve 到结果的完整路径与两层防串轮

四层叠起来就是 MCP 供给侧的完整剖面:协议决定边界,开发决定效率,部署决定存活,源码决定上限。

8、总结

本篇把 MRTR 的 SDK 实现走完:InputRequiredResult 三字段一校验器,wire 上以 resultType 判别;注册期静态分析建依赖图,调用期 resolver 先于工具体、答案未齐则体零次执行;三态由注解决定解包或分支;_uses_input_required 一处判断分流两代协议;问题指纹防答案串轮,AES-GCM 信封防状态调包。十篇合起来是一棵供给侧技能树:读协议会判别双结果与自描述请求,写工具三原语加 Context 加 Resolve 足够覆盖绝大多数场景,上生产传输、认证、多实例状态一个不能省,读源码从模型层、引擎、resolve 三处下手就能改得动 SDK。行动建议:对于读完系列的读者,建议把第 4 篇的 deploy 示例当走读入口,在 Tool.from_function 与 _fulfil 各下一个断点跑两轮调用;再用 RequestStateSecurity 自配密钥起一个 server,解开自己发出的 request_state——配上密钥它就是最好的调试日志。MCP 供给侧的大门到此推开,剩下的路在真机上。

相关推荐

​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