本文由 Huifer 撰写 — TanStack Ship 的独立开发者和维护者。
2026-11-09 17:45:28Z,npm 把
@tanstack/ai的latestdist-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/ai1.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.742Z | 2026-11-09T17:45:28.315Z |
| 描述 | 「类型安全的 TypeScript AI SDK,支持流式聊天、工具调用、智能体、结构化输出和多模态生成。」 | 未变 |
| 许可证 | MIT | MIT |
| 运行环境 | Node >=18 | Node >=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 B | 648 个文件 / 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.ts | manager 把 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:
// @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 运行层级这样使用:
// 共享 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 里的版本范围:
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:
| 包管理器 | 命令 |
|---|---|
| npm | npm install @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0 |
| pnpm | pnpm add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0 |
| yarn | yarn add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0 |
# 安装,然后确认 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