SEP-1034:在信息征询 schema 中支持所有基本类型的默认值

SEP-1034:在信息征询 schema 中支持所有基本类型的默认值

社区译文;来源: MCP 29affa6b

本 SEP 已达到 Final 状态,并作为已接受设计的历史记录保留。 定稿后对协议所做的更改不会反映在此处。权威要求请参阅当前规范 及其变更日志。
字段值
SEP1034
标题在信息征询 schema 中支持所有基本类型的默认值
状态Final
类型标准跟踪
创建日期2025-07-22
作者Tapan Chugh (chugh.tapan@gmail.com)
发起人无
PR#1034

摘要

本 SEP 建议在 MCP 信息征询 schema 的所有基本类型(StringSchema、NumberSchema 和 EnumSchema)中增加默认值支持,扩展目前仅覆盖 BooleanSchema 的能力。

动机

MCP 中的信息征询提供了一种缓解复杂 API 设计的方法:工具可以按需请求信息,不必采用复杂曲折的参数处理方式。然而,当前的问题是用户必须手动输入一些显而易见、本可预填的信息,导致交互不够自然。目前只有 BooleanSchema 在信息征询请求中支持默认值。这一限制使服务器无法为文本输入、数值和枚举选择提供合理的默认值,增加了用户负担。

真实场景示例

以实现电子邮件回复功能为例。没有信息征询时,工具会变得笨重:

def reply_to_email_thread(
    thread_id: str,
    content: str,
    recipient_list: List[str] = [],
    cc_list: List[str] = []
) -> None:
    # Ambiguity: Does empty list mean "no recipients" or "use defaults"?
    # Complex logic needed to handle different combinations

使用信息征询后,工具签名本身可以简单得多:

def reply_to_email_thread(
    thread_id: str,
    content: Optional[str] = ""
) -> None:
    # Code can lookup the participants from the original thread
    # and prepare an elicitation request with the defaults setup
const response = await client.request("elicitation/create", {
  message: "Configure email reply",
  requestedSchema: {
    type: "object",
    properties: {
      recipients: {
        type: "string",
        title: "Recipients",
        default: "[email protected], [email protected]"  // Pre-filled
      },
      cc: {
        type: "string",
        title: "CC",
        default: "[email protected]"  // Pre-filled
      },
      content: {
        type: "string",
        title: "Message"
        default: "" // If provided in the tool above
      }
    }
  }
});

实现

一个可运行的实现表明,客户端只需很少的改动(约 10 行代码)即可显示默认值:

  • 实现 PR:https://github.com/chughtapan/fast-agent/pull/2
  • 使用上述电子邮件回复流程的演示:https://asciinema.org/a/X7aQZjT2B5jVwn9dJ9sqQVkOM

规范

Schema 变更

扩展信息征询的基本类型 schema,使其包含可选默认值:

export interface StringSchema {
  type: "string";
  title?: string;
  description?: string;
  minLength?: number;
  maxLength?: number;
  format?: "email" | "uri" | "date" | "date-time";
  default?: string; // NEW
}

export interface NumberSchema {
  type: "number" | "integer";
  title?: string;
  description?: string;
  minimum?: number;
  maximum?: number;
  default?: number; // NEW
}

export interface EnumSchema {
  type: "string";
  title?: string;
  description?: string;
  enum: string[];
  enumNames?: string[];
  default?: string; // NEW - must be one of enum values
}

// BooleanSchema already has default?: boolean

行为

  1. default 字段是可选的,因此保持完全向后兼容
  2. 默认值必须与 schema 类型匹配
  3. 对于 EnumSchema,默认值必须是有效枚举值之一
  4. 支持默认值的客户端 SHOULD 预填表单字段。不支持默认值的客户端 MAY 完全忽略该字段。

理由

  1. 总体理由是沿用 BooleanSchema 已建立的先例,而不是创建新机制。
  2. 将默认值设为可选可确保向后兼容。
  3. 这延续了保持客户端实现简单的总体思路。

考虑过的替代方案

  1. 服务器端模板:服务器可以单独维护模板,但这会增加复杂性
  2. 新的请求类型:为带默认值的表单增加独立请求类型会割裂 API
  3. 必填默认值:强制要求默认值会破坏现有实现

向后兼容性

此变更完全向后兼容,不包含破坏性变更。不理解默认值的客户端会忽略它们,现有信息征询请求可继续保持不变。客户端可以按自己的节奏采用默认值支持。

安全影响

没有新的安全问题:

  1. 无敏感数据:现有的“不得请求敏感信息”指导仍然适用
  2. 客户端控制:客户端仍完全控制向服务器发送哪些数据
  3. 用户可见性:默认值对用户可见,用户可在提交前修改