虚幻引擎 MCP 接入 yeee-eh/dsh-unreal-engine

dsh-unreal-engine

把 Unreal Engine 5.8+ 的 MCP 服务接入 DeepSeek Harness —— 在 DSH 的设置里一键探测并配置端点，装上、接上、就能用。

DSH agent ──[dsh-mcp-client]──> UE 5.8 内置 MCP server ──> 编辑器 DSH 官方自带 Epic 官方自带 ↑ 本插件：设置页 + 端点探测

命令里的两个占位符

本文档的命令用到两个变量，先设好再用：

| 占位符 | 含义 | 怎么设 |
| $env:DSH_HOME | DSH 的配置根目录，通常 C:\Users\<你的用户名>\.dsh | 见下 |
| $RepoRoot | 本插件源码目录（从 GitHub 克隆后的仓库目录） | 见下 |

DSH_HOME：普通 PowerShell 里它可能是空的 —— DSH 只在自己的子进程里注入它
if (-not $env:DSH_HOME) { $env:DSH_HOME = "$env:USERPROFILE\.dsh" }

RepoRoot：把下面这行改成你克隆下来的目录 $RepoRoot = 'C:\path\to\dsh-unreal-engine'

两个变量都只对当前终端会话有效。想永久生效就写进用户环境变量。

它解决什么问题

不装本插件时，接入 UE 要手写这段 YAML（改 cordis.patch.yml）：

#- insert:
- id: mcp-unreal
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: unreal
transport: streamable-http
url: 'http://127.0.0.1:8000/mcp'
...

而且端点写错、端口被占、编辑器没开时，得到的只是一个空工具列表，没有线索。

装本插件后，这些变成一个设置页：自动探测，探不到就手动粘贴日志行。

安装(建议直接让dsh帮你安装，省时省力。文档文件里面有很多dsh安装时亲自踩过的坑，已总结出文字，方便ai查阅)

本插件走 bundle 频道（和 dshmarket、dsh-chat-manager、dsh-better-sidebar 一样）：插件自己带 cordis.patch.yml 负责挂载，你的 ~/.dsh/cordis.patch.yml 保持为空。

这是卸载能安全的前提 —— 卸载不需要动用户文件。

1. 让包能被 profile 解析到

cd $env:DSH_HOME\profiles\web
pnpm add file:$RepoRoot

或者（不想让 pnpm 改 package.json 时）建一个目录连接：

New-Item -ItemType Junction
-Path "$env:DSH_HOME\profiles\node_modules\dsh-unreal-engine"
-Target '$RepoRoot'

⚠️ 放 profiles/node_modules（共享层），不是 profiles/web/node_modules。
原因见下面「为什么放共享层」。

2. 登记到 profile 的 bundles 列表

编辑 $env:DSH_HOME\profiles\web\package.json，把包名加进 dsh.profile.bundles：

"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"...",
"dsh-unreal-engine" ← 加这一行 ], "patchReload": "live" } }

这一步是关键：只有出现在 bundles 里，DSH 才会应用本包自己的 cordis.patch.yml。

3. 确认 home 补丁是空的

$env:DSH_HOME\cordis.patch.yml 应该只有 []。

如果里面还有 unreal-engine / mcp-unreal 的 insert 块，删掉它们 ——否则同一组 id 会出现两次，加载失败。

4. 校验 + 重启

dsh --profile sdk # 能安静退出（exit=0、无输出）= 插件树能加载

然后重启 DSH。

卸载

因为走的是 bundle 频道，卸载不需要手动改任何 YAML：

1. 从 bundles 列表移除

$env:DSH_HOME\profiles\web\package.json → 删掉 "dsh-unreal-engine" 那一行。

2. 移除包

cd $env:DSH_HOME\profiles\web
dsh plugin --profile web remove dsh-unreal-engine

（dsh plugin 只是把参数转发给 pnpm，所以 pnpm remove dsh-unreal-engine 等价。）

如果当初用的是 junction，直接删掉它：

Remove-Item "$env:DSH_HOME\profiles\node_modules\dsh-unreal-engine" -Force
Remove-Item "$env:DSH_HOME\profiles\web\node_modules\dsh-unreal-engine" -Force -EA SilentlyContinue

3. 清理插件数据（可选）

Remove-Item "$env:DSH_HOME\unreal-engine.json" -Force -EA SilentlyContinue

4. 重启 DSH

分发给别人

打包（你自己做）

cd $RepoRoot
npm pack --pack-destination ..\dist

产出 dsh-unreal-engine-0.1.0.tgz（约 30 KB）。把它发给对方即可。

打包前建议跑一遍：npm test 和 node lib/js-expr-probe.mjs。

对方怎么装

假设对方把 .tgz 放在 D:\Downloads\：

1. 装包
cd $env:DSH_HOME\profiles\web
pnpm add D:\Downloads\dsh-unreal-engine-0.1.0.tgz

2. 登记到 bundles（这一步目前需要手动）编辑 $env:DSH_HOME\profiles\web\package.json，把包名加进 dsh.profile.bundles

