SimpleMCPBridge — Unity 侧桥接包

让 AI Agent（Claude、Cursor 等）通过 MCP 协议直接控制 Unity Editor / Runtime。
必须配合 SimpleMcpServer 使用。

AI Agent (Claude Code / Cursor)
    │  MCP SSE (GET /sse + POST /mcp)
    ▼
SimpleMcpServer (Node.js/TypeScript)   ← 另一个仓库，需单独 clone
    │  WebSocket (ws://)
    ▼
SimpleMCPBridge (C#)                   ← 本仓库，clone 到 Unity Assets/ 下
    │
    ▼
Unity Editor / Runtime

支持同时连接多个 Bridge（如 Editor + Android 设备），路由规则 last-registration-wins。

SimpleMCPBridge 的设计理念是 structured memory query（结构化内存查询），而非 screenshot-based perception（基于截图的视觉感知）。

为什么这样设计？

具体做法：

• 血条 → 读 Slider.value（精确浮点值），不分析像素颜色
• UI 文字 → 读 Text.text / TMP_Text.text（字符串），不 OCR
• 玩家状态 → 读 Transform.position + Rigidbody.velocity + Animator 参数，不截图推断
• 场景对象 → 遍历 Transform 层级 + GetComponent，不视觉识别
• 敌人感知 → game.get_entities 批量读 AI/Health 组件，不数像素

camera.screenshot 仅作为辅助手段（调试、确认视觉布局），不是感知游戏状态的主路径。所有游戏状态都应从 Unity 对象的组件属性中直接读取。

工具类别机制：127 个工具按类别组织（[Scene]/[Ui]/[Ngui]/[Input]/[Game]…）， 并支持运行时按类别动态开关（tools.enable / tools.disable）——只注册当前 任务需要的工具集，减少 token 消耗。详见下文「工具类别与动态注册」章节。

• Node.js 22+ — 运行 MCP Server
• Git — 克隆仓库
• Unity 2022.3+

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

安装后目录结构：

Assets/
├── SimpleMCPBridge/        ← 本仓库（git clone）
│   ├── Runtime/             # 运行时桥接代码
│   │   ├── BridgeClient.cs          # 核心桥接逻辑（连接/消息/加密）
│   │   ├── MCPBridge.cs             # MonoBehaviour 组件（生命周期/重连）
│   │   ├── MessageRouter.cs         # JSON-RPC 消息路由
│   │   ├── MCPToolRegistry.cs       # [MCPTool] 自动发现/注册
│   │   ├── MCPToolAttribute.cs      # [MCPTool] + [MCPToolClass] 特性
│   │   ├── MCPMethodConst.cs        # 工具名常量
│   │   ├── EncryptionHelper.cs      # AES-256-CBC 加解密
│   │   ├── WebSocketClient.cs       # 零依赖 RFC 6455 WebSocket（[Obsolete]，参考用）
│   │   ├── NetWebSocketClient.cs    # 活动传输：.NET ClientWebSocket 封装
│   │   ├── WebSocketInterfaces.cs   # WebSocket 接口抽象
│   │   ├── Config/
│   │   │   └── BridgeConfig.cs      # 配置加载（Editor/Player）
│   │   ├── Handlers/       # 工具处理器（17+ Handler，127 个工具）
│   │   │   └── NguiHandler.cs   # NGUI 工具（#if NGUI_ON 条件编译，未装 NGUI 不注册）
│   │   ├── Tools/          # 工具辅助类
│   │   └── Models/
│   ├── Editor/
│   │   └── MCPBridgeEditor.cs       # MCPBridge 组件 Inspector（CustomEditor，非窗口）
│   ├── Prefabs/
│   │   └── MCPBridge.prefab         # 预置组件（默认 127.0.0.1:45678，自动重连）
│   ├── Plugins/             # 依赖 DLL（已含仓库内，clone 即可用）
│   ├── Resources/
│   │   └── bridge-config.json   # 包内兜底配置（Editor/Player 首次自动拷贝的来源）
│   └── SimpleMCPBridge.asmdef  # 程序集定义（含 versionDefines）
├── SimpleMCPBridge-config/   # 项目本地配置（首次启动自动生成，不在包内）
│   └── bridge-config.json    # Editor 用 IP/Port/加密配置
├── ...

SimpleMCPBridge 是独立 git 仓库，不是 Unity 项目的子模块。 Plugins DLL 已包含在仓库内，clone 后无需手动下载。

# 任意目录下克隆
cd D:/dev/  # 举例，随意放哪里
git clone https://github.com/redcool/SimpleMCPServer.git
cd SimpleMCPServer
# 首次需要安装依赖
npm install
npm run build

之后每次启动只需运行 start.bat（会自动 build + 启动）。

通过 Unity Package Manager 安装：

UPM Git URL:
https://github.com/CyberAgentGameEntertainment/InstantReplay.git?path=Packages/jp.co.cyberagent.instant-replay#release

或者手动编辑 Packages/manifest.json：

{
  "dependencies": {
    "jp.co.cyberagent.instant-replay": "https://github.com/CyberAgentGameEntertainment/InstantReplay.git?path=Packages/jp.co.cyberagent.instant-replay#release"
  }
}

安装后 SimpleMCPBridge.asmdef 的 versionDefines 会自动检测到该包，定义 INSTANT_REPLAY_ON 宏。

1. 启动 MCP Server（双击 SimpleMcpServer/start.bat）
2. 用 Unity 打开项目，把 Assets/SimpleMCPBridge/Prefabs/MCPBridge.prefab 拖进场景 （或给任意 GameObject 添加 MCPBridge 组件）
3. 选中该物体，Inspector 内显示连接状态/Bridge ID/错误面板，以及 Server IP/Port 字段和 Connect 按钮（默认 127.0.0.1:45678）
4. 点击 Connect（若勾选 Auto Reconnect，断线自动重连）

MCPBridge 是 [ExecuteAlways] 组件：Edit Mode / Play Mode / 构建后的 Player 均可用； 勾选 Dont Destroy On Load 后跨场景存活，进出 Play Mode 自动重连。

编辑 bridge-config.json：

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

配置加载策略（BridgeConfig.cs，首次自动生成、已存在不覆盖）：

• Editor — 项目 Assets/SimpleMCPBridge-config/bridge-config.json，首次自动从包内 Resources/bridge-config.json 拷贝生成；用户可改，重启生效
• Player — Application.persistentDataPath/bridge-config.json，逻辑同上
• 兜底 — 包内 Resources/bridge-config.json 内嵌默认值

scene.call_component_method 权限字段（可选，需重启生效）：

• methodBlocklist — 追加拦截项（"MethodName" 或 "TypeName.MethodName"，大小写不敏感）；代码默认 6 项 （destroy/destroyimmediate/destroyobject/quit/quitimmediate/disconnect）始终生效，无法通过配置移除
• methodAllowlist — 空 = 关闭；非空 = 白名单模式，只放行命中的方法；白名单不会覆盖黑名单 （代码默认 + 配置追加的双重拦截始终优先）

替代 TLS/wss 的 AES-256-CBC 载荷加密：

启用：Server 和 Bridge 的配置中设置相同的 encryptionKey。

选择载荷加密而非 TLS/wss 的原因：Unity Editor（Mono）TLS 兼容性差，Android IL2CPP 自签名证书部署复杂。

所有场景工具同时支持两种方式定位 GameObject：

解析优先级：instanceId > path。两个都传时先试 instanceId，找不到再 fallback 路径。

平台支持: recording.* 基于 CyberAgent InstantReplay，该包官方支持 Android / iOS / macOS / Windows / Linux（需 ffmpeg）/ Web（需 WebCodecs），全部走 OS 原生编码（MediaCodec / VideoToolbox / Media Foundation）， 无需外部工具。桥注册平台为 Android | iOS | Standalone | Editor 且 RequirePlayMode = true（仅 Play Mode 注册）。 Editor（Windows/macOS）侧录制——例如 AI 迭代粒子特效时的反馈回路——已默认启用（2026-08 起，Windows Editor 录制已实测通过）；multi-bridge 下如 Editor 与 Android 同时在线，遵循 last-registration-wins，需要确定性目标时用 bridge.call 显式指定。Editor 下输出到项目 VideoRecord/（与 camera.screenshot 同根目录），设备构建输出到 temporaryCachePath/VideoRecord/。

录制流程：

1. scene.enter_play_mode          # 进入播放模式
2. recording.start                # 开始录制（默认 1280x720@30fps）
3. scene.set_transform(...)       # 操作场景对象
4. recording.stop                 # 停止录制
5. recording.status → polling    # 轮询直到 state="completed"
6. scene.exit_play_mode           # 退出播放模式

Quality → Bitrate 映射：

FreshFrameProvider：每帧创建独立 RenderTexture，解决 InstantReplay 默认 ScreenshotFrameProvider 的纹理重用竞态问题。

gamepad 按键名：south/a、east/b、north/x、west/y、leftShoulder/lb、rightShoulder/rb、leftStick、rightStick、start、select/back、dpadUp/down/left/right

gamepad 轴名：leftStickX/Y、rightStickX/Y、leftTrigger、rightTrigger

针对使用 NGUI（第三方老牌 UI 插件）的旧项目。与上方 uGUI 工具互相独立、互不互斥： 可同时开启，也可 tools.disable ["Ui"] 只留 NGUI（或反之，类别 Ngui/Ui）。 点击模拟直接复用 input.click_screen（NGUI 的 UICamera 响应屏幕坐标）。

安装 NGUI（两种方式任选）：tasharen/ngui 仓库无 package.json，不能直接用 versionDefines 检测。

方式 A：包化成 UPM 包（推荐）——NGUI_ON 由 versionDefines 自动定义：

1. git clone https://github.com/tasharen/ngui.git <某目录>
2. 仓库根补 package.json：{"name": "com.tasharen.ngui", "version": "3.12.0", ...}
3. 建 asmdef：Scripts/NGUI.asmdef（运行时，程序集名 NGUI）+ Scripts/Editor/NGUI.Editor.asmdef（includePlatforms: ["Editor"]，引用 NGUI）
4. 排除示例：Assets/NGUI/Examples → 改名 Examples~
5. 项目 Packages/manifest.json 加 "com.tasharen.ngui": "file:../../ngui"

方式 B：源码直接放 Assets/ + 手动符号——仅省去「package.json + manifest 引用」：

1. NGUI 源码拷入 Assets/NGUI/，必须建与方式 A 相同的两个 asmdef（asmdef 程序集无法引用裸放进 Assembly-CSharp 的 NGUI 代码）
2. 排除示例：Assets/NGUI/Examples → 改名 Examples~
3. 手动加 NGUI_ON 符号：Project Settings → Player → Scripting Define Symbols 加 NGUI_ON（或 SimpleMCPBridge.asmdef 的 defineConstraints 加 "NGUI_ON"）

⚠️ 警告：#if NGUI_ON 打开但 NGUI 类型不可解析会报 CS0246——NGUI 源码必须放在有 NGUI.asmdef 的程序集里， 且 SimpleMCPBridge.asmdef 的 references 含 "NGUI"（软引用）。两种方式此前提相同。

SimpleMCPBridge 侧已配好：asmdef versionDefines（com.tasharen.ngui → NGUI_ON）+ references 软引用 "NGUI"。未装 NGUI 时工具不注册、仅一条 warning，不影响编译。

针对使用 UI Toolkit（UnityEngine.UIElements，UXML/USS/UIDocument）构建运行时 UI 的项目。 与 uGUI（类别 Ui）和 NGUI（类别 Ngui）互相独立、互不互斥，类别 Uitk。 UI Toolkit 是引擎内置模块，无条件编译——无需装包、无需 versionDefines，注册即用； 面板未 attach（非运行态）时优雅返回空结果，无需 Play Mode。 不设 UITK_ON 条件编译（有意决策）：com.unity.modules.uielements 是内置模块非可选包，2022.3 必在； 客户工程 runtime 不用 UITK 时用 tools.disable ["Uitk"] 裁剪（临时、任务级，domain reload 自动恢复全开）。 UITK 交互事件依赖 EventSystem 桥接：面板要接收指针事件，场景必须有 PanelEventHandler + PanelRaycaster （通常挂在 UIDocument 的 PanelSettings 持有者上，如 EventSystem/Default Panel Settings）——没有桥接则 UITK 无事件。 注意：UITK 元素是 VisualElement（非 GameObject，无 instanceId）——用 panelIndex/panelPath + 元素 path 寻址 （uitk.get_elements 返回的 fullPath）。input.click_screen（EventSystem）能否驱动 UITK 取决于场景是否桥接： 面板 GameObject 挂了 PanelEventHandler + PanelRaycaster 时（UIDocument + EventSystem 的标准集成），click_screen 可经 EventSystem 射中面板并触发 Clickable 的 clicked（已实测验证）；未桥接时 EventSystem 射不到 UITK 面板。 确定性点击仍用 uitk.click（向 panel 注入 pooled PointerDown/Up，Clickable 自动生成 ClickEvent）。

Unity 没有 PlayerPrefs key 枚举 API——playerprefs.get_all 只能列出本会话经 set/get 见过的 key（其他代码写入的持久 key 无法枚举，用 playerprefs.get 精确读取）。

创作/预览（Edit Mode 可撤销）+ 运行时播放（Play Mode 才注册）。使用模型：Editor 创作（资产）+ Runtime 播放。模块属性走 typed 代码路径（零反射，规避 CS1612 与 il2cpp 裁剪），改模块属性须先存局部变量。

材质颜色/贴图用 scene.set_material（ParticleSystemRenderer 是 Renderer）；保存用 scene.save_prefab（assetPath 参数）。素材创作流程：先 scene.instantiate_prefab（PrefabUtility.InstantiatePrefab，保留 prefab 关联）把特效 prefab 放进场景 → particle.set 赋内置材质自动落在 prefab 同目录 → 或 particle.create/set 显式传 materialDir。配方参考：火焰/爆炸/火花/烟雾/魔法/雨雪/光点/传送门 → 见 AGENTS.md「Particle 特效创作」配方表。

这些工具使用 RequirePlayMode = true，仅当 Play Mode 激活时才注册。

由 SimpleMcpServer 直接提供，不在 Bridge 注册：

每个工具的描述都以 [类别] 开头（如 [Scene] 获取完整的场景层级树...）， 类别由工具名前缀自动派生（scene.xxx → Scene，assetbundle.xxx → AssetBundle）， 方便人眼和 AI 快速扫描、分组。

工具按类别动态注册/注销，避免无关工具干扰调用方：

示例：本次任务只用场景操作，把无关的 AssetBundle/Shader/Recording 关掉：

{"name": "tools.disable", "arguments": {"categories": ["AssetBundle", "Shader", "Recording"]}}

之后 tools.list_categories 会显示这三类 "enabled": false，它们也不会出现在 tools/list 结果里。任务结束后 tools.reset 一键还原。

要点：

• 默认全部启用——条件编译只决定工具"是否存在"（装包即编译注册，如 NGUI 装上后 ngui.* 自动可用）， tools.enable 无需 AI 主动调用；tools.disable 是纯 AI 侧裁剪机制，用于砍掉无关工具省 token
• 类别状态是 static 的（纯内存，无 EditorPrefs/PlayerPrefs 持久化）：跨 Play Mode 切换、router 重建保留； 脚本重编译 / Editor 重启（domain reload）后重置为全部启用
• tools.disable all 会保留 Tools 类别本身（4 个控制工具），保证永远能恢复
• mcp.list_tools / tools/list 返回的就是当前启用的工具子集
• 新增工具类时无需手动登记类别——注册器按名称前缀自动归类

多个 Unity Bridge 可同时连接。三层机制：

1. 默认路由：last-registration-wins — 后连接的 bridge 覆盖同名工具
2. 显式路由：bridge.call 指定 target = bridgeId，绕过默认路由，确定性调用
3. 断开 failover：某 bridge 断开时，其路由的工具若被其他在线 bridge 注册，自动回退；否则清除

• Editor bridge（92+ tools）与 Android bridge（部分工具）共存
• Bridge 断线：该 bridge 的工具从路由表移除；有其他 bridge 注册同工具时自动回退
• 无 bridge 时待处理调用进入重试队列（30s 宽限期）
• 使用 bridge.list 查看所有已连接 bridge（ID、IP、工具列表）
• ⚠️ BridgeId 每次连接重新生成（GUID），clientPort 是随机客户端端口——不要用 ip+port 作稳定标识，精确调用一律用 bridgeId
• tools/list（含 MCP ListTools）返回的每个 bridge 工具 description 带 [bridge: ip:port (id前8位)] 前缀 = 该工具当前路由目标（last-registration-wins 结果）。AI 可直接从工具列表得知调用会打到哪个 bridge

Bridge 可通过 Server 调用外部 LLM：

Bridge → Server: {"type":"ai_request","prompt":"...","context":{...},"requestId":"..."}
Server → Bridge: {"type":"ai_response","text":"...","requestId":"..."}

• 支持任何 OpenAI 兼容 API（OpenAI、Agnes、Ollama 等）
• API Key 支持 LLM_API_KEY 环境变量
• Server config.json 中 llm.enabled: false 关闭

1. 创建新类：

using SimpleMCPBridge.Runtime;
using static SimpleMCPBridge.Runtime.Handlers.HandlerUtils;

public class MyTools
{
    [MCPTool("my_tool_name", "工具描述",
             Platform = MCPToolPlatforms.All,
             RequirePlayMode = true)]
    public static string MyTool(string paramsJson)
    {
        var args = ParseJsonObject(paramsJson);
        var name = GetString(args, "name", "default");
        return "{\"success\":true}";
    }
}

RequirePlayMode = true 时该工具仅当应用处于播放模式时注册，避免 Editor Edit Mode 下误调用。

类别自动派生：工具描述会带上 [类别] 前缀，类别默认取自工具名前缀 （my_tool_name → MyTool，assetbundle.xxx → AssetBundle）。如需自定义类别：

[MCPTool("my_tool_name", "工具描述", Category = "CustomGroup")]

归类后即可用 tools.enable / tools.disable 按类别动态开关。

2. 自动注册 — MessageRouter 构造时扫描程序集，自动发现带 [MCPTool] 的方法。

• 方法签名必须为 public static string MethodName(string paramsJson)
• 类需要 public 无参构造函数（static class 自动跳过）
• [MCPToolClass] 标记类可加速发现
• Platform 可选，控制哪些构建目标注册该工具
• RequirePlayMode 可选，为 true 时工具仅在 Play Mode 时注册
• Category 可选，覆盖自动派生的类别名（默认取工具名前缀）
• 修改 C# 后等待 Unity 编译完成

用法：using static SimpleMCPBridge.Runtime.Handlers.HandlerUtils;

录制工具依赖 CyberAgent InstantReplay（Unity Package jp.co.cyberagent.instant-replay）。

SimpleMCPBridge.asmdef 中 versionDefines 自动检测包是否存在，存在时定义 INSTANT_REPLAY_ON：

editor.eval 通过 Mono.CSharp 动态编译并在内存中执行任意 C# 代码 —— 等同于完全的 Unity/机器控制（读写任意文件、删除资产、网络访问、启动进程等）。这是工具集最强的"逃生舱":当某个场景操作没有专用工具覆盖时,AI 可用 eval 即时补救。

默认 ON,以用户方便为先。开发调试、快速原型、补救缺口工具时即时可用,不必先翻配置。若环境不可信（共享机器/公网暴露的服务器),关闭它。

双重 gate（任一关闭即不可用）:

• Server 侧 config.json → evalEnabled（默认 true）:false 时 tools/list 不暴露 editor.eval 给 agent,agent 看不到也就调不到。
• Bridge 侧 EditorPrefs SimpleMCPBridge_EvalEnabled（默认 true）:执行前再检查一次;MCPBridge Inspector 显示为 "Editor Eval (global)" toggle,关闭后调用返回错误。

风险面:任何能调用 /rpc 的 AI 都能执行任意代码。本工具不做代码内容过滤（任意代码无法穷举拦截,黑名单无意义）。安全靠网络层 gate —— allowedIps 白名单默认仅本机（127.0.0.1/::1）。云部署（ip:0.0.0.0）前务必扩白名单到可信 IP 段,或直接 evalEnabled:false。

关闭方法（任一即可）:

• SimpleMcpServer/config.json 设 "evalEnabled": false（重启 server,对所有 agent 隐藏）
• Unity Editor: MCPBridge Inspector 的 eval toggle（立即生效,单机）
• 代码:EditorPrefs.SetBool("SimpleMCPBridge_EvalEnabled", false)

详见 AGENTS.md「editor.eval 安全说明」。

加密载荷格式从 {"encrypted":"<base64>"} JSON 包装改为 #ENC#<base64> 前缀格式。Server 端也必须使用 #ENC# 前缀，两端需同步更新。

多线程安全、资源泄漏修复、性能优化等多项改进。

根因：InstantReplay 始终创建音频轨道，即使 enableAudio=false。音频轨道从未收到帧。 影响：无害。MP4 视频轨道完整，播放正常。

BuildJsonObject(("key", "value")) 生成 "key":value（裸词，无效 JSON）。字符串值必须通过 EscapeString("value") 包装: ("key", JsonHelper.EscapeString("value")) → "key":"value"。数值和 bool 不需要包装。

同类陷阱 —— 控制字符未转义：EscapeString 原先只处理 " \ \n \r \t，漏了 JSON 规范要求转义的 U+0000–U+001F 控制字符（及 \b \f）。工具返回含控制字符的字符串（如 Vector3.ToString() 的 (0, 0, 0)、二进制数据、带格式符的文本）会产出无效 JSON → 服务器日志 Invalid JSON from bridge → 客户端表现 30s 超时（像 handler 挂起,实际是响应被丢弃）。EscapeString 已补全 \b \f 及 \uXXXX 兜底；非字符串值（float/int 的 ToString("G")）不受影响。诊断：server.log 搜 Invalid JSON,用 node -e "JSON.parse(...)" 定位裸词位置。

ws 库的 WebSocketServer 在进程退出后有时端口保持绑定：

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

开启多个 Unity 进程（如多个 Editor 窗口）时各自建立独立 WebSocket 连接，每个进程一个 bridgeId。

MCPToolRegistry 在 BridgeClient 构造时扫描注册工具。由于 BridgeClient 是单例，工具注册只发生一次。进出 Play Mode 时如果 bridge 未断开，工具列表不会动态更新。但在标准工作流中（domain reload → bridge 重连），每次进入/退出 Play Mode 都会重新注册。

MCP Server（SimpleMcpServer）必须在一个可见的 cmd 窗口中运行，不能以无窗口/后台方式启动：

• 用 start.bat 启动（会打开 cmd 窗口并显示日志）
• 不要用 Start-Process -NoNewWindow 或后台服务方式启动
• 原因：服务器日志（连接、工具调用、AB 传输）实时输出到窗口，便于排查问题；且服务器进程需要保持前台运行

当 Editor 和 Android 两个 bridge 同时连接，且 Editor 处于 Play Mode 时，last-registration-wins 规则会让 Editor 覆盖同名工具（如 shader.hot_replace、assetbundle.hot_replace）的路由。此时直接调用这些工具会路由到 Editor 而非 Android。

这是有意的默认行为（见「Multi-Bridge 路由」三层机制）：无指定目标时，服务器按注册顺序取最后一个。需要确定性目标时，用 bridge.call 显式指定：

{
  "name": "bridge.call",
  "arguments": {
    "target": "<android_bridge_id>",
    "method": "assetbundle.hot_replace",
    "params": { "abUrl": "http://<server_ip>:45678/ab/<bundle>" }
  }
}

bridge.list 可查看各 bridge 的 ID 和 IP（Android 通常为 10.0.x.x）。

Unity 的 AB 去重机制：相同内容的 AssetBundle 只能被 LoadFromMemory 加载一次。若 shader.hot_replace 已加载某 AB 且未卸载，后续 assetbundle.hot_replace 加载同内容 AB 会报：

The AssetBundle 'Memory' can't be loaded because another AssetBundle with the same files is already loaded.

解决：每次部署前先调用 assetbundle.unload_all 卸载所有已加载 bundle，或使用不同内容的 AB（不同文件名/内容）。