MCP handler 内幕:Context 与 Resolve

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

第 3 篇《MCP Python SDK v2 实战》把三原语的注册写法走了一遍:@mcp.tool() 把普通函数变成工具,函数名、docstring、类型提示合起来就是全部接口定义。但那些 handler 本质上仍是纯函数——参数进、结果出,执行期间外界一无所知。真实的工具远不止于此:批量任务要向客户端报进度,处理中途要读 server 自己暴露的资源,昂贵资源要全服务共享,有时还得在开工前向用户要一个确认。这些运行时能力,v2 收敛在两个机制里:注入给 handler 的 Context 对象,与声明式依赖 Resolve(fn)。

本篇是全系列第 4 篇、Server 开发层第 2 篇,按"Context 解构 → lifespan 共享资源 → Resolve 依赖注入 → MRTR 多轮往返 → 错误处理 → 实战"组织,读完你能把一个纯函数工具升级成带进度、带状态、能跟用户对话的完整 handler。结论均以 mcp 2.3.0 源码与官方文档站为准(本文写作时 2026 年 11 月)。


1、handler 不只是函数

纯函数模式有三个盲区。其一,长任务对客户端完全黑盒:模型发起 tools/call 后只能干等,中间没有任何反馈通道。其二,handler 够不着 server 自身的环境——连接池、启动配置、请求元数据,这些在函数参数里都没有入口。其三,工具参数由模型填,"这个值必须问用户本人"的诉求在纯函数模型里无解。

v2 的答案分两层。Context 负责注入运行时句柄:函数加一个注解为 Context 的参数,SDK 就把当前请求的上下文对象递进来,参数名任意、不需要可整个省略。Resolve 负责声明依赖:参数标成 Annotated[T, Resolve(fn)],这个参数不进工具 schema、不由模型填,改由 fn 在工具体运行前生成注入。handler 的常见诉求与提供方对照如下。

诉求 提供方
上报任务进度 Context 的 report_progress
读取本 server 资源 Context 的 read_resource
全服务共享昂贵资源 lifespan 与 lifespan_context
向用户收集输入 Resolve 加 Elicit
预期内的失败中止 抛 ToolError

下文逐个展开,最后用一个批量导入工具把五件事串起来。

2、解构 Context 对象

先看注入写法与最常用的进度上报,示例如下。

from mcp.server.mcpserver import Context, MCPServer

mcp = MCPServer("Demo")

@mcp.tool()
async def lengthy(task: str, ctx: Context) -> str:
    """执行一个长任务,期间向客户端上报进度。"""
    for step in range(1, 11):
        await ctx.report_progress(step, 10, message=f"步骤 {step} 完成")
    return f"{task} 完成"

解读:参数注解为 Context 即触发注入,参数名随意;工具不需要它就整个删掉。report_progress(progress, total=None, message=None) 把进度通知推给客户端——GA 版里进度通知是纯 server-to-client 方向,客户端界面与模型都能看到长任务在推进。同一把句柄还能读资源:await ctx.read_resource("docs://catalog") 在工具里复用第 3 篇注册的资源,免得自己再写一遍读取逻辑。

2.1、日志族已废弃

