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

使用

前置：clone 并配置 SimpleMCPBridge

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

编辑 Assets/SimpleMCPBridge/bridge-config.json：

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

1. 启动 Unity Bridge

1. 用 Unity 打开项目

2. 菜单栏 → PowerUtilities → SimpleMCPBridge

3. 点击 Connect to Server

Bridge 生命周期独立于窗口：关闭窗口后 bridge 继续运行，进出 Play Mode 自动重连（依赖 [InitializeOnLoad] + EditorPrefs 持久化标志）。

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 桥实测 108 个桥工具 + 服务端合成 2 个 = 110 个）。下表按类别简述常用工具；完整清单见 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 工具开关（Editor 侧仍有自己的开关，见桥 README）

• 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           # 入口 + WS Server + MCP handlers
└── types.ts           # 类型定义
tests/
├── test-e2e.cjs           # E2E 测试（initialize + tools/list + get_hierarchy）
└── test-playmode-cycle.cjs # Play Mode 循环测试（进出播放验证 bridge 自动重连）

故障排查

"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 使用纯 TCP 实现 RFC 6455 WebSocket，零外部依赖

• 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 复制生成；改完配置重启生效