MCP Python SDK · 第 6 章上下文、依赖与请求生命周期

文档摘要

MCP Python SDK · 第 6 章上下文、依赖与请求生命周期章节摘要:前几章的工具、资源、提示词都是「被调用时执行一段函数」,但真实的服务端很少这么简单——它需要在执行中读取别的资源、上报进度、写日志、拿到请求头、访问一个数据库连接。本章讲的就是「一次请求内部的工程能力」。核心有两个机制:一是 (上下文)对象,它按类型注解自动注入,提供 / / / / 等请求级能力;二是 (依赖解析),它用的写法,在工具执行前由一个解析函数填充某些参数——这些参数对模型不可见,却能在每次调用时动态获取(如当前用户、数据库会话)。两者合起来,让 MCP 工具从「纯函数」升级为「与请求环境交互的完整业务逻辑」。读完本章,你能写出真正贴近生产的工具。

MCP Python SDK · 第 6 章上下文、依赖与请求生命周期

章节摘要:前几章的工具、资源、提示词都是「被调用时执行一段函数」,但真实的服务端很少这么简单——它需要在执行中读取别的资源、上报进度、写日志、拿到请求头、访问一个数据库连接。本章讲的就是「一次请求内部的工程能力」。核心有两个机制:一是 Context(上下文)对象,它按类型注解自动注入,提供 read_resource / report_progress / elicit / session / headers 等请求级能力;二是 Resolve(依赖解析),它用 Annotated[T, Resolve(fn)] 的写法,在工具执行前由一个解析函数填充某些参数——这些参数对模型不可见,却能在每次调用时动态获取(如当前用户、数据库会话)。两者合起来,让 MCP 工具从「纯函数」升级为「与请求环境交互的完整业务逻辑」。读完本章,你能写出真正贴近生产的工具。

学习目标

阅读完本章,你应当能够:

用 Context 类型注解把请求级对象注入工具/资源/提示词函数,并调用它的核心方法(read_resource / report_progress / info 等)。
解释 Resolve(fn) 依赖解析的工作机制——解析函数在工具执行前运行,其返回值填充被注解的参数,且该参数对模型不可见。
区分 Context(SDK 内置的请求级对象)与 Resolve(你自定义的依赖注入)在用途上的差异,并各举一个适用场景。
用生命周期(Lifespan)上下文在服务端启动时建立共享资源(如数据库连接池),并在每次请求里复用。
描述一次请求的完整生命周期——从传输层收到 JSON-RPC、经上下文注入、依赖解析、工具执行,到结果返回。

核心概念速览

整章逻辑可浓缩为一句话:Context 给你「请求内」的能力(读资源、报进度、拿会话),Resolve 给你「请求前」的依赖注入(对模型隐藏的参数填充),两者让 MCP 工具从纯函数变成完整的业务逻辑单元。

子章节导航

01 Context 对象:请求级能力的统一入口

讲清 Context 如何按类型注解注入(在工具/资源/提示词函数签名上加 ctx: Context),以及它的核心方法:read_resource(读别的资源)、report_progress(上报进度)、info / debug 等日志方法、session(访问底层会话)、headers(读请求头)、request_id。重点说明它「对模型不可见」。

02 Resolve 依赖解析:对模型隐藏的参数注入

这是 v2 的新机制,类比 FastAPI 的 Depends。讲清 Annotated[User, Resolve(get_current_user)] 的写法:解析函数 get_current_user 在工具执行前运行,返回值填充 User 参数,而这个参数不会出现在给模型的工具 Schema 里。用它实现「当前用户」「数据库会话」「配置」等动态依赖。

03 Context 与 Resolve 的分工

一个关键对比。两者都解决「让工具拿到请求环境信息」,但定位不同:Context 是 SDK 提供的通用请求对象(方法固定),Resolve 是你自定义的依赖注入(完全灵活)。用一张对照表讲透何时用哪个,以及它们如何协作。

04 生命周期上下文:服务端启动时建立的共享资源

工具经常需要共享资源(数据库连接池、HTTP 客户端、缓存)。讲清生命周期(Lifespan)机制:在服务端启动时运行一段异步函数,返回的对象放进 lifespan_context,每次请求里通过 Context 访问。这是避免「每次请求重建连接」的关键。

子章节之间的逻辑关系

本章遵循「请求内能力 → 请求前依赖 → 两者分工 → 跨请求共享」的递进,层层扩大工具的能力边界:


Context (01)   ── 请求内:读资源、报进度、拿会话
   │
   ▼
Resolve (02)   ── 请求前:对模型隐藏的参数填充
   │
   ▼
分工对比 (03)  ── 何时用 Context,何时用 Resolve
   │
   ▼
Lifespan (04)  ── 跨请求:启动时建立的共享资源
   │
   ▼
第 7 章:更进一步——工具执行中途向用户「反问」

Context 解决「请求内能做什么」,Resolve 解决「请求前能准备什么」,两者分工让你既不用在函数里硬塞样板代码,也能把依赖与业务分离;生命周期上下文则把视野扩大到「服务端级别」的共享状态。四节合起来,覆盖了工具执行所需的全部工程能力,并为第 7 章(引导填写,Resolve 的高级用法)埋下伏笔。

前置知识与后续延伸

前置知识:

第 3、4 章的工具/资源/提示词函数定义(知道函数签名长什么样)
Python 类型注解进阶(理解 Annotated[T, ...] 的写法)
第 2 章的请求生命周期概念(端到端旅程)

本章为后续章节奠定的基础:

Context 是第 7 章(引导填写 ctx.elicit、采样 ctx.session)的操作对象
Resolve 机制是第 7 章「Resolve 返回 Elicit 实现引导填写」现代写法的基础
生命周期上下文会在第 8 章(传输层启动)被引用
「对模型不可见」的参数处理思想会在第 12 章(扩展)再次出现

MCP Python SDK · 第 6 章 上下文、依赖与请求生命周期

文档摘要