SEP-2106：工具的 inputSchema 与 outputSchema 符合 JSON Schema 2020-12

• 状态（Status）: Final
• 类型（Type）: Standards Track
• 创建（Created）: 2026-01-06
• 作者（Author(s)）: John McBride (@jpmcb) —— 原始提案；Ola Hungerford (@olaservo) —— 当前引导者，SEP-1850 转换后
• 担保人（Sponsor）: Ola Hungerford (@olaservo)
• PR: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2106

作者身份说明： 原始提案由 John McBride (@jpmcb) 在 PR #881 中撰写，早于 SEP-1850 基于 PR 的工作流。本文件将该提案转换为当前 SEP 格式，并由 Ola Hungerford (@olaservo) 引导，她还根据评审反馈修订了向后兼容性、安全影响和 SDK 迁移章节。原始文字和设计意图仍属 John；转换以来的实质性变更在本 PR 的提交历史中跟踪。

​

摘要

• inputSchema：保留 type: "object" 为必需（因为工具参数是对象），但允许任何额外的 JSON Schema 属性，以支持强大的校验组合（anyOf、oneOf、allOf 等）
• outputSchema：完全支持 JSON Schema 2020-12，因为 MCP 服务器可能返回任何有效的 JSON
• structuredContent：接受任何经 outputSchema 校验的 JSON 值

​

动机

1. inputSchema 限制：当前只允许 type、properties 和 required 字段。这妨碍了使用 anyOf、oneOf 和 allOf 等组合关键字来实现复杂的对象校验模式。
2. outputSchema 限制：同样被限制为带 properties 和 required 的 type: "object"，尽管规范声称支持”JSON Schema”。
3. structuredContent 限制：被定义为 { [key: string]: unknown }（一个带字符串键的对象），这妨碍了返回数组——一种常见的 API 响应模式。

​

现实世界的影响

[
  { "hour": "09:00", "temp": 68, "conditions": "sunny" },
  { "hour": "10:00", "temp": 72, "conditions": "partly cloudy" },
  { "hour": "11:00", "temp": 75, "conditions": "cloudy" }
]

{
  "forecasts": [
    { "hour": "09:00", "temp": 68, "conditions": "sunny" },
    ...
  ]
}

• 为响应添加了不必要的嵌套
• 与常见的 REST API 模式相冲突
• 妨碍了对数组响应的直接 schema 校验

​

Schema 组合用例

{
  "type": "object",
  "oneOf": [
    { "properties": { "id": { "type": "string" } }, "required": ["id"] },
    { "properties": { "name": { "type": "string" } }, "required": ["name"] }
  ]
}

​

规范

​

1. 放宽 inputSchema

inputSchema: {
  type: "object";
  properties?: { [key: string]: object };
  required?: string[];
};

inputSchema: {
  $schema?: string;
  type: "object";
  [key: string]: unknown;
};

• 组合关键字：anyOf、oneOf、allOf、not
• 条件 schema：if/then/else
• 引用 schema：$ref、$defs
• 任何其他有效的 JSON Schema 2020-12 关键字

​

2. 放宽 outputSchema

outputSchema?: {
  type: "object";
  properties?: { [key: string]: object };
  required?: string[];
};

outputSchema?: {
  $schema?: string;
  [key: string]: unknown;
};

​

3. 放宽 structuredContent

structuredContent?: { [key: string]: unknown };

structuredContent?: unknown;

• 对象：{ "key": "value" }
• 数组：[1, 2, 3] 或 [{ "id": "abc" }, { "id": "xyz" }]
• 基本类型："string"、42、true、null

​

4. 文档更新

• 移除关于 structuredContent”作为 JSON 对象返回”的陈述
• 澄清 structuredContent 可以是符合 outputSchema 的任何 JSON 值
• 添加演示数组响应的示例

​

5. 示例

​

返回对象数组的工具：

{
  "name": "list_users",
  "description": "List all users in the system",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
    }
  },
  "outputSchema": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      },
      "required": ["id", "name"]
    }
  }
}

{
  "content": [
    {
      "type": "text",
      "text": "Found 2 users: Alice (u1, alice@example.com) and Bob (u2, bob@example.com)."
    }
  ],
  "structuredContent": [
    { "id": "u1", "name": "Alice", "email": "alice@example.com" },
    { "id": "u2", "name": "Bob", "email": "bob@example.com" }
  ]
}

​

带组合 schema 的工具：

{
  "name": "find_resource",
  "description": "Find a resource by ID or name",
  "inputSchema": {
    "type": "object",
    "oneOf": [
      {
        "properties": { "id": { "type": "string", "format": "uuid" } },
        "required": ["id"]
      },
      {
        "properties": { "name": { "type": "string", "minLength": 1 } },
        "required": ["name"]
      }
    ]
  }
}

​

理由

​

为何不只是允许数组？

1. 支持 JSON Schema 2020-12 的全部能力
2. 与规范对 JSON Schema 支持的声称对齐
3. 提供一致、有原则的方式，而非零敲碎打的修补

​

为何不要求封装对象？

1. 它为响应增加了不必要的复杂性
2. 它与常见的 API 设计模式相冲突
3. 它妨碍了对实际响应结构的直接 schema 校验
4. JSON Schema 已经优雅地处理数组校验

