cocos-web-inspector-mcp 0.1.5 → 0.1.6

package/README.md

@@ -108,6 +108,7 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 | `cocos_set_node_active` | Set one node's active state. Registered only with `--allow-runtime-mutation`; returns before/after state. | `pageUrl?`; `uuid`; `active` boolean |
 | `cocos_set_transform` | Update supplied position, rotation, and/or scale fields for one node. | `pageUrl?`; `uuid`; `position?`, `rotation?`, `scale?` finite vectors |
 | `cocos_set_property` | Update one bounded public component data property. | `pageUrl?`; node `uuid`; `componentUuid`; `key`; primitive/vector/size/color `value` matching current shape |
+| `cocos_click_node` | Dispatch a real mouse click at the visible center of one UI node so Button/touch handlers run. Registered only with `--allow-runtime-mutation`. | `pageUrl?`; `uuid` |
 | `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_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` |
@@ -116,11 +117,12 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 | `cocos_get_node` | Return one node's path, parent, bounded direct children, and components. | `pageUrl?`; `uuid` |
 | `cocos_snapshot_subtree` | Return a bounded stateless hierarchy snapshot; clients compare snapshots. | `pageUrl?`; `uuid`; `maxDepth?`; `maxNodes?` |
 | `cocos_get_node_bounds` | Return bounded canvas/viewport bounds, anchor, world position, and visibility for one UI node. | `pageUrl?`; `uuid` |
-| `cocos_capture_node` | Return an in-memory viewport-clipped PNG for one visible UI node; 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` |
+| `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_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. FPS, frame time, draw calls, triangles, and generic invalid-reference checks return `UNSUPPORTED_PUBLIC_API` until stable passive public Cocos APIs are verified. `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, limits captures to 1,024 × 1,024 CSS pixels / 1,048,576 total pixels, returns PNG base64 in-memory, and rejects oversized responses. Mutation results provide `before` values for manual inverse calls, but restoration cannot undo lifecycle callbacks or other runtime side effects. Frame stepping is unsupported pending a verified public Cocos API compatibility matrix.
+`cocos_runtime_diagnostics` does not enable profiler/statistics systems. FPS, frame time, draw calls, triangles, and generic invalid-reference checks return `UNSUPPORTED_PUBLIC_API` until stable passive public Cocos APIs are verified. `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, limits captures to 1,024 × 1,024 CSS pixels / 1,048,576 total pixels, returns PNG (or JPEG fallback) base64 in-memory, and rejects responses still oversized after JPEG quality steps. Mutation results provide `before` values for manual inverse calls, but restoration cannot undo lifecycle callbacks or other runtime side effects. Frame stepping is unsupported pending a verified public Cocos API compatibility matrix.
 
 ### Page selection
 
@@ -129,6 +131,14 @@ Eligible game pages must use HTTP or HTTPS on a loopback host.
 - With one eligible page, `pageUrl` may be omitted.
 - With multiple eligible pages, `pageUrl` is required.
 - `pageUrl` must exactly match the full URL reported by the browser, including path, query, and fragment.
+- Tabs with identical URLs cannot be told apart; close duplicates before inspecting.
+
+Every MCP client pointed at the same CDP endpoint sees every loopback tab in that browser. When several projects run at once, give each project its own Chromium, port, and profile, then configure the server at project scope:
+
+```sh
+chrome --remote-debugging-address=127.0.0.1 --remote-debugging-port=9223 --user-data-dir="$HOME/.cocos-mcp/project-a"
+claude mcp add cocos-web-inspector npx -- -y cocos-web-inspector-mcp@latest --cdp-endpoint http://127.0.0.1:9223
+```
 
 Tool validation, connection, selection, and inspection failures are returned as MCP tool errors. Operational errors include JSON `structuredContent` and text content with stable `code` and `message` fields. Current codes include `CDP_UNAVAILABLE`, `NO_LOCAL_PAGE`, `MULTIPLE_PAGES`, `PAGE_NOT_FOUND`, `COCOS_NOT_FOUND`, `SCENE_NOT_READY`, `NODE_NOT_FOUND`, and `COMPONENT_NOT_FOUND`.
 
@@ -169,6 +179,8 @@ Inspection still executes fixed bridge code inside the attached page. Treat all
 
 Property serialization skips accessors, private-prefixed keys, functions, symbols, cycles, and secret-like key names such as tokens, cookies, passwords, credentials, authorization data, and storage.
 
