cocos-web-inspector-mcp 1.0.0 → 2.0.0

package/README.md

@@ -16,11 +16,28 @@ By default it does not edit Cocos game state, launch browsers, expose browser ne
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 22+
 - A Chromium browser started with remote debugging bound to loopback
 - A Cocos Creator 3.x web build served from loopback
 
-Start Chrome on Windows with a disposable profile:
+The quickest start launches a locally installed Chrome with a disposable profile, loopback-only remote debugging, and the game URL, then prints the matching `claude mcp add` command:
+
+```powershell
+npx --yes cocos-web-inspector-mcp launch http://localhost:7456/
+npx --yes cocos-web-inspector-mcp launch http://localhost:7456/ --port 9223 --device iphone-14 --landscape --cpu-slowdown 4 --network fast-3g
+```
+
+`launch` options: `--port` (default `9222`), `--profile <dir>` (default a per-port directory under the system temp folder), `--chrome-path` (or `CHROME_PATH`), and the `cocos_emulate_device` settings `--device`, `--landscape`, `--cpu-slowdown`, and `--network`. Chrome drops emulation when its controlling CDP session closes, so with emulation flags the command stays attached; press Ctrl+C to close Chrome. The MCP server itself never launches a browser.
+
+Check a setup step by step, with a fix for each failure:
+
+```powershell
+npx --yes cocos-web-inspector-mcp doctor --cdp-endpoint http://127.0.0.1:9222
+```
+
+`doctor` checks the endpoint policy, what answers on the port, eligible localhost pages, Cocos 3.x detection, and the active scene. It exits with status 1 when a check fails.
+
+Or start Chrome manually on Windows with a disposable profile:
 
 ```powershell
 chrome.exe --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 --user-data-dir="$env:TEMP\cocos-mcp-profile"
@@ -56,7 +73,7 @@ Endpoint precedence is:
 2. `COCOS_CDP_ENDPOINT`
 3. `http://127.0.0.1:9222`
 
-`--cdp-endpoint` is the only supported CLI option. It identifies the browser CDP endpoint, not a game page URL.
+`--cdp-endpoint` and `--allow-runtime-mutation` are the only server options; `launch` and `doctor` are separate commands. `--cdp-endpoint` identifies the browser CDP endpoint, not a game page URL.
 
 The server uses stdio for MCP. Standard output is reserved for protocol traffic; startup diagnostics are written to standard error.
 
@@ -112,6 +129,8 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 | `cocos_pause` | Pause the Cocos director when its public API supports it. | `pageUrl?` |
 | `cocos_resume` | Resume the Cocos director when its public API supports it. | `pageUrl?` |
 | `cocos_step_frame` | Advance a paused game by 1–60 fixed-delta frames through `cc.game.step`, then stay paused. Fails unless paused first. | `pageUrl?`, `frames?` |
+| `cocos_show_stats` | Show or hide the engine's FPS, draw-call, and triangle overlay through the public `profiler` API. | `pageUrl?`; `visible` boolean |
+| `cocos_emulate_device` | Emulate a mobile device like the Chrome device toolbar: viewport, DPR, touch (mouse input arrives as touch), user agent, and orientation; optionally slow the CPU or network. Settings merge across calls. | `pageUrl?`; `preset?` (`iphone-se`, `iphone-14`, `iphone-14-pro-max`, `pixel-7`, `galaxy-s20`, `ipad-mini`) or `width`+`height` `200..4000` with `deviceScaleFactor?` `1..4` and `mobile?`; `orientation?`; `cpuSlowdown?` `1..20`; `network?` (`online`, `offline`, `slow-3g`, `fast-3g`, `fast-4g`); `reload?`; or `reset: true` |
 | `cocos_scene_tree` | Return a bounded scene tree with node and component summaries. | `pageUrl?`; `maxDepth?` integer `0..20`, default `6`; `maxNodes?` integer `1..5000`, default `500` |
 | `cocos_find_node` | Find nodes with exact or combined bounded filters. | `pageUrl?`; at least one of `uuid`, `name`, `path`, `nameContains`, `componentType`, `active`, `pathPrefix`; `limit?` integer `1..100`, default `20` |
 | `cocos_get_components` | Return bounded component summaries for a node. | `pageUrl?`; `uuid` |
@@ -121,9 +140,10 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 | `cocos_capture_node` | Return an in-memory viewport-clipped image for one visible UI node: PNG, falling back to JPEG when PNG exceeds the response limit; no file is written. | `pageUrl?`; `uuid` |
 | `cocos_get_properties` | Serialize public properties for a node or one component selected by type or UUID. | `pageUrl?`; `uuid`; `componentType?` or `componentUuid?`; `maxDepth?` integer `0..6`, default `3`; `0` returns top-level primitives |
 | `cocos_wait_for_property` | Poll one top-level property until it strictly equals a primitive value or the timeout passes. | `pageUrl?`; `uuid`; `componentType?` or `componentUuid?`; `key`; `equals`; `timeoutMs?` `100..30000`, default `5000`; `intervalMs?` `50..5000`, default `200` |
