SEP-2322: 多轮往返请求

Documentation Index

Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

摘要

​

动机

1. 短暂型：服务器端不会累积状态。
   • 如果服务器需要更多信息来处理工具调用，它可以在收到额外信息时从头开始。
   • 示例：天气应用、访问电子邮件
2. 持久型：服务器端会累积状态。
   • 在向客户端请求更多信息之前，服务器可能会生成大量状态；在收到客户端的信息后，它可能需要恢复这些状态以继续处理。
   • 服务器可能需要在等待客户端提供更多信息的同时在后台继续处理，在这种情况下就需要服务器端状态来跟踪该持续进行的处理。
   • 示例：访问代理、启动虚拟机并需要用户交互来操作该虚拟机

1. 客户端发送工具调用请求。以此为例，假设负载均衡器碰巧将该请求发送到了服务器实例 A。
2. 服务器 A 打开一个 SSE 流，并在该流上发送澄清请求。
3. 客户端将澄清响应作为一个单独的请求发送，负载均衡器会完全独立于步骤 1 中所选实例来选择服务器实例。以此为例，假设负载均衡器碰巧将该请求发送到了服务器实例 B。
4. 服务器 A 必须以某种方式发现发往服务器 B 的澄清响应。
5. 然后服务器 A 在步骤 2 中打开的 SSE 流上发送工具调用结果。

• 跨服务器实例共享的持久化存储层：服务器可以 部署并管理一个持久化存储层（例如 PostgreSQL、Redis、 DynamoDB），使多个服务器实例能够将一个服务器实例上的澄清响应与另一个服务器实例上原本正在进行的 工具调用对应起来。这种方式有若干缺点：
  • 持久化存储层极其昂贵，尤其是对于 可能原本并不具备此类存储层的短暂型工具（例如天气 工具）而言。
  • 持久化存储层带来显著的可靠性问题： 它会成为关键依赖，因此也可能成为单点故障。为了避免这一点，它必须提供高可用、复制和备份机制。
  • 持久化存储层会成为瓶颈，限制横向 扩展能力。地理分布式部署要么需要昂贵的 全局复制，要么需要粘性路由。
  • 持久化存储层还带来显著的运维 复杂性。在横向扩展部署中，它需要 分布式锁或共识协议。它还需要特殊的 垃圾回收逻辑来判断何时可以清理共享内容， 这需要仔细权衡：过于激进地清理状态会降低存储成本，但会限制用户可响应的时长； 而较不激进地清理则能容纳响应缓慢的用户，但会 增加存储成本。
  • 这种方式要求工具实现中具备特殊行为， 以便与持久化存储层集成。如今的 MCP SDK 并没有针对这类存储层集成的特殊钩子， 这意味着通过 SDK 编写内联代码会非常困难。
• 负载均衡中的状态性：借助 cookie，可以 让负载均衡层确保步骤 3 中的澄清请求被送达与步骤 1 中原始请求相同的服务器实例。该方式虽然 通常比持久化存储层更便宜，但也有以下 缺点：
  • 它要求负载 均衡器进行特殊配置和行为，这通常难以管理。
  • 它打破了正常的负载均衡模型，导致负载分布不均，从而增加运行服务的成本。
  • 它要求客户端具备特殊行为，以传递用于状态性的 cookie。
  • 它要求工具实现将澄清请求与正在进行的工具调用对应起来。（MCP SDK 中有一些代码来处理这一点，但在 HTTP 世界中这仍然是一个非常奇怪的模式。）
  • 它没有故障容错能力。如果服务器实例宕机，所有 状态都会丢失，工具调用就需要从头开始。（这对短暂型工具不一定重要，但对持久型工具而言是个问题。）

​

规范

​

Schema 变更

export type InputRequest =
  | CreateMessageRequest
  | ElicitRequest
  | ListRootsRequest;

export interface InputRequests {
  [key: string]: InputRequest;
}

export type InputResponse =
  | CreateMessageResult
  | ElicitResult
  | ListRootsResult;

export interface InputResponses {
  [key: string]: InputResponse;
}

"inputRequests": {
  // 询问请求。
  "github_login": {
    "method": "elicitation/create",
    "params": {
      "mode": "form",
      "message": "Please provide your GitHub username",
      "requestedSchema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "required": ["name"]
      }
    }
  },
  // 采样请求。
  "capital_of_france" : {
    "method": "sampling/createMessage",
    "params": {
      "messages": [
        {
          "role": "user",
          "content": {
            "type": "text",
            "text": "What is the capital of France?"
          }
        }
      ],
      "modelPreferences": {
        "hints": [
          {
            "name": "claude-3-sonnet"
          }
        ],
        "intelligencePriority": 0.8,
        "speedPriority": 0.5
      },
      "systemPrompt": "You are a helpful assistant.",
      "maxTokens": 100
    }
  }
}