+An allowlist of display fields is read directly from their backing data fields, still without invoking getters: `Label.string`, `RichText.string`, `Button.interactable`, `Toggle.isChecked`, and `Sprite.spriteFrame` (name and UUID only).
+
 These controls reduce accidental disclosure; they do not make CDP a complete security boundary. Always:
 
 - Use a disposable browser profile.
@@ -190,8 +202,8 @@ The test suite covers URL policy, CDP connection reuse and recovery, scene trave
 
 ## Troubleshooting
 
-- `CDP_UNAVAILABLE`: start Chromium with loopback remote debugging; rerun `npm run install:chromium` for development tests.
-- `MULTIPLE_PAGES`: call `cocos_list_pages`, then pass the exact reported `pageUrl`.
+- `CDP_UNAVAILABLE`: start Chromium with loopback remote debugging; rerun `npm run install:chromium` for development tests. A `404` usually means Chrome's built-in remote debugging toggle (`chrome://inspect/#remote-debugging`) holds the port; turn it off or use another port, and check listeners with `lsof -nP -iTCP:9222 -sTCP:LISTEN`. When `127.0.0.1` returns 404 or refuses the connection, the server retries `[::1]` on the same port.
+- `MULTIPLE_PAGES`: call `cocos_list_pages`, then pass the exact reported `pageUrl`. If tabs share one URL, close duplicates or use a separate Chromium per project (see Page selection).
 - `COCOS_NOT_FOUND` or `SCENE_NOT_READY`: wait for the web build to finish loading; use `cocos_runtime_info` after the active scene exists.
 - Runtime mutation tools missing: restart the server with `--allow-runtime-mutation`; a tool call cannot enable this mode.
 - Bounds/capture unavailable: select a visible UI node with `UITransform`. Capture is viewport-only, bounded, and never falls back to a full-page screenshot.

package/dist/src/bridge.d.ts

@@ -89,6 +89,7 @@ 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 function inspectCocosPage(): unknown;
 export declare function inspectCocos(request: BridgeRequest): unknown;
 export {};

package/dist/src/bridge.js

