Python MCP SDK 服务端结构化输出(Structured Output)完整指南:返回类型注解即输出 Schema

原创2026-09-21 22:36:021,355 阅读
文章标签:人工智能大模型MCP 服务MCP Clients工具调用后端

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)。

登录后查看全文
python-sdk