MCP Inspector Bridge
by
Provides a modern runtime node inspection and AI bridge panel for Cocos Creator 2.4.x, enabling dual‑pane debugging, property editing, drawcall analysis, memory profiling, screen picking, and automatic bridging to large language model clients.
MCP Inspector Bridge Overview
What is MCP Inspector Bridge about?
MCP Inspector Bridge delivers a Vue 3 + Electron based debugging panel specially crafted for Cocos Creator 2.4.x. It injects a non‑intrusive probe into the running game, captures the full node hierarchy, and exposes a rich set of tools—node tree search, two‑way property editing, draw‑call diagnostics, memory analysis, screen picking, performance overlay, and a multi‑instance MCP server that bridges the engine to AI clients such as Claude, Cursor, and 20+ other large‑model interfaces.
How to use MCP Inspector Bridge?
- Clone or copy the repository into a Cocos Creator plugin folder:
# Global plugin location ~/.CocosCreator/packages/mcp-inspector-bridge/ # Or project‑specific location your‑project/packages/mcp-inspector-bridge/ - Install dependencies (includes
esbuildfor the probe):npm install - Build the TypeScript sources and package the probe:
npm run build - Open Cocos Creator, load any scene, then select MCP Bridge → Open Runtime Panel from the menu.
- Click Preview Run. The panel automatically captures the game preview, loads the node tree, and activates all debugging tabs.
- (Optional) Enable AI bridging in the Settings tab – the built‑in MCP server starts on port 4456 and auto‑increments if the port is busy.
Key Features of MCP Inspector Bridge
- Dual‑pane workflow – left side shows the live game view, right side houses node tree, property inspector, DevTools, and performance panels.
- Runtime probe & node tree – non‑intrusive injection, keyword‑AND search, strict path filtering, auto‑clear on blank clicks.
- Screen picker & bounding‑box highlight – accurate polygon overlay, cross‑camera support, area‑weighted selection.
- AI MCP bridge – multi‑instance server, automatic detection of 22+ AI clients, handshake with project metadata, log capture via CDP or fallback injection, screenshot injection for LLMs.
- Two‑way property editor – supports numbers, strings, booleans, arrays, colors, enums; live sync without dirtying the editor scene.
- Memory profiler – bundle‑level ranking, peak tracking, UUID ↔ asset path conversion, quick asset locator.
- Render debugger – draw‑call batch break detection, hash‑deduped reporting, frame‑snapshot analysis, node jump‑from‑draw‑call.
- Performance overlay – FPS (instant, avg, 1% low, 0.1% low), draw‑call count, logic/render time, memory, node count; configurable polling rates and threshold‑based coloring.
- Engine controls – pause/resume, single‑step, FPS overlay toggle, global mute.
- Custom preview resolutions – persistent presets, global profile storage, auto‑refresh on change.
- Screenshot & video recording – Chromium‑level capture, clipboard copy, file save dialog, configurable frame rate & resolution, FFmpeg‑based MP4 export with fallback to WebM.
- Dynamic atlas & physics inspector – live view of atlas settings, texture bleed, physics manager parameters, collision draw flags.
- Responsive UI – 32+ device resolution presets, prefab locator, draggable tabs, persistent layout, zoom & font scaling.
- Zero‑noise debugging – probe logs silenced by default; enable with
window.__MCP_DEBUG__ = true.
Use Cases of MCP Inspector Bridge
- Game developers needing an in‑engine inspector that works on Cocos Creator 2.4.x without the unstable built‑in Chromium DevTools.
- Artists & designers who want to tweak component properties at runtime and see immediate visual feedback.
- Performance engineers tracking draw‑call bottlenecks, memory spikes, and frame‑time distribution during playtests.
- AI‑assisted development teams leveraging Claude, Cursor, or other LLMs to query the scene hierarchy, request screenshots, or command the engine directly via the MCP bridge.
- QA testers performing rapid node picking, hierarchy search, and on‑the‑fly property changes to reproduce bugs.
FAQ from the MCP Inspector Bridge
Q: Which Cocos Creator versions are supported? A: Cocos Creator 2.4.x, including custom builds that have been upgraded to Electron 14+.
Q: Do I need to rebuild the probe after modifying game code? A: No. The probe is injected at runtime; changes to game scripts are reflected automatically when you restart the preview.
Q: What if port 4456 is already in use?
A: The server includes an EADDRINUSE detection routine that increments the port number until a free one is found.
Q: Can I disable the AI bridge? A: Yes. In the Settings tab, turn off “AI Bridge” to stop listening for external LLM clients.
Q: How is logging handled?
A: Log capture uses CDP Runtime.consoleAPICalled when available; otherwise it falls back to script injection. Logs are silenced by default and can be enabled with window.__MCP_DEBUG__ = true.
Q: Is there support for Windows/macOS/Linux? A: The plugin runs inside Cocos Creator, which itself is cross‑platform. Video export to MP4 requires FFmpeg on the host OS.
Q: Where are my preferences saved?
A: Settings such as custom resolutions, panel widths, and overlay toggles are persisted under the project’s settings/ directory via Editor.Profile.
MCP Inspector Bridge's README
MCP Inspector Bridge
专为 Cocos Creator 2.4.x 打造的现代化运行时节点审查与 DevTools 桥接插件。
基于 Vue 3 + Electron BrowserView 架构，提供双分栏沉浸式调试体验：左侧游戏预览、右侧节点树/属性检查/DevTools/性能分析，彻底解决原版内嵌 Chromium DevTools 的挂起死锁问题。
🚀 快速开始
环境要求
- Cocos Creator 2.4.x （广泛兼容官方原版以及魔改升级至 Electron 14+ 的特殊高版本环境）
- Node.js ≥ 14
安装
将本项目克隆或复制到 Cocos Creator 的插件目录中：
# 全局插件目录
~/.CocosCreator/packages/mcp-inspector-bridge/
# 或项目级插件目录
your-project/packages/mcp-inspector-bridge/
构建
# 安装依赖（包含 esbuild）
npm install
# 编译 TypeScript + 打包探针模块与 MCP 客户端
npm run build
使用
- 在 Cocos Creator 中打开任意场景
- 菜单栏 → MCP 桥接器 → 开启运行时面板
- 点击 预览运行 按钮，插件面板将自动捕获游戏预览并加载节点树
✨ 核心特性
🖥️ 双分栏工作流
采用 Vue 3 构建主面板，左侧 Webview 渲染游戏视口，右侧集成多功能调试标签页，实现"边玩边审"的沉浸式体验。
⚡ 运行时探针与节点树
基于预加载脚本 (preload.ts) 无侵入注入探针至游戏运行时，实时截获完整节点树结构。
- 多关键词穿透搜索：支持空格分词的 AND 逻辑匹配，可穿透至组件类名层级搜索（如输入
Animation定位所有挂载该组件的节点） - 严格路径过滤：搜索结果仅展示命中节点及其直系祖先，自动隐藏无关分支
- 空白区域取消选中：点击空白即可清除所有焦点，联动属性面板归零与高亮退场
🎯 节点高亮与屏幕拾取
- 包围盒高亮：鼠标悬停/选中节点时，游戏画面实时渲染精准的贴边多边形轮廓，零宽高节点自动降级为十字准星
- 屏幕拾取器：直接在游戏画面中点击选取节点，基于多摄像机阵列扫描 + CullingMask 分组继承 + 面积权重透层算法，完美适配多镜头、多分组、Fit 缩放等复杂场景
🤖 AI MCP 集成桥 (Multi-Instance Ready)
为 LLM (大模型如 Claude/Cursor) 提供双端通信与跨进程的游戏引擎交互视界。
- 多实例动态寻址 (Multi-Instance Support)：内置
EADDRINUSE冲突递增机制，支持同时开启多个编辑器实例，实现不同项目端口的自动隔离（默认 4456）。 - 基于项目身份的握手协议：心跳回执注入
projectName与projectPath，允许 AI 快速识别目标平行宇宙。 - 多端全平台自动配置：支持向 22 款主流 AI 客户端（如 Claude Desktop、Cursor 等）进行自动探测与免配桥接。
- MCP 路由工具扩展：提供
get_active_instances扫描活跃端口、set_active_instance绑定指定项目端口、以及refresh_preview主动刷新游戏预览窗口。 - 环境安全异常零漏截获 (Eager Log Capture)：针对 Webview 预览采用 CDP
Runtime.consoleAPICalled零注入被动监听（非侵入式，完美保留 DevTools 源归属）；针对 BrowserView 采用原生console-message事件。双重防御配合每秒后台激进式探测定时器，在游戏初始化第一帧即接管日志，彻底杜绝早期生命周期错误丢失。CDP 不可用时自动降级至注入方案。 - 超保真渲染验证实况图：直接为大语言模型一键注入运行时截图，打破次元壁。
- 可视化 MCP 通信降维打击 (Debug Console)：在偏好设置面板内置专属通信日志流，实时抓取前后端请求细节与返回结构；更具备极致的数据防爆护城河（自动截断长字符串与双峰队首淘汰流控机制），轻松排查大语言建模幻觉与传输丢包。
🔍 属性检查器
遵循现代化卡片化 UI 设计规范 (Modern Card-based UI)，选中节点后实时展示结构清晰、分栏合理的组件属性库：
- 双向属性同步与编辑：
number/string/boolean以及现代化多行下潜渲染的array、Anchor、Color、Opacity、Group等全景属性双向实时更新；string属性支持多行文本编辑 (textarea 替代 input，Enter 键插入换行)；并且内置 0.5 秒高频属性轮询挂载鼠标与焦点双重意图拦截保护，在节点产生自动动画、物理位移时实现完美的数据追平，而在用户试图编辑时自动停止刷新以防光标跳跃。 - 纯运行时注入：所有修改直接操作内存实例，不脏化编辑器 Scene 数据，无"是否保存"弹窗
- 组件启停控制：统一的的复选开关
enabled，一键休眠/唤醒指定组件 - 引用追踪定位 🎯：节点级引用、资源字典、预制体地址均可无痛一键跳转定位归属并闪烁对焦
- 智能枚举下拉：基于运行时原型的强反射抓取，自动兼容多达 40 种官方内置枚举（诸如
Sprite.type) 以及业务测自定义枚举列表，拒绝盲填查字典的痛苦 - 组件 JSON 免签分发：点击组件 🖨️ 图标，将规避循环污染后的数据一键打印直出控制台绿幕，并自动顺时写入系统安全剪贴板
- 节点对象直连控制台：点击节点基础属性区右上角的 🖨️ 图标，将整个实例对象剥离序列化负担，直接交由 DevTools 原生审查，突破隐藏私有字段盲区
📉 内存剖析器
按 Bundle 分域聚合的资源内存排行榜：
- 极值水位追踪：实时记录每个 Bundle 的历史最高/最低内存，趋势箭头（↑↓）即时预警
- UUID 逆向解码：自动将混淆的 UUID 还原为
db://assets/textures/...可读路径 - 一键资源定位 🎯：点击即可在编辑器资源管理器中高亮对应文件
- 宏观内存汇总：榜单头部实时聚合由底层探针累加的总体内存消耗
🩺 渲染调试器
运行时 DrawCall 合批断流诊断：
- 静默拦截：AOP 劫持渲染管线，零控制台污染
- 频次聚合：Hash 去重 + 触发次数徽章，60FPS 连环断流也不卡
- 帧快照三栏分析：渲染命令树 / 单步回绘画布 / 管线参数明细
- 逆向节点定位 📌：从 DrawCall 直接跳转至游戏节点
📊 实时性能叠加框
在游戏预览区左上角渲染半透明 Vue 性能数据面板，彻底解决引擎内置 cc.debug.setDisplayStats() 在高分辨率/移动端预览下完全无法辨认的问题：
- 帧率全维度: 瞬时 FPS、平均帧率 (Avg)、1% Low FPS、0.1% Low FPS，基于 600 帧环形缓冲区逐帧统计百分位
- 渲染指标: DrawCall、Logic 耗时、Render 耗时
- 资源概况: 实时内存占用 (Mem)、场景节点总数 (Nodes)
- 智能轮询: 性能数据 200ms、内存 1s、节点计数 2s 三档独立速率，节点 O(n) 遍历开销可控
- 颜色自适应: 各项指标根据预设阈值独立着色（绿/橙/红），低帧阈值逐级放宽
⏭️ 引擎控制
- 暂停/恢复游戏引擎
- 单帧步进
- FPS 叠加框开关 (替代引擎内置 FPS，控制插件叠加框显隐)
- 全局静音
📐 自定义预览分辨率
在偏好设置面板（⚙️ 设置标签页）中管理全局自定义分辨率预设，出现在预览窗口下拉菜单的「自定义」分组中：
- 添加 / 编辑 / 删除：自定义分辨率名称（选填，未填显示
自定义分辨率（W×H））与宽高 - 全局持久化：基于
Editor.Profile全局存储，一次配置多项目共享 - 即时同步：修改后下拉菜单实时刷新，正在使用的分辨率被删除时自动回退为「自动充满」
📸 游戏截图
在游戏预览区右上角提供半透明截图按钮（📷），与 FPS 叠加框风格一致，一键截取当前游戏画面。
- Chromium 合成器级截图：基于
webContents.capturePage()精确捕获游戏渲染输出，不受 WebGLpreserveDrawingBuffer限制，无黑屏问题。 - 并行双通道输出：点击即自动复制到系统剪贴板，同时弹出保存对话框（PNG 格式，默认时间戳文件名），互不阻塞。
- 设计分辨率感知：运行时探针自动采集
cc.view.getDesignResolutionSize()，预留精确缩放能力。
🎥 游戏录屏
在截图按钮下方提供半透明录屏按钮（📹），支持一键录像并弹出系统保存文件对话框，并在“⚙️ 设置”面板提供专属配置。
- 动态帧率及分辨率缩放：可在设置中调节录制帧率（15、24、30、60 FPS）和分辨率缩放（0.5x、1.0x、1.5x、2.0x）。支持离屏双缓冲 Canvas 后台渲染以规避 WebGL OOM 并输出高清视频。
- 播放器进度条与寻道自动修复 (EBML Duration Fix)：自主重写 WebM EBML 二进制头部时长的注入，100% 解决 MediaRecorder 录屏视频在常规播放器里“无法拖拽、进度条不匹配”的问题。
- 游戏音轨旁路混音：全局代理
AudioNode.prototype.connect。当发声源连接到扬声器时，自动静默双路连接至录制目标，实现音视频轨道在流级的纳秒级完美对齐。 - MP4 转码与安全自愈降级：支持保存为
.webm或.mp4格式。保存 MP4 时优先检测插件根目录下<插件根目录>/bin/win32/ffmpeg.exe（或其他系统环境变量中的 FFmpeg），智能使用 H.264 (libx264) 或内置 MPEG-4 编码器执行转码。若未检测到 FFmpeg，则自动弹窗警告并安全回退保存为已修复进度条的.webm格式。
🔭 全景环境探针
- 动态图集监测 (Dynamic Atlas)：实时查阅框架层 Dynamic Atlas 的详细开关设置与贴图出血 (Bleeding) 策略。
- 动态图集高性能查看器 (High Performance Atlas Viewer)：突破闭包壁垒实现 WebGL 显存级纹理直出。内置受控二维抛拽视口结构 (2D Transform Viewport)，支持超大缓冲纹理 (如 2048x2048) 的平移、无极中心滚轮缩放与首屏自适应显示，根除浏览器的
zoom滚动条塌缩崩溃。 - 2D 物理与碰撞洞察：可随时监测物理系统 (PhysicsManager) 的宏观步进设置与复杂的调试遮罩 (DrawFlags)，以及基础碰撞组件 (CollisionManager) 的轮廓标记渲染开关。
- 加载器快照追踪：直接暴露底层环境下的 Downloader 核心池指标及并发状态。
🎛️ 响应式界面
- 分辨率模拟：内建 32+ 款覆盖全生态的高精度设备分辨率预设（涵盖 iOS/iPadOS 新老阵营、安卓直板全档位、折叠屏全形态以及平板横向视口），完美支撑全场景安全区及越界适配检测，并支持一键横竖屏翻转。
- 预制体资源定位器 (Prefab Asset Locator 🎯)：自动侦测组件所在预制体并提供跳转捷径。
- 响应式渲染诊断面板：流体自适应的三列布局代替硬性百分比，并辅以无原生括号的极简说明文本。
- UI 无极缩放与字号解耦：右侧特设“⚙️ 设置”，支持分别操控全局缩放比例（Zoom）以统御框架，或调节基础字号（Base Font）打磨排版，根除 1080P 或低分辨率下的拥挤死锁。
- 检查器多维排版：支持“横向/纵向”双模式切换，解除固有排版约束；节点树/属性面板尺寸任您拖动并自动持久保存。
- 拖拽排序标签页：自定义标签顺序，重启保持
- 紧凑图标工具栏：极窄面板下也不变形，悬浮提示补全信息
- 防溢出画面：双层 CSS 注入锁死滚动条，横竖屏均无杂物
💾 偏好持久化
分辨率、FPS 叠加框开关、静音状态、面板宽度等设置自动保存至项目级 settings/ 目录，重启即恢复。
🧼 零噪音调试
默认静默所有探针日志，控制台 100% 留给游戏业务。需要排障时设置 window.__MCP_DEBUG__ = true 即可开启底层追踪。
🛡️ 稳定性保障
| 机制 | 说明 |
|---|---|
| 场景校验沙盒 | 以 IPC isEditorSceneActive 为唯一放行条件，未就绪时完全不访问预览服务器，根治 stashScene 崩溃 |
| 后台挂起复原 | ResizeObserver + pendingRefresh 标记，后台切回自动恢复画面 |
| 多实例端口适配 | 核心桥接器端口自动冲突探测并向上扫描，多开项目实例互不串台 |
| IPC 降级容错 | 原生通道失联时自动切入 DOM 轮询，2 秒后静默警告 |
| 单向数据流 | 严格杜绝面板↔探针的 IPC 递归循环 |
| Scene 节点只读 | 自动拦截 cc.Scene 属性访问，防止引擎报错 |
| Electron 跨代容灾 | 针对移除了 remote 模块的高版本引警环境 (Electron 14+) 实施智能垫片防空回退，防止面板因强制解构陷入瘫痪白屏 |
| IPC 克隆防御隔离 | 将对象结构化克隆(structuredClone)降级为跨沙盒的安全 JSON 序列化，杜绝探针在上传不可克隆引用（如原型函数/DOM）时导致整条通信链挂起崩溃 |
📦 项目结构
mcp-inspector-bridge/
├── package.json # 插件清单与脚本定义
├── main.js # Cocos 插件主进程入口
├── dist/ # 编译产物目录
├── src/
│ ├── main.ts # 主进程逻辑 (IPC 注册、 BrowserView 管理)
│ ├── preload.ts # Webview 预加载脚本 (IPC 桥接 + 探针注入)
│ ├── scene-script.ts # 编辑器 Scene 进程脚本 (仅用于少量原生操作)
│ ├── ipc-router.ts # 分发 IPC 与 WebContents 异步交互路由
│ ├── cdp-log-listener.ts # CDP 日志监听器 (BrowserView 原生事件 / Webview CDP debugger / 注入降级)
│ ├── panel/
│ │ ├── index.ts # 面板入口，Vue 3 应用挂载
│ │ ├── index.html # 面板 HTML 模板与样式
│ │ ├── store.ts # 全局响应式状态
│ │ ├── composables/ # Vue Composable 模块
│ │ │ ├── useLayout.ts # 分辨率/布局/拖拽
│ │ │ ├── useGameView.ts # 游戏视图生命周期
│ │ │ ├── useDevTools.ts # DevTools BrowserView 管理
│ │ │ ├── useNodeSystem.ts # 节点选择/属性系统
│ │ │ ├── useProfiler.ts # 性能数据采集
│ │ │ └── useTabs.ts # 标签页排序
│ │ └── components/ # Vue 组件
│ │ ├── NodeTree.ts # 节点树组件
│ │ ├── NodeInspector.ts # 属性检查器
│ │ ├── RenderDebugger.ts # 渲染调试器
│ │ └── WidgetVisualizer.ts # Widget 可视化
│ ├── mcp-client/ # MCP 原生客户端与服务层
│ │ ├── index.ts # MCP Stdio 服务器入口，处理多实例扫描与路由切换
│ │ ├── tools.ts # MCP 工具集定义 (ping, get_active_instances, etc.)
│ │ ├── resources.ts # MCP 资源订阅定义 (scene://hierarchy)
│ │ ├── prompts.ts # MCP 提示词下发策略
│ │ └── configurator.ts # 22+ 款主流 AI 客户端配置自动注入器
│ └── probe/ # 探针模块 (esbuild → dist/probe.js)
│ ├── index.ts # 探针主入口与生命周期
│ ├── crawler.ts # 节点树爬虫
│ ├── highlighter.ts # 高亮渲染层
│ ├── picker.ts # 屏幕拾取器
│ ├── profiler.ts # 帧率/耗时采集
│ ├── memory.ts # 内存资源扫描
│ ├── render-debugger.ts # 渲染管线劫持
│ └── logger.ts # 调试日志门控
├── memory/ # 项目章程文档
└── specs/ # 功能规范文档
💡 开发说明
- 技术栈：TypeScript + Vue 3 + Electron BrowserView + Cocos Creator 2.4.x Extension API
- 构建工具：
tsc(主面板) +esbuild(探针模块 IIFE 打包) - 监听模式：
npm run watch可同时启动 tsc 和 esbuild 的文件监听 - 调试开关：在游戏预览的控制台中执行
window.__MCP_DEBUG__ = true开启探针详细日志 - 详细更新记录：参见 UPDATE_LOG.md
MCP Inspector Bridge Reviews
Login Required
Please log in to share your review and rating for this MCP.
Similar MCP Servers like MCP Inspector Bridge
Explore related MCPs that share similar capabilities and solve comparable challenges
Git
Officialby modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
Zed
OfficialClientby zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
Everything
Officialby modelcontextprotocol
Model Context Protocol Servers
Time
Officialby modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
Cline
OfficialClientby cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
Context7 MCP
Officialby upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
Daytona
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
Continue
OfficialClientby continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
GitHub MCP Server
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.