@@ -15,11 +15,24 @@ export async function captureNode(page, uuid) {
     const clip = result.clippedViewport;
     if (!clip || !Number.isFinite(clip.x) || !Number.isFinite(clip.y) || !Number.isFinite(clip.width) || !Number.isFinite(clip.height) || clip.width <= 0 || clip.height <= 0 || clip.width > 1_024 || clip.height > 1_024 || clip.width * clip.height > 1_048_576)
         return { captured: false, reason: 'CAPTURE_LIMIT' };
-    const png = await page.screenshot({ type: 'png', clip });
-    const data = png.toString('base64');
-    if (Buffer.byteLength(JSON.stringify({ data }), 'utf8') > MAX_BYTES - 4_096)
-        return { captured: false, reason: 'RESPONSE_LIMIT' };
-    return { captured: true, mimeType: 'image/png', data, width: Math.round(clip.width), height: Math.round(clip.height) };
+    // ponytail: device-pixel PNG, then CSS-pixel JPEG quality steps; add CDP clip.scale downscaling if captures still hit the limit.
+    const attempts = [{ type: 'png', scale: 'device' }, ...[80, 60, 40].map(quality => ({ type: 'jpeg', quality, scale: 'css' }))];
+    for (const options of attempts) {
+        const data = (await page.screenshot({ ...options, clip })).toString('base64');
+        if (Buffer.byteLength(JSON.stringify({ data }), 'utf8') <= MAX_BYTES - 4_096) {
+            return { captured: true, mimeType: `image/${options.type}`, data, width: Math.round(clip.width), height: Math.round(clip.height) };
+        }
+    }
+    return { captured: false, reason: 'RESPONSE_LIMIT' };
+}
+export async function clickNode(page, uuid) {
+    const result = await page.evaluate(inspectCocos, { action: 'getNodeBounds', uuid });
+    if (!result.available || !result.visible)
+        return { clicked: false, reason: result.reason ?? 'OUTSIDE_VIEWPORT' };
+    const clip = result.clippedViewport;
+    const point = { x: clip.x + clip.width / 2, y: clip.y + clip.height / 2 };
+    await page.mouse.click(point.x, point.y);
+    return { clicked: true, target: { nodeUuid: uuid }, point, runtimeOnly: true };
 }
 export function inspectCocosPage() {
     const root = globalThis;
@@ -158,8 +171,24 @@ export function inspectCocos(request) {
         const worldY = Math.min(...points.map(point => Number(point.y)));
         const worldWidth = Math.max(...points.map(point => Number(point.x))) - worldX;
         const worldHeight = Math.max(...points.map(point => Number(point.y))) - worldY;
+        // Project through the owning Canvas camera; the visible-area mapping is wrong once the camera no longer centers on it.
+        let camera;
+        for (let current = node, depth = 0; current && !camera && depth < 100; current = current.parent, depth++) {
+            camera = components(current).find(component => componentName(component) === 'Canvas')?.cameraComponent;
+        }
+        const screen = typeof camera?.worldToScreen === 'function' && cc.Vec3 && canvas.width > 0 && canvas.height > 0
+            ? points.map(point => camera.worldToScreen(new cc.Vec3(Number(point.x), Number(point.y), 0), new cc.Vec3()))
+            : undefined;
         const origin = cc.view?.getVisibleOrigin?.() ?? { x: 0, y: 0 };
-        const viewport = { x: canvasRect.left + (worldX - Number(origin.x ?? 0)) * canvasRect.width / Number(visible.width), y: canvasRect.top + (Number(origin.y ?? 0) + Number(visible.height) - worldY - worldHeight) * canvasRect.height / Number(visible.height), width: worldWidth * canvasRect.width / Number(visible.width), height: worldHeight * canvasRect.height / Number(visible.height) };
+        const viewport = screen?.every(point => Number.isFinite(point.x) && Number.isFinite(point.y))
+            ? (() => {
+                const xs = screen.map(point => Number(point.x));
+                const ys = screen.map(point => Number(point.y));
+                const sx = canvasRect.width / canvas.width;
+                const sy = canvasRect.height / canvas.height;
+                return { x: canvasRect.left + Math.min(...xs) * sx, y: canvasRect.top + (canvas.height - Math.max(...ys)) * sy, width: (Math.max(...xs) - Math.min(...xs)) * sx, height: (Math.max(...ys) - Math.min(...ys)) * sy };
+            })()
+            : { x: canvasRect.left + (worldX - Number(origin.x ?? 0)) * canvasRect.width / Number(visible.width), y: canvasRect.top + (Number(origin.y ?? 0) + Number(visible.height) - worldY - worldHeight) * canvasRect.height / Number(visible.height), width: worldWidth * canvasRect.width / Number(visible.width), height: worldHeight * canvasRect.height / Number(visible.height) };
         if (!Object.values(viewport).every(Number.isFinite) || viewport.width <= 0 || viewport.height <= 0)
             return { available: false, reason: 'INVALID_GEOMETRY' };
         const clipped = { x: Math.max(0, viewport.x), y: Math.max(0, viewport.y), width: Math.max(0, Math.min(innerWidth, viewport.x + viewport.width) - Math.max(0, viewport.x)), height: Math.max(0, Math.min(innerHeight, viewport.y + viewport.height) - Math.max(0, viewport.y)) };
@@ -372,7 +401,7 @@ export function inspectCocos(request) {
             }
             if (reference && uuid && dataProperty(value, 'node'))
                 return { $type: 'Component', uuid: String(uuid), type: componentName(value) };
-            if (depth >= maxDepth) {
+            if (depth > 0 && depth >= maxDepth) {
                 truncate('MAX_DEPTH');
                 return '[MaxDepth]';
             }
@@ -425,12 +454,39 @@ export function inspectCocos(request) {
             seen.delete(value);
             return output;
         };
+        // ponytail: fixed allowlist of display backing fields, read without getters; extend per component when smoke tests need more.
+        const displayFields = {};
+        const readDisplay = (type, key, backing) => {
+            if (typeof cc[type] !== 'function' || !(selected instanceof cc[type]))
+                return;
+            const value = dataProperty(selected, backing);
+            if (typeof value === 'string') {
+                if (value.length > 2_000)
+                    truncate('STRING_LIMIT');
+                displayFields[key] = value.slice(0, 2_000);
+            }
+            else if (value === null || typeof value === 'boolean' || typeof value === 'number')
+                displayFields[key] = value;
+        };
+        readDisplay('Label', 'string', '_string');
+        readDisplay('RichText', 'string', '_string');
+        readDisplay('Button', 'interactable', '_interactable');
+        readDisplay('Toggle', 'isChecked', '_isChecked');
+        if (typeof cc.Sprite === 'function' && selected instanceof cc.Sprite) {
+            const frame = dataProperty(selected, '_spriteFrame');
+            displayFields.spriteFrame = frame && typeof frame === 'object'
+                ? { $type: 'SpriteFrame', name: String(dataProperty(frame, '_name') ?? '').slice(0, 500), uuid: String(dataProperty(frame, '_uuid') ?? '') }
+                : null;
+        }
+        const properties = serialize(selected, 0, false);
+        Object.assign(properties, displayFields);
+        returned += Object.keys(displayFields).length;
         return {
             version,
             node: summary(node),
             componentType: request.componentType ?? (selected === node ? undefined : componentName(selected)),
             componentUuid: selected === node ? undefined : String(selected.uuid ?? ''),
-            properties: serialize(selected, 0, false),
+            properties,
             truncated,
             truncationReasons: [...truncationReasons],
             propertyCount,

package/dist/src/browser.js

@@ -85,7 +85,7 @@ export class BrowserConnection {
             if (selected.length === 0)
                 throw new InspectorError('PAGE_NOT_FOUND', `Local page not found: ${sanitizeUrl(pageUrl)}`);
             if (selected.length > 1)
-                throw new InspectorError('MULTIPLE_PAGES', `Multiple localhost pages match pageUrl: ${sanitizeUrl(pageUrl)}`);
+                throw new InspectorError('MULTIPLE_PAGES', `Multiple localhost pages match pageUrl: ${sanitizeUrl(pageUrl)}; close duplicate tabs or use a separate Chromium per project`);
             return selected[0];
         }
         if (pages.length === 0)
@@ -113,7 +113,15 @@ export class BrowserConnection {
             return this.#browser;
         if (this.#connecting)
             return this.#connecting;
-        const connecting = this.connectOverCDP(this.endpoint, { timeout: this.timeout }).then(async (browser) => {
+        const options = { timeout: this.timeout };
+        const connecting = this.connectOverCDP(this.endpoint, options).catch(error => {
+            // A second Chromium on a taken IPv4 port may bind only [::1].
+            const url = new URL(this.endpoint);
+            if (!['127.0.0.1', 'localhost'].includes(url.hostname) || !/\b404\b|ECONNREFUSED/.test(String(error?.message)))
+                throw error;
+            url.hostname = '[::1]';
+            return this.connectOverCDP(url.toString().replace(/\/$/, ''), options).catch(() => { throw error; });
+        }).then(async (browser) => {
             if (this.#closed) {
                 await browser.close();
                 throw new Error('Browser connection is closed');
@@ -127,7 +135,11 @@ export class BrowserConnection {
         }).catch(error => {
             if (error instanceof InspectorError || error instanceof Error && error.message === 'connect failed')
                 throw error;
-            throw new InspectorError('CDP_UNAVAILABLE', `Unable to connect to Chromium CDP: ${error instanceof Error ? error.message : 'unknown error'}`);
+            const message = error instanceof Error ? error.message : 'unknown error';
+            const hint = /\b404\b/.test(message)
+                ? '; port is likely held by Chrome built-in remote debugging (chrome://inspect/#remote-debugging), which has no /json/version: turn it off or use another port, check with lsof -nP -iTCP:<port> -sTCP:LISTEN'
+                : '';
+            throw new InspectorError('CDP_UNAVAILABLE', `Unable to connect to Chromium CDP: ${message}${hint}`);
         });
         this.#connecting = connecting;
         try {

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, inspectCocosPage, runBridge } from './bridge.js';
+import { captureNode, clickNode, inspectCocosPage, 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 };
@@ -30,13 +30,16 @@ function response(data) {
 function failure(error) {
     if (error instanceof InspectorError)
         return { ...response({ code: error.code, message: error.message }), isError: true };
-    const message = error instanceof Error ? error.message : 'Inspector request failed';
+    const raw = error instanceof Error ? error.message : 'Inspector request failed';
+    // Playwright wraps in-page errors as "page.evaluate: Error: <message>\n<stack>".
+    const message = raw.replace(/^page\.evaluate: (?:Error: )?/, '').split('\n')[0];
     const code = message === 'Cocos Creator 3.x runtime not found' ? 'COCOS_NOT_FOUND'
         : message === 'Active Cocos scene not found' ? 'SCENE_NOT_READY'
             : message.startsWith('Node not found') ? 'NODE_NOT_FOUND'
                 : message === 'Component not found' ? 'COMPONENT_NOT_FOUND'
                     : message === 'Ambiguous component type' ? 'AMBIGUOUS_COMPONENT'
-                        : 'CDP_UNAVAILABLE';
+                        : message.startsWith('Invalid mutation') ? 'INVALID_MUTATION'
+                            : 'CDP_UNAVAILABLE';
     return { ...response({ code, message }), isError: true };
 }
 export function createServer(browser, options = {}) {
@@ -125,6 +128,31 @@ export function createServer(browser, options = {}) {
             .refine(value => !(value.componentType && value.componentUuid), 'Provide componentType or componentUuid, not both'),
         annotations: readOnly,
     }, input => execute({ action: 'getProperties', uuid: input.uuid, componentType: input.componentType, componentUuid: input.componentUuid, maxDepth: input.maxDepth }, input.pageUrl));
+    server.registerTool('cocos_wait_for_property', {
+        description: 'Poll one top-level property of a Cocos node or component until it equals a value or the timeout passes.',
+        inputSchema: z.object({ pageUrl, uuid: z.string().min(1), componentType: z.string().min(1).optional(), componentUuid: z.string().min(1).optional(), key: z.string().min(1).max(200), equals: z.union([z.boolean(), finiteNumber, z.string().max(2_000), z.null()]), timeoutMs: z.number().int().min(100).max(30_000).optional(), intervalMs: z.number().int().min(50).max(5_000).optional() }).strict()
+            .refine(value => !(value.componentType && value.componentUuid), 'Provide componentType or componentUuid, not both'),
+        annotations: readOnly,
+    }, async (input) => {
+        try {
+            const page = await browser.page(input.pageUrl);
+            const request = { action: 'getProperties', uuid: input.uuid, componentType: input.componentType, componentUuid: input.componentUuid, maxDepth: 0 };
+            const deadline = Date.now() + (input.timeoutMs ?? 5_000);
+            let polls = 0;
+            let value;
+            for (;;) {
+                polls++;
+                value = (await runBridge(page, request)).properties?.[input.key];
+                if (value === input.equals || Date.now() >= deadline)
+                    break;
+                await new Promise(resolve => setTimeout(resolve, input.intervalMs ?? 200));
+            }
+            return response({ matched: value === input.equals, key: input.key, value: value ?? null, polls });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
     if (options.allowRuntimeMutation) {
         server.registerTool('cocos_set_node_active', {
             description: 'Set the active state of one Cocos node selected by exact UUID.',
@@ -142,6 +170,18 @@ export function createServer(browser, options = {}) {
             inputSchema: z.object({ pageUrl, uuid: z.string().min(1), componentUuid: z.string().min(1), key: z.string().min(1).max(200), value: propertyValue }).strict(),
             annotations: runtimeMutation,
         }, input => execute({ action: 'setProperty', uuid: input.uuid, componentUuid: input.componentUuid, key: input.key, value: input.value }, input.pageUrl));
+        server.registerTool('cocos_click_node', {
+            description: 'Dispatch a real mouse click at the visible center of one Cocos UI node, so Button and touch handlers run.',
+            inputSchema: z.object({ pageUrl, uuid: z.string().min(1) }).strict(),
+            annotations: { ...runtimeMutation, idempotentHint: false },
+        }, async (input) => {
+            try {
+                return response(await clickNode(await browser.page(input.pageUrl), input.uuid));
+            }
+            catch (error) {
+                return failure(error);
+            }
+        });
         for (const action of ['pause', 'resume']) {
             server.registerTool(`cocos_${action}`, {
                 description: `${action === 'pause' ? 'Pause' : 'Resume'} the Cocos director through its public API.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cocos-web-inspector-mcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Read-only MCP inspector for Cocos Creator 3.x running in local Chromium",
   "license": "MIT",
   "repository": {