《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 两种传输下复用,单测也不需要伪造信封。两个家族的整体关系如下图。
图后三点补充。其一,具体结果类按能力混入: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 节的继承树放在手边——后面每一层都会反复出现这些名字。

