dsh-unity-mcp

让 DSH 里的 AI Agent 直接操控 Unity 编辑器 —— 安装即用，34 个工具覆盖游戏开发全流程。 One-shot integration that gives DSH agents direct control over the Unity Editor.

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

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

本插件是 CoderGamester/mcp-unity（MIT）在 DeepSeek Harness 上的封装：内置 mcp-unity 1.5.0 服务端（兼容上游 1.5.0 的强制令牌认证），自动定位 Unity 项目并注入令牌，安装即用，无需手动编辑 cordis.patch.yml。

工作原理

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

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

Related MCP server: Unity MCP Server

三步上手（TL;DR）

1. dsh plugin --profile web add git+https://github.com/1shuqing/dsh-unity-mcp-authfix.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 次）

• 令牌认证兼容（v1.2）：内置 mcp-unity 1.5.0 客户端，自动发现 Unity 项目并把 MCP_UNITY_SETTINGS_PATH / MCP_UNITY_AUTH_TOKEN_PATH 注入服务端进程，原生支持 上游 1.5.0 网桥的 per-project token 认证（1.4.x 无认证客户端会全部超时）

• 中文文档：本 README 即完整使用说明

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

环境要求

安装

第 1 步：安装 DSH 插件

dsh plugin --profile web add git+https://github.com/1shuqing/dsh-unity-mcp-authfix.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）
    # v1.2：Unity 项目根（含 ProjectSettings/McpUnitySettings.json）。留空则自动
    # 沿插件进程工作目录向上发现——从 Unity 项目目录启动 DSH 时通常无需配置；
    # DSH 以其他目录启动时建议显式指定，否则无法自动注入令牌路径。
    projectPath: 'D:/path/to/unity-project'
    env:                       # 传给服务端进程的额外环境变量
      UNITY_PORT: '8090'       # 自定义 Unity 网桥端口（默认 8090，unity_status 同步探测此端口）
      UNITY_HOST: 'localhost'  # 自定义网桥地址（默认 localhost）
      # v1.2：以下三项一般由插件按项目自动注入；需要手动覆盖时在此设置（优先级更高）：
      # MCP_UNITY_SETTINGS_PATH: 'D:/path/to/unity-project/ProjectSettings/McpUnitySettings.json'
      # MCP_UNITY_AUTH_TOKEN_PATH: 'D:/path/to/unity-project/Library/McpUnity/bridge-token'
      # MCP_UNITY_AUTH_TOKEN: '<64位hex令牌，与 MCP_UNITY_AUTH_TOKEN_PATH 二选一>'
    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: <DSH 自带 node 的可执行路径，如 D:\...\resources\app\node_modules\node\bin\node.exe>
        args:
          - <本插件 vendored 服务端路径：.../node_modules/dsh-unity-mcp/vendor/mcp-unity-server/build/index.js>
        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：unity_status 显示网桥可达，但所有 Unity 工具一直超时/401？ A：这是 mcp-unity 1.4.x ↔ 1.5.0 版本错配的典型症状：上游 1.5.0 起网桥强制 per-project 令牌认证（HTTP Basic mcp-unity:<token>），1.4.x 无认证客户端每次 WebSocket 握手都被 401 拒绝，之后陷入重连排队直到调用超时。修复：

1. 把本插件升级到 v1.2.0（内置 1.5.0 客户端）并重启 DSH Web/profile 进程；

2. 确认插件能找到项目：profile cordis.patch.yml 给 unity-mcp 设 projectPath，或从 Unity 项目目录启动 DSH（自动向上发现）；

3. 令牌缺失/失效时：打开 Unity → Tools > MCP Unity > Server Window 重新生成令牌/客户端配置，再重启 DSH。

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。

工具清单（部分）

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

许可证

• 本封装：MIT

• 内置的 mcp-unity 服务端：MIT © 2024-2025 CoderGamester

• Unity 侧网桥包由上游仓库分发，随你的 Unity 项目安装

致谢

• thyeff/dsh-unity-mcp — 本修复版的基础（v1.1.0）

• CoderGamester/mcp-unity — 本插件封装的核心

• DeepSeek Harness — 插件宿主