cocos-web-inspector-mcp 0.1.6 → 0.1.8

package/README.md

@@ -98,19 +98,20 @@ The endpoint may instead be provided through the MCP process environment:
 
 ## Tools
 
-All tool input objects are strict. Unknown fields are rejected. Inspection tools are annotated as read-only, idempotent, non-destructive, and closed-world. The highlight tool is annotated as a non-destructive, non-idempotent, closed-world temporary mutation because repeated calls reset its removal timer.
+All tool input objects are strict. Unknown fields are rejected. Inspection tools are annotated as read-only, idempotent, non-destructive, and closed-world. The highlight tool is annotated as a non-destructive, non-idempotent, closed-world temporary mutation because repeated calls reset its removal timer. Runtime debugger tools are non-read-only and closed-world; `cocos_click_node` is additionally destructive and open-world because game click handlers can reach real servers or make irreversible changes, and it and `cocos_step_frame` are non-idempotent.
 
 | Tool | Purpose | Inputs |
 | --- | --- | --- |
 | `cocos_list_pages` | List bounded summaries of eligible localhost pages, including sanitized URL, title, Cocos detection, version, and scene name. | None |
 | `cocos_runtime_info` | Return bounded engine, scene, canvas, view, director, and node-count information. | `pageUrl?` |
-| `cocos_runtime_diagnostics` | Return passive bounded hierarchy counts, depth, and duplicate names. Render metrics remain explicitly unsupported. | `pageUrl?` |
+| `cocos_runtime_diagnostics` | Return passive bounded hierarchy counts, depth, duplicate names, and render metrics (FPS, frame time, draw calls, triangles, instances). | `pageUrl?` |
 | `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_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_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` |
@@ -122,7 +123,7 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 | `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 (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.
+`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.
 
 ### Page selection
 
@@ -198,7 +199,7 @@ npm run check
 
 `npm run check` type-checks, builds, runs the self-contained Node.js tests, exercises a vendored Cocos Creator 3.8.8 web fixture through live Chromium and CDP, packs the npm tarball, installs it into a temporary project, and smoke-tests the installed binary. Use it before pushing. `npm test` remains available for build plus self-tests only; `npm run test:integration` runs the live browser test separately.
 
-The test suite covers URL policy, CDP connection reuse and recovery, scene traversal, property redaction and cycle handling, output bounds, Cocos version rejection, strict tool schemas, exact tool annotations, real page selection, inspector and debugger tools, visual bounds/capture, snapshots, diagnostics, and browser reconnection. CI installs the matching Playwright Chromium revision, runs the full check on Ubuntu and Windows with Node.js 20 and 22, and rejects high-severity production dependency advisories.
+The test suite covers URL policy, CDP connection reuse and recovery, scene traversal, property redaction and cycle handling, output bounds, Cocos version rejection, strict tool schemas, exact tool annotations, real page selection, inspector and debugger tools, visual bounds/capture, snapshots, diagnostics, and browser reconnection. CI installs the matching Playwright Chromium revision, runs the full check on Ubuntu and Windows with Node.js 20, 22, and 24, and rejects high-severity production dependency advisories.
 
 ## Troubleshooting
 