"inputResponses": {
  // 询问响应（ElicitResult）。
  "github_login": {
    "action": "accept",
    "content": {
      "name": "octocat"
    }
  },
  // 采样响应（CreateMessageResult）。
  "capital_of_france": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

export interface InputRequiredResult extends Result {
  // 由服务器发起的请求，客户端必须在重试原始请求之前完成。
  inputRequests?: InputRequests;
  // 客户端在重试原始请求时需要回传给服务器的请求状态。
  // 注意：客户端必须将其视为不透明的 blob；不得以任何方式解释它。
  requestState?: string;
}

// 包含 input responses 和 request state 的 RequestParams 类型。
// 这些参数可以包含在任何客户端发起的请求中。
export interface InputResponseRequestParams extends RequestParams {
  // 用于承载 InputRequiredResult 消息中服务器请求的响应的新字段。
  // 对于 response 的 inputRequests 字段中的每个键，这里必须出现相同的键及其关联响应。
  inputResponses?: InputResponses;
  // 从客户端回传给服务器的 request state。
  requestState?: string;
}

/**
 * 通用结果字段。
 *
 * @category Common Types
 */
export interface Result {
  _meta?: MetaObject;
  // 指示结果类型的新字段，允许客户端确定如何解析结果对象。如果未指定 resultType，则应假定为 "complete"。
  resultType: ResultType;
  [key: string]: unknown;
}

export type ResultType =
  | "complete" // 请求已成功完成，结果包含最终内容。
  | "input_required"; // 请求尚未完成，结果包含一个 {@link InputRequiredResult} 对象

​

客户端请求的服务器发起请求支持

​

短暂工具工作流

1. 客户端发送工具调用请求。
2. 服务器返回一个单独的响应，表明该请求尚未完成。该响应可以包含客户端必须完成的输入请求。它也可以包含一些请求状态，客户端必须将其回传给服务器。该响应会终止原始请求。通常它会作为单独的响应发送，而不是通过 SSE 流发送，不过目前（这在未来的 SEP 中可能会改变）也允许在 SSE 流中发送该响应，且可以跟随（例如）进度通知。如果这个未完成响应是通过 SSE 流发送的，那么它必须是 SSE 流中的最后一条消息，就像普通响应一样。
3. 客户端发送一个新的工具调用请求，与原始请求完全独立。这个新的工具调用包含对第 2 步输入请求的响应。它还包含服务器在第 2 步中指定的请求状态。
4. 服务器返回一个 CallToolResponse。

​

短暂工作流的真实示例

​

请求状态的使用场景

使用场景 1：滚动升级

1. 客户端发送工具调用请求，命中运行旧版本的服务器实例。
2. 服务器返回一个未完成响应，指示 “github_login” 和 “google_login” 的输入请求。
3. 客户端发送一个新的工具调用请求，其中包含对 “github_login” 和 “google_login” 输入请求的响应。这一次它命中了运行新版本的服务器实例。
4. 服务器返回另一个未完成响应，指示客户端尚未提供的 “microsoft_login” 输入请求。然而，该响应还包含请求状态，其中包含已提供的 “github_login” 响应，因此客户端不需要再次提示用户输入相同的信息。
5. 客户端发送第三个工具调用请求，其中包含对 “microsoft_login” 输入请求的响应，并回传服务器在第 4 步提供的请求状态。
6. 服务器现在在请求状态中看到了 “github_login” 信息，在 input responses 中看到了 “microsoft_login” 状态，因此该请求现在包含了服务器执行工具调用并返回完整响应所需的一切信息。

使用场景 2：负载卸载

1. 客户端发送原始请求，负载均衡器将其路由到服务器实例 A。
2. 服务器实例 A 在做完大量计算后决定需要卸载负载。它发送一个未完成响应，在 requestState 字段中包含其已累积的状态，但不包含 inputRequests 字段。
3. 客户端使用附加了 requestState 字段的请求进行重试。负载均衡器将此请求路由到服务器实例 B。
4. 服务器实例 B 从 requestState 字段中看到的状态开始，因此从服务器实例 A 停止的地方继续计算，并最终返回完整响应。

​

短暂工作流的协议要求

1. 服务器行为：
   • 服务器 MAY 对任何客户端发起的请求响应 InputRequiredResult。该消息 MAY 作为独立响应发送，或作为 SSE 流中的最后一条消息发送，不过实现方建议优先采用前者。如果使用 SSE 流，服务器 MUST NOT 在未完成响应消息之后再发送任何消息。
   • InputRequiredResult MAY 包含 inputRequests 字段。
   • InputRequiredResult MAY 包含 requestState 字段。如果指定，该字段是仅对服务器有意义的不透明字符串。服务器可以自由地以任何格式编码状态（例如纯 JSON、base64 编码 JSON、加密 JWT、序列化二进制等）。
   • 如果请求包含 requestState 字段，服务器 MUST 始终验证该状态，因为客户端是不受信任的中介。如果担心篡改，服务器 SHOULD 使用其选择的加密算法对 requestState 字段进行加密（例如，可以使用 AES-GCM 或签名 JWT），以确保机密性和完整性。请注意，还存在重放/劫持攻击的风险：经过身份验证的攻击者可能会重新发送原本发给另一个用户的状态。因此，如果请求状态包含任何特定于原始用户的数据，服务器 MUST 使用某种机制在密码学上将该数据绑定到原始用户，并且 MUST 验证客户端发送的 requestState 数据是否与当前已认证用户相关联。使用明文状态的服务器 MUST 将解码后的值视为不可信输入，并以与验证任何客户端提供数据相同的方式进行验证。
2. 客户端行为：
   • 如果客户端收到一条 InputRequiredResult 消息，并且该消息包含 inputRequests 字段，那么客户端 MUST 在重试原始请求之前构造所请求的输入。相反，如果消息不包含 inputRequests 字段，那么客户端 MAY 立即重试原始请求。
   • 如果客户端收到一条包含 requestState 字段的 InputRequiredResult 消息，它在重试原始请求时 MUST 回传该字段的精确值。客户端 MUST NOT 检查、解析、修改 requestState 的内容，也不得对其内容作任何假设。如果 InputRequiredResult 不包含 requestState 字段，那么客户端 MUST NOT 在重试中包含该字段。

​

持久工具工作流

1. 服务器将 Task Status 设为 input_required。此时服务器可以暂停处理请求。
2. 客户端通过调用 tasks/get 获取 Task Status，并看到需要更多信息。
3. 客户端调用 tasks/result
4. 服务器返回 InputRequests 对象。
5. 客户端调用包含 InputResponses 对象以及 Task 元数据字段的 tasks/input_response 请求。
6. 服务器恢复处理，并将 TaskStatus 设回 working。

​

持久工作流的协议要求

1. 服务器行为：
   • 服务器 MAY 通过指示任务处于 input_required 状态来响应 tasks/get。
   • 当任务处于 input_required 状态时，服务器 MUST 在 tasks/result 响应中包含 inputRequests 字段。
2. 客户端行为：
   • 当 tasks/get 显示状态为 input_required 时，客户端 MUST 调用 tasks/result 以获取输入请求。客户端 SHOULD 构造这些请求的结果，然后调用 tasks/input_response，连同 input responses 一起提供任务所需输入。
   • 客户端 MAY 选择不满足这些输入请求，在这种情况下可以取消任务。

​

短暂与持久工作流之间的交互

1. 客户端发送带有 task 元数据的工具调用请求。
2. 服务器返回 inputRequests 响应，表明处理该请求还需要更多信息。该响应会终止原始请求。
3. 客户端发送一个新的工具调用请求，与原始请求完全独立，其中包含 inputResponses 对象以及 task 元数据。
4. 服务器返回一个 task ID，表明它将会在后台处理该请求。后续所有交互都将通过 Tasks API 完成。

​

错误处理指导

1. 客户端重试原始工具调用，这次包含 inputResponses 对象，但响应缺少服务器处理请求所需的必需信息。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    },
    "inputResponses": {
      "not_requested_info": {
        "action": "accept",
        "content": {
          "not_requested_param_name": "Information the server did not request"
        }
      }
    }
  }
}

