thyeff/dsh-unity-mcp

dsh-unity-mcp

让 DSH 里的 AI Agent 直接操控 Unity 编辑器 —— 安装即用，34 个工具覆盖游戏开发全流程。
一次性集成，让 DSH Agent 直接控制 Unity 编辑器。

简体中文文档 · 功能特性 · 安装 · 进阶玩法 · 常见问题

让 DeepSeek Harness（DSH）里的 AI Agent 直接操控 Unity 编辑器：一键安装本插件后，Agent 即可获得 34 个 Unity 工具，覆盖游戏开发全流程。

本插件是 CoderGamester/mcp-unity（MIT）在 DeepSeek Harness 上的封装：内置 mcp-unity 1.4.0 服务端，安装即用，无需手动编辑 cordis.patch.yml。

工作原理

DSH Agent ──MCP(stdio)──> dsh-unity-mcp ──> 内置 mcp-unity 服务端 ──TCP :8090──> Unity 网桥包（编辑器进程内）

DSH 侧安装本插件、Unity 侧在项目里安装网桥包（com.gamelovers.mcp-unity），中间链路全部自动建立，无需手动配置。

三步上手（TL;DR）

1. dsh plugin --profile web add git+https://github.com/thyeff/dsh-unity-mcp.git
2. Unity 项目的 Packages/manifest.json 加入网桥包（详见安装）
3. 打开 Unity 编辑器，对 Agent 说：「查看当前场景层级」

功能特性

- 零配置接入：安装插件即自动注册 MCP 服务端，无需手写任何配置
- 34 个 Unity 工具：场景管理、GameObject 增删改查、组件/材质操作、Prefab、菜单执行、测试运行、控制台日志读取等
- 网桥诊断（v1.1）：本地工具 unity_status 先探后调——TCP 探测 Unity 网桥是否在线，Unity 未启动时 Agent 秒级知道，不再干等 60 秒超时
- 配置校验（v1.1）：超时等数值配置带 schema 校验，非法值在加载期直接报错，不会悄悄注销工具
- 自动重连：Unity 编辑器重启后自动恢复连接（指数退避，最多 10 次）
- 中文文档：本 README 即完整使用说明

工具命名空间为 unity，Agent 内调用形如 mcp__unity__create_scene、mcp__unity__update_gameobject 等；另有本地诊断工具 unity_status（不带 mcp__ 前缀）。

环境要求

| 组件 | 要求 |
|------|------|
| DeepSeek Harness | DSH Desktop 或 DSH CLI（核心包 0.1.1-rc.2 及以上） |
| Unity | 2022.3 及以上（推荐 Unity 6） |
| Node.js | 无需单独安装（使用 Harness 自带运行时） |

安装

第 1 步：安装 DSH 插件

dsh plugin --profile web add git+https://github.com/thyeff/dsh-unity-mcp.git

或在 DSH 网页的插件市场（若已收录）中搜索 dsh-unity-mcp 安装。

第 2 步：在 Unity 项目中安装网桥包

打开你的 Unity 项目根目录下的 Packages/manifest.json，在 dependencies 中加入：

{
"dependencies": {
"com.gamelovers.mcp-unity": "https://github.com/CoderGamester/mcp-unity.git"
}
}

保存后回到 Unity 编辑器，等待包解析完成（也可以通过 Package Manager → Add package from git URL 粘贴同样的地址）。

第 3 步：验证

1. 确保 Unity 编辑器已打开且加载了项目（网桥运行在编辑器进程内，监听 8090 端口）
2. 在 DSH 中新建会话，对 Agent 说：

先检查 Unity 网桥状态，再看当前场景层级

Agent 先调 unity_status（网桥可达即接入成功），再调 mcp__unity__get_scenes_hierarchy 返回场景树。

可选配置

在 profile 的 cordis.patch.yml 中可覆写本插件行为（一般无需配置）。本插件以 id: unity-mcp 插入，patch 需按 id 匹配：

- id: unity-mcp
config:
serverName: unity          # MCP 工具命名空间，默认 unity
toolCallTimeoutMs: 60000   # 单次工具调用超时，默认 60 秒（必须 > 0）
probeTimeoutMs: 2000       # unity_status 探测网桥的超时，默认 2 秒（必须 ≥ 100）
env:                       # 传给服务端进程的额外环境变量
UNITY_PORT: '8090'       # 自定义 Unity 网桥端口（默认 8090，unity_status 同步探测此端口）
UNITY_HOST: 'localhost'  # 自定义网桥地址（默认 localhost）
reconnect:                 # 重连策略（默认指数退避，1s 起、30s 封顶、10 次）
enabled: true
maxAttempts: 10

