SEP-2549: 列表结果的 TTL

​

摘要

​

动机

1. 基于 HTTP 的传输需要 SSE 流：许多客户端和服务器在支持长连接 SSE 流时存在困难，而通知正是需要这些流的。目标是让 SSE 流成为一种可选优化，同时无需它们也能支持协议功能。TTL 允许客户端按可预测的时间表轮询，而无需依赖服务器推送通知。
2. 实现复杂性：客户端和服务器都必须实现通知订阅与投递基础设施。许多简单服务器的功能列表很少变化（甚至从不变化），但如果希望客户端保持最新，仍然必须支持通知机制。
3. 缺少新鲜度信号：即使可以接收通知的客户端，也无法知道一个列表有多“稳定”。一个工具列表每天变化一次的服务器，与一个每秒变化一次的服务器，对客户端来说看起来是一样的——两者都只是在人发生变化时发送通知。TTL 提供了明确的新鲜度提示。
4. 与 Web 标准一致：HTTP 缓存（Cache-Control: max-age）和 DNS TTL 长期以来都证明了，基于时间的新鲜度提示是一种简单且广为理解的减少不必要重新获取的机制。MCP 也可以从同样的模式中受益。

​

规范

​

新接口：CacheableResult

​

架构变更（TypeScript）

/**
 * 一个支持客户端侧缓存的带生存时间（TTL）提示的结果。
 *
 * @internal
 */
export interface CacheableResult extends Result {
  /**
   * 来自服务器的提示，指示客户端在重新获取之前
   * MAY 缓存此响应的时长（毫秒）。语义
   * 类似于 HTTP Cache-Control 的 max-age。
   *
   * - 如果为 0，则响应 SHOULD 立即视为过期，客户端
   *   MAY 在每次需要该结果时都重新获取。
   * - 如果为正数，客户端 SHOULD 在接收响应后的这段
   *   毫秒内将结果视为新鲜。
   */
  ttlMs: number & { readonly minimum: 0 };

  /**
   * 指示缓存响应的预期作用域，类似于 HTTP
   * Cache-Control: public 与 Cache-Control: private。
   *
   * - "public"：任何客户端或中间代理（例如共享网关、代理）
   *   MAY 缓存该响应并将其提供给任何用户。
   * - "private"：只有请求该响应的用户的客户端 MAY 缓存该响应。
   *   共享缓存（例如多租户网关）MUST NOT 将缓存副本提供给不同的用户。
   *
   * 如果省略，默认为 "public"。
   */
  cacheScope: "public" | "private";
}

​

语义

​

新鲜度计算

​

缓存作用域

• "public"：响应不包含用户特定数据。任何客户端、共享网关或缓存代理 MAY 存储该缓存响应，并将其提供给任何用户。这适用于对所有用户都相同的工具、提示和资源模板列表。
• "private"：响应包含用户特定数据。只有请求该响应的用户的客户端 MAY 缓存它。共享缓存（例如多租户 API 网关）MUST NOT 将 "private" 缓存响应提供给不同的用户。这适用于依赖已认证用户的 resources/read 结果，或按用户变化的过滤列表结果。

​

与通知的交互

• 服务器 MAY 提供 ttlMs，而不在其能力声明中声明 listChanged: true。在这种情况下，客户端完全依赖 TTL。
• 服务器 MAY 同时声明 listChanged: true 并 提供 ttlMs。在这种情况下，客户端可以使用 TTL 避免在通知之间进行不必要的重新获取，而通知则充当立即失效信号。

​

与分页的交互

• 每个页面响应都带有自己的 ttlMs 值。每一页的新鲜度时钟从该页被接收时开始。
• 服务器 MAY 在不同页面上返回不同的 ttlMs 值（例如：稳定列表的前几页使用更长 TTL，最后一页使用更短 TTL）。
• 不保证跨页一致性。如果底层数据在分页获取之间发生变化，客户端可能观察到重复或缺失——这与 HTTP 分页 API 面临的是同样的权衡。
• 需要完整列表一致快照的客户端 SHOULD 从头重新获取（不带 cursor）。
• 如果 cursor 变为无效（例如，服务器对先前有效的 cursor 返回错误），客户端 SHOULD 丢弃所有已缓存页面，并从头重新获取。

​

错误处理

• 如果 ttlMs 存在但为负整数，客户端 SHOULD 忽略它，并按 0（立即过期）处理。

​

原因

​

为什么不替换 list_changed 通知？

​

为什么 TTL 使用整数毫秒？

​

为什么不直接使用 HTTP 缓存？

​

向后兼容性

• 现有不提供它的服务器将继续按原样工作。如果 ttlMs 字段缺失，客户端 SHOULD 假定默认 ttlMs 为 0（立即过期），并依赖其自身的缓存启发式规则或通知，这也是当前行为。
• 不理解该字段的现有客户端将忽略它，因为 MCP 的结果对象通过基础类型 Result 上的 [key: string]: unknown 允许额外属性。
• cacheScope 是必需的，因为对于旧服务器没有安全的默认值。服务器必须显式声明预期的缓存范围，以防止意外缓存用户特定数据。
• 不修改或移除任何现有字段或行为。
• 不需要能力协商。
• SDK 维护者可以选择在其 SDK 中为 ttl 和 cacheScope 添加默认值以简化采用，但这不是合规所必需的。

​

参考实现

​

安全影响