cocos-web-inspector-mcp 0.1.6 → 0.1.7

package/README.md

@@ -122,7 +122,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. 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, 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. Frame stepping is unsupported pending a verified public Cocos API compatibility matrix.
 
 ### Page selection
 

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');
@@ -329,17 +344,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 +417,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 +498,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'

package/package.json

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