Python MCP SDK 服务端结构化输出(Structured Output)完整指南:返回类型注解即输出 Schema
Python MCP SDK 服务端结构化输出(Structured Output)完整指南:返回类型注解即输出 Schema
本指南讲解 Model Context Protocol Python SDK(本项目 python-sdk)中服务端 Tool 的**结构化输出(Structured Output)**机制:一个普通的 Tool 返回值如何同时产生面向模型的 content 文本通道与面向应用的 structured_content 数据通道,以及 SDK 如何依据返回类型注解自动推导 output_schema 并对返回值做校验。读完本文,你将掌握从标量、Pydantic 模型、TypedDict、dataclass 到列表、字典等各类返回形态下的 Schema 推导规则、structured_output 开关的用法,以及底层 FuncMetadata 的实现原理。
核心结论一句话:函数的返回类型注解就是输出 Schema——你早已写好了它。
一个 Tool 的两个输出通道
一个返回普通 str 的 Tool,其结果实际上会出现两次:一次作为文本放在 content 中,一次作为 {"result": "..."} 放在 structured_content 中。
本主题围绕的就是这第二个通道:它从哪里来、能呈现哪些形态、SDK 又是如何保证它"不撒谎"的。
为什么同一个值要发送两遍?因为两个消费方完全不同:
content是给模型看的。语言模型读取的是文本,这是它能看到的结果中唯一的部分。structured_content是给模型运行于其中的应用看的:代码需要的是17这个数,而不是一句包含 "17" 的句子。output_schema是二者之间的契约,在 Tool 首次被调用之前就已经随tools/list发布。
你只需要返回一个 Python 值,SDK 会负责填充全部三者。
输出 Schema:从签名自动推导
以 docs_src/structured_output/tutorial001.py 为例:
from mcp.server import MCPServer
mcp = MCPServer("Weather")
READINGS = {"London": 17, "Cairo": 34, "Reykjavik": 4}
@mcp.tool()
def get_temperature(city: str) -> int:
"""Current temperature in a city, in whole degrees Celsius."""
return READINGS[city]
关键的一行是函数签名中的 -> int。正是它,使得 SDK 在 tools/list 阶段为这个 Tool 携带一个 output_schema,与基于参数构建的输入 Schema(见 Tools 指南)并列发布:
{
"properties": {
"result": {"title": "Result", "type": "integer"}
},
"required": ["result"],
"title": "get_temperatureOutput",
"type": "object"
}
裸的 int 不是 JSON 对象,因此 SDK 会把它包装进 {"result": ...} 中。调用该 Tool 后,两个通道都会被填充:
result.content # [TextContent(text="17")]
result.structured_content # {"result": 17}
每个标量类型都享受同样的包装:str、int、float、bool、bytes、None。
返回 Pydantic 模型:Schema 即类本身
把输出形态声明为一个 Pydantic BaseModel 并返回实例(见 docs_src/structured_output/tutorial002.py):
from pydantic import BaseModel, Field
from mcp.server import MCPServer
mcp = MCPServer("Weather")
class WeatherData(BaseModel):
temperature: float = Field(description="Degrees Celsius.")
humidity: float = Field(description="Relative humidity, 0 to 1.")
conditions: str
@mcp.tool()
def get_weather(city: str) -> WeatherData:
"""Current weather for a city."""
return WeatherData(temperature=16.2, humidity=0.83, conditions="Overcast")
此时 WeatherData 本身就是 Schema,不再有包装,也没有 result 键:
{
"properties": {
"temperature": {"description": "Degrees Celsius.", "title": "Temperature", "type": "number"},
"humidity": {"description": "Relative humidity, 0 to 1.", "title": "Humidity", "type": "number"},
"conditions": {"title": "Conditions", "type": "string"}
},
"required": ["temperature", "humidity", "conditions"],
"title": "WeatherData",
"type": "object"
}
structured_content 就是这个对象本身,字段一一对应:
result.structured_content # {"temperature": 16.2, "humidity": 0.83, "conditions": "Overcast"}
而模型也没有被冷落:SDK 会把同一个对象序列化成 JSON 文本放进 content:
{
"temperature": 16.2,
"humidity": 0.83,
"conditions": "Overcast"
}
注意,temperature 和 humidity 上的 Field(description=...) 被原样带入了 Schema。同一个 Field,之前用来描述输入,现在也用来描述输出。
如果你用过 FastAPI 的
response_model,你会觉得似曾相识:Pydantic 模型作为声明的响应,序列化与文档化全部由框架代劳。唯一区别在于,这里全部声明就是那一行返回类型注解,没有额外的参数。
TypedDict:不想建类时的同款 Schema
并非每种形态都值得定义一个类。TypedDict 能产生完全相同的 Schema(见 docs_src/structured_output/tutorial003.py):
from typing import TypedDict
from mcp.server import MCPServer
mcp = MCPServer("Weather")
class WeatherData(TypedDict):
temperature: float
humidity: float
conditions: str
@mcp.tool()
def get_weather(city: str) -> WeatherData:
"""Current weather for a city."""
return WeatherData(temperature=16.2, humidity=0.83, conditions="Overcast")
在运行时 TypedDict 就是普通的 dict,所以你直接构建并返回它即可。Schema、校验和 structured_content 的规则与 BaseModel 版本完全一致:给类加上 docstring 或使用 Annotated[..., Field(description=...)],它们就会成为字段描述;一个你故意没放进字典的 NotRequired 键,也自然不会出现在 structured_content 里。
Dataclass 与普通注解类
Dataclass 同样适用,任何属性带类型注解的普通类也都可以。SDK 会在幕后基于这些注解构建一个 Pydantic 模型(见 docs_src/structured_output/tutorial004.py):
from dataclasses import dataclass
from mcp.server import MCPServer
mcp = MCPServer("Weather")
@dataclass
class WeatherData:
temperature: float
humidity: float
conditions: str
@mcp.tool()
def get_weather(city: str) -> WeatherData:
"""Current weather for a city."""
return WeatherData(temperature=16.2, humidity=0.83, conditions="Overcast")
三种写法(BaseModel、TypedDict、dataclass)对应同一份 Schema。用你代码库里已经存在的那种即可。
列表与容器类型:result 包装加 $defs 引用
list<a href="https://link.gitcode.com/i/61f9cd0948fc7bef87ab5ee11a92ab05" target="_blank">...] 同样不是 JSON 对象,所以它也会获得 {"result": ...} 包装,而元素类型在包装内部以 $defs 引用的形式出现(见 [docs_src/structured_output/tutorial005.py):
from pydantic import BaseModel
from mcp.server import MCPServer
mcp = MCPServer("Weather")
class WeatherData(BaseModel):
temperature: float
humidity: float
conditions: str
@mcp.tool()
def get_forecast(city: str, days: int) -> list[WeatherData]:
"""Daily forecast for a city."""
return [WeatherData(temperature=16.2 + day, humidity=0.83, conditions="Overcast") for day in range(days)]
对应的 output_schema:
{
"$defs": {
"WeatherData": {
"properties": {
"temperature": {"title": "Temperature", "type": "number"},
"humidity": {"title": "Humidity", "type": "number"},
"conditions": {"title": "Conditions", "type": "string"}
},
"required": ["temperature", "humidity", "conditions"],
"title": "WeatherData",
"type": "object"
}
},
"properties": {
"result": {"items": {"$ref": "#/$defs/WeatherData"}, "title": "Result", "type": "array"}
},
"required": ["result"],
"title": "get_forecastOutput",
"type": "object"
}
请求两天的预报,structured_content 就是 {"result": [{...}, {...}]}。而 content 会变成两个 TextContent 块,每项一个:列表是为模型展开的,而不是拼成一整条字符串倾倒过去。
tuple[...]、类型联合(union)以及 Optional[...] 都采用同样的包装方式。
字典:唯一天然是 JSON 对象的泛型
dict<a href="https://link.gitcode.com/i/4ef674b88b29459299b1423801c84f7f" target="_blank">str, ...] 是唯一一种本身就是 JSON 对象的泛型,因此它不会被包装(见 [docs_src/structured_output/tutorial006.py):
from mcp.server import MCPServer
mcp = MCPServer("Weather")
READINGS = {"London": 16.2, "Cairo": 34.1, "Reykjavik": 4.4}
@mcp.tool()
def get_temperatures(cities: list[str]) -> dict[str, float]:
"""Current temperature for each city, in degrees Celsius."""
return {city: READINGS[city] for city in cities}
其 output_schema 直接就是字典形态:
{
"additionalProperties": {"type": "number"},
"title": "get_temperaturesDictOutput",
"type": "object"
}
structured_content 也保持字典原样:
result.structured_content # {"London": 16.2, "Reykjavik": 4.4}
注意键必须是 str。dict<a href="https://link.gitcode.com/i/9ae4be9e92d2ed22dde14bda7bc8cfb7" target="_blank">int, float] 无法构成 JSON 对象,因此会回退到 {"result": ...} 包装。从源码看,字典结果的校验与序列化使用 Pydantic 的 TypeAdapter;如果你检查某个 Tool 的 FuncMetadata.output_model,它保存的正是这个字典类型注解及其 Schema 标题(见 [func_metadata.py)。
输出校验:Schema 不是文档,是约束
output_schema 不是写给人看的文档。函数返回的任何东西在离开服务器之前都会被拿来与它校验。
手工构建值时你感觉不到校验的存在——Pydantic 早就保证了你的 WeatherData 是一个合法的 WeatherData。但当数据来自你无法控制的第三方时,问题就会暴露。看这个例子(docs_src/structured_output/tutorial007.py):
import json
from pydantic import BaseModel
from mcp.server import MCPServer
mcp = MCPServer("Weather")
UPSTREAM = {"London": '{"temperature": 16.2, "conditions": "Overcast"}'}
class WeatherData(BaseModel):
temperature: float
humidity: float
conditions: str
@mcp.tool()
def get_weather(city: str) -> WeatherData:
"""Current weather for a city."""
return json.loads(UPSTREAM[city])
注解承诺返回 WeatherData,但上游响应突然不再发送 humidity 字段了。
调用 get_weather 时,SDK 不会悄悄把一个半空的坏对象交给客户端。调用会失败:客户端收到 is_error=True 且错误信息为 Error executing tool get_weather,于是模型知道这次调用失败了,而不是自信满满地"读到"一份并不存在的天气数据。具体的字段名则出现在服务器端 ERROR 级别的日志中,供你排查:
Tool 'get_weather' raised an unexpected exception
...
pydantic_core._pydantic_core.ValidationError: 1 validation error for WeatherData
humidity
Field required [type=missing, input_value={'temperature': 16.2, 'conditions': 'Overcast'}, input_type=dict]
顺带一提,从 -> WeatherData 的 Tool 里返回普通 dict 是完全合法的——上面的 json.loads 产出的正是 dict。校验针对的是值本身,而不是 Python 类型。
退出结构化输出:structured_output=False
有时返回类型注解只是写给类型检查器看的,并不想参与协议。传入 structured_output=False,Tool 就变成纯文本(见 docs_src/structured_output/tutorial008.py):
from mcp.server import MCPServer
mcp = MCPServer("Weather")
@mcp.tool(structured_output=False)
def weather_report(city: str) -> str:
"""A human-readable weather report for a city."""
return f"{city}: 17 degrees, overcast, light rain easing by evening."
没有 output_schema、没有包装、没有校验。structured_content 为 None,content 就是你返回的那个字符串。
与之相对,structured_output=True 会把自动检测变成硬性要求:一个返回类型无法产出 Schema 的 Tool,会在导入时直接抛出异常,而不是默默回退为纯文本。
内容块与媒体:默认帮你退出
内容块与媒体(TextContent、EmbeddedResource、Image、Audio 等,无论是单独返回、作为 list/tuple/Sequence 的元素,还是作为联合类型的分支)默认都会被帮你退出结构化输出:它们本就是给模型阅读的,自动检测不会从它们推导 Schema(Image 与 Audio 详见 图片、音频与图标)。不过,structured_output=True 仍会为内容块类强制创建 Schema。
无类型注解的类:唯一的静默退出
有一种情况会"不请自来"地失去结构化输出:返回一个类体内没有任何注解的类(见 docs_src/structured_output/tutorial009.py):
from mcp.server import MCPServer
mcp = MCPServer("Weather")
class Station:
def __init__(self, name: str, online: bool):
self.name = name
self.online = online
@mcp.tool()
def get_station(name: str) -> Station:
"""Look up a weather station by name."""
return Station(name=name, online=True)
Station 在 __init__ 里设置了 name 和 online,但类本身什么也没有声明。SDK 读取类的注解,一无所获,于是放弃。
它是静默放弃的。
output_schema为None,structured_content为None,模型读到的文本是对象的repr:"<server.Station object at 0x7f539d75b230>"没有报错、没有警告,只有一个废掉的 Tool。解决办法:把注解挪到类体内,或者传
structured_output=True,后者会在模块导入的瞬间把这种情况变成硬错误:Function get_station: return type <class 'server.Station'> is not serializable for structured output。
如果你需要完全的控制权(自己构建
CallToolResult,或者附加应用可见而模型不可见的_meta字段),那就应该使用 底层 Server(Low-level Server)。
底层实现:FuncMetadata 如何推导 Schema
从源码看,结构化输出的核心逻辑集中在 func_metadata.py 中的 FuncMetadata 数据类:
output_schema:对外发布的 JSON Schema;output_model存在且output_schema尚未生成时,会通过TypeAdapter(...).json_schema()推导并内联根引用。output_model:结构化输出所校验的类型——可以是声明的BaseModel/TypedDict,也可以是针对包装型、dict[str, T]与注解类返回而合成的模型。wrap_output:布尔标志,标记函数结果是否需要被包装进{"result": ...}。
_create_output_model(见 func_metadata.py)的分支逻辑印证了文档中的全部规则:
BaseModel、TypedDict、dataclass、带注解的普通类 → 模型直接就是 Schema,wrap_output = False;dict[str, T]→ 不包装;而dict[int, float]这类非字符串键的字典 → 需要包装,wrap_output = True;- 列表、元组、
Union、Optional等其余泛型 → 一律包装; - 标量(
str、int、float、bool、bytes、None)→ 包装; structured_output=False时直接跳过推导;structured_output=None且返回类型属于内容块时,自动检测也会跳过。
_create_wrapped_model(见 func_metadata.py)则负责动态创建一个带 result 字段的包装模型,这正是文档中 {"result": ...} 包装与 get_temperatureOutput 这类标题的来源。
校验与序列化阶段,call_with_args 在结果非错误且存在 output_model 时,会用 TypeAdapter.validate_python(result.structured_content) 校验,再以 mode="json", by_alias=True 序列化(见 func_metadata.py),最终产出一个同时携带 content 与 structured_content 的 CallToolResult。
围绕这套行为,仓库还提供了完整的测试覆盖,见 tests/docs_src/test_structured_output.py,以及可直接运行的全部示例代码 docs_src/structured_output/,适合动手验证每种返回形态的 Schema 与校验表现。
要点回顾
- 返回类型注解就是输出 Schema,它会随
tools/list以output_schema的形式发布。 - 标量、列表、元组与联合类型会被包装进
{"result": ...};模型、TypedDict、dataclass、带注解的类以及dict[str, ...]本身就是对象,保持原样。 - 每个结果都同时携带
content(文本,给模型)和structured_content(数据,给应用)。 - 返回值会与 Schema 校验。校验不通过是一次 Tool 错误,而不是一份损坏的结果。
structured_output=False可以让单个 Tool 退出结构化输出;内容块、Image、Audio默认退出;没有类型注解的类会静默退出,务必警惕。
至此,你已经掌握了 Tool 能够"说"出的一切形态。下一步是第二个原语:资源(Resources)。