TanStack AI 1.4.0:MCP 请求级 _meta 与安全升级指南

本文解析 @tanstack/ai 1.4.0 为 MCP 工具调用加入的按请求 _meta:依据 npm 元数据、tarball 差异与官方文档,拆解 9 个文件变更,解释 ai-mcp 1.2.0 为何必须配套升级,并给出多租户场景下的安装、传输层验证、缓存隔离与回滚清单,帮助你安全完成版本迁移。

Huifer
Huifer
November 12, 202610 min read
其他语言:Deutsch · English

本文由 Huifer 撰写 — TanStack Ship 的独立开发者和维护者。

2026-11-09 17:45:28Z,npm 把 @tanstack/ai 的 latest dist-tag 指向新版本时,我按自己模板里每次升级依赖的习惯,拉下 1.3.0 和 1.4.0 两个已发布的 tarball,对随包提供的类型声明做 diff,而不是相信发布摘要。差异涉及 648 个文件里的 9 个,讲出的故事比「AI SDK 更新」具体得多:1.4.0 让单个 MCP 请求可以携带自己的上下文。

已核实来源:TanStack AI 文档 · TanStack · GitHub 上的 TanStack AI · npm 上的 @tanstack/ai 1.4.0 · web.dev · Cloudflare Workers 文档

最后更新:2026-11-12

TanStack AI 1.4.0 只发布了一个面向用户的新功能:按请求传递 MCP _meta。 npm registry 记录显示,@tanstack/ai@1.4.0 于 2026-11-09T17:45:28.315Z 发布,并带有 latest dist-tag。把已发布的 tarball 与 1.3.0 对比,648 个文件里有 9 个变化;整个差异就是一个新增的 requestMeta hook,让每次 MCP 工具调用和每次 ui:// 资源读取都能把自己的 _meta(租户、用户或追踪上下文)发给 MCP 服务器。本文会讲清变更内容、升级步骤,以及必须一起升级的那个依赖。

要点速览

  • 实测: @tanstack/ai@1.4.0 于 2026-11-09T17:45:28.315Z 发布,比 1.3.0 晚 4 小时 36 分 57 秒。
  • 实测: 648 个已发布文件中有 9 个发生变化;解包后体积从 5,898,105 → 5,905,099 字节(+6,994 B,+0.12%)。
  • 实测: 唯一新增的公开 API 是 MCPRequestMeta / MCPRequestMetaInput 类型,以及 MCP chat 选项里的 requestMeta。
  • 实测: 传输侧实现位于 @tanstack/ai-mcp@1.2.0,它在核心包发布 18 分 40 秒后才发布——单装核心包 1.4.0 不会发送 _meta。
  • 我的判断: 不用 MCP 的项目可以低风险升级;共用同一个 MCP 连接池的多租户应用则必须升级。
  • 选型决策: 横向对比 AI SaaS 样板项目,看看哪些起步模板已经内置按请求传递的 MCP 上下文。

定义: @tanstack/ai@1.4.0 是 TanStack 在 2026 年 11 月发布的类型安全 AI SDK 版本,它在 MCP chat 运行中加入 requestMeta hook,让每次工具调用和每次 ui:// 资源读取都能把自己的 _meta(租户、用户或追踪上下文)发给 MCP 服务器。

@tanstack/ai 1.4.0 实际发布了什么:已核实的记录

我把这一节拆成 registry 记录能证明的部分和 tarball 差异能证明的部分;发布说明把两者混在一起时,升级计划最容易出错。

npm registry 记录中的事实

下面每一行都读自 1.4.0 的 npm registry 记录。1.3.0 一列读取的是同一份文件、同一层级,因此差异可以直接比较。

registry 字段@tanstack/ai@1.3.0@tanstack/ai@1.4.0
发布时间戳2026-11-09T13:08:31.742Z2026-11-09T17:45:28.315Z
描述「类型安全的 TypeScript AI SDK,支持流式聊天、工具调用、智能体、结构化输出和多模态生成。」未变
许可证MITMIT
运行环境Node >=18Node >=18
peer 依赖@opentelemetry/api >= 1.9.0未变
内部依赖@tanstack/ai-utils@^1.1.0, @tanstack/ai-event-client@^1.0.1未变
外部依赖@ag-ui/core@1.0.0, partial-json@^0.1.7, fast-json-patch@^3.1.1, @cfworker/json-schema@^4.1.1, @standard-schema/spec@^1.1.0未变
导出子路径10 个(., ./byok, ./locks, ./client, ./testing, ./adapters, ./byok/server, ./middlewares, ./middlewares/otel, ./adapter-internals)未变
已发布文件数 / 解包字节数648 个文件 / 5,898,105 B648 个文件 / 5,905,099 B

