用途:让浏览器中的智能体在开发阶段读取库的内部信息。包为 @tanstack/devtools-webmcp,无运行时依赖,这些工具不会出现在 devtools 面板中。
注册:从库中调用 registerDevtoolsTools,传入 pluginId、可选的 instanceId 以及 tools 数组;每个工具需要 name、description、execute。execute 接收输入和 { signal },返回可被 JSON.stringify 序列化的数据,并原样发送给浏览器。可选字段有 title、inputSchema(JSON Schema,不用于 TypeScript 类型推断)、以及 readOnlyHint、untrustedContentHint、consequentialHint 提示;helper 会把 annotations.debugging 设为 true。
命名:浏览器工具名为 pluginId.name,instanceId 为非空字符串时为 pluginId.instanceId.name。每个组成部分只能包含 ASCII 字母、数字、_、-、.,完整名称长度 1 到 128 字符。
清理与替换:调用立刻返回 stop。同一 pluginId 与 instanceId 的再次调用会替换之前的列表并中止先前的 controller,之前的 stop 随之失效。传入空 tools 数组会移除该 pluginId 与 instanceId 下的工具。
错误:helper 对每个错误写一条 console.error,不抛出。pluginId 或 instanceId 非法则不注册任何工具且保留旧注册;name 非法或完整名超过 128 字符则跳过该工具,同列表其余合法工具仍注册;全名重复或被其他代码占用则浏览器拒绝该工具,helper 记录错误;inputSchema 无法序列化同样会被拒绝并记录,继续注册其余工具。
导入:开发时使用根导入,仅当 process.env.NODE_ENV 为 'development' 时是真实 helper,其他环境(含未设置)为 no-op。需要在生产保留工具时改用 @tanstack/devtools-webmcp/production。浏览器查找顺序为 document.modelContext 上的 registerTool,其次 navigator.modelContext.registerTool;两者都没有时返回清理函数且不抛错、不写日志,适用于服务端渲染、Node 及无 WebMCP 的浏览器。常见错误包括名称中使用冒号、生产中误用根导入、在注册后立刻调用 stop()。