cocos-web-inspector-mcp 2.2.0 → 2.3.0

package/README.md

@@ -50,21 +50,26 @@ Keep this browser profile separate from normal browsing. CDP provides code-execu
 A Cocos native build with **Debug** checked runs a V8 inspector inside the app; release builds do not. Attach to it over adb instead of Chromium:
 
 ```sh
-adb logcat -d -s Cocos | grep "Debugger listening" -A1   # prints ws=IP_ADDR_OF_THIS_DEVICE:<port>/...
-adb forward tcp:<port> tcp:<port>
+npx --yes cocos-web-inspector-mcp doctor --native   # finds the port in logcat, runs adb forward, checks the scene
 npx --yes cocos-web-inspector-mcp --native-endpoint http://127.0.0.1:<port>
 ```
 
+`doctor --native` reads the port from the engine's `Debugger listening` logcat line, forwards it to the same loopback port, and prints the `claude mcp add` command. By hand: `adb logcat -d -s Cocos | grep "Debugger listening" -A1`, then `adb forward tcp:<port> tcp:<port>`.
+
 The template asks for port 6086, but on Android the engine moves it above 37000 when it cannot list network interfaces (43086 on a Creator 3.8.8 build), so read the port from logcat. `--native-endpoint` must be loopback, and it replaces `--cdp-endpoint` for that server process.
 
 The V8 inspector has no page, so native mode registers only the tools that read or change the Cocos graph, plus adb-backed input and logs:
 
+- `cocos_capture_node` crops a device screenshot (`adb exec-out screencap`, gzipped on the device) to the node's viewport bounds and returns a PNG, downsampled by whole steps (`scale`) when it would exceed the response limit. It takes 1.5 to 2.5 s over Wi-Fi adb on a 3200x1440 screen and, like taps, assumes a full-screen game.
 - `cocos_click_node` and `cocos_drag_node` tap and swipe with `adb shell input`, at the node's viewport center, which equals screen pixels for a full-screen game. `steps` does not apply to a native drag. Set `ANDROID_SERIAL` when several devices are attached.
 - `cocos_type_text` taps the EditBox, waits for the engine's Android input activity (`CocosEditBoxActivity`), clears it, and types with `adb shell input text`, so `text-changed` fires per character. Text must be printable ASCII without `%s`. The device keyboard still processes the keys, so autocorrect or a Vietnamese Telex layout can rewrite them (`test` becomes `tét`); the result reports `matches: false` with the text the game received. `submit` presses Enter, which closes a single-line box with `editing-did-ended`; `editing-return` fires only from the activity's confirm button. Clearing uses `input keycombination`, Android 12+.
+- With `--allow-browser-data`, `cocos_network_requests` and `cocos_network_request` report XHR, `fetch` (which the native polyfill runs over XHR), and WebSocket traffic. The first network call installs hooks in the game that keep the last 200 requests and the last 50 frames per socket, so traffic before that call is not seen; the note says when capture started. Bodies and frames are masked like web bodies, headers like web headers. `cocos_storage` reads `localStorage` (native builds back it with SQLite); `session` and `cookies` report `available: false`, since native builds have neither.
 - `cocos_console_messages` (with `--allow-browser-data`) reads the app process's `Cocos`-tagged logcat lines, so it includes logs from before the server attached, bounded by the device log buffer. `console.log` and `console.debug` both report as `log`; an uncaught error spans several `error` lines.
-- Not registered: `cocos_capture_node`, `cocos_emulate_device`, `cocos_highlight_node`, `cocos_get_selection` (DOM overlays draw nothing), `cocos_analyze_batches` (the native 2D batcher runs in C++), `cocos_step_frame` (stepping from the inspector renders outside the native frame loop and crashed the app), and the network and storage tools.
+- Not registered: `cocos_emulate_device`, `cocos_highlight_node`, `cocos_get_selection` (DOM overlays draw nothing), `cocos_analyze_batches` (the native 2D batcher runs in C++), and `cocos_step_frame` (stepping from the inspector renders outside the native frame loop and crashed the app).
+
+The inspector accepts one session at a time, so the server connects per call; Chrome DevTools can attach between calls, and a call made while DevTools is attached fails with `CDP_UNAVAILABLE`. An adb server restart or a USB drop takes the forward with it; when the endpoint stops answering, the server reads the port from logcat and forwards it again once before failing, so a call usually recovers on its own. If calls keep failing with `CDP_UNAVAILABLE`, run `doctor --native`. When a phone keeps dropping off USB (common through hubs), switch adb to Wi-Fi with `adb tcpip 5555` and `adb connect <phone-ip>:5555`, then forward and set `ANDROID_SERIAL=<phone-ip>:5555`; the endpoint stays `127.0.0.1`.
 
-The inspector accepts one session at a time, so the server connects per call; Chrome DevTools can attach between calls, and a call made while DevTools is attached fails with `CDP_UNAVAILABLE`. If calls start failing with `CDP_UNAVAILABLE` while the app runs, the adb server restarted and dropped the forward; run `adb forward` again.
+Only a build with the inspector compiled in can attach. If a game's Debug build fails, setting `USE_V8_DEBUGGER_FORCE` and `CC_DEBUG_FORCE` to `ON` in `native/engine/common/CMakeLists.txt` keeps the inspector in a release build; never ship such a build.
 
 ## Install and run
 

package/dist/src/bridge.d.ts

@@ -132,7 +132,21 @@ type PropertyValue = boolean | number | string | {
     b: number;
     a?: number | undefined;
 };
+/** Whether a tool result, sent as both text and structuredContent, stays under the response ceiling. */
+export declare function fitsResponse(result: unknown): boolean;
 export declare function runBridge(page: Page, request: BridgeRequest): Promise<unknown>;