有两行决定了这次升级的风险高低。导出映射没有变化,所以应用里的导入路径都不用改。而且所有依赖范围都没动,安装时的依赖解析图与 1.3.0 完全一致——这个版本不会破坏你的 lockfile。

9 个文件的差异

真正的答案在 tarball 差异里。9 个变更路径里,4 个是编译后的 .js/.js.map 产物,3 个是对应的 TypeScript 源码,还有 1 个是 package.json 里的版本字段。

变更路径(1.3.0 → 1.4.0)变更内容
src/activities/chat/mcp/types.ts新增 MCPRequestMeta 和 MCPRequestMetaInput 类型;源端 tools() 选项加入 requestMeta;readResource() 增加可选的第二个参数
src/activities/chat/mcp/manager.tsmanager 把 requestMeta 传进每个源的 tools() 调用,以及绑定好的 readResource 闭包
src/index.ts从包根路径导出这两个新类型
dist/esm/** + package.json上述代码的编译输出,外加版本号升到 1.4.0

包里其他内容都没动。这是一次刻意收窄范围的发布:一个 hook、一个联合类型、一个可选参数。

唯一发布的新功能:按请求传递 MCP _meta

在讲 API 前先把用例说清楚,因为它决定你到底需不需要这个版本。

这个 hook 实际如何运行

官方文档在托管式 MCP 指南的「向 MCP 服务器发送请求上下文」一节中介绍了它。它解决的问题是:共享 MCP 连接池只建立一次连接,因此每个请求的 header 都相同。如果每个请求属于不同租户,header 就承载不了这份上下文;而 _meta 会随单个请求一起传递,无论底层 transport 是哪一种。

文档写明的行为:

  • 这个 hook 在每次 MCP 请求开始时运行一次。工具发现不会调用它。
  • 它会收到 method 和 serverId;tools/call 还带有 toolName 和 args,resources/read 带有 uri。在连接池里,serverId 是配置键。
  • 返回 undefined 就不发送 _meta。
  • 客户端会剔除 MCP 保留的键:progressToken,以及 io.modelcontextprotocol/、mcp.dev/ 这类前缀。
  • 如果 hook 抛错,只有当前请求会失败:工具调用会作为工具错误发给模型,ui:// 读取则只是不返回 widget。
  • _meta 不参与 toolCacheMiddleware 的缓存键,所以命中缓存时不会发出请求,hook 也完全不会运行。

最后一点是我在生产环境评审时一定会提醒的坑:如果多个租户共用一套缓存存储,租户标识必须成为 keyFn 的一部分,否则某个租户缓存的工具结果可能被返回给另一个租户。

类型接口长什么样

1.4.0 随包发布的类型声明,是一个可辨识联合类型加一个函数类型。摘自已发布的 dist/esm/activities/chat/mcp/types.d.ts:

typescript
// @tanstack/ai@1.4.0 — 已发布的类型接口(结构原样保留)
export type MCPRequestMetaInput =
  | {
      method: 'tools/call'
      serverId: string | undefined
      toolName: string
      args: Record<string, unknown>
    }
  | { method: 'resources/read'; serverId: string | undefined; uri: string }

export type MCPRequestMeta = (
  request: MCPRequestMetaInput,
) =>
  | Record<string, unknown>
  | undefined
  | Promise<Record<string, unknown> | undefined>

按官方文档,在 chat 运行层级这样使用:

typescript
// 共享 MCP 连接池上的按请求上下文。
const stream = chat({
  adapter: openaiText('gpt-6.1-sol'),
  messages,
  threadId,
  runId,
  mcp: {
    clients: [sharedPool],
    connection: 'keep-alive',
    requestMeta: ({ serverId }) =>
      serverId === 'internal'
        ? { 'acme.com/tenantId': tenantId, 'acme.com/traceId': traceId }
        : undefined,
  },
})

serverId === 'internal' 这个判断就是多租户模式:一个连接池、多个服务器,上下文只转发给获准查看它的服务器。手动管理工具的应用还可以在下一层使用同一个 hook —— mcp.tools({ requestMeta }),手动 MCP 指南中有示例。

如何升级到 1.4.0

先确认实际安装的版本

先看实际解析出来的依赖树,而不是 package.json 里的版本范围:

bash
npm ls @tanstack/ai @tanstack/ai-mcp
npm view @tanstack/ai dist-tags
npm view @tanstack/ai-mcp dist-tags

如果应用完全不用 MCP,1.4.0 对它没有实际作用,升不升级都行。如果用了 MCP,第二行比第一行更关键。

安装锁定的版本组合

锁定精确版本,让 CI 和同事都解析到同一个 tarball:

包管理器命令
npmnpm install @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0
pnpmpnpm add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0
yarnyarn add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0
bash
# 安装,然后确认 lockfile 解析到了预期版本
pnpm add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0
grep -E '"@tanstack/ai(-mcp)?"' pnpm-lock.yaml
pnpm typecheck && pnpm test

静默失效场景:核心包 1.4.0 搭配 ai-mcp 1.1.1

这一点最容易漏掉,也是我为什么继续检查适配包、而不是只看核心包的原因。

@tanstack/ai-mcp@1.2.0 的发布时间是 2026-11-09T18:04:08.072Z,比核心包 1.4.0 晚 18 分 40 秒。它与 1.1.1 的差异涉及 15 个已发布路径(计入 source map 后为 19 个),补上了传输侧实现:一个 requestMetaParams() 辅助函数,负责过滤保留键,过滤后没有剩余内容就返回 {};callMcpTool() 新增 meta 参数;readResource()、getPrompt() 和 callTool() 新增 options.meta;连接池上的 readResource() 也改为可感知 serverId。它还把依赖从 @tanstack/ai@^1.3.0 改成了 @tanstack/ai@^1.4.0。

所以:只安装核心包,得到的只是一个有类型、却什么也不做的 hook。 如果依赖树里仍是 ai-mcp@1.1.1,类型系统会接受 requestMeta,但 hook 从不运行,也没有 _meta 到达服务器,全程不报任何错误。TypeScript 不会警告,npm 也不会警告,因为核心包完全不依赖 @tanstack/ai-mcp;依赖关系是反过来的。

两个包要一起升级,并在传输层做断言验证,而不是只验证类型。

这个版本支撑了 AI SaaS 模板的哪项能力

这是一次技术性发布,下面说它真正影响的选型决策。

共享 MCP 连接上的多租户上下文

每个接入共享 MCP 连接池的 AI SaaS 产品都会碰到同一堵墙:连接保活且共享,无法承载按请求区分的身份信息。在 1.4.0 之前,要么每个请求新建连接(每次调用都要付出延迟),要么设计一套与连接池机制相冲突的自定义 header 方案。有了 1.4.0 加 ai-mcp@1.2.0,租户、用户和追踪标识就能随每次工具调用一起传递。

这是模板该具备的能力,不是应用里该自己补的细节。 一个内置 MCP 工具调用的起步模板,也应该同时内置按请求上下文、取消机制,以及区分租户的工具缓存键;否则每个客户都得在每条路由里重复写同样三行代码。这正是我横向对比 AI SaaS 样板项目时采用的视角,也值得拿来问任何卖家:你的 MCP 层会转发租户信息吗?租户标识又是在哪里进入工具缓存键的?

哪个模板适合这个用例

如果你的产品是带工具的 AI 聊天,关键问题不是「用哪个 SDK 版本」,而是「哪个起步模板已经锁定并测试过一组确认可用的 @tanstack/ai 版本与 MCP client 组合」。AI Image Studio 模板是最接近媒体类流水线参考实现的样例,完整模板目录则覆盖聊天、RAG 和 agent 形态的产品。在写第一个 prompt handler 之前,这两处都值得先预览。

升级检查清单与回滚方案

把下面当作 PR 检查清单,每一行都是一道放行条件。

合并前

  • 确认应用是否用了 MCP;如果没用,这次升级只是形式上的变化。
  • 阅读 GitHub 上的 1.4.0 发布说明,留意类型接口反映不出来的行为变化。
  • 在同一次提交里同时升级 @tanstack/ai 和 @tanstack/ai-mcp。
  • 在传输层断言:在测试用 MCP 服务器里打印 request.params._meta,确认对应键已经送达。
  • 如果启用了 toolCacheMiddleware,上线前把租户标识放进 keyFn。
  • 确认 pnpm typecheck 和 AI 路由测试套件通过,而不只是冒烟测试。

回滚

  • 保留上一个 lockfile 对应的提交,确保一次 git revert 就能回退这次升级。
  • 在 Cloudflare 上,Workers 版本不可变,可以从控制台回退——先确认要恢复到哪个版本。
  • 部署期间盯紧错误追踪工具;MCP 工具错误数突然上升就是早期信号。
  • 在你惯常的生产观察窗口内让 1.4.0 充分跑稳之前,不要删除旧 lockfile。

局限、披露与如何理解这些结论

本文采用的结论类型。 实测指直接读取 npm registry 元数据,或对比两个已发布 tarball 得出的差异。计算指我对这些文件所做的算术(6,994 字节的差值、18 分 40 秒的发布间隔、1.3.0 与 1.4.0 之间 4 小时 36 分 57 秒的间隔)。估计指我的判断。用户提供在这里没有对应内容——本文没有任何指标来自用户或客户。代理指标指用来代替某个我无法测量的量的数字;本文没有这类数字。

我没有做的事。 我没有在生产应用里跑过 1.4.0。我只对比了两个已发布的 tarball,并阅读了随包发布的类型声明和源码。我没有对流式延迟、token 成本或 _meta 开销做基准测试,也不声称这些方面有任何改善。我拿不到上游 1.4.0 changelog 的正文,所以如果维护者发布了没有类型变化的运行时行为变更,本指南也不会体现——上线前请查看 GitHub releases。

文档现状。 截至 2026-11-12,官方 MCP 文档已在托管式 MCP和手动 MCP页面中介绍 requestMeta,但顶层的 MCP 工具页面还没有提到它。我记录的是文档当前的样子,不是我希望它变成的样子。

利益披露。 我维护 TanStack Ship,上面链接的模板都是我自己的产品。除了作为其 SDK 的用户,我与 TanStack 团队没有实质关联,本文也没有赞助。实际结果可能因你的应用、MCP 服务器和工具链而不同。

常见问题

@tanstack/ai 1.4.0 到底改了什么? 只有一个功能:为 MCP 增加按请求运行的 requestMeta hook。已发布的差异涉及 648 个文件中的 9 个,新增 MCPRequestMeta 和 MCPRequestMetaInput 类型,并在 MCP chat 选项和 MCP 源的 tools() 选项中加入可选的 requestMeta。导出映射和所有依赖范围都没变,因此导入路径无需改写。

@tanstack/ai 1.4.0 是破坏性更新吗? 这是次版本升级,已发布的差异里没有删除或重命名任何现有 API。readResource() 新增的是可选的第二个参数,忽略它的实现仍然兼容。不过仍要阅读上游发布说明:我的对比只限于类型接口和随包发布的源码。

也需要升级 @tanstack/ai-mcp 吗? 如果你用了 MCP,就需要。_meta 的传输由 @tanstack/ai-mcp@1.2.0 实现,它比核心包晚 18 分钟发布。如果依赖树里还是 ai-mcp@1.1.1,类型会接受这个 hook,但它永远到不了传输层——这是静默空操作,不是报错。

requestMeta 会拖慢每次工具调用吗? 我没有测量,所以不会给出数字。随包发布的代码只能说明:hook 在每次请求开始时运行一次;toolCacheMiddleware 命中缓存时不会发出请求,因此会完全跳过这个 hook。

如何确认租户上下文真的送达了? 要在传输层断言,而不是只看类型:在测试用 MCP 服务器的 handler 里打印 request.params._meta,确认发起工具调用时你的租户键存在,而 hook 返回 undefined 时该键不存在。

结论与下一步

@tanstack/ai@1.4.0 是一次范围很窄、风险较低的发布,全部内容就是按请求传递 MCP 上下文:648 个文件里改了 9 个,导出映射未变,只新增一个 hook,让共享 MCP 连接池能在每次工具调用中带上租户、用户或追踪身份信息。风险不在 API,而在于只升级核心包、却没有同步升级 @tanstack/ai-mcp@1.2.0——这会让功能静默失效。

下一步:横向对比 AI SaaS 样板项目,看看哪些已经转发按请求传递的 MCP 上下文、并使用区分租户的缓存键;然后在写第一个 prompt handler 之前,预览 AI Image Studio 模板或浏览所有模板。

相关阅读: TanStack AI 1.2.0 发布指南 · TanStack AI 1.1.0 发布指南 · TanStack AI Effect Adapter