如果你正在使用 Unreal_mcp 让 AI 助手操控 Unreal Engine，那么从 0.5.x 升级到 0.6 是一次真正的「单一 unreal 工具革命」：0.5.30 对外暴露的 23 个独立 MCP 工具，在 0.6 中被永久合并为唯一的unreal网关工具；任何仍按旧方式直接调用工具名的请求，都会收到一张可执行的DIRECT_TOOL_CALL_REMOVED迁移回执。本文用最短路径带你完成迁移，并逐条讲清这次变更背后的动机、回执机制与破坏性改动。

⚠️版本提示：0.6 目前发布在 npm 的beta标签下（unreal-engine-mcp-server@beta），latest仍指向 0.5.30。升级前建议先通读 CHANGELOG.md 中各 beta 版本的⚠️ Migration小节。

从 23 个工具到 1 个工具：这次「革命」改了什么

0.5.30 时代，客户端在tools/list里能看到 23 个独立工具（manage_asset、control_actor、manage_blueprint……），每个工具又挂载几十个 action。对 AI 客户端来说，这意味着数百份工具 schema 同时挤在上下文里——既昂贵，又容易诱发「幻觉式」的错配调用。

0.6 把整个公共面收敛为一个静态的unreal工具：

三个必须知道的结论：

• 这是永久切换，没有开关。TypeScript 侧的MCP_GATEWAY_MODE环境变量与原生侧的Enable Native Gateway（bEnableNativeGateway）项目设置均已被删除，不存在「恢复旧 23 工具列表」的选项。
• 两条链路行为一致。无论走原生 HTTP（Route A，默认端口3000）还是 stdio（Route B），tools/list永远只返回unreal，并抑制tools/list_changed通知。
• 23 个父工具降级为内部路由边界。它们不再出现在客户端列表中，但execute仍接受{tool, action}旧式拼写——旧调用里的工具名和 action 名基本都还能用，只是入口从「直接调工具」变成了「调unreal」。

单一 unreal 工具的 4 个操作：search → describe → execute

0.6 的整个公开面就是unreal工具的 4 个操作，模型按需只加载即将使用的那一份契约，而不是几百份 schema：

典型的一次「召唤点光源」对话，从 0.5 的「猜工具名 + 猜参数」变成三步：

{ "operation": "search", "query": "spawn actor" }

{ "operation": "describe", "tool": "control_actor", "action": "spawn" }

{ "operation": "execute", "tool": "control_actor", "action": "spawn", "params": { "classPath": "/Script/Engine.PointLight", "actorName": "KeyLight", "location": [0, 0, 300] } }

完整契约说明见 docs/gateway-client-guide.md，全部能力的生成式参考清单在 docs/action-reference.generated.md。

直接调用移除：DIRECT_TOOL_CALL_REMOVED 回执如何工作

这是 0.6 唯一的「硬破坏」：任何tools/call的name不是unreal（比如name: "manage_asset"）的请求不再被路由，而是返回一张有界、可复制粘贴执行的迁移回执：

{ "success": false, "operation": "execute", "errorCode": "DIRECT_TOOL_CALL_REMOVED", "tool": "control_actor", "message": "Direct tool calls are removed. Call the 'unreal' gateway with operation 'execute' to run 'control_actor.spawn'.", "nextCall": { "operation": "execute", "tool": "control_actor", "action": "spawn", "params": { "classPath": "/Script/Engine.PointLight" } } }

回执里的nextCall只下钻一层，规则非常克制：

其中params的迁移规则：把旧调用里嵌套的params包装摊平（顶层键优先），再剔除action、subAction、params、operation四个控制字段，只留下真正的业务参数。把这张nextCall原样通过unreal跑一遍，迁移即完成——这也是官方为模型准备的「自愈」通道。

实现代码可对照阅读：TypeScript 侧在 direct-call-migration.ts，原生传输侧的等价实现在 McpNativeGatewayDirectCallMigration.cpp，两条链路保证同一形状的回执。

迁移三步走：从 0.5.x 旧调用到 0.6 新调用

1. 换服务器：客户端配置改用npx -y unreal-engine-mcp-server@beta启动（务必保留@beta，否则装到 0.5.30，与 0.6 插件不匹配），传入UE_PROJECT_PATH，并确保 Node.js ≥ 20.19（0.6 不再支持 Node 18）。
2. 换插件：删除Plugins/McpAutomationBridge，解压EngineWire-plugin-<version>.zip到其位置（0.6 中插件已更名为EngineWire）；.uproject里若写的是旧名McpAutomationBridge，请改为EngineWire——旧名下的设置项[/Script/McpAutomationBridge.McpAutomationBridgeSettings]在 0.6 中仍能被加载，无需手工搬移。
3. 改调用点：把tools/call中name: "manage_asset"之类的旧调用，改成对unreal的调用：先search找到能力，再describe拿契约，最后execute执行。不确定具体该调哪个时，直接重发回执里的nextCall即可。

0.6 破坏性变更检查清单

除了直接调用移除，以下变更同样会影响 0.5.x 时代的客户端与脚本：

验证迁移是否成功

• 插件加载后，编辑器状态栏应显示MCP :3000 (0)；客户端连上后括号里的数字 +1。
• 让助手执行「列出当前关卡的 actor」「在视图口截图」这类请求——它应能通过一次search找到能力并返回真实结果，而不再是DIRECT_TOOL_CALL_REMOVED。
• 若某次调用仍返回该回执，检查两点：客户端是否仍在直接以旧工具名发起tools/call；运行的服务器是否为@beta版本。
• 服务端开发可跑npm run test:unit与npm run registry:check验证契约与生成物一致，能力记录目录 src/tools/catalog/capabilities/records/ 是唯一事实来源，所有*.generated.*文件都由此生成，切勿手改。

参考资料与关键文件

• 📖 README.md —— 0.6 线总览、快速开始与unreal工具说明
• 📡 docs/gateway-client-guide.md —— 网关契约；「Deprecation and removal behavior」一节专讲DIRECT_TOOL_CALL_REMOVED
• 📋 docs/action-reference.generated.md —— 全部能力、副作用、scope 与 consent 的生成式清单
• 🔐 docs/security-and-receipts.md —— 授权拒绝码、consent 与回执安全
• 🧭 docs/protocol.md —— 两条传输链路、协议版本协商与取消机制
• 📝 CHANGELOG.md —— 0.6.0-beta-a 起每个 beta 的 Migration 小节
• 🏗️ plugins/EngineWire/ —— 引擎侧 C++ 插件源码
• ⚙️ scripts/generate-canonical-registry.ts —— 能力记录到生成契约、原生分片与 action reference 的生成流水线

迁移的本质可以一句话概括：入口从「23 个工具名」收敛为「1 个unreal工具」，而旧名字并没有死——它们作为内部路由边界和可解析别名继续工作，回执会替你走完剩下的路。