企业官网建设流程全解析

• 后端
• MCP 服务
• MCP Clients
• AI Agent
• 人工智能

本篇技术指南聚焦 mcp-use（TypeScript）框架中已退役或仅保留兼容性的旧模式（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 线上传输字段名一致。而工具结果类型ToolResult（tools.ts#L154-L160）则要求：一旦声明了outputSchema，回调必须返回携带匹配structuredContent的结果，或显式返回isError: true的结果——这一约束同时存在于编译期类型与 SDK 运行时校验中。

因此，迁移的第一步永远是搜索而非替换：在源码、测试、示例和项目文档中检索退役标识符（见下文检查清单第 1 条），再逐个确认公共导入与注册签名。

替换已退役模式：新旧对照与逐项解读

下表完整继承自 migration.md，列出已退役/兼容模式与当前推荐写法的对照：

以下逐条展开其迁移要点与源码依据。

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）的ToolRef（tools.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 返回GetPromptResult（index.ts#L37-L54）。源码明确指出：这些 deprecated helpers 只是产生相同 tool 信封的薄封装（thin shims），resource/prompt 注册仍会为兼容性转换 helper 形状的返回值。迁移时优先改写为原始信封，例如带outputSchema的工具：

return { content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data, };

7~8.widget.tsx→view.tsx，widget: { name }→view: { name }

交互式渲染文件从resources/<name>/widget.tsx迁移到views/<name>/view.tsx，工具的绑定声明从widget: { name }改为view: { name }。ToolViewConfig（tools.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 hooks：useToolContext、useViewState、useHostContext、useDisplayMode等（对应实现位于 react/hooks 目录）。运行时 bootstrap（如registerViews/__primeViews，见 server.ts#L609-L631）取代了聚合 Provider 包装器。

重建交互式 UI：7 步迁移流程

对于每一个「渲染型工具」（rendering tool），migration.md 给出了完整迁移流程，逐条展开如下：

1. 移动入口：把渲染入口迁至views/<name>/view.tsx。
2. 导出工具 ref：在 server 入口导出该工具声明产生的ToolRef——这是useToolContext<"tool-name">()得以推断输入/输出类型的前提。
3. 补充outputSchema与view: { name }：View 绑定强制要求outputSchema，View 读取结果structuredContent时以该 schema 作为类型来源（tools.ts#L104-L108）。
4. 分类放置数据：模型可读文本放content，类型化渲染数据放structuredContent，仅 View 调用的数据放_meta。
5. 解构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）。
6. 用聚焦 hooks 替换聚合 UI 方法：如useViewState管理 View 本地状态、useHostContext读取宿主能力、useDisplayMode感知展示模式。
7. 迁移 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 capabilities），ctx.auth才承载已验证身份（verified identity）。同理，禁止使用模块全局变量承载跨请求身份、elicitation 连续性或持久业务状态（SKILL.md Guardrails）。

传输层约定同样需要调整：

• basePath用于 MCP endpoint 路径。源码对basePath有严格校验：必须是绝对 URL pathname，不允许空段、尾斜杠、query、fragment 或空白字符（config.ts#L269-L285），否则抛出TypeError。
• MCP_URL用于外部可见的公共 origin（public origin）。不得基于 localhost 假设自行拼接公共 URL——部署环境不同，localhost 推断必然失效。

迁移检查清单：7 步验证闭环

migration.md 提供了一份可直接执行的收尾清单，完整继承如下并补充执行要点：

1. 搜索退役标识符：在源码、测试、示例与项目文档中检索上表列出的全部旧写法（mcp-use/server导入、toolschema、链式tool()、widget、聚合 Provider 等）。
2. 确认公共导入与注册签名：对照已安装包的实际导出与签名，而不是参照历史文档或旧示例。
3. 先跑类型生成与类型检查：运行类型生成（如mcp-env.d.ts相关生成）与 typecheck，再解读下游报错——否则错误可能源于过期声明而非真实代码问题。
4. 真实客户端验证：用真实客户端（而非仅靠源码构建）逐一演练每个迁移过的 tool、resource template 与 prompt。
5. 逐项渲染验证每个 View：测试 pending、error、ready 三态、交互、资源（assets）与 CSP 行为。
6. 边界变更验证：当认证、notifications、elicitation 等边界发生变化时，通过受支持的客户端测试这些能力。
7. 打包并从干净消费者导入：当包导出或依赖发生变化时，执行打包并从全新消费者项目中导入验证，排除陈旧缓存或残留产物干扰。

migration.md 特别提示：不要仅因项目现有代码中出现某个 API 就保留它——凡已安装版本中不存在的 API 都不得保留（SKILL.md Guardrails）；也不要仅凭源码构建通过就宣称迁移成功，尤其是类型、包导出、认证或交互行为发生变更的场景。

迁移后的落地建议

完成上述迁移后，建议以create-mcp-use-app@latest生成的新模板为基准对照检查（匹配包版本或 dist-tag，beta/canary/已有版本项目尤其如此），并以skills/mcp-builder/references/verification.md作为上报实现完成前的最终核验依据。迁移不是一次性重命名，而是「先搜索、再确认类型、后逐边界验证」的工程闭环——行为正确、边界验证充分，才是一次成功的迁移。

• 后端
• MCP 服务
• MCP Clients
• AI Agent
• 人工智能