3. 重启 DSH

关于第 2 步为什么不能省：DSH 有个 reconcileProfilePlugins 函数，会读安装包里的 dsh.bundle 声明并自动登记 bundles，但在 0.1.5-rc 这套已安装的版本里它从未被调用 （只有定义和导出）。所以 bundles 那一行必须手动加。

官方 CLI 的 dsh plugin --profile web add <包> 会做这个登记，但要求 dsh 在 PATH 上 —— 从 npx 缓存启动的安装环境通常没有。
用绝对路径可以绕过： & "$env:LOCALAPPDATA\npm-cache\_npx\<hash>\node_modules\.bin\dsh.ps1" plugin --profile web add <包>

⚠️ 对方的环境必须有 MCP SDK

本插件不打包 SDK，而是复用 DSH 自带的。探测功能需要能解析到 @modelcontextprotocol/client（新版）或 @modelcontextprotocol/sdk（旧版）。

解析器（lib/mcp-client-loader.mjs）会依次尝试：
1. 插件自己所在位置（Node 常规向上查找）
2. $env:DSH_HOME/profiles 与 $env:DSH_HOME
3. DSH 自己的安装目录（从 process.argv[1] 定位，覆盖 npx 缓存运行的情形）
4. 从 node 可执行文件位置向上找 node_modules

全失败时它会列出每一次尝试的具体原因，而不是甩一个 MODULE_NOT_FOUND。

所以如果对方探测报「无法解析 MCP 客户端模块」，把那段诊断贴出来就能定位。

为什么放共享层（profiles/node_modules）

profiles/web/node_modules 看起来更自然，但会出问题：

- bundle 是按 profile 解析的
- 而同一个包可能被多个 profile 引用（web / sdk / …）
- 放 web/node_modules 时，用 dsh --profile sdk 启动会报 Cannot find package 'dsh-unreal-engine'（已实测踩过）

放 profiles/node_modules 则所有 profile 都能解析到。

改端点端口

MCP 端点的 URL 用 !!js 读环境变量，缺省回落到 UE 默认端口：

url: !!js "process.env.DSH_UNREAL_MCP_URL || 'http://127.0.0.1:8000/mcp'"

所以改端口不用编辑 YAML —— 设一个环境变量即可：

$env:DSH_UNREAL_MCP_URL = 'http://127.0.0.1:8123/mcp'
dsh --profile web

⚠️ Loader 求值 !!js 是同步的，作用域是 new Function('ctx','expr',...)，没有 import。所以绝不能写 !!js "(await import('file:///...'))..." —— 会直接报错。
只写同步表达式（process.env.xxx 这类）。

使用

打开 设置 → 虚幻引擎。

| 操作 | 说明 |
| 自动探测并保存 | 从 8000 端口起逐个尝试真正的 MCP 握手（不只是探端口），找到就保存 |
| 手动输入 | 探测失败时用。粘贴 UE Output Log 整行，或直接填端口号 |
| 结果区 | 显示 Toolset 数量、meta 工具名、协议版本 —— 都是真实握手得到的 |

手动输入能识别哪些格式

LogModelContextProtocol: Starting MCP server on port 8000 (override with -ModelContextProtocolPort=N)
LogHttpListener: Created new HttpListener on 127.0.0.1:8000
http://127.0.0.1:8000/mcp
8000

全部会收敛到 http://127.0.0.1:8000/mcp。

⚠️ 改完要重启 DSH

dsh-mcp-client 在启动时连接 MCP 服务器并注册工具，没有运行时重配接口。
保存设置后需要重启 DSH 才生效。

UE 侧准备（一次性）

1. UE 编辑器 → Edit → Plugins → 搜索 ModelContextProtocol → 启用 → 重启编辑器
2. Window → Output Log，底部输入框执行： ModelContextProtocol.StartServer

3. 确认日志出现 Created new HttpListener on 127.0.0.1:8000

架构