2. 服务器返回一个未完成响应，表明客户端需要对一个询问请求作出响应才能完成工具调用，并包含要回传的请求状态：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "input_required",
    "inputRequests": {
      "github_login": {
        "method": "elicitation/create",
        "params": {
          "mode": "form",
          "message": "Please provide your GitHub username",
          "requestedSchema": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              }
            },
            "required": ["name"]
          }
        }
      }
    }
  }
}

2. 服务器返回一个未完成响应，表明客户端需要提供缺失信息以使请求成功。

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tasks/input_response",
  "params": {
    "inputResponses": {
      "echo_input": {
        "action": "accept",
        "content": {
          "not_requested_parameter": "Information the server did not request."
        }
      }
    },
    "_meta": {
      "io.modelcontextprotocol/related-task": {
        "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5"
      }
    }
  }
}

{
  "id": 4,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "io.modelcontextprotocol/related-task": {
        "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5"
      }
    }
  }
}

​

原因说明

​

向后兼容性

def my_tool():
  do_work()
  await elicit_more_info()
  do_more_work()
  return tool_result

def my_tool(request):
  if(request.requestState):
      state = decode(request.requestState)
  if(request.inputResponses):
      additionalInfo = decode(request.inputResponses)

  do_work(state, additionalInfo)
  if(more_info_needed):
    return IncompleteResponse();
  else
    do_more_work()
    return tool_result

​

安全影响

​

参考实现

​

致谢