+| `cocos_get_selection` | Return the node the user last Alt+clicked on the game canvas: node summary and path, viewport box, and the hit stack under the point (topmost first). The first call installs the picker. | `pageUrl?`; `disable?` removes the picker, overlay, and selection |
 | `cocos_highlight_node` | Draw a temporary pointer-transparent overlay around a UI node. | `pageUrl?`; `uuid`; `durationMs?` integer `100..10000`, default `2000` |
 
-`cocos_runtime_diagnostics` does not enable profiler/statistics systems. Render metrics are read from the values `Root` and the GFX device already update every frame (the same sources as `root.fps` and `device.numDrawCalls`), whether or not the profiler is shown; draw calls include the profiler overlay when it is visible. Generic invalid-reference checks still return `UNSUPPORTED_PUBLIC_API`. `cocos_highlight_node` temporarily mutates the page DOM only. It does not mutate the Cocos node/component graph or game state. `cocos_capture_node` clips only to the visible browser viewport, never falls back to full-page capture, bounds captures by the visible viewport and encoded response size rather than a fixed pixel cap, returns PNG (or JPEG fallback) base64 in-memory, downscales down to 0.25× (reported as `scale`) when JPEG quality steps are not enough, and rejects responses still oversized after that. Mutation results provide `before` values for manual inverse calls, but restoration cannot undo lifecycle callbacks or other runtime side effects. `cocos_step_frame` uses the public `cc.game.step` (fixed `game.frameTime` delta); because `director.tick` skips logic while the director is paused, it resumes the director only for the synchronous step call and pauses it again.
+`cocos_runtime_diagnostics` does not enable profiler/statistics systems. Render metrics are read from the values `Root` and the GFX device already update every frame (the same sources as `root.fps` and `device.numDrawCalls`), whether or not the profiler is shown; draw calls include the profiler overlay when it is visible. Generic invalid-reference checks still return `UNSUPPORTED_PUBLIC_API`. `cocos_get_selection` lets the user point at a node instead of describing it: it installs a capture-phase listener that consumes only Alt+clicks on the game canvas, so the game never sees them, and draws a labelled pointer-transparent overlay. It picks the topmost active node with a `UITransform` whose box contains the point; inactive nodes are skipped. The selection is reported `stale` once that node leaves the scene, and the picker disappears on reload. `cocos_highlight_node` temporarily mutates the page DOM only. It does not mutate the Cocos node/component graph or game state. `cocos_capture_node` clips only to the visible browser viewport, never falls back to full-page capture, bounds captures by the visible viewport and encoded response size rather than a fixed pixel cap, returns PNG (or JPEG fallback) base64 in-memory, downscales down to 0.25× (reported as `scale`) when JPEG quality steps are not enough, and rejects responses still oversized after that. Mutation results provide `before` values for manual inverse calls, but restoration cannot undo lifecycle callbacks or other runtime side effects. `cocos_step_frame` uses the public `cc.game.step` (fixed `game.frameTime` delta); because `director.tick` skips logic while the director is paused, it resumes the director only for the synchronous step call and pauses it again. `cocos_show_stats` is an explicit configuration change; while the overlay is visible, draw-call metrics include it. `cocos_emulate_device` holds a CDP session per page: emulation ends on `reset`, when the server disconnects, or when the server process exits, and `reset` also clears viewport overrides set by other CDP clients on that page. Cocos reads the user agent and touch support at startup, so pass `reload: true` for the game to see a new device class. Network throttling only delays traffic; it never reads requests or responses.
 
 ### Page selection
 
@@ -210,6 +230,8 @@ The test suite covers URL policy, CDP connection reuse and recovery, scene trave
 - Bounds/capture unavailable: select a visible UI node with `UITransform`. `INACTIVE` means the node or an ancestor is inactive. Capture is viewport-only, bounded, and never falls back to a full-page screenshot; `RESPONSE_LIMIT` means even a 0.25× JPEG exceeded the response budget, so capture a smaller node.
 - `cocos_snapshot_subtree` returns `RESPONSE_LIMIT` with a partial tree: snapshot a deeper node, or lower `maxDepth`.
 - `cocos_step_frame` returns `INVALID_MUTATION`: call `cocos_pause` first.
+- `doctor` reports HTTP 404 on the port: Chrome's built-in remote debugging holds it; see `CDP_UNAVAILABLE` above.
+- Game still behaves like desktop after `cocos_emulate_device`: call it again with `reload: true`; Cocos detects mobile and touch at startup.
 - Render metrics `fps` reads 0: the engine publishes FPS once per elapsed second, so read again after the scene has run for a second.
 
 ## Release and compatibility

package/dist/src/bridge.d.ts

