MCP 源码:mcp-types 模型层

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

《MCP 协议与实现》前七篇走完了协议、开发、测试、传输、生产化五个层面,第 7 篇结尾预告的源码篇从本篇开始。第一站不是传输也不是分发,而是整个 SDK 的地基——mcp-types 类型包:运行时每一层,传输收到的报文、会话层组装的信封、dispatcher 路由的请求、handler 收到的参数,都是这个包里定义的 pydantic 对象。模型层认不清,后面的运行时代码读起来就全是失去含义的类名。

本篇拆的是 mcp-types 2.3.0(随官方 Python SDK v2.3.0 发布,以下源码均出自解包后的 wheel)。全文按“拆包动机 → 包结构 → 消息继承树 → 三原语字段 → _meta 建模 → pydantic 红利 → 生态位”组织,读完你会看到一套“用强类型承载持续演进的文本协议”的完整工程方案。


1、为什么要拆出类型包

第 3 篇介绍 SDK v2 重构时提过一条:wire 类型从主包拆出,独立成 mcp-types 包。当时它只是迁移注意事项里的一行,站在源码视角看,这是 v2 里最有生态意识的一刀。

先看拆之前的处境。v1 里协议模型住在 mcp.types,与整个运行时同一个发布单元:想写一个只校验 MCP 报文的小工具——网关、代理、录制回放的测试夹具——安装 v1 等于把传输、会话、HTTP 全家桶拖进依赖。类型定义本应是最轻的依赖,却背上了最重的包。

v2 拆包后依赖关系变成单向:运行时包 mcp 依赖 mcp-types,反向为零。量级可以量化——v2.3.0 运行时里有 61 个源文件 import mcp-types,覆盖会话、分发、共享上下文各层;而 mcp-types 定位是纯 pydantic 包,包内没有任何文件反向 import 运行时,装它就是装“协议本身”。

判断一个包该不该拆,看依赖方向比看代码量更准:被所有人依赖、不依赖任何人的模块,就是天然的包边界。

收益方不止 SDK 自己。第 3 篇提过的第三方 FastMCP 框架、报文校验器、给其他语言生成代码的 schema 导出器,都只需要“协议长什么样”,不需要“怎么收发”。类型包独立后,这些工具的依赖清单干净一截,与 SDK 的版本节奏也解耦了。

2、包结构与三层架构

先看全貌。mcp-types 2.3.0 解包后的目录结构如下。

mcp_types/
├── __init__.py       # 从 _types 全量再导出(453 行)
├── _types.py         # 单体模型层:全版本超集(2198 行)
├── jsonrpc.py        # JSON-RPC 信封与错误码(148 行)
├── methods.py        # 按版本分派的方法表(746 行)
├── version.py        # 协议版本登记与比较(74 行)
├── _wire_base.py     # 生成模型的共用基类(9 行)
├── _v2025_11_25/     # 按版本冻结的线形模型(3391 行)
└── _v2026_07_28/     # 按版本冻结的线形模型(3617 行)

解读:两个 _v 子包行数最多,却是内部件——methods.py 的模块注释写明这些是 internal validators、不得直接 import。真正面向用户代码的是 _types.py 这个单体,__init__.py 从它全量再导出。各模块职责如下。

模块 行数 职责
_types.py 2198 全版本超集模型,用户代码拿到的类型
jsonrpc.py 148 JSON-RPC 信封、错误码与消息联合类型
methods.py 746 方法名到模型的分发表,版本门槛在此
version.py 74 已知版本登记与大小比较
_v2025_11_25 3391 2025-11-25 线形的严格校验模型
_v2026_07_28 3617 2026-07-28 线形的严格校验模型

整体是三层设计。底层 _v* 按 schema 版本逐字生成,回答“这份报文在该版本下合法吗”;中层 methods.py 把方法名与版本的二元组映射到对应线形模型,注释原话是“key absence is the version gate”——键不存在即版本不支持;顶层 _types.py 是跨版本超集,“version-free models user code receives”,用户代码只接触这一层。报文在边界处过底层验线形,转成超集模型后在 SDK 内部流转,发出时再按对端版本序列化。

version.py 只有一屏,却有个值得记住的观点:协议版本用日期命名,字典序恰好等于时间序,但代码不依赖这个巧合。已知版本是枚举集合 KNOWN_PROTOCOL_VERSIONS(2024-11-05 到 2026-07-28 共五个),比较统一走 is_version_at_least;注释专门警告未来的版本号未必还是日期形状,陌生字符串必须保守比较,免得 zzz 意外地大于 2025-11-25。

3、消息模型的继承树

模型层第一课是“两个家族”:jsonrpc.py 里的信封家族,直接继承 pydantic 的 BaseModel;_types.py 里的领域家族,全部继承自定义基类 MCPModel。MCPModel 的全部内容是一条配置,如下。

class MCPModel(BaseModel):
    """Base class for all MCP protocol types."""

    model_config = ConfigDict(alias_generator=to_camel,
                              populate_by_name=True)

解读:alias_generator=to_camel 让 Python 侧用蛇形命名(input_schema),序列化时自动转驼峰(inputSchema);populate_by_name=True 保证两种名字都能构造与解析。这一条配置就是全包“Python 习惯与 JSON 习惯”之间的翻译层。

信封家族照抄 JSON-RPC 2.0 规范,以请求类为例。

RequestId = Annotated[int, Field(strict=True)] | str

class JSONRPCRequest(BaseModel):
    jsonrpc: Literal["2.0"]
    id: RequestId
    method: str
    params: dict[str, Any] | None = None

解读:jsonrpc 是写死的字面量类型,版本号写错直接校验失败;id 用 strict int 防止整数被悄悄解析成浮点;method 与 params 在信封层保持宽泛的 str 与 dict,因为“方法名是什么、参数长什么样”是领域家族的事。四个信封类(请求、通知、响应、错误)组成联合类型 JSONRPCMessage,配一个 TypeAdapter 就是整条消息的解码器,第 7 节会用到。

领域家族的基类则把方法名焊进类型。Request 的定义如下。

class Request(MCPModel, Generic[RequestParamsT, MethodT]):
    """Base class for JSON-RPC requests.

    The JSON-RPC envelope (`jsonrpc`, `id`) is attached by
    the session layer (see `mcp_types.jsonrpc`), not carried here.
    """
    method: MethodT
    params: RequestParamsT

解读:method 的类型不是 str,而是类型参数 MethodT——每个具体请求类用字面量把方法名写死,如 CallToolRequest 继承 Request[CallToolRequestParams, Literal["tools/call"]],方法名拼错时类型检查器当场报错,而不是等运行时查表失败。再看 docstring 第二句:领域模型不携带 jsonrpc 与 id,信封由会话层附加——同一条 CallToolRequest 在 stdio 与 HTTP 两种传输下复用,单测也不需要伪造信封。两个家族的整体关系如下图。

classDiagram class BaseModel class MCPModel class Request { +method +params } class Notification { +method +params } class Result { +meta } class JSONRPCRequest class JSONRPCNotification class JSONRPCResponse class JSONRPCError BaseModel <|-- MCPModel BaseModel <|-- JSONRPCRequest BaseModel <|-- JSONRPCNotification BaseModel <|-- JSONRPCResponse BaseModel <|-- JSONRPCError MCPModel <|-- Request MCPModel <|-- Notification MCPModel <|-- Result Request <|-- ListToolsRequest Result <|-- ListToolsResult Notification <|-- ProgressNotification

图后三点补充。其一,具体结果类按能力混入:ListToolsResult 同时继承 PaginatedResult 与 CacheableResult,分页游标与缓存指令是两组可叠加的 mixin。其二,Request 还有个 ClassVar name_param——把参数里的名字镜像进 Mcp-Name 请求头(第 2 篇讲过的头路由面),SDK 据此为网关提供路由信息。其三,信封家族还保管错误码,三段归属如下。

区段 归属 代表常量
-32700 至 -32603 JSON-RPC 标准错误 PARSE_ERROR 与 METHOD_NOT_FOUND
-32020 至 -32099 规范定义,顺序分配 UNSUPPORTED_PROTOCOL_VERSION
-32000 至 -32019 SDK 实现自用 CONNECTION_CLOSED 与 REQUEST_TIMEOUT

解读:规范段里还留着两个“退役永不复用”的号码(-32002、-32042),注释原话 reserved-never-reused;SDK 自用的 CONNECTION_CLOSED 则注明 never emitted on the wire——连接断开是本地事件不是协议事件,占号但永不上线。把规范的账与实现的账记在同一处却分栏存放,这种自律在协议实现里并不多见。

4、三原语模型的字段

Tool、Resource、Prompt 三个模型都继承 BaseMetadata——只有 name(必填)与 title(可选标题)两个字段的“身份层”,再各自长出差异化字段。先看 Tool,节选如下(省略各字段 docstring)。

class Tool(BaseMetadata):
    """Definition for a tool the client can call."""

    description: str | None = None
    input_schema: dict[str, Any]            # 根节点必须是 object
    execution: ToolExecution | None = None  # 仅 2025-11-25 存在
    output_schema: dict[str, Any] | None = None
    icons: list[Icon] | None = None
    annotations: ToolAnnotations | None = None
    meta: Meta | None = Field(alias="_meta", default=None)

解读:input_schema 是唯一必填的业务字段,类型直接用 dict[str, Any] 而不是自造 Schema 模型——JSON Schema 本身就是开放结构,包一层反而丢信息;docstring 注明 2026-07-28 放开到完整的 JSON Schema 2020-12 关键字,更早版本只认 type、properties、required 三件套。output_schema 对应调用结果里的 structured_content。execution 是版本化石:只出现在 2025-11-25,下一版即移除,模型层照样保留并注明版本。

annotations 的类型 ToolAnnotations 有五个字段——title、read_only_hint、destructive_hint、idempotent_hint、open_world_hint——全带 hint 后缀,docstring 的警告值得原样读:这些都是提示而非承诺,客户端绝不应依据不可信 server 的注解做工具使用决策。

再看 Resource 与 Prompt,同样节选。

class Resource(BaseMetadata):
    uri: str                            # 资源定位符,必填
    description: str | None = None
    mime_type: str | None = None
    size: int | None = None             # 编码与分词前的字节数
    icons: list[Icon] | None = None
    annotations: Annotations | None = None
    meta: Meta | None = Field(alias="_meta", default=None)

class Prompt(BaseMetadata):
    description: str | None = None
    arguments: list[PromptArgument] | None = None
    icons: list[Icon] | None = None
    meta: Meta | None = Field(alias="_meta", default=None)

解读:Resource 的身份不靠 name 靠 uri——第 1 篇讲过,资源由客户端按需读取,uri 就是读取的钥匙;size 的注释是全包最贴心的一句:字节数按 base64 编码与分词之前的原始内容计,供 Host 展示大小并估算上下文窗口占用。Prompt 最薄,只有模板参数列表 PromptArgument(描述加是否必填)。三者差异汇总如下。

原语 身份字段 参数契约 差异化元数据
Tool name inputSchema 与 outputSchema annotations 提示组
Resource uri 无 mimeType 与 size
Prompt name arguments 模板参数 无

字段的差异正好呼应第 1 篇的控制权切分:tool 交给模型自主调用,所以要有给模型读的 description 与给它传参的 input_schema;resource 交给应用按需读取,uri、mime_type、size 这些“给应用看的”元数据一个不少;prompt 交给用户显式触发,模板参数之外别无所求。协议里的每次分工,落到模型层就是一张字段清单。

5、_meta 的建模技巧

第 2 篇讲无状态内核时 _meta 反复出场:协议版本、客户端身份、能力清单都从握手搬进了每个请求的 _meta。这个“什么都可能装”的字段怎么建模?答案不是 RootModel,也不是普通 dict,而是一个带 extra_items 的 TypedDict,定义节选如下。

class RequestParamsMeta(TypedDict, extra_items=Any):
    progress_token: NotRequired[ProgressToken]

class RequestParams(MCPModel):
    meta: RequestParamsMeta | None = Field(alias="_meta",
                                           default=None)

PROTOCOL_VERSION_META_KEY = "io.modelcontextprotocol/protocolVersion"
CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo"
CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities"