@@ -206,7 +207,10 @@ The test suite covers URL policy, CDP connection reuse and recovery, scene trave
 - `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.
+- 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.
+- 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

@@ -61,6 +61,9 @@ export type BridgeRequest = {
     action: 'pause';
 } | {
     action: 'resume';
+} | {
+    action: 'stepFrame';
+    frames?: number | undefined;
 };
 type Vector3 = {
     x: number;

package/dist/src/bridge.js

@@ -13,16 +13,30 @@ export async function captureNode(page, uuid) {
     if (!result.available || !result.visible)
         return { captured: false, reason: result.reason ?? 'OUTSIDE_VIEWPORT' };
     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' };
-    // ponytail: device-pixel PNG, then CSS-pixel JPEG quality steps; add CDP clip.scale downscaling if captures still hit the limit.
+    if (!clip || !Number.isFinite(clip.x) || !Number.isFinite(clip.y) || !Number.isFinite(clip.width) || !Number.isFinite(clip.height) || clip.width <= 0 || clip.height <= 0)
+        return { captured: false, reason: 'INVALID_GEOMETRY' };
+    const fits = (data) => Buffer.byteLength(JSON.stringify({ data }), 'utf8') <= MAX_BYTES - 4_096;
+    const size = { width: Math.round(clip.width), height: Math.round(clip.height) };
+    // Device-pixel PNG, then CSS-pixel JPEG quality steps.
     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) };
+        if (fits(data))
+            return { captured: true, mimeType: `image/${options.type}`, data, ...size };
+    }
+    // Playwright has no output scale, so downscale through CDP; its clip is document-relative.
+    const session = await page.context().newCDPSession(page);
+    try {
+        const [scrollX, scrollY] = await page.evaluate(() => [window.scrollX, window.scrollY]);
+        for (const scale of [0.75, 0.5, 0.35, 0.25]) {
+            const { data } = await session.send('Page.captureScreenshot', { format: 'jpeg', quality: 60, clip: { x: clip.x + scrollX, y: clip.y + scrollY, width: clip.width, height: clip.height, scale } });
+            if (fits(data))
+                return { captured: true, mimeType: 'image/jpeg', data, ...size, scale };
         }
     }
+    finally {
+        await session.detach().catch(() => { });
+    }
     return { captured: false, reason: 'RESPONSE_LIMIT' };
 }
 export async function clickNode(page, uuid) {
@@ -192,7 +206,8 @@ export function inspectCocos(request) {
         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)) };
-        return { available: true, canvas: { x: worldX, y: worldY, width: worldWidth, height: worldHeight }, viewport, clippedViewport: clipped, anchor: { x: Number(transform.anchorPoint.x), y: Number(transform.anchorPoint.y) }, worldPosition: { x: Number(position.x), y: Number(position.y), z: Number(position.z ?? 0) }, visible: clipped.width > 0 && clipped.height > 0, outsideViewport: clipped.width === 0 || clipped.height === 0 };
+        const inactive = node.activeInHierarchy === false;
+        return { available: true, canvas: { x: worldX, y: worldY, width: worldWidth, height: worldHeight }, viewport, clippedViewport: clipped, anchor: { x: Number(transform.anchorPoint.x), y: Number(transform.anchorPoint.y) }, worldPosition: { x: Number(position.x), y: Number(position.y), z: Number(position.z ?? 0) }, visible: !inactive && clipped.width > 0 && clipped.height > 0, outsideViewport: clipped.width === 0 || clipped.height === 0, ...(inactive ? { reason: 'INACTIVE' } : {}) };
     };
     if (request.action === 'runtimeInfo') {
         const canvas = cc.game?.canvas ?? root.document?.querySelector('#GameCanvas');
@@ -231,13 +246,28 @@ export function inspectCocos(request) {
             }
         });
         const duplicateNames = [...names.entries()].filter(([, uuids]) => uuids.length > 1).slice(0, 100).map(([name, uuids]) => ({ name, uuids, count: uuids.length }));
+        // Root and the GFX device update these every frame whether or not the profiler is shown; read backing fields, never getters.
+        const renderRoot = cc.director && typeof cc.director === 'object' ? dataProperty(cc.director, '_root') : undefined;
+        const device = renderRoot && typeof renderRoot === 'object' ? dataProperty(renderRoot, '_device') : undefined;
+        const metric = (owner, key) => {
+            const value = owner && typeof owner === 'object' ? dataProperty(owner, key) : undefined;
+            return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+        };
+        const render = { fps: metric(renderRoot, '_fps'), frameTimeMs: metric(renderRoot, '_frameTime'), drawCalls: metric(device, '_numDrawCalls'), triangles: metric(device, '_numTris'), instances: metric(device, '_numInstances') };
+        if (render.frameTimeMs !== undefined)
+            render.frameTimeMs *= 1_000;
+        const unavailableMetrics = { invalidComponentReferences: 'UNSUPPORTED_PUBLIC_API' };
+        for (const [key, value] of Object.entries(render))
+            if (value === undefined)
+                unavailableMetrics[key] = 'UNSUPPORTED_PUBLIC_API';
         return {
             version,
             nodeCount,
             componentCount,
             maxHierarchyDepth: maxDepth,
             duplicateNames,
-            unavailableMetrics: { fps: 'UNSUPPORTED_PUBLIC_API', frameTime: 'UNSUPPORTED_PUBLIC_API', drawCalls: 'UNSUPPORTED_PUBLIC_API', triangles: 'UNSUPPORTED_PUBLIC_API', invalidComponentReferences: 'UNSUPPORTED_PUBLIC_API' },
+            render: Object.fromEntries(Object.entries(render).filter(([, value]) => value !== undefined)),
+            unavailableMetrics,
             truncated: traversal.truncated || duplicateNames.length >= 100,
             truncationReasons: traversal.truncated || duplicateNames.length >= 100 ? ['NODE_LIMIT'] : [],
         };
@@ -329,17 +359,24 @@ export function inspectCocos(request) {
         const maxDepth = Math.min(Math.max(request.maxDepth ?? 6, 0), 20);
         const maxNodes = Math.min(Math.max(request.maxNodes ?? 500, 1), 5_000);
         let count = 0;
+        // ponytail: the MCP response carries text and structuredContent, so ~70 KB of JSON (escaped text + structured copy) fits runBridge's ceiling; stop early instead of dropping everything.
+        let bytes = 0;
         const reasons = new Set();
         const build = (node, depth) => {
             if (count >= maxNodes) {
                 reasons.add('NODE_LIMIT');
                 return undefined;
             }
-            count++;
             const item = {
                 ...summary(node),
                 components: components(node).slice(0, 200).map(component => ({ type: componentName(component), uuid: String(component.uuid ?? ''), enabled: component.enabled !== false })),
             };
+            bytes += JSON.stringify(item).length;
+            if (bytes > 70_000) {
+                reasons.add('RESPONSE_LIMIT');
+                return undefined;
+            }
+            count++;
             if (components(node).length > 200)
                 reasons.add('NODE_LIMIT');
             if (depth >= maxDepth) {
@@ -395,12 +432,16 @@ export function inspectCocos(request) {
             }
             if (typeof value !== 'object')
                 return undefined;
-            const uuid = dataProperty(value, 'uuid');
-            if (reference && uuid && Array.isArray(dataProperty(value, 'children'))) {
-                return { $type: 'Node', uuid: String(uuid), name: String(dataProperty(value, 'name') ?? '').slice(0, 500) };
+            // Cocos 3.x exposes uuid/children/name as accessors; read their backing fields instead.
+            const uuid = dataProperty(value, 'uuid') ?? dataProperty(value, '_id');
+            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) };
             }
             if (reference && uuid && dataProperty(value, 'node'))
                 return { $type: 'Component', uuid: String(uuid), type: componentName(value) };
+            if (reference && typeof cc.Asset === 'function' && value instanceof cc.Asset) {
+                return { $type: componentName(value), name: String(dataProperty(value, '_name') ?? '').slice(0, 500), uuid: String(dataProperty(value, '_uuid') ?? '') };
+            }
             if (depth > 0 && depth >= maxDepth) {
                 truncate('MAX_DEPTH');
                 return '[MaxDepth]';
@@ -472,6 +513,13 @@ export function inspectCocos(request) {
         readDisplay('RichText', 'string', '_string');
         readDisplay('Button', 'interactable', '_interactable');
         readDisplay('Toggle', 'isChecked', '_isChecked');
+        if (selected === node) {
+            for (const key of ['name', 'active', 'activeInHierarchy']) {
+                const value = dataProperty(node, key) ?? dataProperty(node, `_${key}`);
+                if (typeof value === 'string' || typeof value === 'boolean')
+                    displayFields[key] = typeof value === 'string' ? value.slice(0, 500) : value;
+            }
+        }
         if (typeof cc.Sprite === 'function' && selected instanceof cc.Sprite) {
             const frame = dataProperty(selected, '_spriteFrame');
             displayFields.spriteFrame = frame && typeof frame === 'object'
@@ -526,6 +574,29 @@ export function inspectCocos(request) {
         const after = directorState();
         return { changed: before.paused !== after.paused, target: {}, before, after, runtimeOnly: true };
     }
+    if (request.action === 'stepFrame') {
+        const game = cc.game;
+        if (typeof game?.step !== 'function' || typeof game.isPaused !== 'function' || typeof cc.director?.getTotalFrames !== 'function')
+            invalidMutation('game.step is unavailable');
+        const directorPaused = directorState().paused;
+        if (!directorPaused && !game.isPaused())
+            invalidMutation('pause the game before stepping');
+        const before = cc.director.getTotalFrames();
+        // game.step ticks the director, which skips logic while director-paused; unpause only inside this synchronous call.
+        for (let frame = 0; frame < (request.frames ?? 1); frame++) {
+            if (directorPaused)
+                cc.director.resume();
+            try {
+                game.step();
+            }
+            finally {
+                if (directorPaused)
+                    cc.director.pause();
+            }
+        }
+        const after = cc.director.getTotalFrames();
+        return { changed: after !== before, target: {}, before: { totalFrames: before }, after: { totalFrames: after }, runtimeOnly: true };
+    }
     if (request.action === 'setNodeActive') {
         const node = findByUuid(request.uuid);
         const before = node.active !== false;

package/dist/src/server.js

@@ -171,9 +171,10 @@ export function createServer(browser, options = {}) {
             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.',
+            description: 'Dispatch a real mouse click at the visible center of one Cocos UI node, so Button and touch handlers run. Handlers may call game servers or make irreversible changes.',
             inputSchema: z.object({ pageUrl, uuid: z.string().min(1) }).strict(),
-            annotations: { ...runtimeMutation, idempotentHint: false },
+            // Game click handlers run arbitrary code: a login button reaches real servers, a buy button spends currency.
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         }, async (input) => {
             try {
                 return response(await clickNode(await browser.page(input.pageUrl), input.uuid));
@@ -189,6 +190,11 @@ export function createServer(browser, options = {}) {
                 annotations: runtimeMutation,
             }, input => execute({ action }, input.pageUrl));
         }
+        server.registerTool('cocos_step_frame', {
+            description: 'Advance a paused Cocos game by fixed-delta frames through cc.game.step; requires cocos_pause first.',
+            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_highlight_node', {
         description: 'Temporarily draw a pointer-transparent DOM overlay around one Cocos UI node.',

package/package.json

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