+export type Clip = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** The node's visible viewport rectangle, or why it has none. */
+export declare function visibleClip(page: Page, uuid: string): Promise<Clip | {
+    reason: string;
+}>;
+/** Whether base64 image data stays under the response ceiling. */
+export declare const fitsImage: (data: string) => boolean;
 export declare function captureNode(page: Page, uuid: string): Promise<unknown>;
 export declare function nodeCenter(page: Page, uuid: string): Promise<{
     x: number;

package/dist/src/bridge.js

@@ -1,21 +1,30 @@
 const MAX_BYTES = 200_000;
+/** Whether a tool result, sent as both text and structuredContent, stays under the response ceiling. */
+export function fitsResponse(result) {
+    const encoded = JSON.stringify({ content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result });
+    return Buffer.byteLength(encoded, 'utf8') <= MAX_BYTES - 4_096;
+}
 export async function runBridge(page, request) {
     const result = await page.evaluate(inspectCocos, request);
-    const text = JSON.stringify(result);
-    const encoded = JSON.stringify({ content: [{ type: 'text', text }], structuredContent: result });
-    if (Buffer.byteLength(encoded, 'utf8') > MAX_BYTES - 4_096) {
-        return { truncated: true, truncationReasons: ['RESPONSE_LIMIT'] };
-    }
-    return result;
+    return fitsResponse(result) ? result : { truncated: true, truncationReasons: ['RESPONSE_LIMIT'] };
 }
-export async function captureNode(page, uuid) {
+/** The node's visible viewport rectangle, or why it has none. */
+export async function visibleClip(page, uuid) {
     const result = await page.evaluate(inspectCocos, { action: 'getNodeBounds', uuid });
     if (!result.available || !result.visible)
-        return { captured: false, reason: result.reason ?? 'OUTSIDE_VIEWPORT' };
+        return { 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)
-        return { captured: false, reason: 'INVALID_GEOMETRY' };
-    const fits = (data) => Buffer.byteLength(JSON.stringify({ data }), 'utf8') <= MAX_BYTES - 4_096;
+    if (!clip || ![clip.x, clip.y, clip.width, clip.height].every(Number.isFinite) || clip.width <= 0 || clip.height <= 0)
+        return { reason: 'INVALID_GEOMETRY' };
+    return clip;
+}
+/** Whether base64 image data stays under the response ceiling. */
+export const fitsImage = (data) => Buffer.byteLength(JSON.stringify({ data }), 'utf8') <= MAX_BYTES - 4_096;
+export async function captureNode(page, uuid) {
+    const clip = await visibleClip(page, uuid);
+    if ('reason' in clip)
+        return { captured: false, reason: clip.reason };
+    const fits = fitsImage;
     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' }))];
@@ -40,11 +49,8 @@ export async function captureNode(page, uuid) {
     return { captured: false, reason: 'RESPONSE_LIMIT' };
 }
 export async function nodeCenter(page, uuid) {
-    const result = await page.evaluate(inspectCocos, { action: 'getNodeBounds', uuid });
-    if (!result.available || !result.visible)
-        return { reason: result.reason ?? 'OUTSIDE_VIEWPORT' };
-    const clip = result.clippedViewport;
-    return { x: clip.x + clip.width / 2, y: clip.y + clip.height / 2 };
+    const clip = await visibleClip(page, uuid);
+    return 'reason' in clip ? clip : { x: clip.x + clip.width / 2, y: clip.y + clip.height / 2 };
 }
 // Under touch emulation Chrome turns mouse input into touch and never acknowledges Playwright's mouse calls, so send touch directly.
 function pointer(page) {
@@ -810,11 +816,9 @@ export function inspectCocos(request) {
             }
         }
         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;
-            }
+            // Native (JSB) nodes keep these in C++ behind accessors; summary reads the same public getters the scene tree reports.
+            const { name, active, activeInHierarchy } = summary(node);
+            Object.assign(displayFields, { name, active, activeInHierarchy });
         }
         if (typeof cc.Sprite === 'function' && selected instanceof cc.Sprite) {
             const frame = dataProperty(selected, '_spriteFrame');
@@ -1162,7 +1166,21 @@ export function inspectCocos(request) {
     }
     // Asset helpers read backing fields only; refCount, width, and texture getters stay untouched.
     const assetName = (asset) => String(dataProperty(asset, '_name') ?? '').slice(0, 500);
-    const assetUuid = (asset) => String(dataProperty(asset, '_uuid') ?? '');
+    // Native (JSB) assets keep _uuid behind a C++ accessor, which data reads skip; the asset cache is keyed by uuid, so look it up there.
+    let cachedUuids;
+    const assetUuid = (asset) => {
+        const own = dataProperty(asset, '_uuid');
+        if (typeof own === 'string' && own)
+            return own;
+        if (!cachedUuids) {
+            cachedUuids = new Map();
+            const map = dataProperty(cc.assetManager?.assets ?? {}, '_map');
+            for (const [key, value] of Object.entries((map && typeof map === 'object' ? map : {})))
+                if (value && typeof value === 'object')
+                    cachedUuids.set(value, key);
+        }
+        return cachedUuids.get(asset) ?? '';
+    };
     const gfxBytes = (texture) => {
         const gfx = texture && typeof texture === 'object' ? dataProperty(texture, '_gfxTexture') : undefined;
         const size = gfx && typeof gfx === 'object' ? dataProperty(gfx, '_size') : undefined;
@@ -1681,10 +1699,13 @@ export function inspectCocos(request) {
         // Unused first, then by GPU bytes and refCount: the likeliest leaks lead.
         items.sort((a, b) => Number(b.status === 'unused') - Number(a.status === 'unused') || (b.bytes ?? 0) - (a.bytes ?? 0) || b.refCount - a.refCount);
         const memory = dataProperty(dataProperty(dataProperty(cc.director, '_root') ?? {}, '_device') ?? {}, '_memoryStatus');
+        // Native (JSB) GFX textures live in C++ and expose no byte size to JS; report that instead of zeros that read as "no textures".
+        const textureCount = Object.entries(byType).filter(([type]) => /Texture/.test(type)).reduce((sum, [, bucket]) => sum + bucket.count, 0);
+        const bytesUnavailable = totalBytes === 0 && textureCount > 0;
         return {
             version,
             assetCount: Math.min(total, 50_000),
-            textureBytes: totalBytes,
+            ...(bytesUnavailable ? { textureBytes: null, unavailableMetrics: { textureBytes: 'UNSUPPORTED_PUBLIC_API' } } : { textureBytes: totalBytes }),
             ...(memory ? { gpuMemory: { textureBytes: Number(dataProperty(memory, 'textureSize') ?? 0), bufferBytes: Number(dataProperty(memory, 'bufferSize') ?? 0) } } : {}),
             byType,
             assets: items.slice(0, limit),

package/dist/src/browser-data.d.ts

@@ -13,11 +13,26 @@ export declare function consoleMessages(page: Page, options: {
     textContains?: string | undefined;
     limit?: number | undefined;
 }): Promise<unknown>;
-export declare function networkRequests(page: Page, options: {
+export declare function networkRequests(page: Page, options: RequestFilter): Promise<unknown>;
+type RequestRow = {
+    url: string;
+    resourceType: string;
+    status: number | null;
+    failure?: string;
+};
+type RequestFilter = {
     urlContains?: string | undefined;
     resourceType?: string | undefined;
     failedOnly?: boolean | undefined;
     limit?: number | undefined;
-}): Promise<unknown>;
+};
+/** Filters request rows and keeps the newest `limit`; shared by the browser and native network tools. */
+export declare function selectRequests<T extends RequestRow>(rows: T[], options: RequestFilter, note: string): {
+    requests: T[];
+    matched: number;
+    truncated: boolean;
+    note: string;
+};
 export declare function networkRequest(page: Page, id: number, includeBody: boolean): Promise<unknown>;
 export declare function storage(page: Page, area: 'local' | 'session' | 'cookies', keyContains?: string, limit?: number): Promise<unknown>;
+export {};

package/dist/src/browser-data.js

@@ -84,7 +84,6 @@ const idOf = (request) => {
     return id;
 };
 export async function networkRequests(page, options) {
-    const limit = options.limit ?? 50;
     const rows = await Promise.all((await page.requests()).map(async (request) => {
         const response = await request.response().catch(() => null);
         const failure = request.failure()?.errorText;
@@ -99,10 +98,15 @@ export async function networkRequests(page, options) {
             ...(timing.responseEnd > 0 ? { durationMs: Math.round(timing.responseEnd) } : {}),
         };
     }));
+    return selectRequests(rows, options, 'Requests since this server attached; Playwright drops old entries to bound memory.');
+}
+/** Filters request rows and keeps the newest `limit`; shared by the browser and native network tools. */
+export function selectRequests(rows, options, note) {
+    const limit = options.limit ?? 50;
     const matched = rows.filter(row => (!options.urlContains || row.url.includes(options.urlContains))
         && (!options.resourceType || row.resourceType === options.resourceType)
         && (!options.failedOnly || row.failure || (row.status ?? 0) >= 400));
-    return { requests: matched.slice(-limit), matched: matched.length, truncated: matched.length > limit, note: 'Requests since this server attached; Playwright drops old entries to bound memory.' };
+    return { requests: matched.slice(-limit), matched: matched.length, truncated: matched.length > limit, note };
 }
 export async function networkRequest(page, id, includeBody) {
     const request = (await page.requests()).find(candidate => requestIds.get(candidate) === id);
@@ -132,6 +136,9 @@ export async function networkRequest(page, id, includeBody) {
 }
 export async function storage(page, area, keyContains, limit = 100) {
     if (area === 'cookies') {
+        // A native (JSB) runtime has no browser context or cookie jar.
+        if (typeof page.context !== 'function')
+            return { area, available: false, reason: 'UNSUPPORTED_PUBLIC_API', entries: [], matched: 0, truncated: false };
         // Cookie values are always withheld; names and attributes are enough to debug expiry and scope.
         const cookies = (await page.context().cookies(page.url())).filter(cookie => !keyContains || cookie.name.includes(keyContains));
         return {
@@ -141,8 +148,11 @@ export async function storage(page, area, keyContains, limit = 100) {
             truncated: cookies.length > limit,
         };
     }
+    // Native (JSB) builds have localStorage only, backed by a SQLite file; there is no sessionStorage or cookie jar.
     const entries = await page.evaluate(store => {
-        const target = store === 'local' ? localStorage : sessionStorage;
+        const target = store === 'local' ? localStorage : globalThis.sessionStorage;
+        if (!target)
+            return null;
         const out = [];
         for (let index = 0; index < target.length && index < 5_000; index++) {
             const key = target.key(index);
@@ -151,6 +161,8 @@ export async function storage(page, area, keyContains, limit = 100) {
         }
         return out;
     }, area);
+    if (!entries)
+        return { area, available: false, reason: 'UNSUPPORTED_PUBLIC_API', entries: [], matched: 0, truncated: false };
     const matched = entries.filter(([key]) => !keyContains || key.includes(keyContains));
     return {
         area,

package/dist/src/cli.js

@@ -5,6 +5,7 @@ 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';
+import { forwardInspector, NativeConnection } from './native.js';
 const write = (line) => process.stdout.write(`${line}\n`);
 function flags(args, names, booleans = []) {
     const values = {};
@@ -124,10 +125,39 @@ async function launch(args) {
     await exited;
     process.exit(0);
 }
+// Native debug builds: find the inspector port in logcat, forward it over adb, and check the Cocos runtime through it.
+async function nativeDoctor() {
+    const fail = (code, message, fix) => {
+        write(`FAIL  ${code}: ${message}\n      Fix: ${fix}`);
+        process.exitCode = 1;
+    };
+    let port;
+    try {
+        port = await forwardInspector();
+    }
+    catch (error) {
+        return fail('CDP_UNAVAILABLE', error instanceof Error ? error.message : 'adb failed', 'install Android platform-tools, check adb devices, and set ANDROID_SERIAL when several devices are attached');
+    }
+    if (port === undefined)
+        return fail('CDP_UNAVAILABLE', 'no "Debugger listening" line in the device log', 'start a Cocos native build made with Debug checked; release builds have no inspector');
+    write(`ok    debug build listens on device port ${port}; forwarded to 127.0.0.1:${port}`);
+    const endpoint = `http://127.0.0.1:${port}`;
+    const info = await (await new NativeConnection(endpoint).page()).evaluate(inspectCocosPage).catch(error => error);
+    if (info instanceof Error)
+        return fail('CDP_UNAVAILABLE', info.message, 'close Chrome DevTools attached to the game; the inspector takes one session at a time');
+    if (!info.cocos?.detected)
+        return fail('COCOS_NOT_FOUND', 'no Cocos Creator 3.x runtime in the app', 'wait for the game to finish loading');
+    if (!info.cocos.sceneName)
+        return fail('SCENE_NOT_READY', `Cocos ${info.cocos.version} has no active scene yet`, 'wait for the first scene to load');
+    write(`ok    Cocos ${info.cocos.version}, scene "${info.cocos.sceneName}"`);
+    write(`\nAdd it to Claude Code:\n  claude mcp add cocos-native -- npx -y cocos-web-inspector-mcp --native-endpoint ${endpoint}`);
+}
 async function doctor(args) {
-    const { values, positional } = flags(args, ['--cdp-endpoint']);
+    const { values, positional } = flags(args, ['--cdp-endpoint'], ['--native']);
     if (positional.length)
-        throw new Error('Usage: cocos-web-inspector-mcp doctor [--cdp-endpoint <url>]');
+        throw new Error('Usage: cocos-web-inspector-mcp doctor [--cdp-endpoint <url> | --native]');
+    if (values['--native'])
+        return nativeDoctor();
     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}`);

package/dist/src/native.d.ts

@@ -1,4 +1,6 @@
 import type { Page } from 'playwright-core';
+import { type Clip } from './bridge.js';
+import { selectRequests } from './browser-data.js';
 type Evaluate = (webSocketUrl: string, expression: string, timeout: number) => Promise<unknown>;
 export declare class NativeConnection {
     #private;
@@ -11,6 +13,16 @@ export declare class NativeConnection {
 }
 export declare function nativeClick(page: Page, uuid: string): Promise<unknown>;
 export declare function nativeDrag(page: Page, uuid: string, dx: number, dy: number, durationMs?: number): Promise<unknown>;
+export declare function nativeCaptureNode(page: Page, uuid: string): Promise<unknown>;
+/** Crops a raw screencap to the clip and encodes an RGB PNG, sampling every n-th pixel until it fits the response. */
+export declare function cropPng(raw: Buffer, clip: Clip): unknown;
+/**
+ * The inspector port from the engine's own "Debugger listening" logcat lines: the latest one, or `expected` only when
+ * some line names it. Any app can log under the Cocos tag, so reconnects pass the port they already used.
+ */
+export declare function inspectorPort(logcat: string, expected?: number): number | undefined;
+/** Forwards the device's inspector port to the same loopback port; returns it, or undefined when no debug build has logged one. */
+export declare function forwardInspector(expected?: number): Promise<number | undefined>;
 /** Parses `logcat -v epoch` lines of the Cocos tag; console.log and console.debug share one level there and map to log. */
 export declare function parseCocosLogcat(output: string): Array<{
     type: string;
@@ -23,4 +35,6 @@ export declare function nativeConsoleMessages(page: Page, options: {
     limit?: number | undefined;
 }): Promise<unknown>;
 export declare function nativeTypeText(page: Page, uuid: string, text: string, submit: boolean): Promise<unknown>;
+export declare function nativeNetworkRequests(page: Page, options: Parameters<typeof selectRequests>[1]): Promise<unknown>;
+export declare function nativeNetworkRequest(page: Page, id: number, includeBody: boolean): Promise<unknown>;
 export {};

package/dist/src/native.js

@@ -1,8 +1,9 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { nodeCenter, runBridge } from './bridge.js';
+import { crc32, deflateSync, gunzipSync } from 'node:zlib';
+import { fitsImage, fitsResponse, nodeCenter, runBridge, visibleClip } from './bridge.js';
 import { InspectorError, validateLocalUrl } from './browser.js';
-import { redactText } from './browser-data.js';
+import { redactBody, redactHeaders, redactText, redactUrl, selectRequests } from './browser-data.js';
 // Cocos native debug builds (V8) run a Node-style inspector: Runtime and Debugger domains only, no pages, one session at a time.
 // ponytail: one WebSocket per call so Chrome DevTools can attach between calls; keep a socket open if per-call latency matters.
 export class NativeConnection {
@@ -27,14 +28,21 @@ export class NativeConnection {
         return this.#page;
     }
     async close() { }
+    async #targets() {
+        const response = await fetch(new URL('/json/list', this.#http), { signal: AbortSignal.timeout(10_000) });
+        return await response.json();
+    }
     async #evaluate(fn, arg) {
         let targets;
         try {
-            const response = await fetch(new URL('/json/list', this.#http), { signal: AbortSignal.timeout(10_000) });
-            targets = await response.json();
+            targets = await this.#targets();
         }
         catch (error) {
-            throw new InspectorError('CDP_UNAVAILABLE', `Unable to reach the native inspector at ${this.#http.host}: ${error instanceof Error ? error.message : 'unknown error'}; run the debug build, find its port in logcat "Debugger listening", then adb forward tcp:<port> tcp:<port>`);
+            // An adb server restart or a USB drop takes the forward with it; restore it once, only to the device port this endpoint names.
+            const restored = await forwardInspector(Number(this.#http.port)).catch(() => undefined);
+            targets = restored === undefined ? [] : await this.#targets().catch(() => []);
+            if (!targets.length)
+                throw new InspectorError('CDP_UNAVAILABLE', `Unable to reach the native inspector at ${this.#http.host}: ${error instanceof Error ? error.message : 'unknown error'}; check that the debug build is running and adb sees the device (run doctor --native)`);
         }
         if (!Array.isArray(targets) || targets.length === 0)
             throw new InspectorError('NO_LOCAL_PAGE', 'Native inspector lists no target');
@@ -79,15 +87,16 @@ async function evaluateOverWebSocket(webSocketUrl, expression, timeout) {
 // Real input and logs go through adb on the device the inspector is forwarded from. adb picks the device itself;
 // with several attached, set ANDROID_SERIAL. Arguments are numbers or a validated package name, never free text.
 const run = promisify(execFile);
-async function adb(args) {
+async function adbBuffer(args) {
     try {
-        return (await run('adb', args, { timeout: 15_000, maxBuffer: 16 * 1024 * 1024 })).stdout;
+        return (await run('adb', args, { encoding: 'buffer', timeout: 15_000, maxBuffer: 16 * 1024 * 1024 })).stdout;
     }
     catch (error) {
         const message = error instanceof Error ? error.message.split('\n')[0] : 'unknown error';
         throw new InspectorError('CDP_UNAVAILABLE', `adb ${args[0]} failed: ${message.slice(0, 300)}; check adb devices, and set ANDROID_SERIAL when several are attached`);
     }
 }
+const adb = async (args) => (await adbBuffer(args)).toString();
 // ponytail: viewport coordinates equal screen pixels only for a full-screen game (the Cocos default); add the window offset for windowed apps.
 const pixel = (value) => String(Math.round(value));
 const settle = () => new Promise(resolve => setTimeout(resolve, 300));
@@ -110,6 +119,65 @@ export async function nativeDrag(page, uuid, dx, dy, durationMs = 300) {
     await settle();
     return { dragged: true, target: { nodeUuid: uuid }, from, to, input: 'adb', runtimeOnly: true };
 }
+// Raw `screencap` output: width, height, and pixel format as uint32 LE, a colorspace word on Android 12+, then RGBA rows
+// in the current display rotation. The device gzips it (18 MB raw takes ~20 s over Wi-Fi adb, ~1.5 s gzipped), and cropping
+// raw pixels needs only zlib here, where decoding `screencap -p` would need a PNG decoder.
+export async function nativeCaptureNode(page, uuid) {
+    const clip = await visibleClip(page, uuid);
+    if ('reason' in clip)
+        return { captured: false, reason: clip.reason };
+    const raw = gunzipSync(await adbBuffer(['exec-out', 'screencap | gzip -1']), { maxOutputLength: 256 * 1024 * 1024 });
+    return cropPng(raw, clip);
+}
+/** Crops a raw screencap to the clip and encodes an RGB PNG, sampling every n-th pixel until it fits the response. */
+export function cropPng(raw, clip) {
+    if (raw.length < 12)
+        return { captured: false, reason: 'SCREENCAP_FAILED' };
+    const screenWidth = raw.readUInt32LE(0);
+    const screenHeight = raw.readUInt32LE(4);
+    const header = raw.length - screenWidth * screenHeight * 4;
+    // 1 is RGBA_8888 and 2 is RGBX_8888; other formats are not 4 bytes per pixel.
+    if (![1, 2].includes(raw.readUInt32LE(8)) || (header !== 12 && header !== 16))
+        return { captured: false, reason: 'UNSUPPORTED_PIXEL_FORMAT' };
+    // ponytail: viewport pixels equal screen pixels only for a full-screen game, as for adb taps; add the window offset for windowed apps.
+    const left = Math.max(0, Math.floor(clip.x));
+    const top = Math.max(0, Math.floor(clip.y));
+    const right = Math.min(screenWidth, Math.ceil(clip.x + clip.width));
+    const bottom = Math.min(screenHeight, Math.ceil(clip.y + clip.height));
+    if (right <= left || bottom <= top)
+        return { captured: false, reason: 'OUTSIDE_VIEWPORT' };
+    // ponytail: nearest-pixel sampling keeps this dependency-free; box filtering would read text better when downscaled.
+    for (const step of [1, 2, 3, 4, 6, 8]) {
+        const width = Math.ceil((right - left) / step);
+        const height = Math.ceil((bottom - top) / step);
+        const rows = Buffer.alloc((width * 3 + 1) * height);
+        for (let y = 0; y < height; y++) {
+            const out = y * (width * 3 + 1) + 1;
+            const source = header + ((top + y * step) * screenWidth + left) * 4;
+            for (let x = 0; x < width; x++)
+                raw.copy(rows, out + x * 3, source + x * step * 4, source + x * step * 4 + 3);
+        }
+        const data = png(width, height, rows).toString('base64');
+        if (fitsImage(data))
+            return { captured: true, mimeType: 'image/png', data, width: right - left, height: bottom - top, ...(step > 1 ? { scale: 1 / step } : {}) };
+    }
+    return { captured: false, reason: 'RESPONSE_LIMIT' };
+}
+function png(width, height, rows) {
+    const chunk = (type, body) => {
+        const head = Buffer.alloc(8);
+        head.writeUInt32BE(body.length, 0);
+        head.write(type, 4, 'ascii');
+        const crc = Buffer.alloc(4);
+        crc.writeUInt32BE(crc32(body, crc32(type)), 0);
+        return Buffer.concat([head, body, crc]);
+    };
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr.set([8, 2, 0, 0, 0], 8); // 8-bit RGB, no interlace
+    return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk('IHDR', ihdr), chunk('IDAT', deflateSync(rows, { level: 9 })), chunk('IEND', Buffer.alloc(0))]);
+}
 // The app's own process, from its files directory, so logs of other Cocos apps on the device never mix in.
 async function appProcess(page) {
     const path = String(await page.evaluate(() => globalThis.jsb?.fileUtils?.getWritablePath?.() ?? ''));
@@ -121,6 +189,21 @@ async function appProcess(page) {
         throw new InspectorError('CDP_UNAVAILABLE', `App ${name} is not running`);
     return pid;
 }
+/**
+ * The inspector port from the engine's own "Debugger listening" logcat lines: the latest one, or `expected` only when
+ * some line names it. Any app can log under the Cocos tag, so reconnects pass the port they already used.
+ */
+export function inspectorPort(logcat, expected) {
+    const ports = [...logcat.matchAll(/js_app\.html\?v8only=true&ws=[^:\s]+:(\d{2,5})\//g)].map(match => Number(match[1])).filter(port => port >= 1_024 && port <= 65_535);
+    return expected === undefined ? ports.at(-1) : ports.includes(expected) ? expected : undefined;
+}
+/** Forwards the device's inspector port to the same loopback port; returns it, or undefined when no debug build has logged one. */
+export async function forwardInspector(expected) {
+    const port = inspectorPort(await adb(['logcat', '-d', '-s', 'Cocos:D']), expected);
+    if (port !== undefined)
+        await adb(['forward', `tcp:${port}`, `tcp:${port}`]);
+    return port;
+}
 const levels = { V: 'debug', D: 'log', I: 'info', W: 'warning', E: 'error', F: 'error' };
 /** Parses `logcat -v epoch` lines of the Cocos tag; console.log and console.debug share one level there and map to log. */
 export function parseCocosLogcat(output) {
@@ -182,3 +265,173 @@ export async function nativeTypeText(page, uuid, text, submit) {
     const matches = typeof properties?.string === 'string' ? properties.string === text : undefined;
     return { typed: true, target: { nodeUuid: uuid }, length: text.length, submitted: submit, after, ...(matches === undefined ? {} : { matches }), ...(matches === false ? { hint: 'The device keyboard changed the text; switch it to a plain English layout without autocorrect' } : {}), input: 'adb', runtimeOnly: true };
 }
+function nativeNetwork(query) {
+    const root = globalThis;
+    const MAX_ENTRIES = 200;
+    const MAX_BODY = 100_000;
+    const clip = (value) => typeof value === 'string' ? value.slice(0, MAX_BODY)
+        : value instanceof ArrayBuffer ? `[binary ${value.byteLength} bytes]` : value == null ? '' : `[${typeof value}]`;
+    let state = root.__cocosWebInspectorNetwork;
+    const installedNow = !state;
+    if (!state) {
+        state = root.__cocosWebInspectorNetwork = { entries: [], nextId: 1, installedAt: Date.now() };
+        const record = (entry) => {
+            entry.id = state.nextId++;
+            state.entries.push(entry);
+            if (state.entries.length > MAX_ENTRIES)
+                state.entries.shift();
+            return entry;
+        };
+        const Xhr = root.XMLHttpRequest;
+        if (typeof Xhr === 'function') {
+            const proto = Xhr.prototype;
+            const open = proto.open;
+            const send = proto.send;
+            const setHeader = proto.setRequestHeader;
+            proto.open = function (method, url, ...rest) {
+                this.__cwi = { method: String(method).toUpperCase(), url: String(url), headers: {} };
+                return open.call(this, method, url, ...rest);
+            };
+            proto.setRequestHeader = function (name, value) {
+                // The ring lives in game memory that other game code can read, so credential headers are masked as they are captured.
+                // ponytail: bodies stay raw in the ring and are redacted only when returned; redact here too if third-party SDKs are a concern.
+                if (this.__cwi)
+                    this.__cwi.headers[String(name)] = /auth|cookie|token|secret|api-?key|password|session/i.test(String(name)) ? '[redacted]' : String(value);
+                return setHeader.call(this, name, value);
+            };
+            proto.send = function (body) {
+                const meta = this.__cwi;
+                if (meta) {
+                    const entry = record({ kind: 'xhr', method: meta.method, url: meta.url, requestHeaders: meta.headers, requestBody: clip(body), startedAt: Date.now() });
+                    this.__cwiDone = (failure) => {
+                        if (entry.endedAt)
+                            return;
+                        entry.endedAt = Date.now();
+                        entry.status = Number(this.status) || null;
+                        if (failure)
+                            entry.failure = failure;
+                        try {
+                            entry.responseHeaders = String(this.getAllResponseHeaders() ?? '').slice(0, 10_000);
+                        }
+                        catch { /* not ready */ }
+                        try {
+                            entry.responseBody = clip(this.responseType === '' || this.responseType === 'text' ? this.responseText : this.response);
+                        }
+                        catch { /* unreadable */ }
+                    };
+                    // Native XHR dispatches only through on* properties, and its addEventListener just assigns them, so listeners
+                    // would replace the game's handlers. Chain through accessors instead; the native side reads them with a plain get.
+                    // ponytail: reading xhr.onload returns the chain, not the game's function; keep a handler map if identity matters.
+                    if (!this.__cwiHooked) {
+                        this.__cwiHooked = true;
+                        const xhr = this;
+                        for (const [name, failure] of [['onload', undefined], ['onerror', 'error'], ['ontimeout', 'timeout'], ['onabort', 'abort']]) {
+                            let handler = this[name];
+                            const chain = function (event) {
+                                try {
+                                    xhr.__cwiDone(failure);
+                                }
+                                catch { /* never break the game */ }
+                                return typeof handler === 'function' ? handler.call(this, event) : undefined;
+                            };
+                            Object.defineProperty(this, name, { configurable: true, get: () => chain, set: (fn) => { handler = fn; } });
+                        }
+                    }
+                }
+                return send.call(this, body);
+            };
+        }
+        const NativeSocket = root.WebSocket;
+        if (typeof NativeSocket === 'function') {
+            // Pass every argument through: native WebSocket takes (url, protocols, caFilePath), and dropping the CA file
+            // changes how the game's TLS connection is verified.
+            const Wrapped = function (...args) {
+                const socket = new NativeSocket(...args);
+                const entry = record({ kind: 'websocket', method: 'GET', url: String(args[0]), startedAt: Date.now(), frames: [], framesSeen: 0 });
+                const frame = (direction, data) => {
+                    entry.framesSeen++;
+                    entry.frames.push({ direction, at: Date.now(), data: clip(data).slice(0, 2_000) });
+                    if (entry.frames.length > 50)
+                        entry.frames.shift();
+                };
+                const send = socket.send;
+                socket.send = function (data) { frame('sent', data); return send.call(socket, data); };
+                // Native sockets dispatch only through on* properties; wrap each handler as the game assigns it.
+                for (const [name, hook] of [
+                    ['onopen', () => { entry.status = 101; }],
+                    ['onmessage', (event) => frame('received', event?.data)],
+                    ['onerror', () => { entry.failure = 'error'; }],
+                    ['onclose', (event) => { entry.endedAt = Date.now(); entry.closeCode = Number(event?.code) || null; }],
+                ]) {
+                    let handler = null;
+                    Object.defineProperty(socket, name, {
+                        configurable: true,
+                        get: () => handler,
+                        set: (fn) => { handler = typeof fn === 'function' ? function (event) { try {
+                            hook(event);
+                        }
+                        catch { /* never break the game */ } return fn.call(this, event); } : fn; },
+                    });
+                }
+                return socket;
+            };
+            Wrapped.prototype = NativeSocket.prototype;
+            for (const key of ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'])
+                Wrapped[key] = NativeSocket[key];
+            root.WebSocket = Wrapped;
+        }
+    }
+    if (query.action === 'list')
+        return { installedAt: state.installedAt, installedNow, entries: state.entries.map(({ requestBody: _b, responseBody: _r, frames: _f, requestHeaders: _h, responseHeaders: _rh, ...summary }) => summary) };
+    const entry = state.entries.find(candidate => candidate.id === query.id);
+    return entry ? { installedAt: state.installedAt, entry } : { installedAt: state.installedAt, entry: null };
+}
+const sinceNote = (installedAt, installedNow) => installedNow
+    ? 'Capture started with this call; make the game send traffic, then list again.'
+    : `Requests and WebSocket frames since capture started at ${new Date(installedAt).toISOString()}; the game keeps the last 200.`;
+export async function nativeNetworkRequests(page, options) {
+    const { installedAt, installedNow, entries } = await page.evaluate(nativeNetwork, { action: 'list' });
+    const rows = entries.map(entry => ({
+        id: entry.id,
+        method: entry.method,
+        url: redactUrl(entry.url),
+        resourceType: entry.kind,
+        status: entry.status ?? null,
+        ...(entry.failure ? { failure: String(entry.failure).slice(0, 300) } : {}),
+        ...(entry.endedAt ? { durationMs: entry.endedAt - entry.startedAt } : {}),
+        ...(entry.kind === 'websocket' ? { frames: entry.framesSeen } : {}),
+    }));
+    return selectRequests(rows, options, sinceNote(installedAt, installedNow));
+}
+export async function nativeNetworkRequest(page, id, includeBody) {
+    const { entry } = await page.evaluate(nativeNetwork, { action: 'get', id });
+    if (!entry)
+        throw new InspectorError('REQUEST_NOT_FOUND', `Request ${id} not found; list requests again, older entries are dropped`);
+    // Split each "name: value" line at its first colon only; dates and URLs carry more.
+    const headers = (raw) => Object.fromEntries(raw.split(/\r?\n/).map(line => /^([^:]+):\s*(.*)$/.exec(line)).filter(match => !!match).map(match => [match[1].trim().toLowerCase(), match[2]]));
+    const frames = entry.kind === 'websocket' && includeBody ? entry.frames.map((frame) => ({ direction: frame.direction, at: new Date(frame.at).toISOString(), data: redactBody(frame.data).body })) : undefined;
+    // Native results skip runBridge, so enforce the response ceiling here: drop the oldest frames, then the bodies.
+    let result = detail(entry, id, includeBody, headers, frames);
+    while (frames?.length && !fitsResponse(result)) {
+        frames.splice(0, Math.max(1, Math.ceil(frames.length / 4)));
+        result = { ...detail(entry, id, includeBody, headers, frames), framesDropped: true };
+    }
+    return fitsResponse(result) ? result : { ...detail(entry, id, false, headers, undefined), truncated: true, truncationReasons: ['RESPONSE_LIMIT'] };
+}
+function detail(entry, id, includeBody, headers, frames) {
+    return {
+        id,
+        method: entry.method,
+        url: redactUrl(entry.url),
+        resourceType: entry.kind,
+        ...(entry.requestHeaders ? { requestHeaders: redactHeaders(entry.requestHeaders) } : {}),
+        ...(includeBody && entry.requestBody ? { requestBody: redactBody(entry.requestBody) } : {}),
+        status: entry.status ?? null,
+        ...(entry.responseHeaders ? { responseHeaders: redactHeaders(headers(entry.responseHeaders)) } : {}),
+        ...(entry.failure ? { failure: String(entry.failure).slice(0, 300) } : {}),
+        ...(entry.closeCode ? { closeCode: entry.closeCode } : {}),
+        ...(includeBody && entry.responseBody ? { responseBody: redactBody(entry.responseBody) } : {}),
+        ...(entry.kind === 'websocket' ? { framesSeen: entry.framesSeen, ...(frames ? { frames } : {}) } : {}),
+        timing: { startedAt: new Date(entry.startedAt).toISOString(), ...(entry.endedAt ? { durationMs: entry.endedAt - entry.startedAt } : {}) },
+    };
+}

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 { nativeClick, nativeConsoleMessages, nativeDrag, nativeTypeText } from './native.js';
+import { nativeCaptureNode, nativeClick, nativeConsoleMessages, nativeDrag, nativeNetworkRequest, nativeNetworkRequests, nativeTypeText } from './native.js';
 import { consoleMessages, networkRequest, networkRequests, storage } from './browser-data.js';
 import { captureNode, clickNode, devicePresetNames, dragNode, emulateDevice, inspectCocosPage, networkProfileNames, runBridge, typeText } from './bridge.js';
 const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
@@ -61,7 +61,7 @@ function failure(error) {
 }
 export function createServer(browser, options = {}) {
     const server = new McpServer({ name: 'cocos-web-inspector-mcp', version });
-    // A native (JSB) runtime has no page: screenshots, device emulation, and network/cookie readers need a browser,
+    // A native (JSB) runtime has no page: screenshots and device emulation need a browser,
     // the DOM overlays draw nothing, the 2D batcher runs in C++ where analyze_batches cannot observe it,
     // and game.step renders outside the native frame loop, which crashed a 3.8.8 Android build in the GFX pipeline.
     const web = !options.native;
@@ -136,12 +136,11 @@ export function createServer(browser, options = {}) {
         inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
         annotations: readOnly,
     }, input => executeNode(input, uuid => ({ action: 'getNodeBounds', uuid })));
-    if (web)
-        server.registerTool('cocos_capture_node', {
-            description: 'Capture a bounded viewport-clipped PNG for one visible Cocos UI node UUID.',
-            inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
-            annotations: readOnly,
-        }, input => withNode(input, captureNode));
+    server.registerTool('cocos_capture_node', {
+        description: 'Capture a bounded viewport-clipped PNG for one visible Cocos UI node UUID.',
+        inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
+        annotations: readOnly,
+    }, input => withNode(input, web ? captureNode : nativeCaptureNode));
     server.registerTool('cocos_get_components', {
         description: 'List bounded component summaries for one Cocos node UUID.',
         inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
@@ -316,24 +315,21 @@ export function createServer(browser, options = {}) {
             inputSchema: z.object({ pageUrl, types: z.array(z.enum(['log', 'debug', 'info', 'error', 'warning', 'assert', 'trace', 'pageerror'])).max(8).optional(), textContains: z.string().min(1).max(200).optional(), limit: z.number().int().min(1).max(200).optional() }).strict(),
             annotations: browserData,
         }, input => run(async () => (web ? consoleMessages : nativeConsoleMessages)(await browser.page(input.pageUrl), input)));
-        // ponytail: native network and storage need jsb XHR hooks and a jsb.localStorage reader; add them when a native game needs them.
-        if (web) {
-            server.registerTool('cocos_network_requests', {
-                description: 'List recent network requests since the server attached: id, method, URL with secret query values masked, resource type, status, failure, and duration. Use cocos_network_request for headers and bodies.',
-                inputSchema: z.object({ pageUrl, urlContains: z.string().min(1).max(500).optional(), resourceType: z.string().min(1).max(40).optional(), failedOnly: z.boolean().optional(), limit: z.number().int().min(1).max(200).optional() }).strict(),
-                annotations: browserData,
-            }, input => run(async () => networkRequests(await browser.page(input.pageUrl), input)));
-            server.registerTool('cocos_network_request', {
-                description: 'Return one request by id from cocos_network_requests: headers with authorization and cookies masked, status, timing, and optionally text bodies up to 20 KB with secret-like JSON and form fields masked.',
-                inputSchema: z.object({ pageUrl, id: z.number().int().min(1), includeBody: z.boolean().optional() }).strict(),
-                annotations: browserData,
-            }, input => run(async () => networkRequest(await browser.page(input.pageUrl), input.id, input.includeBody ?? false)));
-            server.registerTool('cocos_storage', {
-                description: 'Read localStorage or sessionStorage entries, or cookie names and attributes for the page. Secret-like keys and every cookie value are masked; JSON values are masked by key.',
-                inputSchema: z.object({ pageUrl, area: z.enum(['local', 'session', 'cookies']), keyContains: z.string().min(1).max(200).optional(), limit: z.number().int().min(1).max(500).optional() }).strict(),
-                annotations: browserData,
-            }, input => run(async () => storage(await browser.page(input.pageUrl), input.area, input.keyContains, input.limit)));
-        }
+        server.registerTool('cocos_network_requests', {
+            description: 'List recent network requests since the server attached: id, method, URL with secret query values masked, resource type, status, failure, and duration. Use cocos_network_request for headers and bodies.',
+            inputSchema: z.object({ pageUrl, urlContains: z.string().min(1).max(500).optional(), resourceType: z.string().min(1).max(40).optional(), failedOnly: z.boolean().optional(), limit: z.number().int().min(1).max(200).optional() }).strict(),
+            annotations: browserData,
+        }, input => run(async () => (web ? networkRequests : nativeNetworkRequests)(await browser.page(input.pageUrl), input)));
+        server.registerTool('cocos_network_request', {
+            description: 'Return one request by id from cocos_network_requests: headers with authorization and cookies masked, status, timing, and optionally text bodies up to 20 KB with secret-like JSON and form fields masked.',
+            inputSchema: z.object({ pageUrl, id: z.number().int().min(1), includeBody: z.boolean().optional() }).strict(),
+            annotations: browserData,
+        }, input => run(async () => (web ? networkRequest : nativeNetworkRequest)(await browser.page(input.pageUrl), input.id, input.includeBody ?? false)));
+        server.registerTool('cocos_storage', {
+            description: 'Read localStorage or sessionStorage entries, or cookie names and attributes for the page. Secret-like keys and every cookie value are masked; JSON values are masked by key.',
+            inputSchema: z.object({ pageUrl, area: z.enum(['local', 'session', 'cookies']), keyContains: z.string().min(1).max(200).optional(), limit: z.number().int().min(1).max(500).optional() }).strict(),
+            annotations: browserData,
+        }, input => run(async () => storage(await browser.page(input.pageUrl), input.area, input.keyContains, input.limit)));
     }
     if (web)
         server.registerTool('cocos_get_selection', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cocos-web-inspector-mcp",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "MCP server to inspect and debug Cocos Creator 3.x web builds in local Chromium over CDP",
   "license": "MIT",
   "repository": {