​

现实世界的 API 模式

• GitHub Events API：返回事件对象数组
• AccuWeather Search API：返回位置匹配数组
• REST 集合端点：标准的 GET /users 返回 [{...}, {...}]

​

与 JSON Schema 2020-12 对齐

​

SDK 生态证据

1. 显式错误消息承认这一局限：
   raise ValueError(
       f"Output schemas must represent object types due to MCP spec limitations."
   )
   
2. 自动封装基础设施增加了复杂性：
   • 一个 _WrappedResult dataclass 封装非对象返回
   • 一个自定义的 x-fastmcp-wrap-result 扩展支持客户端侧解封装
   • SDK 和客户端都需要匹配的封装/解封装逻辑
3. 这些变通办法已导致真实缺陷：
   • Issue #2455：没有 type: object 的 $ref schema 破坏了服务器上的所有工具
   • Issue #2421：意外的 {"result": ...} 封装令用户困惑

​

OpenAPI 先例

​

向后兼容性

​

兼容性矩阵

​

TypeScript / SDK 迁移

const result = await client.callTool({ name: "get_weather", arguments: { ... } });
const temp = result.structuredContent?.temperature;        // previously compiled (type: unknown)
const city = result.structuredContent?.["city"] as string; // previously compiled

const sc = result.structuredContent;
if (sc && typeof sc === "object" && !Array.isArray(sc)) {
  const temp = (sc as Record<string, unknown>).temperature;
}

• 在 SDK 发布说明中记录该迁移。
• 在符合工效学之处，提供类型化辅助工具（例如对工具 outputSchema 的泛型），使消费者无需手写收窄守卫。

​

迁移路径

• 服务器：无需迁移即可像以前一样工作。要使用数组或基本类型 structuredContent，还需发出一个序列化的 TextContent 回退。
• 客户端：旧客户端继续针对仅对象服务器工作。要消费新的灵活性，应在 structuredContent 中接受任何 JSON 值，并在存在 outputSchema 时对照校验。
• SDK：更新生成的类型以反映新 schema（structuredContent 为 unknown，开放式的 inputSchema/outputSchema），并在发布说明中指出源码破坏性的类型变更。

​

安全影响

​

$ref 解引用（SSRF 与 Fetch-DoS）

• 实现**不得（MUST NOT）**自动解引用解析为网络 URI 的 $ref 值（即任何不是同文档 JSON 指针，如 #/$defs/Foo 或内部 $anchor 的东西）。
• 此处”自动”意为”作为正常校验或 schema 处理的一部分，无需显式的操作员动作”。实现**可以（MAY）提供一个获取非本地 $ref 的选择加入模式，但它必须默认禁用，并应当（SHOULD）**强制执行主机允许列表（或至少拒绝环回、链路本地和私有网络地址）、应用超时和大小限制，并记录解引用的 URI。
• 因未解析的外部 $ref 而校验失败的 schema **应当（SHOULD）**被拒绝，而非默默地被当作宽松处理。

​

组合关键字的资源使用

​

参考实现

​

TypeScript SDK

• 分支：olaservo/typescript-sdk@sep-834-v1x
• npm：@olaservo/mcp-sdk@1.25.2-sep834.4
• 关键变更：
  • inputSchema：保留 type: "object" 但允许任何额外的 JSON Schema 属性（如 oneOf/anyOf 组合）
  • outputSchema：任何有效的 JSON Schema 对象（数组、基本类型、对象、组合）
  • structuredContent：任何 JSON 值（对象、数组或基本类型）
  • McpServer 高层 API 更新以支持数组和基本类型 outputSchema

​

Everything Server 演示工具

• 分支：olaservo/servers@sep-834-json-schema-2020-12
• npm：@olaservo/mcp-server-everything-sep834@1.1.0-sep834.1
• 工具：
  • get-weather-forecast：直接在 structuredContent 中返回逐小时预报的原始数组
    • 与 SEP-2106 动机章节中的确切示例匹配
    • outputSchema：z.array(HourlyForecastSchema) —— 根为数组类型
    • structuredContent：[{hour, temp, conditions}, ...] —— 直接数组
  • find-by-id-or-name：演示灵活的输入模式（接受 id 或 name）
  • get-count：直接在 structuredContent 中返回原始数字（不封装在对象中）
    • outputSchema：z.number() —— 根为基本类型
    • structuredContent：42 —— 直接基本类型

​

相关链接

• 原始 PR：https://github.com/modelcontextprotocol/modelcontextprotocol/pull/881
• 相关 issue：https://github.com/modelcontextprotocol/modelcontextprotocol/issues/834
• outputSchema 类型限制不一致：https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1906
• TypeScript SDK schema 类型：https://github.com/modelcontextprotocol/typescript-sdk/issues/1149
• SEP-2200（澄清工具结果内容与模型可见性）：https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2200

​

实现指南

1. 更新 inputSchema 类型，保留 type: "object" 但允许任何额外的 JSON Schema 属性
2. 更新 outputSchema 类型，允许任何有效的 JSON Schema（移除 type: "object" 约束）
3. 更新 structuredContent 类型，接受任何有效的 JSON 值
4. 相应地更新 JSON Schema 定义

​

致谢