v1 教程里常见的 await ctx.info("处理中") 在 v2 里别再写了:log 与 debug、info、warning、error 整族方法都标注了废弃(2026-07-28 起,SEP-2577),调用会触发 MCPDeprecationWarning,而这个警告默认就会打印(官方文档站 的 What's New 有说明)。MCP 级日志通道正在退出协议,服务端自有日志请回到 Python logging 模块——也顺带守住第 3 篇的告诫:stdio 模式下 stdout 是协议线,别用 print。

2.2、常用成员一览

Context 其余常用成员如下,均按 2.3.0 源码口径。

成员 类别 说明
request_id 属性 本次请求的唯一 ID
protocol_version 属性 协商出的协议版本,请求外为 None
headers 属性 HTTP 传输携带的请求头,stdio 下为 None
client_capabilities 属性 客户端声明的能力
input_responses 属性 MRTR 重试轮带回传的答案,首轮为 None
request_state 属性 MRTR 重试轮回显的状态,首轮为 None
session 属性 底层会话,进阶用法入口

两点提醒:headers 是客户端送来的输入,源码 docstring 明言不要把任何头当身份断言,鉴权走正式认证层;input_responses 与 request_state 服务第 5 节的多轮往返,先记位置。

3、lifespan 全会话共享

第 3 篇实战里,知识库的文档与向量都是模块级全局变量——demo 够用,工程上有短板:import 即建资源、难以按需清理、多进程各建一套。v2 的正解是 MCPServer 构造器的 lifespan 参数,且语义与 v1 有一个关键差异:streamable HTTP 下 lifespan 现在在启动时只跑一次,产出的状态被所有会话与请求共享;此前是每个会话各跑一次,无状态模式甚至每个请求跑一次(What's New 有明确说明)。连接池、缓存这类昂贵资源因此便宜了一个量级;反过来,每连接一份的资源现在应放进 handler 体内。写法如下。

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

import httpx
from mcp.server.mcpserver import Context, MCPServer

@asynccontextmanager
async def app_lifespan(server: MCPServer) -> AsyncIterator[dict]:
    async with httpx.AsyncClient(timeout=10) as http:
        yield {"http": http}

mcp = MCPServer("Fetcher", lifespan=app_lifespan)

@mcp.tool()
async def fetch(url: str, ctx: Context) -> str:
    """抓取 URL 并返回正文开头。"""
    http: httpx.AsyncClient = ctx.request_context.lifespan_context["http"]
    resp = await http.get(url)
    return resp.text[:500]

解读:lifespan 是一个收 server 实例、返回 async context manager 的函数,@asynccontextmanager 修饰最顺手;yield 出去的值就是共享状态,server 启动时进入、关停时清理。handler 一侧没有专门的取用方法,lifespan 上下文挂在请求上下文上,经 ctx.request_context.lifespan_context 访问;把工具参数注解写成 Context[dict],类型检查器还能认出它的类型。

注意:lifespan 只放全服务共享、无会话归属的资源。会话级状态塞进来会被并发请求互相踩踏,这类状态属于 handler 体内。

4、Resolve 依赖注入

最难的需求单独讲:工具执行前需要一个只有用户知道的值。第 2 篇在协议层给过答案——GA 版用 MRTR 把"还差输入"作为正常响应返回,老协议用 elicitation 反向请求客户端,两代报文完全不同。Resolve 就是 SDK 藏掉这层差异的方式:参数标 Annotated[T, Resolve(fn)],值改由 fn 生成注入,模型看不见这个参数。

fn 的规矩按源码口径:参数可以是 Context、嵌套的 Resolve(...)(构成依赖 DAG,注册期查环)、或按名字吃工具实参;返回值可以是普通值,也可以是三种请求标记——Elicit(message, schema) 问用户、Sample(...) 借客户端模型补全、ListRoots() 要文件系统根。示例如下。

from typing import Annotated

from pydantic import BaseModel

from mcp.server.mcpserver import (
    AcceptedElicitation, Context, Elicit, ElicitationResult, MCPServer, Resolve,
)

class Overwrite(BaseModel):
    agree: bool

async def ask_overwrite(filename: str) -> Elicit[Overwrite]:
    return Elicit(f"{filename} 已存在,覆盖吗?", Overwrite)

@mcp.tool()
async def save_as(
    filename: str,
    overwrite: Annotated[ElicitationResult[Overwrite], Resolve(ask_overwrite)],
) -> str:
    """保存文件,重名时先征得用户同意。"""
    if isinstance(overwrite, AcceptedElicitation) and overwrite.data.agree:
        return f"已覆盖 {filename}"
    return "用户未同意,未保存"

解读三个要点。其一,ask_overwrite 按名字收了工具实参 filename,问题文案因此能依赖运行时值,resolver 不只能问死问题。其二,消费形态有两种:注解为 T 直接拿解包值,用户拒绝或取消时 SDK 自动抛 ToolError 中止调用;注解为 ElicitationResult[T] 拿完整三态(AcceptedElicitation、DeclinedElicitation、CancelledElicitation)自己分支,例中选的是后者。其三,Elicit 绑定的 schema 只允许原始类型字段,渲染期强校验。同一段声明在两代协议上怎么落地,时序如下。

sequenceDiagram participant C as 客户端 participant S as Server C->>S: tools/call save_as S->>S: 运行 resolver 得到 Elicit 标记 alt 协议为 2026-07-28 及以后 S-->>C: resultType=input_required C->>S: 重试请求携带 input_responses else 旧协议客户端 S->>C: elicitation/create 反向请求 C-->>S: ElicitResult 应答 end S->>S: 注入参数后运行工具体 S-->>C: resultType=complete

解读:GA 版链路里 resolver 不阻塞等待——SDK 把问题打包进 InputRequiredResult 的 input_requests,随 request_state 一并返回;客户端重试带回答案后,SDK 先核对答案对应的问题指纹:答案只对当初问出的原话生效,改写过措辞的问题会重新再问。旧协议链路则是同步反向请求,一问一答在连接内完成。每个问题只问一次,答案随 request_state 跨轮携带。

5、handler 侧的 MRTR

第 2 篇看的是 wire 报文(SEP-2322),handler 侧的接口就两个属性:ctx.input_responses 是客户端对上一轮 input_requests 的答案映射,ctx.request_state 是上一轮回显的不透明状态,首轮都为 None。Resolve 是推荐姿势,但 SDK 保留了手工通道——handler 直接返回 InputRequiredResult,示例如下。

from pydantic import BaseModel
from mcp_types import ElicitRequest, ElicitRequestFormParams, InputRequiredResult
from mcp.server.elicitation import render_elicitation_schema

class Confirm(BaseModel):
    ok: bool

@mcp.tool()
async def deploy(env: str, ctx: Context) -> str | InputRequiredResult:
    """部署到指定环境,首轮征询确认。"""
    if ctx.input_responses is None:
        return InputRequiredResult(
            input_requests={"confirm": ElicitRequest(
                params=ElicitRequestFormParams(
                    message=f"确认部署到 {env}?",
                    requested_schema=render_elicitation_schema(Confirm),
                ))},
            request_state=env,
        )
    answer = ctx.input_responses.get("confirm")
    if answer is None or answer.action != "accept":
        return "用户未确认,已取消"
    return f"已部署到 {env}"

解读:手工模式要自己组装 input_requests——ElicitRequest 包 message 与 requested_schema(用 render_elicitation_schema 渲染,仍限原始类型),键名自定,第二轮按同样的键从 input_responses 取回答案;request_state 是原样回显的字符串,例中拿来携带 env。两条硬约束:返回注解必须带 InputRequiredResult 分支;一个调用只有一条 request_state 通道,同时声明 Resolve 参数又手工返回 InputRequiredResult,注册期就以 InvalidSignature 拒绝——两条流会互相覆盖状态、永远无法收敛。另有 v1 遗产 ctx.elicit(message, schema) 仍在:只对旧协议连接可用,2026-07-28 连接上没有反向通道,会以 NoBackChannelError 失败,新代码一律 Resolve。

6、用 ToolError 报错

第 3 篇 calc 的原则是业务错误当正常结果返回。但有一类失败不该伪装成结果:注定中止、且模型读了能自救的失败,抛 ToolError(源码见 python-sdk 仓库)。源码口径:从工具或 resolver 抛出,调用以 is_error=True 收场,你的消息进 content 给模型读,服务端 INFO 级记录、不带堆栈;其他任何异常(协议错误 MCPError 除外)都按崩溃处理——模型只看到 Error executing tool 工具名,原始信息不外泄,服务端 ERROR 级记完整堆栈。三条路径的归宿对比如下。

失败方式 模型看到 服务端日志
返回错误文案字符串 正常结果原文 无
抛 ToolError is_error 结果附你的消息 INFO 无堆栈
抛其他异常 Error executing tool 工具名 ERROR 带堆栈

改造第 3 节的 fetch,让网络失败走 ToolError,示例如下。

from mcp.server.mcpserver.exceptions import ToolError

@mcp.tool()
async def fetch(url: str, ctx: Context) -> str:
    """抓取 URL,网络失败时中止。"""
    http: httpx.AsyncClient = ctx.request_context.lifespan_context["http"]
    try:
        resp = await http.get(url)
    except httpx.HTTPError as exc:
        raise ToolError(f"请求失败:{exc}") from exc
    if resp.status_code >= 400:
        raise ToolError(f"上游返回 {resp.status_code}")
    return resp.text[:500]

解读:ToolError 的消息是给模型的修复线索,要带上足以让它改参数重试的信息。三个同族细节:SDK 对未知工具名、schema 校验失败自己也抛 ToolError;UnexpectedToolError 是 SDK 包装崩溃的子类,在 MCPServer.call_tool() 外围捕获它可区分预期失败与崩溃;pydantic 校验器里按惯例抛 ValueError,会落进参数校验失败这条预期通道。资源侧的对应物是 ResourceError 与 ResourceNotFoundError。

7、实战:带进度的批处理

把五个机制合体:批量拉取文档入库。lifespan 建共享 HTTP 客户端与存储,Resolve 在开工前问重复策略,工具循环里逐篇报进度。先看启动侧。

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

import httpx
from mcp.server.mcpserver import MCPServer

@asynccontextmanager
async def bulk_lifespan(server: MCPServer) -> AsyncIterator[dict]:
    async with httpx.AsyncClient(timeout=30) as http:
        yield {"http": http, "store": {}}

mcp = MCPServer("Bulk", lifespan=bulk_lifespan)

解读:连接池与文档仓都挂在 lifespan 上,所有会话共享一份,server 关停时随上下文一并清理。再看工具侧。

from typing import Annotated

from pydantic import BaseModel

from mcp.server.mcpserver import Context, Elicit, Resolve

class DupPolicy(BaseModel):
    skip: bool  # True 跳过重复,False 覆盖

async def ask_policy() -> Elicit[DupPolicy]:
    return Elicit("遇到重复文档:跳过还是覆盖?", DupPolicy)

@mcp.tool()
async def import_docs(
    urls: list[str],
    policy: Annotated[DupPolicy, Resolve(ask_policy)],
    ctx: Context,
) -> str:
    """批量拉取文档入库,实时上报进度。"""
    pool = ctx.request_context.lifespan_context
    done = 0
    for url in urls:
        name = url.rsplit("/", 1)[-1] or url
        if name in pool["store"] and policy.skip:
            continue
        resp = await pool["http"].get(url)
        pool["store"][name] = resp.text[:2000]
        done += 1
        await ctx.report_progress(done, len(urls), message=name)
    return f"导入 {done} 篇,库存 {len(pool['store'])} 篇"

解读:policy 参数用的是解包注解,模型看不到它、也填不了它,值由 ask_policy 向用户要来;用户拒绝时 SDK 自动以 ToolError 中止,想自定义拒绝行为就换成 ElicitationResult[DupPolicy] 自己分支。进度每篇一报,客户端实时可见;store 跨调用累计、重启即清空,正好体现共享但非持久的定位。

8、总结

handler 从纯函数长成完整的运行时参与者:Context 按类型注入,report_progress 可用、log 整族已废弃;lifespan 启动一次、全会话共享,handler 经 request_context.lifespan_context 取用;Resolve 声明依赖,Elicit 标记问用户,两代协议自动分流,问题指纹保证答案不串轮;手工 InputRequiredResult 与 Resolve 互斥;ToolError 给模型可读的失败,其余异常对客户端不可见。留三道练习:

  • 给第 3 篇知识库的 search 工具加进度上报,按批计算相似度时逐批 report_progress
  • 把实战的 DupPolicy 改成 ElicitationResult 注解,用户拒绝时返回友好文案而非中止
  • 写一个嵌套 resolver:ask_policy 依赖另一个 resolver 取默认策略,验证 DAG 与注册期查环

对于正在把工具做厚的读者,建议顺序是:先用 Context 补进度与资源读取,共享资源交给 lifespan,等真正要向用户开口再引入 Resolve。工具写厚之后的调试与接入真实宿主,本系列第 5 篇展开。

相关推荐

​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