dsh-unreal-engine/
├── lib/
│ ├── index.js 宿主半：/unreal-engine/* 路由 + 配置持久化 │ ├── endpoint.mjs 端点解析（纯函数） │ ├── probe.mjs MCP 握手探测（流式 HTTP） │ ├── mcp-client-loader.mjs MCP SDK 解析（兼容新旧包名 + 多位置回退） │ ├── client-bundle.test.mjs 客户端 bundle 契约测试（9 个） │ ├── config.test.mjs 配置持久化测试（9 个） │ ├── endpoint.test.mjs 端点解析 / 探测测试（15 个） │ └── js-expr-probe.mjs !!js 求值作用域探针（4 项，可执行） ├── client/ │ └── client.js 浏览器半：设置页（settings.section） ├── tools/ │ └── ue5-dsh-doctor.mjs 连通性诊断脚本（5 段链路，零依赖） ├── skills/ │ └── unreal-mcp/ UE 操作规范（需手动拷到 $env:DSH_HOME\skills\） │ ├── SKILL.md │ └── references/ │ ├── setup.md │ └── troubleshooting.md ├── cordis.patch.yml 本插件自己的挂载补丁（bundle 频道） ├── CHANGELOG.md 更新日志 ├── MIGRATION.md junction → 标准安装的迁移手册 ├── RECOVERY.md 应急恢复卡 ├── LICENSE MIT（纯正文，供 GitHub 识别） └── NOTICE.md 第三方组件归属 / UE EULA 注意 / 商标

MCP SDK 的解析为什么要单独一个文件

DSH 的 MCP 桥接对 SDK 的依赖改名过一次：

| | 包名 | 入口 |
| 旧 | @modelcontextprotocol/sdk | /client/index.js、/client/streamableHttp.js |
| 新（v2） | @modelcontextprotocol/client | .、/stdio（另拆出 core） |

本插件的探测功能复用同一份 SDK，但不能假设用的是哪一代、装在哪里 ——它可能被提升到 profile 的 node_modules，也可能只存在于 DSH 自己的安装目录里（从 npx 缓存运行的情形）。

mcp-client-loader.mjs 按「包名 × 子路径 × 解析根」逐个尝试，覆盖四个位置：插件自身、$env:DSH_HOME、DSH 自己的安装目录（从 process.argv[1] 定位）、
node 可执行文件位置。全失败时列出每次尝试的具体原因，而不是甩一个 MODULE_NOT_FOUND。

配置为什么落在 JSON 文件而不是 settings.yaml

浏览器侧的 settings 文档在启动时读不到 —— 而 MCP 客户端恰好在启动时连接。
所以设置页把端点写进 $env:DSH_HOME/unreal-engine.json，宿主进程能直接读。

MCP 行的 url 用 !!js 读环境变量（DSH_UNREAL_MCP_URL），缺省回落到 UE 默认端口：

url: !!js "process.env.DSH_UNREAL_MCP_URL || 'http://127.0.0.1:8000/mcp'"

⚠️ 已知缺口：设置页保存的值和这一行目前不联动。
探测到非 8000 的端口时，需要手动设 DSH_UNREAL_MCP_URL。
这次的取舍是为了绕开「!!js 求值是同步的、作用域里没有 import」。

已知限制

| 限制 | 说明 |
| 改设置需重启 DSH | MCP 客户端只在启动时连接，没有运行时重配接口 |
| 设置值 ←→ mcp 行不联动 | 见上；探测到非默认端口需设环境变量 |
| bundles 需手动登记 | DSH 的 reconcileProfilePlugins 本该自动做，但当前版本从未调用它 |
| 客户端渲染未在浏览器实机验证 | 有 boot graph 证据 + 契约测试，但没在浏览器里点过 |
| 只支持 UE 5.8+ | 官方 MCP 是 5.8 引入的；5.3–5.7 需改用第三方 stdio server |

测试与诊断

cd $RepoRoot
npm test # 33 个单元测试
npm run probe # !!js 求值作用域探针（4 项）
npm run doctor # 连通性诊断（5 段链路）

单元测试覆盖：
- 端点解析 —— UE 真实日志行、URL 规范化、候选端口生成、越界拒绝
- 探测 —— 失败归类（ECONNREFUSED / 超时）、自动扫描
- 配置持久化 —— 读写、损坏容错、增量更新、临时文件不残留
- 客户端 bundle 契约 —— 注册 id 必须等于包名、顶层无 import/export、不引用 node: 内置模块、exports["./client"] 指向真实文件

npm run doctor 会依次检查：
1. Node 版本（需 >= 20）
2. UE 端点可达性
3. MCP 握手（协议版本、会话 id）
4. 工具枚举 + Toolset 注册表（防止「工具数恒为 3」造成的假通过）
5. DSH 配置落位（包是否安装、bundles 是否登记、home 补丁是否干净）

注意：doctor 需要 UE 已开并执行过 ModelContextProtocol.StartServer。
第 5 项与 UE 无关，任何时候都能跑。

UE 操作规范（Skill）

skills/unreal-mcp/ 是给模型看的操作规范：渐进式工具发现的三步法、风险分级、非幂等操作的重试纪律、安全边界。

⚠️ DSH 不会自动安装它 —— 技能只从固定路径扫描，且不扫 node_modules： <项目根>/.dsh/skills、<项目根>/.agents/skills、$env:DSH_HOME/skills、~/.agents/skills。

手动拷过去（注意只扫一层）： Copy-Item -Recurse "$RepoRoot\skills\unreal-mcp" "$env:DSH_HOME\skills\unreal-mcp"

⚠️ 安全

UE 官方 MCP 默认只监听 loopback，且没有任何鉴权。 任何能访问该端口的人都能完全控制你的编辑器。

- 绝不要暴露到公网或局域网，不要设 0.0.0.0
- DSH 的审批门禁是唯一护栏，不要关闭

许可证

本包以 MIT 发布 —— 见 LICENSE。

不包含任何 Epic Games 或 DeepSeek 的代码。第三方组件归属、Unreal Engine EULA 相关注意事项与商标声明见 NOTICE.md。