模型上下文协议规范(2025-06-18)—— 操作引导
翻译自:https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation
ℹ️ 协议修订:2025-06-18
ℹ️ 操作引导在此版本的MCP规范中是新引入的,其设计可能会在未来的协议版本中演变。
模型上下文协议(MCP)提供了一种标准化的方式,使服务器能够在与客户端的交互过程中通过客户端向用户请求额外的信息。此流程允许客户端在与用户的交互和数据共享中保持控制,同时使服务器能够动态地收集必要的信息。服务器通过 JSON 模式向用户请求结构化数据以验证响应。
用户交互模型
在MCP中,信息操作引导允许服务器通过启用用户输入请求嵌套在其他MCP服务器功能内部,从而实现交互式工作流程。
实现可以自由地通过任何符合其需求的接口模式来展现操作引导过程——协议本身并未规定任何特定的用户交互模型。
ℹ️ 为了信任与安全及保障:
- 服务器绝不可使用操作引导性请求获取敏感信息。
应用程序应该:
提供明确显示是哪个服务器正在请求信息的用户界面。
允许用户在发送前审阅和修改他们的回复
尊重用户隐私,并提供明确的拒绝和取消选项
能力
支持操作引导的客户端必须在初始化期间声明elicitation
功能:
{
"capabilities": {
"elicitation": {}
}
}
协议消息
创建需求操作引导请求
要向用户请求信息,服务器会发送一个 elicitation/create
请求:
简单文本请求
请求:
{
"jsonrpc": "2.0",
"id": 1,
"method": "elicitation/create",
"params": {
"message": "Please provide your GitHub username",
"requestedSchema": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"]
}
}
}
响应:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"action": "accept",
"content": {
"name": "octocat"
}
}
}
结构化数据请求
请求:
{
"jsonrpc": "2.0",
"id": 2,
"method": "elicitation/create",
"params": {
"message": "请提供您的联系方式",
"requestedSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "您的全名"
},
"email": {
"type": "string",
"format": "email",
"description": "您的电子邮件地址"
},
"age": {
"type": "number",
"minimum": 18,
"description": "您的年龄"
}
},
"required": ["name", "email"]
}
}
}
响应:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"action": "accept",
"content": {
"name": "Monalisa Octocat",
"email": "octocat@github.com",
"age": 30
}
}
}
拒绝响应示例:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"action": "reject"
}
}
取消响应示例:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"action": "cancel"
}
}
消息流
请求模式
requestedSchema
字段允许服务器使用受限的 JSON Schema
子集来定义预期响应的结构。为了简化客户端的实现,操作引导模式仅限于具有原始属性的简单对象。
"requestedSchema": {
"type": "object",
"properties": {
"propertyName": {
"type": "string",
"title": "Display Name",
"description": "Description of the property"
},
"anotherProperty": {
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"required": ["propertyName"]
}
支持的模式类型
该模式仅限于以下基本类型:
- 字符串模式
{
"type": "string",
"title": "显示名称",
"description": "描述文本",
"minLength": 3,
"maxLength": 50,
"pattern": "^[A-Za-z]+$",
"format": "email"
}
支持的格式:email
、uri
、date
、date-time
- 数字模式
{
"type": "number", // 或 "integer"
"title": "显示名称",
"description": "描述文本",
"minimum": 0,
"maximum": 100
}
- 布尔模式
{
"type": "boolean",
"title": "显示名称",
"description": "描述文本",
"default": false
}
- 枚举模式
原样返回:
{
"type": "string",
"title": "显示名称",
"description": "描述文本",
"enum": ["option1", "option2", "option3"],
"enumNames": ["Option 1", "Option 2", "Option 3"]
}
客户端可以使用此模式来:
- 生成适当的输入表单
- 在发送之前验证用户输入。
- 为用户提供更好的指导
请注意,为了简化客户端实现,复杂的嵌套结构、对象数组以及其他高级 JSON Schema 功能故意不予支持。
响应行动
启发式响应使用三步动作模型来清楚地区分不同的用户操作:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"action": "accept", // or "reject" or "cancel"
"content": {
"propertyName": "value",
"anotherProperty": 42
}
}
}
三个响应动作是:
-
接受(
action: "accept"
):用户明确批准并提交了数据content
字段包含与请求的模式匹配的提交数据。- 示例:用户点击了“提交”、“确定”、“确认”等。
-
拒绝(
action: "reject"
):用户明确拒绝了请求- 通常省略
content
字段。 - 示例:用户点击了“拒绝”、“不接受”、“否”等。
- 通常省略
-
取消(
action: "cancel"
):用户在未做出明确选择的情况下取消。- 通常省略
content
字段。 - 示例:用户关闭了对话框,点击了外部区域,按下了 Escape 键等。
- 通常省略
服务器应适当处理每种状态。
- 接受:处理提交的数据
- 拒绝:处理明确的拒绝(例如,提供替代方案)
- 取消:处理解散(例如,稍后再次提示)。
安全性考虑
- 服务器绝不能通过套取方式请求敏感信息。
- 客户端应当实现用户批准控制。
- 双方应该根据提供的模式验证提取内容。
- 客户端应当清楚表明是哪个服务器正在请求信息。
- 客户端应允许用户随时拒绝操作引导请求。
- 客户端应该实现速率限制。
- 客户端应该以一种清晰的方式提出操作引导请求,明确表明所需的信息是什么以及为什么需要这些信息。