mcp-use 旧版模式迁移指南：从 `schema`/`widget` 迁移到 `inputSchema`/`view` 的完整实践

后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载本篇技术指南聚焦 mcp-useTypeScript框架中已退役或仅保留兼容性的旧模式retired / compatibility-only patterns的迁移。文中以skills/mcp-builder/references/migration.md为骨架结合 server 包源码、React 钩子与类型声明展开帮助你理解「行为迁移而非名称迁移」的底层逻辑并掌握将旧式mcp-use/server导入、内联回调、链式tool()、widget配置与聚合 Provider 平滑迁移到当前版本 API 的完整路径。读完本文你将能够依据一份可执行的 7 步检查清单独立完成工具、资源、提示词、View 与认证边界的迁移验证。适用前提迁移工作始终以已安装的mcp-use包及其导出的类型、生成的声明文件为唯一事实源source of truth而非以历史 changelog 或复制来的旧示例为准。若当前项目源码中不存在任何下文列出的退役标识符则本参考无需阅读。迁移的第一性原则迁移行为而非名称skills/mcp-builder/references/migration.md开篇即强调只有当项目仍包含已从安装包中移除、或已不再是推荐写法的旧模式时才需要阅读本参考。迁移的核心不是机械地把schema重命名为inputSchema——因为 prompts提示词的schema字段是有意保留的而是要迁移行为本身并对每一个变更过的边界用已安装版本的类型做校验。在 server 包类型定义 中可以看到这一设计的事实依据ToolDefinition同时声明了inputSchema与schema两个字段源码注释明确写道schema是inputSchema的别名alias并在新代码中优先使用inputSchema因为它与 MCP 线上传输字段名一致。而工具结果类型ToolResulttools.ts#L154-L160则要求一旦声明了outputSchema回调必须返回携带匹配structuredContent的结果或显式返回isError: true的结果——这一约束同时存在于编译期类型与 SDK 运行时校验中。因此迁移的第一步永远是搜索而非替换在源码、测试、示例和项目文档中检索退役标识符见下文检查清单第 1 条再逐个确认公共导入与注册签名。替换已退役模式新旧对照与逐项解读下表完整继承自 migration.md列出已退役/兼容模式与当前推荐写法的对照旧模式或兼容写法当前替换写法Server 从mcp-use/server导入从mcp-use导入公共 Server APIToolschemaToolinputSchemaprompt 参数仍使用schema内联回调字段将回调作为注册方法的第二个参数传入链式server.tool(...).tool(...)分别注册tool()返回ToolRef嵌套的 resource-template 配置顶层uriTemplate与complete字段将 response helpers 作为默认结果路径返回原始的 tool、resource 或 prompt 协议信封protocol enveloperesources/name/widget.tsxviews/name/view.tsxToolwidget: { name }Toolview: { name }widget({ props, output }){ content, structuredContent, _meta? }useWidget()或useWidgetProps()解构的useToolContexttool-name()聚合 Provider 包装器运行时 bootstrap 聚焦的 React hooks 与组件聚合 widget 状态与宿主方法useViewState、useHostContext、useDisplayMode及聚焦 hooks以下逐条展开其迁移要点与源码依据。1. 导入路径mcp-use/server→mcp-use旧版从mcp-use/server子路径导入服务端 API当前版本要求公共 Server API 一律从包根mcp-use导入。查看 server 包入口文件 可以看到当前根入口聚合导出了MCPServer、createMcpMount、fetch 中间件、registerViews、requestLogger以及CallToolResult/ReadResourceResult/GetPromptResult等协议信封类型。与此同时React API 从mcp-use/react导入OAuth 提供方适配器从各自的mcp-use/oauth/*子路径导入——这三类导入路径在 SKILL.md 的 Core invariants 中被列为必须遵守的框架约定。2.schema→inputSchema仅限 Tool工具参数声明从schema迁移为inputSchema。inputSchema接受任何实现了StandardSchemaWithJSON的标准 schema 库zod v4、ArkType、Valibot 等字段描述会作为 LLM 提示线索输入在回调执行前由 SDK 完成校验线上以inputSchema字段名发出tools.ts#L64-L72。重要例外prompt提示词参数仍使用schema因此不要机械地全局重命名每一个schema。资源与 prompt 的回调签名也应独立于工具进行确认。3. 内联回调字段 → 注册方法的第二参数旧式写法可能在定义对象内联回调当前注册签名统一为「定义对象 回调」两个参数。例如 server.ts 中resource(definition, callback)即把静态资源定义与回调分离resourceTemplate(definition, callback)亦然server.ts#L694-L709。4. 链式tool()→ 分别注册tool()返回ToolRef旧式写法允许server.tool(...).tool(...)链式注册当前tool()返回的是携带工具名称与幻影类型phantom input/output types的ToolReftools.ts#L111-L129不再支持链式。每个工具应单独调用server.tool(definition, callback)注册并把被 View 消费的工具 ref 从 server 入口导出见下文「重建交互式 UI」第 2 步。5. 嵌套 resource-template 配置 → 顶层uriTemplate与complete参数化资源的模板配置从嵌套结构上移为定义对象的顶层字段。ResourceTemplateDefinition携带顶层uriTemplate模板字符串与complete补全回调。源码中complete会经过normalizeCompletions归一化后与模板一并存储server.ts#L704-L709。类型层面const类型参数保证uriTemplate在推断期间保持字符串字面量类型从而让InferTemplateParams能够依据模板变量为回调params提供精确类型。6. response helpers → 原始协议信封旧版依赖text(...)、object(...)等 response helpers 作为默认返回路径当前推荐直接返回 SDK 的原始协议信封工具返回CallToolResult、资源返回ReadResourceResult、prompt 返回GetPromptResultindex.ts#L37-L54。源码明确指出这些 deprecated helpers 只是产生相同 tool 信封的薄封装thin shimsresource/prompt 注册仍会为兼容性转换 helper 形状的返回值。迁移时优先改写为原始信封例如带outputSchema的工具return { content: [{ type: text, text: JSON.stringify(data) }], structuredContent: data, };7~8.widget.tsx→view.tsxwidget: { name }→view: { name }交互式渲染文件从resources/name/widget.tsx迁移到views/name/view.tsx工具的绑定声明从widget: { name }改为view: { name }。ToolViewConfigtools.ts#L24-L51说明了一个 View 最多绑定一个工具该工具拥有 View 资源的事实description、csp、permissions、domain、prefersBorder第二个命名同一 View 的工具会被拒绝。View 组件由 view 文件导出框架把这些字段发射到该 View 的 MCP resource 的_meta.ui上供宿主读取。9.widget({ props, output })→{ content, structuredContent, _meta? }旧式 widget 回调签名改为标准结果信封。content存放模型可读文本structuredContent存放类型化的渲染数据_meta存放仅 View 使用的调用数据。注意 SDK 的运行时规则当structuredContent是非对象值且没有type: text块时SDK 会自动附加 JSON 文本块对象形负载则需要自行包含文本序列化tools.ts#L143-L152。10~12.useWidget()→useToolContext()聚合 Provider → 聚焦 hooks旧式useWidget()/useWidgetProps()与聚合 Provider、聚合 widget 状态和宿主方法统一替换为聚焦的 React hooksuseToolContext、useViewState、useHostContext、useDisplayMode等对应实现位于 react/hooks 目录。运行时 bootstrap如registerViews/__primeViews见 server.ts#L609-L631取代了聚合 Provider 包装器。重建交互式 UI7 步迁移流程对于每一个「渲染型工具」rendering toolmigration.md 给出了完整迁移流程逐条展开如下移动入口把渲染入口迁至views/name/view.tsx。导出工具 ref在 server 入口导出该工具声明产生的ToolRef——这是useToolContexttool-name()得以推断输入/输出类型的前提。补充outputSchema与view: { name }View 绑定强制要求outputSchemaView 读取结果structuredContent时以该 schema 作为类型来源tools.ts#L104-L108。分类放置数据模型可读文本放content类型化渲染数据放structuredContent仅 View 调用的数据放_meta。解构useToolContext()并处理三态在读取toolOutput前必须处理 pending、error、ready 三种状态。参考 use-tool-context.ts 的示例——status error渲染错误横幅、status pending渲染骨架屏、status ready渲染toolOutput。该 hook 通过useSyncExternalStore订阅运行时的延迟生命周期首个携带structuredContent的成功结果或工具错误会成为终态后续生命周期通知不能覆盖该终态use-tool-context.ts#L51-L63。用聚焦 hooks 替换聚合 UI 方法如useViewState管理 View 本地状态、useHostContext读取宿主能力、useDisplayMode感知展示模式。迁移 CSP 与资源CSP 迁至view.csp字段公共资源通过框架 base 解析。ToolViewConfig.csp会被发射到 resource 的_meta.ui.csp框架在发射时会自动把 server origin 追加进connectDomains、把配置的 assets origin或 server origin追加进resourceDomains其余作者设置字段frameDomains、baseUriDomains等原样透传tools.ts#L32-L38。移除传输与会话假设请求作用域与外部存储迁移不只是 UI 表面。migration.md 要求把回调视为请求作用域request-scoped且可能并发执行的代码。以下旧假设必须移除活动会话注册表active-session registries不再维护全局会话表会话亲和session affinity不假定同一客户端的连续请求落在同一处理路径内存用户身份in-memory user identity不把用户身份缓存在模块全局响应后客户端定位post-response client targeting不在响应返回后继续定向操作客户端。上述状态一律改为请求上下文request context或外部存储external store承载。身份与可变工作流状态应保持请求作用域或放入外部存储客户端上报的元数据一律视为未经验证SKILL.md Core invariants。在认证边界上ctx.client只能用于自报能力self-reported capabilitiesctx.auth才承载已验证身份verified identity。同理禁止使用模块全局变量承载跨请求身份、elicitation 连续性或持久业务状态SKILL.md Guardrails。传输层约定同样需要调整basePath用于 MCP endpoint 路径。源码对basePath有严格校验必须是绝对 URL pathname不允许空段、尾斜杠、query、fragment 或空白字符config.ts#L269-L285否则抛出TypeError。MCP_URL用于外部可见的公共 originpublic origin。不得基于 localhost 假设自行拼接公共 URL——部署环境不同localhost 推断必然失效。迁移检查清单7 步验证闭环migration.md 提供了一份可直接执行的收尾清单完整继承如下并补充执行要点搜索退役标识符在源码、测试、示例与项目文档中检索上表列出的全部旧写法mcp-use/server导入、toolschema、链式tool()、widget、聚合 Provider 等。确认公共导入与注册签名对照已安装包的实际导出与签名而不是参照历史文档或旧示例。先跑类型生成与类型检查运行类型生成如mcp-env.d.ts相关生成与 typecheck再解读下游报错——否则错误可能源于过期声明而非真实代码问题。真实客户端验证用真实客户端而非仅靠源码构建逐一演练每个迁移过的 tool、resource template 与 prompt。逐项渲染验证每个 View测试 pending、error、ready 三态、交互、资源assets与 CSP 行为。边界变更验证当认证、notifications、elicitation 等边界发生变化时通过受支持的客户端测试这些能力。打包并从干净消费者导入当包导出或依赖发生变化时执行打包并从全新消费者项目中导入验证排除陈旧缓存或残留产物干扰。migration.md 特别提示不要仅因项目现有代码中出现某个 API 就保留它——凡已安装版本中不存在的 API 都不得保留SKILL.md Guardrails也不要仅凭源码构建通过就宣称迁移成功尤其是类型、包导出、认证或交互行为发生变更的场景。迁移后的落地建议完成上述迁移后建议以create-mcp-use-applatest生成的新模板为基准对照检查匹配包版本或 dist-tagbeta/canary/已有版本项目尤其如此并以skills/mcp-builder/references/verification.md作为上报实现完成前的最终核验依据。迁移不是一次性重命名而是「先搜索、再确认类型、后逐边界验证」的工程闭环——行为正确、边界验证充分才是一次成功的迁移。赞分享后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载相关推荐最完整的Android Sunflower迁移指南从View到Jetpack Compose的实践最完整的Android Sunflower迁移指南从View到Jetpack Compose的实践 你是否正在寻找将Android应用从传统View体系迁移到移动开发示例工程JumpServer容器镜像源迁移的技术内幕与部署优化指南JumpServer容器镜像源迁移的技术内幕与部署优化指南 技术故障现象与影响范围分析 近期部分用户在部署JumpServer v4.9.0 ce版本时遭遇后端认证鉴权运维应用安全合规审计终极Handlebars.js版本迁移指南从旧版本无缝升级到5.0的实用技巧终极Handlebars.js版本迁移指南从旧版本无缝升级到5.0的实用技巧 Handlebars.js作为一款Minimal templating on前端上一篇Plain Craft Launcher 2为什么这款免费启动器能让你的Minecraft体验更简单高效下一篇如何快速解决Windows热键冲突Hotkey Detective完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考