把 MCP Server 迁到无状态规范：2026-07-28 版的破坏性变更与逐项改法

这五类代码是高风险区，先用一条命令看它们在哪些文件里：

# 在 MCP Server 仓库根目录执行
grep -rn "Mcp-Session-Id" --include=*.py --include=*.ts --include=*.js .
grep -rn "initialize" --include=*.py --include=*.ts --include=*.js .
grep -rn "sampling\|roots\|logging" --include=*.py --include=*.ts .
grep -rn "32002" .
grep -rn "inputSchema" --include=*.py --include=*.ts .

官方 SDK 升级到 2.x 之后，服务端的处理函数不再依赖会话对象。你要做的是把「从会话里取用户/租户」改成「从请求自带的元数据里取」。协议层版本、客户端身份与能力都走 _meta 字段：

// 请求自带的保留键（前缀使用反向 DNS 记号）
// io.modelcontextprotocol/protocolVersion
// io.modelcontextprotocol/clientInfo
// io.modelcontextprotocol/clientCapabilities
// 每个请求都要带：MCP-Protocol-Version 与 Mcp-Method 两个头

// 服务端：从请求上下文读取，而不是从会话缓存读取
function handleToolCall(req, res) {
  const meta = req.meta || {};
  const client = meta['io.modelcontextprotocol/clientInfo'];
  const version = meta['io.modelcontextprotocol/protocolVersion'];
  if (!version) return res.error(-32600, 'missing MCP-Protocol-Version');
  // 后续一律不使用「上次那个会话」，全部按本次请求参数决策
  return runTool(req.params, { client, version });
}

无状态不等于「服务端不能有状态」。官方推荐的做法与普通 HTTP API 一致：在工具调用里生成一个显式句柄返回给模型，模型在后续调用中当成普通参数传回来。

// 调用开始时：服务端生成句柄，状态存在自己这边（数据库/缓存）
// tools/call  create_report  ->  { handle: "rpt_9f2c7a", status: "draft" }

// 后续调用：模型把句柄当普通参数传回
// tools/call  update_section  ->  { handle: "rpt_9f2c7a", section: "risk" }

// 服务端每次都必须用本次请求的授权上下文校验句柄归属
def resolve(handle, auth_ctx):
    row = db.get(handle)
    if not row or row.tenant != auth_ctx.tenant:
        raise PermissionError("handle not owned by caller")
    return row

旧版里 sampling、elicitation、roots 这些「服务端向客户端发起请求」的动作是骑在一条常开的流上完成的。无状态之后没有那条流了，改用新的 Multi Round-Trip Requests（MRTR） 模式：服务端返回一个需要补充信息的中间结果，客户端补齐后重新发起该次调用。

# 服务端：需要用户确认时，不挂起连接，而是返回可继续的状态
{
  "status": "input_required",
  "request_id": "mrtr_31ab",
  "prompt": "导出范围请二选一：全量 / 仅本月",
  "options": ["all", "this_month"]
}

# 客户端：拿到 input_required 后补齐参数，再发一次同一个工具调用
{ "name": "export_report", "arguments": { "range": "this_month", "mrtr": "mrtr_31ab" } }

规范给了至少 12 个月的移除窗口，所以现有部署还有时间，但新功能不要再建在这三者之上。迁移映射如下：

这两处最危险，因为它们不会让服务起不来，只会让逻辑悄悄跑偏：

# 变更一：资源不存在时的错误码
- 旧：MCP 自定义的 -32002
+ 新：JSON-RPC 标准 -32602
# 如果你的代码按字面匹配 -32002，升级后会“漏掉”所有 missing resource 错误

# 变更二：inputSchema 支持完整 JSON Schema 2020-12
# 现在合法：oneOf / anyOf / $ref
# 假设 schema 是扁平结构的解析器需要同步升级

# 1) 先用 Inspector 验证新规范行为
npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp
#    重点关注：tools/list 是否可缓存（看 ttlMs）
#              工具调用是否无需 initialize 即可完成

# 2) 再用未升级的老客户端连一次，确认不会 400
#    老客户端会带 Mcp-Session-Id，服务端必须忽略而非拒绝

# 3) 压测一把水平扩展：把服务放两副本，前面挂普通轮询负载均衡
#    连续调用 20 次，确认没有请求因“换了实例”而失败