解读:这套设计一石三鸟。其一,progress_token 用 NotRequired 声明——唯一被核心协议定义了语义的键拿到类型化入口,进度通知靠它回关联请求(第 4 篇的 report_progress);其二,extra_items=Any 让其余所有键原样往返,自定义键、扩展键、未来的规范键互不干扰;其三,规范预留键收编为常量,反域名命名空间 io.modelcontextprotocol/* 把官方键与生态键隔开,读写都经 *_META_KEY 常量而非裸字符串。

RequestParams 的 docstring 还交代了与无状态的衔接:_meta 在 2026-07-28 及之后的请求线上必填,但预留键由会话层自动填——业务代码经 SDK 发请求时不用手填版本与身份,直连 HTTP 的实现才要自己管。

留一处不对称给细心的读者:请求侧的 _meta 是结构化 TypedDict,通知与结果侧的 _meta 就是 dict[str, Any] 全开放。原因朴素——目前只有请求侧存在 SDK 需要类型化读写的键;结果侧唯一的预留键 serverInfo(服务器自报身份,注释特意声明仅用于展示调试、不得影响行为与安全)用裸 dict 存取已够。类型强度跟着实际需求走,不预支复杂度。

6、pydantic 的红利

pydantic 带来的第一份红利是三个出口自动一致:同一份类定义同时服务校验(构造即验证)、序列化(驼峰上线)、schema 导出。构造一个工具并序列化的示例如下。

from mcp_types import Tool

tool = Tool(
    name="get_weather",
    description="查询城市天气",
    input_schema={"type": "object",
                  "properties": {"city": {"type": "string"}}},
)
wire = tool.model_dump(by_alias=True, exclude_none=True)
# wire 里是 inputSchema 与 description,蛇形名自动转驼峰

解读:规范改版时只改模型,校验、序列化、model_json_schema() 三个出口随之同步,不存在第二份手写 schema 漂移的问题。

第二份红利是“超集加外置门槛”。_types.py 末尾注释写明:顶层联合类型是所有支持版本的超集,逐版本合法性记录在 methods、不在此强制。用户代码拿到的 ListToolsResult 不因对端版本变化,版本差异被压在收发边界上。超集里甚至保留着 Tasks 全家——注释写明 2025-11-25 引入、2026-07-28 移出核心规范,模型留着但被排除在联合类型之外、永不分发,版本化石有了安放处。

第三份红利藏在默认值里。2026-07-28 新增的缓存指令(第 1 篇的 ttlMs 与 cacheScope)住在 CacheableResult 里,两个字段都带防呆默认,如下。

class CacheableResult(Result):
    ttl_ms: Annotated[int, Field(ge=0)] = 0
    cache_scope: Literal["public", "private"] = "private"

解读:docstring 写得直白——handler 不设置任何缓存指令时,产出的是“立即过期、仅私有缓存”的保守结果,不会因漏填而意外开启共享缓存。EmptyResult 同理:result_type 默认 None 使其序列化为空对象 {},因为部署中的 TypeScript 与 Rust 同伴 SDK 对空结果严格校验,多一个键就拒收。默认值是跨语言互操作的第一道防线。

第四份是开放联合。resultType 字段的类型是 Literal["complete", "input_required"] | str——前两个值归核心协议,其余留给扩展(tasks 扩展已预留 task)。强类型与协议演进这对矛盾,用“字面量联合加一个 str 出口”完成折中。

7、类型包的生态位

最后看谁在用它。第一条路径在 SDK 内部:v2.3.0 运行时里 61 个文件 import mcp-types——会话层拿信封类组帧,dispatcher 拿 methods 的方法表路由,handler 拿三原语模型取参,共享上下文拿 META_KEY 常量。运行时本质上是绕着模型层运转的机器。

第二条路径在 SDK 之外。最轻的用法是拿现成的 adapter 校验报文,代码如下。

from mcp_types import jsonrpc_message_adapter

msg = jsonrpc_message_adapter.validate_json(
    '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
)
print(type(msg).__name__)   # JSONRPCRequest

解读:一行拿到具体信封类型。写代理、录制回放夹具,或只想要一份“MCP 报文长什么样”的参考实现,装 mcp-types 就够,运行时一个字节都不用拖——第 1 节的拆包动机在这里落了地。

对 server 作者还有一层隐性收益:类型即协议文档。想知道 tools/list 该回什么,打开 _types.py 搜 ListToolsResult,每个字段的 docstring 都注明线上语义与版本边界,比翻规范网页快。第 3 篇“类型即文档”一节讲过用法,本篇补上了它的实现底座。

8、总结

回顾本篇:mcp-types 因“被所有人依赖、不依赖任何人”而独立成包;三层结构——版本化线形校验、方法分发表、超集单体——把“严格验线形”与“稳定给用户”分开;消息分信封与领域两家族,方法名焊进 Literal 类型、信封由会话层附加;三原语字段精确映射控制权切分;_meta 用带 extra_items 的 TypedDict 兼得结构与开放;pydantic 让校验、序列化、schema 三个出口自动一致。留三道练习:

  • 在本地 venv 里打开 mcp_types/_types.py,统计继承 Request 与 Result 的类各有多少,与本文继承树对照
  • 构造一个 Tool 并 model_dump(by_alias=True),手写等价 JSON 对比驼峰转换与 exclude_none 的效果
  • 给请求的 _meta 塞一个自定义键,序列化再解析回来,验证 extra_items=Any 的往返保真

下一篇(第 9 篇)读 dispatcher:methods.py 那张“键不存在即版本门槛”的分发表,如何被低层 Server 拿来把 method 字符串路由到本篇这些模型上。对于打算通读 SDK 源码的读者,建议先把第 3 节的继承树放在手边——后面每一层都会反复出现这些名字。

相关推荐

​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