@@ -64,6 +64,16 @@ export type BridgeRequest = {
 } | {
     action: 'stepFrame';
     frames?: number | undefined;
+} | {
+    action: 'showStats';
+    visible: boolean;
+} | {
+    action: 'selection';
+    disable?: boolean | undefined;
+} | {
+    action: 'pickAt';
+    x: number;
+    y: number;
 };
 type Vector3 = {
     x: number;
@@ -93,6 +103,99 @@ type PropertyValue = boolean | number | string | {
 export declare function runBridge(page: Page, request: BridgeRequest): Promise<unknown>;
 export declare function captureNode(page: Page, uuid: string): Promise<unknown>;
 export declare function clickNode(page: Page, uuid: string): Promise<unknown>;
+export declare const devicePresets: {
+    readonly 'iphone-se': {
+        readonly width: 375;
+        readonly height: 667;
+        readonly deviceScaleFactor: 2;
+        readonly mobile: true;
+        readonly userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
+    };
+    readonly 'iphone-14': {
+        readonly width: 390;
+        readonly height: 844;
+        readonly deviceScaleFactor: 3;
+        readonly mobile: true;
+        readonly userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
+    };
+    readonly 'iphone-14-pro-max': {
+        readonly width: 430;
+        readonly height: 932;
+        readonly deviceScaleFactor: 3;
+        readonly mobile: true;
+        readonly userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
+    };
+    readonly 'pixel-7': {
+        readonly width: 412;
+        readonly height: 915;
+        readonly deviceScaleFactor: 2.625;
+        readonly mobile: true;
+        readonly userAgent: string;
+    };
+    readonly 'galaxy-s20': {
+        readonly width: 360;
+        readonly height: 800;
+        readonly deviceScaleFactor: 3;
+        readonly mobile: true;
+        readonly userAgent: string;
+    };
+    readonly 'ipad-mini': {
+        readonly width: 768;
+        readonly height: 1024;
+        readonly deviceScaleFactor: 2;
+        readonly mobile: true;
+        readonly userAgent: "Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
+    };
+};
+export type DevicePreset = keyof typeof devicePresets;
+export declare const devicePresetNames: [DevicePreset, ...DevicePreset[]];
+declare const networkProfiles: {
+    readonly online: {
+        readonly offline: false;
+        readonly latency: 0;
+        readonly downloadThroughput: -1;
+        readonly uploadThroughput: -1;
+    };
+    readonly offline: {
+        readonly offline: true;
+        readonly latency: 0;
+        readonly downloadThroughput: -1;
+        readonly uploadThroughput: -1;
+    };
+    readonly 'slow-3g': {
+        readonly offline: false;
+        readonly latency: 2000;
+        readonly downloadThroughput: 50000;
+        readonly uploadThroughput: 50000;
+    };
+    readonly 'fast-3g': {
+        readonly offline: false;
+        readonly latency: 562.5;
+        readonly downloadThroughput: 180000;
+        readonly uploadThroughput: 84375;
+    };
+    readonly 'fast-4g': {
+        readonly offline: false;
+        readonly latency: 165;
+        readonly downloadThroughput: 1012500;
+        readonly uploadThroughput: 168750;
+    };
+};
+export type NetworkProfile = keyof typeof networkProfiles;
+export declare const networkProfileNames: [NetworkProfile, ...NetworkProfile[]];
+export type EmulationRequest = {
+    reset?: boolean | undefined;
+    preset?: DevicePreset | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    deviceScaleFactor?: number | undefined;
+    mobile?: boolean | undefined;
+    orientation?: 'portrait' | 'landscape' | undefined;
+    cpuSlowdown?: number | undefined;
+    network?: NetworkProfile | undefined;
+    reload?: boolean | undefined;
+};
+export declare function emulateDevice(page: Page, request: EmulationRequest): Promise<unknown>;
 export declare function inspectCocosPage(): unknown;
 export declare function inspectCocos(request: BridgeRequest): unknown;
 export {};

package/dist/src/bridge.js

@@ -48,6 +48,90 @@ export async function clickNode(page, uuid) {
     await page.mouse.click(point.x, point.y);
     return { clicked: true, target: { nodeUuid: uuid }, point, runtimeOnly: true };
 }
+const IOS_UA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
+const IPAD_UA = 'Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
+const androidUa = (model) => `Mozilla/5.0 (Linux; Android 14; ${model}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36`;
+export const devicePresets = {
+    'iphone-se': { width: 375, height: 667, deviceScaleFactor: 2, mobile: true, userAgent: IOS_UA },
+    'iphone-14': { width: 390, height: 844, deviceScaleFactor: 3, mobile: true, userAgent: IOS_UA },
+    'iphone-14-pro-max': { width: 430, height: 932, deviceScaleFactor: 3, mobile: true, userAgent: IOS_UA },
+    'pixel-7': { width: 412, height: 915, deviceScaleFactor: 2.625, mobile: true, userAgent: androidUa('Pixel 7') },
+    'galaxy-s20': { width: 360, height: 800, deviceScaleFactor: 3, mobile: true, userAgent: androidUa('SM-G981B') },
+    'ipad-mini': { width: 768, height: 1024, deviceScaleFactor: 2, mobile: true, userAgent: IPAD_UA },
+};
+export const devicePresetNames = Object.keys(devicePresets);
+// Chrome DevTools throttling presets, in bytes per second and milliseconds.
+const networkProfiles = {
+    online: { offline: false, latency: 0, downloadThroughput: -1, uploadThroughput: -1 },
+    offline: { offline: true, latency: 0, downloadThroughput: -1, uploadThroughput: -1 },
+    'slow-3g': { offline: false, latency: 2_000, downloadThroughput: 50_000, uploadThroughput: 50_000 },
+    'fast-3g': { offline: false, latency: 562.5, downloadThroughput: 180_000, uploadThroughput: 84_375 },
+    'fast-4g': { offline: false, latency: 165, downloadThroughput: 1_012_500, uploadThroughput: 168_750 },
+};
+export const networkProfileNames = Object.keys(networkProfiles);
+// Chrome drops every override when the owning CDP session detaches, so the session lives as long as the emulation.
+const emulations = new WeakMap();
+export async function emulateDevice(page, request) {
+    const current = emulations.get(page);
+    const before = current?.state ?? {};
+    let after = {};
+    if (request.reset) {
+        emulations.delete(page);
+        if (current) {
+            await applyEmulation(current.session, {});
+            await current.session.detach().catch(() => { });
+        }
+    }
+    else {
+        after = { ...before };
+        const base = request.preset ? { preset: request.preset, ...devicePresets[request.preset] }
+            : request.width !== undefined && request.height !== undefined ? { width: request.width, height: request.height, deviceScaleFactor: request.deviceScaleFactor ?? 1, mobile: request.mobile ?? false }
+                : before.device;
+        if (request.orientation && !base)
+            throw new Error('Invalid mutation: orientation needs a preset or width and height');
+        if (base)
+            after.device = { ...base, orientation: request.orientation ?? (base === before.device ? before.device.orientation : 'portrait') };
+        if (request.cpuSlowdown !== undefined)
+            after.cpuSlowdown = request.cpuSlowdown;
+        if (request.network)
+            after.network = request.network;
+        const session = current?.session ?? await page.context().newCDPSession(page);
+        emulations.set(page, { session, state: after });
+        await applyEmulation(session, after);
+    }
+    if (request.reload)
+        await page.reload();
+    const report = (state) => {
+        if (!state.device)
+            return state;
+        const { userAgent: _userAgent, ...device } = state.device;
+        const landscape = device.orientation === 'landscape';
+        return { ...state, device: { ...device, width: landscape ? device.height : device.width, height: landscape ? device.width : device.height } };
+    };
+    return { changed: JSON.stringify(before) !== JSON.stringify(after), target: {}, before: report(before), after: report(after), reloaded: !!request.reload, runtimeOnly: true };
+}
+async function applyEmulation(session, state) {
+    const device = state.device;
+    if (device) {
+        const landscape = device.orientation === 'landscape';
+        await session.send('Emulation.setDeviceMetricsOverride', {
+            width: landscape ? device.height : device.width,
+            height: landscape ? device.width : device.height,
+            deviceScaleFactor: device.deviceScaleFactor,
+            mobile: device.mobile,
+            screenOrientation: { type: landscape ? 'landscapePrimary' : 'portraitPrimary', angle: landscape ? 90 : 0 },
+        });
+    }
+    else
+        await session.send('Emulation.clearDeviceMetricsOverride');
+    const touch = !!device?.mobile;
+    await session.send('Emulation.setTouchEmulationEnabled', touch ? { enabled: true, maxTouchPoints: 5 } : { enabled: false });
+    // Like the Chrome device toolbar: mouse input arrives as touch, which mobile Cocos builds listen for.
+    await session.send('Emulation.setEmitTouchEventsForMouse', { enabled: touch, configuration: 'mobile' });
+    await session.send('Emulation.setUserAgentOverride', { userAgent: device?.userAgent ?? (await session.send('Browser.getVersion')).userAgent });
+    await session.send('Emulation.setCPUThrottlingRate', { rate: state.cpuSlowdown ?? 1 });
+    await session.send('Network.emulateNetworkConditions', networkProfiles[state.network ?? 'online']);
+}
 export function inspectCocosPage() {
     const root = globalThis;
     const cc = root.cc ?? root.CC;
@@ -354,6 +438,107 @@ export function inspectCocos(request) {
             truncationReasons: directChildren.length > 200 || nodeComponents.length > 200 ? ['NODE_LIMIT'] : [],
         };
     }
+    if (request.action === 'pickAt') {
+        // Cocos draws 2D nodes in pre-order, so the last hit in traversal order is the topmost one.
+        const hits = [];
+        walk((node, path) => {
+            if (node === scene || node.activeInHierarchy === false)
+                return;
+            const bounds = nodeBounds(node);
+            const box = bounds.available ? bounds.viewport : undefined;
+            if (box && request.x >= box.x && request.x <= box.x + box.width && request.y >= box.y && request.y <= box.y + box.height)
+                hits.push({ node, path, viewport: box });
+        });
+        const overlay = root.__cocosWebInspectorSelectionOverlay;
+        const top = hits.at(-1);
+        if (!top) {
+            overlay?.remove();
+            return { version, point: { x: request.x, y: request.y }, node: null };
+        }
+        const selection = {
+            point: { x: request.x, y: request.y },
+            node: { ...summary(top.node), path: top.path },
+            viewport: top.viewport,
+            // Parents and siblings under the point, topmost first, for when the pick lands on a child.
+            stack: hits.slice(-10).reverse().map(hit => ({ uuid: String(hit.node.uuid ?? ''), name: String(hit.node.name ?? '').slice(0, 500), path: hit.path })),
+        };
+        const document = root.document;
+        if (document?.body) {
+            let box = overlay;
+            if (!box?.isConnected) {
+                box = document.createElement('div');
+                box.appendChild(document.createElement('span'));
+                root.__cocosWebInspectorSelectionOverlay = box;
+                document.body.appendChild(box);
+            }
+            Object.assign(box.style, {
+                position: 'fixed', pointerEvents: 'none', zIndex: '2147483647', boxSizing: 'border-box',
+                border: '2px solid #ff9f1a', background: 'rgba(255, 159, 26, 0.15)',
+                left: `${top.viewport.x}px`, top: `${top.viewport.y}px`, width: `${top.viewport.width}px`, height: `${top.viewport.height}px`,
+            });
+            const label = box.firstElementChild;
+            Object.assign(label.style, {
+                position: 'absolute', left: '0', bottom: '100%', maxWidth: '480px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+                font: '12px/1.4 monospace', color: '#1a1a1a', background: '#ff9f1a', padding: '1px 4px',
+            });
+            label.textContent = `${selection.node.name} · ${selection.node.path.slice(0, 200)} · ${selection.node.uuid.slice(0, 8)}`;
+        }
+        return selection;
+    }
+    if (request.action === 'selection') {
+        const events = ['pointerdown', 'pointerup', 'mousedown', 'mouseup', 'click', 'touchstart', 'touchend'];
+        const installed = root.__cocosWebInspectorPicker;
+        if (request.disable) {
+            if (installed)
+                for (const type of events)
+                    root.removeEventListener?.(type, installed, true);
+            root.__cocosWebInspectorPicker = undefined;
+            root.__cocosWebInspectorSelection = undefined;
+            root.__cocosWebInspectorSelectionOverlay?.remove();
+            root.__cocosWebInspectorSelectionOverlay = undefined;
+            return { version, picker: false, selection: null };
+        }
+        if (!installed && typeof root.addEventListener === 'function') {
+            const picker = (event) => {
+                const pointer = event;
+                const canvas = cc.game?.canvas ?? root.document?.querySelector('#GameCanvas');
+                if (!pointer.altKey || event.target !== canvas)
+                    return;
+                // Alt+click selects; the game must not also receive it as a tap.
+                event.preventDefault();
+                event.stopImmediatePropagation();
+                if (event.type !== 'pointerdown')
+                    return;
+                try {
+                    // The named function expression is in scope inside the page, so the picker reruns the bridge with a fresh scene.
+                    root.__cocosWebInspectorSelection = inspectCocos({ action: 'pickAt', x: pointer.clientX, y: pointer.clientY });
+                }
+                catch (error) {
+                    root.__cocosWebInspectorSelection = { error: String(error instanceof Error ? error.message : error).slice(0, 500) };
+                }
+            };
+            for (const type of events)
+                root.addEventListener(type, picker, true);
+            root.__cocosWebInspectorPicker = picker;
+        }
+        const selection = root.__cocosWebInspectorSelection;
+        let stale = false;
+        if (selection?.node?.uuid) {
+            try {
+                findByUuid(selection.node.uuid);
+            }
+            catch {
+                stale = true;
+            }
+        }
+        return {
+            version,
+            picker: true,
+            selection: selection ?? null,
+            ...(stale ? { stale: true } : {}),
+            ...(selection ? {} : { hint: 'Alt+click a node on the game canvas, then call again' }),
+        };
+    }
     if (request.action === 'snapshotSubtree') {
         const rootNode = findByUuid(request.uuid);
         const maxDepth = Math.min(Math.max(request.maxDepth ?? 6, 0), 20);
@@ -434,6 +619,10 @@ export function inspectCocos(request) {
                 return undefined;
             // Cocos 3.x exposes uuid/children/name as accessors; read their backing fields instead.
             const uuid = dataProperty(value, 'uuid') ?? dataProperty(value, '_id');
+            // CCObject.isValid is a getter over this flag (Destroyed = 1 << 0 in 3.6-3.8); destroy also nulls _children/node.
+            const flags = dataProperty(value, '_objFlags');
+            if (reference && typeof flags === 'number' && flags & 1)
+                return { $type: typeof cc.Node === 'function' && value instanceof cc.Node ? 'Node' : componentName(value), uuid: String(uuid ?? ''), destroyed: true };
             if (reference && uuid && Array.isArray(dataProperty(value, 'children') ?? dataProperty(value, '_children'))) {
                 return { $type: 'Node', uuid: String(uuid), name: String(dataProperty(value, 'name') ?? dataProperty(value, '_name') ?? '').slice(0, 500) };
             }
@@ -597,6 +786,16 @@ export function inspectCocos(request) {
         const after = cc.director.getTotalFrames();
         return { changed: after !== before, target: {}, before: { totalFrames: before }, after: { totalFrames: after }, runtimeOnly: true };
     }
+    if (request.action === 'showStats') {
+        const profiler = cc.profiler;
+        if (typeof profiler?.isShowingStats !== 'function' || typeof profiler.showStats !== 'function' || typeof profiler.hideStats !== 'function')
+            invalidMutation('profiler stats API is unavailable');
+        const before = Boolean(profiler.isShowingStats());
+        if (before !== request.visible)
+            request.visible ? profiler.showStats() : profiler.hideStats();
+        const after = Boolean(profiler.isShowingStats());
+        return { changed: before !== after, target: {}, before: { visible: before }, after: { visible: after }, runtimeOnly: true };
+    }
     if (request.action === 'setNodeActive') {
         const node = findByUuid(request.uuid);
         const before = node.active !== false;

package/dist/src/cli.d.ts

@@ -0,0 +1 @@
+export declare const commands: Record<string, (args: string[]) => Promise<void>>;

package/dist/src/cli.js

@@ -0,0 +1,189 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { chromium } from 'playwright-core';
+import { BrowserConnection, InspectorError, sanitizeUrl, validateLocalUrl } from './browser.js';
+import { devicePresetNames, emulateDevice, inspectCocosPage, networkProfileNames } from './bridge.js';
+const write = (line) => process.stdout.write(`${line}\n`);
+function flags(args, names, booleans = []) {
+    const values = {};
+    const positional = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (booleans.includes(arg))
+            values[arg] = 'true';
+        else if (names.includes(arg)) {
+            const value = args[++index];
+            if (!value)
+                throw new Error(`${arg} requires a value`);
+            values[arg] = value;
+        }
+        else if (arg.startsWith('-'))
+            throw new Error(`Unknown argument: ${arg}`);
+        else
+            positional.push(arg);
+    }
+    return { values, positional };
+}
+function chromePath(override) {
+    const candidates = override ? [override] : process.env.CHROME_PATH ? [process.env.CHROME_PATH] : process.platform === 'darwin'
+        ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium']
+        : process.platform === 'win32'
+            ? [process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA].filter(Boolean).map(base => join(base, 'Google', 'Chrome', 'Application', 'chrome.exe'))
+            : ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+    const found = candidates.find(candidate => existsSync(candidate));
+    if (!found)
+        throw new Error(`Chrome not found (checked ${candidates.join(', ')}); pass --chrome-path or set CHROME_PATH`);
+    return found;
+}
+async function probe(endpoint) {
+    try {
+        const response = await fetch(new URL('/json/version', endpoint), { signal: AbortSignal.timeout(3_000) });
+        if (!response.ok)
+            return { status: 'http', code: response.status };
+        return { status: 'ok', browser: String((await response.json()).Browser ?? 'unknown') };
+    }
+    catch (error) {
+        return { status: 'down', message: error instanceof Error ? (error.cause instanceof Error ? error.cause.message : error.message) : 'unknown error' };
+    }
+}
+function listener(port) {
+    if (process.platform === 'win32')
+        return undefined;
+    try {
+        return execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n')[1]?.split(/\s+/).slice(0, 2).join(' pid ');
+    }
+    catch {
+        return undefined;
+    }
+}
+async function launch(args) {
+    const { values, positional } = flags(args, ['--port', '--profile', '--chrome-path', '--device', '--cpu-slowdown', '--network'], ['--landscape']);
+    if (positional.length !== 1)
+        throw new Error('Usage: cocos-web-inspector-mcp launch <url> [--port 9222] [--profile <dir>] [--chrome-path <path>] [--device <preset>] [--landscape] [--cpu-slowdown <1-20>] [--network <profile>]');
+    const url = validateLocalUrl(positional[0], true).href;
+    const port = Number(values['--port'] ?? 9222);
+    if (!Number.isInteger(port) || port < 1_024 || port > 65_535)
+        throw new Error('--port must be an integer from 1024 to 65535');
+    const device = values['--device'];
+    if (device && !devicePresetNames.includes(device))
+        throw new Error(`--device must be one of: ${devicePresetNames.join(', ')}`);
+    const network = values['--network'];
+    if (network && !networkProfileNames.includes(network))
+        throw new Error(`--network must be one of: ${networkProfileNames.join(', ')}`);
+    const cpuSlowdown = values['--cpu-slowdown'] === undefined ? undefined : Number(values['--cpu-slowdown']);
+    if (cpuSlowdown !== undefined && !(cpuSlowdown >= 1 && cpuSlowdown <= 20))
+        throw new Error('--cpu-slowdown must be from 1 to 20');
+    if (values['--landscape'] && !device)
+        throw new Error('--landscape needs --device');
+    const endpoint = `http://127.0.0.1:${port}`;
+    if ((await probe(endpoint)).status !== 'down')
+        throw new Error(`Port ${port} is already in use${listener(String(port)) ? ` by ${listener(String(port))}` : ''}; pass --port or stop that process`);
+    const profile = values['--profile'] ?? join(tmpdir(), `cocos-web-inspector-profile-${port}`);
+    const chrome = spawn(chromePath(values['--chrome-path']), [
+        '--remote-debugging-address=127.0.0.1',
+        `--remote-debugging-port=${port}`,
+        `--user-data-dir=${profile}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        url,
+    ], { stdio: 'ignore' });
+    const exited = new Promise(resolve => chrome.once('exit', () => resolve()));
+    const failed = new Promise((_, reject) => chrome.once('error', reject));
+    const deadline = Date.now() + 15_000;
+    while ((await Promise.race([probe(endpoint), failed])).status !== 'ok') {
+        if (chrome.exitCode !== null || Date.now() > deadline)
+            throw new Error(`Chrome did not open remote debugging on port ${port}`);
+        await new Promise(resolve => setTimeout(resolve, 200));
+    }
+    const emulating = device || cpuSlowdown !== undefined || network;
+    if (emulating) {
+        // Chrome drops emulation when its CDP session closes, so this process keeps the connection open.
+        const browser = await chromium.connectOverCDP(endpoint);
+        const deadlinePage = Date.now() + 10_000;
+        let page = browser.contexts().flatMap(context => context.pages()).find(candidate => candidate.url() === url);
+        while (!page && Date.now() < deadlinePage) {
+            await new Promise(resolve => setTimeout(resolve, 200));
+            page = browser.contexts().flatMap(context => context.pages()).find(candidate => candidate.url() === url);
+        }
+        if (!page)
+            throw new Error(`Page ${sanitizeUrl(url)} did not open`);
+        await emulateDevice(page, { preset: device, orientation: values['--landscape'] ? 'landscape' : undefined, cpuSlowdown, network, reload: true });
+    }
+    write(`Chrome is running with loopback remote debugging at ${endpoint}`);
+    write(`Profile: ${profile}`);
+    if (emulating)
+        write(`Emulation: ${[device && `${device}${values['--landscape'] ? ' landscape' : ''}`, cpuSlowdown && `CPU ${cpuSlowdown}x slower`, network].filter(Boolean).join(', ')} (ends when this command stops)`);
+    write('Add the MCP server to Claude Code with:');
+    write(`  claude mcp add cocos-web-inspector -- npx -y cocos-web-inspector-mcp --cdp-endpoint ${endpoint}`);
+    write('Press Ctrl+C to close Chrome.');
+    const stop = () => chrome.kill();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    await exited;
+    process.exit(0);
+}
+async function doctor(args) {
+    const { values, positional } = flags(args, ['--cdp-endpoint']);
+    if (positional.length)
+        throw new Error('Usage: cocos-web-inspector-mcp doctor [--cdp-endpoint <url>]');
+    const endpoint = values['--cdp-endpoint'] ?? process.env.COCOS_CDP_ENDPOINT ?? 'http://127.0.0.1:9222';
+    let failed = false;
+    const pass = (message) => write(`ok    ${message}`);
+    const fail = (code, message, fix) => {
+        failed = true;
+        write(`FAIL  ${code}: ${message}\n      Fix: ${fix}`);
+    };
+    let url;
+    try {
+        url = validateLocalUrl(endpoint);
+        pass(`CDP endpoint ${url.origin} is loopback`);
+    }
+    catch (error) {
+        fail('CDP_UNAVAILABLE', `${error instanceof Error ? error.message : 'Invalid endpoint'}: ${sanitizeUrl(endpoint)}`, 'use an http://127.0.0.1:<port> endpoint');
+        process.exitCode = 1;
+        return;
+    }
+    const port = url.port || (url.protocol === 'https:' || url.protocol === 'wss:' ? '443' : '80');
+    const owner = listener(port);
+    const httpEndpoint = url.origin.replace(/^ws/, 'http');
+    const probed = await probe(httpEndpoint);
+    if (probed.status === 'down')
+        fail('CDP_UNAVAILABLE', `nothing answers on port ${port} (${probed.message})`, `run: npx cocos-web-inspector-mcp launch <game-url> --port ${port}`);
+    else if (probed.status === 'http')
+        fail('CDP_UNAVAILABLE', `port ${port} answers HTTP ${probed.code}${owner ? ` (${owner})` : ''}`, probed.code === 404 ? 'Chrome built-in remote debugging (chrome://inspect/#remote-debugging) holds this port; turn it off or launch on another --port' : 'stop the process holding this port or use another port');
+    else
+        pass(`${probed.browser} answers on port ${port}${owner ? ` (${owner})` : ''}`);
+    const connection = new BrowserConnection(endpoint);
+    try {
+        if (probed.status === 'ok' || probed.status === 'http' && probed.code === 404) {
+            const pages = await connection.pages();
+            if (!pages.length)
+                fail('NO_LOCAL_PAGE', 'no localhost page is open', 'open the game at http://localhost:<port>/ in that Chrome');
+            else
+                pass(`${pages.length} localhost page${pages.length === 1 ? '' : 's'} open`);
+            for (const page of pages.slice(0, 10)) {
+                const info = await page.evaluate(inspectCocosPage).catch(() => undefined);
+                const name = sanitizeUrl(page.url());
+                if (!info?.cocos?.detected)
+                    fail('COCOS_NOT_FOUND', `no Cocos Creator 3.x runtime on ${name}`, 'wait for the build to load, or check that it is a Cocos Creator 3.x web build');
+                else if (!info.cocos.sceneName)
+                    fail('SCENE_NOT_READY', `Cocos ${info.cocos.version} on ${name} has no active scene yet`, 'wait for the first scene to load');
+                else
+                    pass(`Cocos ${info.cocos.version}, scene "${info.cocos.sceneName}" on ${name}`);
+            }
+            if (pages.length > 1)
+                write(`note  ${pages.length} pages: MCP tools need pageUrl (see cocos_list_pages)`);
+        }
+    }
+    catch (error) {
+        fail(error instanceof InspectorError ? error.code : 'CDP_UNAVAILABLE', error instanceof Error ? error.message : 'connection failed', 'restart Chrome with --remote-debugging-port, or use the launch command');
+    }
+    finally {
+        await connection.close().catch(() => { });
+    }
+    if (failed)
+        process.exitCode = 1;
+}
+export const commands = { launch, doctor };

package/dist/src/index.js

@@ -24,6 +24,9 @@ function optionsFromArgs(args) {
     return { endpoint, allowRuntimeMutation };
 }
 async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    if (command === 'launch' || command === 'doctor')
+        return (await import('./cli.js')).commands[command](rest);
     const options = optionsFromArgs(process.argv.slice(2));
     const browser = new BrowserConnection(options.endpoint);
     const server = createServer(browser, { allowRuntimeMutation: options.allowRuntimeMutation });

package/dist/src/server.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { InspectorError, sanitizeUrl } from './browser.js';
-import { captureNode, clickNode, inspectCocosPage, runBridge } from './bridge.js';
+import { captureNode, clickNode, devicePresetNames, emulateDevice, inspectCocosPage, networkProfileNames, runBridge } from './bridge.js';
 const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 const pageUrl = z.url().optional();
 const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
@@ -195,7 +195,46 @@ export function createServer(browser, options = {}) {
             inputSchema: z.object({ pageUrl, frames: z.number().int().min(1).max(60).optional() }).strict(),
             annotations: { ...runtimeMutation, idempotentHint: false },
         }, input => execute({ action: 'stepFrame', frames: input.frames }, input.pageUrl));
+        server.registerTool('cocos_show_stats', {
+            description: 'Show or hide the Cocos profiler overlay (FPS, draw calls, triangles) through the public profiler API.',
+            inputSchema: z.object({ pageUrl, visible: z.boolean() }).strict(),
+            annotations: runtimeMutation,
+        }, input => execute({ action: 'showStats', visible: input.visible }, input.pageUrl));
+        server.registerTool('cocos_emulate_device', {
+            description: 'Emulate a mobile device (viewport, DPR, touch, user agent, orientation) and optionally slow the CPU or network, like the Chrome device toolbar. Settings merge across calls and last until reset or server disconnect; reload lets the game re-detect touch and user agent.',
+            inputSchema: z.object({
+                pageUrl,
+                reset: z.boolean().optional(),
+                preset: z.enum(devicePresetNames).optional(),
+                width: z.number().int().min(200).max(4_000).optional(),
+                height: z.number().int().min(200).max(4_000).optional(),
+                deviceScaleFactor: z.number().min(1).max(4).optional(),
+                mobile: z.boolean().optional(),
+                orientation: z.enum(['portrait', 'landscape']).optional(),
+                cpuSlowdown: z.number().min(1).max(20).optional(),
+                network: z.enum(networkProfileNames).optional(),
+                reload: z.boolean().optional(),
+            }).strict()
+                .refine(value => (value.width === undefined) === (value.height === undefined), 'Provide width and height together')
+                .refine(value => !(value.preset && value.width !== undefined), 'Provide preset or width and height, not both')
+                .refine(value => value.width !== undefined || (value.deviceScaleFactor === undefined && value.mobile === undefined), 'deviceScaleFactor and mobile need width and height')
+                .refine(value => !value.reset || Object.keys(value).every(key => ['pageUrl', 'reset', 'reload'].includes(key)), 'reset accepts only pageUrl and reload'),
+            annotations: { ...runtimeMutation, idempotentHint: false },
+        }, async (input) => {
+            try {
+                return response(await emulateDevice(await browser.page(input.pageUrl), input));
+            }
+            catch (error) {
+                return failure(error);
+            }
+        });
     }
+    server.registerTool('cocos_get_selection', {
+        description: 'Return the node the user last Alt+clicked on the game canvas. The first call installs the picker; Alt+clicks are kept from the game, other input is untouched. disable removes the picker, overlay, and selection.',
+        inputSchema: z.object({ pageUrl, disable: z.boolean().optional() }).strict(),
+        // Installs a page-level listener and DOM overlay only; never touches the Cocos graph.
+        annotations: { ...readOnly, readOnlyHint: false },
+    }, input => execute({ action: 'selection', disable: input.disable }, input.pageUrl));
     server.registerTool('cocos_highlight_node', {
         description: 'Temporarily draw a pointer-transparent DOM overlay around one Cocos UI node.',
         inputSchema: z.object({ pageUrl, uuid: z.string().min(1), durationMs: z.number().int().min(100).max(10_000).optional() }).strict(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cocos-web-inspector-mcp",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "MCP server to inspect and debug Cocos Creator 3.x web builds in local Chromium over CDP",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsc",