SimpleMcpServer

让 AI 代理（Claude Code、OpenCode 等）通过 MCP 协议直接操作 Unity 场景。
必须配合 SimpleMCPBridge（Unity 侧桥接包）使用。

架构

AI Agent (Claude Code / OpenCode)
    │  MCP (stdio)
    ▼
SimpleMcpServer (Node.js/TypeScript)   ← 本仓库
    │  WebSocket
    ▼
SimpleMCPBridge (C#)                   ← 另一个仓库，需单独 clone 到 Unity Assets/
    │
    ▼
Unity Editor / Runtime

• SimpleMcpServer（本仓库）— 处理 MCP 协议，注册工具，转发请求到 Unity

• SimpleMCPBridge（companion repo）— 在 Unity 内运行的 WebSocket 客户端，执行场景操作

Related MCP server: Agent Bridge for Unity

前置条件

• Node.js 22+

• Unity 2022.3+ — 项目已安装 SimpleMCPBridge 包

• npm — 随 Node.js 一起安装

验证 Node.js：

node --version   # 应输出 v22.x.x 或更高
npm --version    # 应输出 10.x.x 或更高

安装与设置

自动安装（推荐）

双击 setup.bat。

手动安装

cd SimpleMcpServer
npm install
npm run build

使用

前置：安装 SimpleMCPBridge

cd YourUnityProject/Assets/
git clone https://github.com/redcool/SimpleMCPBridge_Unity.git SimpleMCPBridge

1. 启动 Unity Bridge（prefab 方式）

1. 用 Unity 打开项目

2. 将 Assets/SimpleMCPBridge/Prefabs/MCPBridge.prefab 拖入场景（或给任意 GameObject 添加 MCPBridge 组件）

3. 选中该对象，Inspector 顶部即显示连接状态（● Connected / ○ Disconnected）、ws://ip:port、Bridge ID 与 Connect / Disconnect 按钮

4. Server IP / Port 默认 127.0.0.1:45678，如需修改见下方 bridge-config.json

Bridge 通过 [ExecuteAlways] 在 Edit Mode、Play Mode、打包运行三态下均工作；默认 isAutoReconnect=true，场景加载、进出 Play Mode、脚本重编译（domain reload）后自动重连，无需手动操作。

bridge-config.json（可选，默认即可用）

Bridge 启动时自动加载配置——配置文件不存在时，首次自动从包内 Resources/bridge-config.json 拷贝生成（已存在则不覆盖），改完需重启生效：

{ "serverIp": "127.0.0.1", "serverPort": 45678, "encryptionKey": "" }

• serverIp/serverPort — 与 Server 侧 config.json 的 ip/port 对应

• encryptionKey — 与 Server 侧 encryptionKey 一致时启用 AES-256-CBC 载荷加密；空 = 透传

• methodBlocklist / methodAllowlist（可选）— scene.call_component_method 权限控制，详见桥 README

2. 启动 MCP Server

推荐：在独立 cmd 窗口运行（不占用 AI 工具的终端）

# 在 PowerShell 或 cmd 中执行：
Start-Process -FilePath "cmd.exe" -ArgumentList "/K", "cd /d path\to\SimpleMcpServer && start.bat"

或者在文件管理器双击 start.bat 也会弹出 cmd 窗口。

# 编译 + 启动（直接在当前终端）
start.bat

# 跳过编译（代码未改时）
start-quick.bat

连接成功输出：

[Server] Bridge connected
[Server] Registered N tool(s) from bridge [ID: xxxx]
[Server] Ready (ws://127.0.0.1:45678)

3. 配置 AI 代理

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["path/to/SimpleMcpServer/dist/index.js"]
    }
  }
}

4. 验证连通性

node tests/test-e2e.cjs

预期输出：*** TEST PASSED ***

对象寻址

Unity 侧的场景工具同时支持两种方式定位 GameObject：

解析优先级：instanceId > path。get_hierarchy 和 get_objects 的返回值同时包含两者。

可用工具

工具由 Unity Bridge 通过 register_tools 动态注册，数量随桥接平台/条件编译变化（当前 Editor 桥实测 127 个桥工具 + 服务端合成 2 个 = 129 个）。下表按类别简述常用工具；完整清单见 SimpleMCPBridge 仓库 README。

场景工具（SceneHandler）

资源工具（AssetHandler，仅 Editor）

录制工具（RecordingHandler）

保存位置：

• PC: 项目根目录 VideoRecord/（Assets 同级）

• Android/iOS: app 临时目录 {temporaryCachePath}/VideoRecord/

编辑器工具

PlayerPrefs 工具（PlayerPrefsHandler）

UI Toolkit 工具（UIToolkitHandler）

配置

编辑 config.json（不存在时首次启动自动从 config.json.template 复制生成，见「首次运行」）。完整字段：

{
    "ip": "0.0.0.0",
    "port": 45678,
    "encryptionKey": "",
    "encryption": false,
    "evalEnabled": true,
    "allowedIps": ["127.0.0.1", "::1"],
    "llm": { "enabled": true, "provider": "agnes", "baseUrl": "https://apihub.agnes-ai.com/v1", "apiKey": "YOUR_API_KEY_HERE", "model": "agnes-2.0-flash", "temperature": 0.7, "maxTokens": 1024 }
}

• ip/port：监听地址与端口。本地 127.0.0.1，云端 0.0.0.0

• encryption/encryptionKey：可选 AES-256-CBC 载荷加密（替代 TLS/wss），Server 与 Bridge 配置需一致；空密钥 = 透传

• evalEnabled：editor.eval 工具开关（默认 true，以用户方便为先 —— 开发调试/快速原型/补救缺口工具时即时可用）。false 时 tools/list 不暴露 editor.eval 给 agent。风险：eval 执行任意 C# = 完全机器控制，任何能调 /rpc 的 AI 可执行任意代码（读写文件、删资产、网络访问）；不可信环境（共享机器/公网暴露）务必关闭或扩 allowedIps 白名单。Editor 侧另有 EditorPrefs SimpleMCPBridge_EvalEnabled 二次 gate，见桥 README「Editor Eval 开关与安全说明」

• allowedIps：IP 白名单（本版本新增）——只放行白名单内的客户端调用 HTTP /rpc、/sse、/mcp 端点，其余返回 403；默认 ["127.0.0.1","::1"] 仅本机；WebSocket 与 /ab 资源端点不受此限制。配置缺失时自动从 config.json.template 复制生成 config.json（首次启动自动创建，见「首次运行」）；字段缺失/为空数组/非数组时回退到默认 ["127.0.0.1","::1"]（仅本机）

• llm：LLM 配置（apiKey 用环境变量 LLM_API_KEY 覆盖更安全；config.json 已被 .gitignore 排除，勿提交真实 key）

开发

npm run dev           # tsx 监听模式
node tests/test-e2e.cjs  # E2E 测试

# 目录结构
src/
├── index.ts           # 入口（启动 server）
├── server.ts          # WS Server + MCP handlers（核心）
├── bridgeState.ts     # bridge 连接状态/路由（last-registration-wins、failover）
├── ab.ts              # AssetBundle 上传/部署端点
├── crypto.ts          # AES-256-CBC 载荷加密（#ENC# 前缀）
├── config.ts          # config.json 加载（缺失时从 template 生成）
├── llm.ts             # LLM 代理（ai_request/ai_response）
├── logger.ts          # 日志（stderr + server.log，脱敏）
├── tools.ts           # 服务端合成工具（bridge.list / bridge.call）
└── types.ts           # 类型定义
tests/
├── test-e2e.cjs           # E2E 测试（initialize + tools/list + get_hierarchy）
├── test-playmode-cycle.cjs # Play Mode 循环测试（进出播放验证 bridge 自动重连）
└── auto-test-android.ps1  # Android 全流程自动化测试

故障排查

"WebSocket server error: listen EADDRINUSE" → 端口被占用，杀掉残留进程：

Get-Process -Name "node" | Stop-Process -Force

"Unity not connected" → Unity 没打开，或 SimpleMCPBridge 没启动

Bridge 进出 Play Mode 后断连 → 确认 Unity 菜单 Edit → Project Settings → Editor → Enter Play Mode Settings 中 Reload Domain 已开启。Bridge 依赖 [InitializeOnLoad] 在 domain reload 后重新订阅 EditorApplication.update。如关闭 Domain Reload，Bridge 连接会在 Play Mode 期间保持，但退出后无法自动重连。

测试超时 → E2E 测试会启动自己的 Server 实例，Bridge 需要通过重试循环重连到新 Server

HTTP 调用返回 403 → 请求源 IP 不在 allowedIps 白名单。修改 config.json 的 allowedIps 加来源 IP 后重启服务端。

相关仓库

技术说明

• MCP SDK v1.x 低阶 API（setRequestHandler），不用 registerTool()（该 API 在 connect() 后抛出异常）

• WebSocket 通信（ws 库），IP/Port 来自 config.json

• 工具通过 register_tools 消息从 Bridge 动态注册到 Server，Bridge 重连后自动重新注册

• Unity Bridge 活动传输为 .NET ClientWebSocket（NetWebSocketClient 封装，BridgeClient.ConnectToServer() 创建）；旧版纯 TCP RFC 6455 实现（WebSocketClient）已标记 [Obsolete] 仅作参考

• Server 同时暴露 HTTP /rpc 端点用于程序化调用（E2E 测试使用）

• /health 端点返回 bridge 连接状态、工具列表、播放模式状态

• HTTP /rpc、/sse、/mcp 端点受 allowedIps 白名单 gate（403）；WebSocket 升级路径与 /ab 不受限

• 消息负载上限 4MB（maxPayload）

• 服务端每 ~30s ping、超时未 pong 判定失活并 terminate() 断连（isAlive 心跳）

• 日志脱敏：工具名 + 参数长度（不打印明文 payload），错误路径保留详情

• config.json 不存在时首次启动自动从 template 复制生成；改完配置重启生效

• 进程级安全网：uncaughtException / unhandledRejection handler 记日志后继续运行（不崩进程），防单个坏工具响应或未捕获 rejection 带走整个 relay（丢连接 + retryQueue + 在途调用）