非法值（如 toolCallTimeoutMs: 0）会在插件加载期被 schema 直接拒绝并报错，而不是让工具静默失效。

patch 是 profile 的 cordis.patch.yml 顶层列表（不要包在 patches: 里）；示例中的 serverName 等均可省略，省略即用默认值。
进阶：与 dsh-mcp-lens 渐进披露搭配（省 token）

默认安装后，34 个 Unity 工具会以 mcp__unity__ 常驻在每个请求的工具清单里——方便，但对 token 敏感的长对话是一笔持续的「常驻税」。

如果在意成本，可以用渐进披露 MCP 网关 dsh-mcp-lens（mcp_search / mcp_call 两个工具）接管 unity 服务端：模型面从 34 个工具收敛到 2 个，用到才披露精确 schema（约省 95% 的相关 schema 字节）。此时不再安装本插件作为 bundle（避免与 mcp-lens 双重注册同名工具），仅把本仓库的 vendored 服务端作为依赖保留：

profile 的 cordis.patch.yml
- id: mcp-lens
config:
servers:
- name: unity
transport: stdio
command:
args:
-
env:
ELECTRON_RUN_AS_NODE: '1'
cachePath: !!js dshHomePath('mcp-lens/catalog.json')
allowTools:
- 'unity/'

两种方式二选一：
- 直连（本插件默认）：零配置、工具即用，适合不在乎 token 或 Unity 工具用得频繁的场景
- 渐进披露（mcp-lens）：常驻 2 工具，适合长对话/多 MCP server、Unity 工具低频使用的场景

常见问题（FAQ）

Q：工具调用报错「连接失败 / ECONNREFUSED」？
A：Unity 编辑器没有打开，或项目未安装网桥包。网桥跑在编辑器进程里——调用任何 Unity 工具前必须先打开 Unity 编辑器并加载项目。让 Agent 先调 unity_status 探测，网桥不可达时它会直接告诉你原因，不必靠超时试错。

Q：8090 端口被占用？
A：关闭占用进程，或在 Unity 网桥设置中更换端口后，通过上面 cordis.patch.yml 的 env 传 UNITY_PORT 对应端口（unity_status 会同步探测该端口；服务端亦会读 Unity 项目的 ProjectSettings/McpUnitySettings.json，以 mcp-unity 上游文档为准）。

Q：如何确认 Agent 真的连上了 Unity？
A：让 Agent 调用 mcp__unity__get_scenes_hierarchy；若返回了真实的场景层级（Main Camera 等）即连通。

Q：与手动配置 @deepseek-ai/dsh-mcp-client 有何区别？
A：效果相同。区别在于本插件内置服务端与默认配置，免去手写 patch；注意不要同时保留手动配置的同名 serverName（unity）条目，否则插件加载会报命名空间冲突——二选一即可。

开发与测试（Development & testing）

仓库自带烟雾测试：对安装副本（或源码 vendor）发起真实 stdio 握手，列出注册的 Unity 工具，用于快速验证服务端可用性与工具完整性。

基于源码 vendor 测试（不依赖已安装副本）
node scripts/smoke.mjs vendor

基于 DSH 中的安装副本测试（先确认已安装本插件）
node scripts/smoke.mjs

仓库 CI（.github/workflows/ci.yml）会校验 package.json、bundle 补丁、入口语法与打包内容。源码结构、升级内置服务端的方法见 CONTRIBUTING.md，变更记录见 CHANGELOG.md。

工具清单（部分）

| 类别 | 工具示例 |
|------|---------|
| 场景 | create_scene / load_scene / save_scene / get_scenes_hierarchy |
| GameObject | update_gameobject / select_gameobject / move_gameobject |
| 资产 | add_asset_to_scene / create_prefab / update_component |
| 质量 | run_tests / get_console_logs / send_console_log |

完整 34 个工具以运行时注册为准，可在会话中问 Agent：「列出所有 unity 工具」。

许可证

- 本封装：MIT
- 内置的 mcp-unity 服务端：MIT © 2024-2025 CoderGamester
- Unity 侧网桥包由上游仓库分发，随你的 Unity 项目安装

致谢

- CoderGamester/mcp-unity — 本插件封装的核心
- DeepSeek Harness — 插件宿主