cocos-web-inspector-mcp 2.1.0 → 2.2.1

package/README.md

@@ -45,6 +45,29 @@ chrome.exe --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 --u
 
 Keep this browser profile separate from normal browsing. CDP provides code-execution-level access to attached pages.
 
+### Native builds (Android)
+
+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 --native-endpoint http://127.0.0.1:<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_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+.
+- `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.
+
+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 or the device dropped off USB, which takes the forward with it; run `adb forward` again. 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`.
+
+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
 
 Run the published npm package with the default CDP endpoint, `http://127.0.0.1:9222`:
@@ -73,7 +96,9 @@ Endpoint precedence is:
 2. `COCOS_CDP_ENDPOINT`
 3. `http://127.0.0.1:9222`
 
-`--cdp-endpoint` and `--allow-runtime-mutation` are the only server options; `launch` and `doctor` are separate commands. `--cdp-endpoint` identifies the browser CDP endpoint, not a game page URL.
+`--native-endpoint` attaches to a native debug build instead (see Native builds).
+
+`--cdp-endpoint`, `--native-endpoint`, and the `--allow-*` flags are the server options; `launch` and `doctor` are separate commands. `--cdp-endpoint` identifies the browser CDP endpoint, not a game page URL.
 
 The server uses stdio for MCP. Standard output is reserved for protocol traffic; startup diagnostics are written to standard error.
 

package/dist/src/bridge.d.ts

@@ -134,6 +134,12 @@ 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 nodeCenter(page: Page, uuid: string): Promise<{
+    x: number;
+    y: number;
+} | {
+    reason: string;
+}>;
 export declare function clickNode(page: Page, uuid: string): Promise<unknown>;
 export declare function dragNode(page: Page, uuid: string, dx: number, dy: number, steps?: number, durationMs?: number): Promise<unknown>;
 export declare function typeText(page: Page, uuid: string, text: string, submit: boolean): Promise<unknown>;

package/dist/src/bridge.js

@@ -39,7 +39,7 @@ export async function captureNode(page, uuid) {
     }
     return { captured: false, reason: 'RESPONSE_LIMIT' };
 }
-async function nodeCenter(page, uuid) {
+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' };
@@ -220,7 +220,8 @@ export function inspectCocosPage() {
 }
 export function inspectCocos(request) {
     const root = globalThis;
-    if (root.location) {
+    // Browsers always report a protocol; only the Cocos native (jsb) location shim has an empty one, and its endpoint was already checked to be loopback.
+    if (root.location && root.location.protocol !== '') {
         const target = new URL(root.location.href);
         const host = target.hostname.replace(/^\[|\]$/g, '').toLowerCase();
         const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
@@ -809,11 +810,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');
@@ -1161,7 +1160,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;
@@ -1351,23 +1364,27 @@ export function inspectCocos(request) {
                 return;
             // cachedCameraPriority is refreshed only on real dispatch, so ask the batcher, as UITransform.cameraPriority does.
             let camera = 0;
+            // Touches carry their window's id and hitTest skips other windows' cameras: 0 on the web, the native window's id (1) on device.
+            let windowId = 0;
             try {
-                camera = Number(cc.director?.root?.batcher2D?.getFirstRenderCamera?.(node)?.priority ?? 0);
+                const found = cc.director?.root?.batcher2D?.getFirstRenderCamera?.(node);
+                camera = Number(found?.priority ?? 0);
+                windowId = Number(found?.systemWindowId ?? 0);
             }
             catch {
                 camera = 0;
             }
-            candidates.push({ node, order, camera });
+            candidates.push({ node, order, camera, windowId });
         });
-        const sorted = candidates.sort((a, b) => b.camera - a.camera || b.order - a.order).map(candidate => candidate.node);
+        const sorted = candidates.sort((a, b) => b.camera - a.camera || b.order - a.order);
         const hits = [];
         let claimer;
-        for (const node of sorted) {
+        for (const { node, windowId } of sorted) {
             const transform = components(node).find(component => componentName(component) === 'UITransform');
             let hit = false;
             // hitTest is the engine's own public query: matrix math and Mask checks, no state change.
             try {
-                hit = !!screenPoint && typeof transform?.hitTest === 'function' && transform.hitTest(screenPoint, 0);
+                hit = !!screenPoint && typeof transform?.hitTest === 'function' && transform.hitTest(screenPoint, windowId);
             }
             catch {
                 hit = false;
@@ -1676,10 +1693,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/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { BrowserConnection } from './browser.js';
+import { NativeConnection } from './native.js';
 import { createServer } from './server.js';
 function optionsFromArgs(args) {
     let endpoint = process.env.COCOS_CDP_ENDPOINT ?? 'http://127.0.0.1:9222';
+    let nativeEndpoint;
     let allowRuntimeMutation = false;
     let allowBrowserData = false;
     let allowMethodCall = false;
@@ -28,18 +30,24 @@ function optionsFromArgs(args) {
             endpoint = value;
             continue;
         }
+        if (arg === '--native-endpoint') {
+            nativeEndpoint = args[++index];
+            if (!nativeEndpoint)
+                throw new Error('--native-endpoint requires a value');
+            continue;
+        }
         if (arg.startsWith('-'))
             throw new Error(`Unknown argument: ${arg}`);
     }
-    return { endpoint, allowRuntimeMutation, allowBrowserData, allowMethodCall };
+    return { endpoint, nativeEndpoint, allowRuntimeMutation, allowBrowserData, allowMethodCall };
 }
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     if (command === 'launch' || command === 'doctor')
         return (await import('./cli.js')).commands[command](rest);
     const options = optionsFromArgs(process.argv.slice(2));
-    const browser = new BrowserConnection(options.endpoint);
-    const server = createServer(browser, { allowRuntimeMutation: options.allowRuntimeMutation, allowBrowserData: options.allowBrowserData, allowMethodCall: options.allowMethodCall });
+    const browser = options.nativeEndpoint ? new NativeConnection(options.nativeEndpoint) : new BrowserConnection(options.endpoint);
+    const server = createServer(browser, { allowRuntimeMutation: options.allowRuntimeMutation, allowBrowserData: options.allowBrowserData, allowMethodCall: options.allowMethodCall, native: !!options.nativeEndpoint });
     let closing = false;
     const close = async () => {
         if (closing)

package/dist/src/native.d.ts

@@ -0,0 +1,26 @@
+import type { Page } from 'playwright-core';
+type Evaluate = (webSocketUrl: string, expression: string, timeout: number) => Promise<unknown>;
+export declare class NativeConnection {
+    #private;
+    private readonly timeout;
+    private readonly evaluateExpression;
+    constructor(endpoint: string, timeout?: number, evaluateExpression?: Evaluate);
+    pages(): Promise<Page[]>;
+    page(_pageUrl?: string): Promise<Page>;
+    close(): Promise<void>;
+}
+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>;
+/** 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;
+    text: string;
+    time: number;
+}>;
+export declare function nativeConsoleMessages(page: Page, options: {
+    types?: string[] | undefined;
+    textContains?: string | undefined;
+    limit?: number | undefined;
+}): Promise<unknown>;
+export declare function nativeTypeText(page: Page, uuid: string, text: string, submit: boolean): Promise<unknown>;
+export {};

package/dist/src/native.js

@@ -0,0 +1,184 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { nodeCenter, runBridge } from './bridge.js';
+import { InspectorError, validateLocalUrl } from './browser.js';
+import { redactText } 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 {
+    timeout;
+    evaluateExpression;
+    #http;
+    #page;
+    constructor(endpoint, timeout = 60_000, evaluateExpression = evaluateOverWebSocket) {
+        this.timeout = timeout;
+        this.evaluateExpression = evaluateExpression;
+        const url = validateLocalUrl(endpoint);
+        url.protocol = url.protocol === 'wss:' || url.protocol === 'https:' ? 'https:' : 'http:';
+        url.pathname = '/';
+        this.#http = url;
+        // Only the evaluate/url subset of Page that runBridge and cocos_list_pages use.
+        this.#page = { url: () => this.#http.href, evaluate: (fn, arg) => this.#evaluate(fn, arg) };
+    }
+    async pages() {
+        return [this.#page];
+    }
+    async page(_pageUrl) {
+        return this.#page;
+    }
+    async close() { }
+    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();
+        }
+        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>`);
+        }
+        if (!Array.isArray(targets) || targets.length === 0)
+            throw new InspectorError('NO_LOCAL_PAGE', 'Native inspector lists no target');
+        const debuggerUrl = targets.find(target => target.webSocketDebuggerUrl)?.webSocketDebuggerUrl;
+        if (!debuggerUrl)
+            throw new InspectorError('CDP_UNAVAILABLE', 'Native inspector already has a session; close Chrome DevTools attached to the game');
+        // Connect to the validated endpoint host, never to the host the target list names.
+        const socketUrl = new URL(new URL(debuggerUrl).pathname, this.#http);
+        socketUrl.protocol = this.#http.protocol === 'https:' ? 'wss:' : 'ws:';
+        // Functions passed here are self-contained (inspectCocos, inspectCocosPage), so their source runs as is.
+        return this.evaluateExpression(socketUrl.href, `(${fn.toString()})(${arg === undefined ? '' : JSON.stringify(arg)})`, this.timeout);
+    }
+}
+async function evaluateOverWebSocket(webSocketUrl, expression, timeout) {
+    const socket = new WebSocket(webSocketUrl);
+    let timer;
+    try {
+        return await new Promise((resolve, reject) => {
+            timer = setTimeout(() => reject(new InspectorError('CDP_UNAVAILABLE', 'Native inspector did not answer in time')), timeout);
+            socket.onerror = () => reject(new InspectorError('CDP_UNAVAILABLE', 'Native inspector connection failed'));
+            socket.onclose = () => reject(new InspectorError('CDP_UNAVAILABLE', 'Native inspector closed the connection'));
+            socket.onopen = () => socket.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { expression, returnByValue: true, awaitPromise: true } }));
+            socket.onmessage = event => {
+                const message = JSON.parse(String(event.data));
+                if (message.id !== 1)
+                    return;
+                if (message.error)
+                    return reject(new InspectorError('CDP_UNAVAILABLE', `Native inspector error: ${String(message.error.message).slice(0, 500)}`));
+                const exception = message.result?.exceptionDetails;
+                // Match Playwright's in-page error text, so the server maps bridge errors to the same codes.
+                if (exception)
+                    return reject(new Error(String(exception.exception?.description ?? exception.text ?? 'Evaluation failed').split('\n')[0].replace(/^Error: /, '')));
+                resolve(message.result?.result?.value);
+            };
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        socket.close();
+    }
+}
+// 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) {
+    try {
+        return (await run('adb', args, { 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`);
+    }
+}
+// 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));
+export async function nativeClick(page, uuid) {
+    const point = await nodeCenter(page, uuid);
+    if ('reason' in point)
+        return { clicked: false, reason: point.reason };
+    await adb(['shell', 'input', 'tap', pixel(point.x), pixel(point.y)]);
+    // adb returns once the event is injected; the game handles it on its next frames.
+    await settle();
+    return { clicked: true, target: { nodeUuid: uuid }, point, input: 'adb', runtimeOnly: true };
+}
+export async function nativeDrag(page, uuid, dx, dy, durationMs = 300) {
+    const from = await nodeCenter(page, uuid);
+    if ('reason' in from)
+        return { dragged: false, reason: from.reason };
+    const to = { x: from.x + dx, y: from.y + dy };
+    // input swipe interpolates its own moves, so steps does not apply.
+    await adb(['shell', 'input', 'swipe', pixel(from.x), pixel(from.y), pixel(to.x), pixel(to.y), String(Math.max(durationMs, 1))]);
+    await settle();
+    return { dragged: true, target: { nodeUuid: uuid }, from, to, input: 'adb', runtimeOnly: true };
+}
+// 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?.() ?? ''));
+    const name = /^\/data\/(?:user\/\d+|data)\/([A-Za-z][\w.]{0,200})\//.exec(path)?.[1];
+    if (!name)
+        throw new InspectorError('CDP_UNAVAILABLE', 'Unable to identify the app package from the native runtime');
+    const pid = (await adb(['shell', 'pidof', name]).catch(() => '')).trim().split(/\s+/)[0] ?? '';
+    if (!/^\d+$/.test(pid))
+        throw new InspectorError('CDP_UNAVAILABLE', `App ${name} is not running`);
+    return pid;
+}
+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) {
+    const messages = [];
+    for (const line of output.split(/\r?\n/)) {
+        const match = /^\s*(\d+\.\d+)\s+\d+\s+\d+\s+([VDIWEF])\s+Cocos\s*:\s?(?:\d\d:\d\d:\d\d \[\w+\]: )?(.*)$/.exec(line);
+        if (match)
+            messages.push({ type: levels[match[2]], text: match[3], time: Number(match[1]) });
+    }
+    return messages;
+}
+export async function nativeConsoleMessages(page, options) {
+    const limit = options.limit ?? 50;
+    const output = await adb(['logcat', '-d', '-v', 'epoch', `--pid=${await appProcess(page)}`, '-s', 'Cocos:V']);
+    const items = parseCocosLogcat(output)
+        .filter(item => !options.types?.length || options.types.includes(item.type))
+        .filter(item => !options.textContains || item.text.includes(options.textContains));
+    const selected = items.slice(-limit).map(item => ({ type: item.type, text: redactText(item.text), time: new Date(item.time * 1_000).toISOString() }));
+    return {
+        messages: selected,
+        matched: items.length,
+        truncated: items.length > limit,
+        note: 'Cocos-tagged logcat lines of the app process since it started, bounded by the device log buffer. Engine lines start with D/ or E/; an uncaught JS error spans several error lines (message, then stack).',
+    };
+}
+// Tapping an EditBox on Android opens CocosEditBoxActivity, a native EditText whose every change fires text-changed in the game.
+export async function nativeTypeText(page, uuid, text, submit) {
+    // input text only types printable ASCII and turns "%s" into a space, so refuse what it would silently mangle.
+    if (!/^[\x20-\x7e]*$/.test(text) || text.includes('%s'))
+        throw new Error('Invalid mutation: native typing supports printable ASCII without "%s"');
+    const { components } = await runBridge(page, { action: 'getComponents', uuid });
+    if (!components?.some(component => component.type === 'EditBox'))
+        throw new Error('Component not found');
+    const clicked = await nativeClick(page, uuid);
+    if (!clicked.clicked)
+        return { typed: false, reason: clicked.reason };
+    let focused = false;
+    for (let attempt = 0; attempt < 10 && !focused; attempt++) {
+        focused = (await adb(['shell', 'dumpsys window | grep mCurrentFocus'])).includes('CocosEditBoxActivity');
+        if (!focused)
+            await settle();
+    }
+    if (!focused)
+        return { typed: false, reason: 'NOT_FOCUSED' };
+    // End, Shift+Home, Delete: select the current content and remove it. keycombination needs Android 12+.
+    await adb(['shell', 'input', 'keyevent', 'KEYCODE_MOVE_END']);
+    await adb(['shell', 'input', 'keycombination', 'KEYCODE_SHIFT_LEFT', 'KEYCODE_MOVE_HOME']);
+    await adb(['shell', 'input', 'keyevent', 'KEYCODE_DEL']);
+    // adb shell joins its arguments into one device shell command line: single-quote the text so it stays one literal word.
+    if (text)
+        await adb(['shell', `input text '${text.replace(/ /g, '%s').replace(/'/g, `'\\''`)}'`]);
+    // Enter closes a single-line box (editing-did-ended); only the activity's confirm button fires editing-return.
+    if (submit)
+        await adb(['shell', 'input', 'keyevent', 'KEYCODE_ENTER']);
+    await settle();
+    const { properties } = await runBridge(page, { action: 'getProperties', uuid, componentType: 'EditBox', maxDepth: 0 });
+    const after = typeof properties?.string === 'string' ? { string: properties.string } : { redacted: true };
+    // The device keyboard still sees the keys: autocorrect or a Telex layout can rewrite "test" as "tét".
+    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 };
+}

package/dist/src/server.d.ts

@@ -1,7 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { BrowserConnection } from './browser.js';
-export declare function createServer(browser: BrowserConnection, options?: {
+import { type NativeConnection } from './native.js';
+export declare function createServer(browser: BrowserConnection | NativeConnection, options?: {
     allowRuntimeMutation?: boolean;
     allowBrowserData?: boolean;
     allowMethodCall?: boolean;
+    native?: boolean;
 }): McpServer;

package/dist/src/server.js

@@ -2,6 +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 { 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'));
@@ -60,6 +61,10 @@ 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,
+    // 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;
     const execute = async (request, selectedPage) => {
         try {
             return response(await runBridge(await browser.page(selectedPage), request));
@@ -131,11 +136,12 @@ export function createServer(browser, options = {}) {
         inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
         annotations: readOnly,
     }, input => executeNode(input, uuid => ({ action: 'getNodeBounds', uuid })));
-    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));
+    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_get_components', {
         description: 'List bounded component summaries for one Cocos node UUID.',
         inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
@@ -188,7 +194,7 @@ export function createServer(browser, options = {}) {
             inputSchema: z.object({ pageUrl, ...target }).strict().refine(oneTarget, oneTargetMessage),
             // 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 },
-        }, input => withNode(input, clickNode));
+        }, input => withNode(input, web ? clickNode : nativeClick));
         // Like click: game drag and input handlers run arbitrary code.
         const realInput = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
         server.registerTool('cocos_drag_node', {
@@ -196,17 +202,18 @@ export function createServer(browser, options = {}) {
             inputSchema: z.object({ pageUrl, ...target, dx: z.number().min(-4_000).max(4_000), dy: z.number().min(-4_000).max(4_000), steps: z.number().int().min(1).max(60).optional(), durationMs: z.number().int().min(0).max(5_000).optional() }).strict().refine(oneTarget, oneTargetMessage)
                 .refine(value => value.dx !== 0 || value.dy !== 0, 'Provide a non-zero dx or dy'),
             annotations: realInput,
-        }, input => withNode(input, (page, uuid) => dragNode(page, uuid, input.dx, input.dy, input.steps, input.durationMs)));
+        }, input => withNode(input, (page, uuid) => web ? dragNode(page, uuid, input.dx, input.dy, input.steps, input.durationMs) : nativeDrag(page, uuid, input.dx, input.dy, input.durationMs)));
         server.registerTool('cocos_type_text', {
             description: 'Tap one Cocos EditBox and type text with real keyboard input, replacing its content, so text-changed and editing events fire; submit presses Enter (editing-return on single-line boxes, a newline in multi-line ones). Password text is never echoed back.',
             inputSchema: z.object({ pageUrl, ...target, text: z.string().max(2_000), submit: z.boolean().optional() }).strict().refine(oneTarget, oneTargetMessage),
             annotations: realInput,
-        }, input => withNode(input, (page, uuid) => typeText(page, uuid, input.text, input.submit ?? false)));
-        server.registerTool('cocos_analyze_batches', {
-            description: 'Capture the 2D draw batches of the next rendered frame: the node that starts each batch and why the previous batch broke (TEXTURE, MATERIAL, MASK, STENCIL, LAYER, BUFFER, MODEL, MIDDLEWARE, ...). Wraps engine batcher methods for that one frame only; the game must be running. tintMs overlays each batch\'s nodes in its own color for that long.',
-            inputSchema: z.object({ pageUrl, limit: z.number().int().min(1).max(500).optional(), tintMs: z.number().int().min(100).max(30_000).optional() }).strict(),
-            annotations: { ...runtimeMutation, idempotentHint: false },
-        }, input => execute({ action: 'analyzeBatches', limit: input.limit, tintMs: input.tintMs }, input.pageUrl));
+        }, input => withNode(input, (page, uuid) => (web ? typeText : nativeTypeText)(page, uuid, input.text, input.submit ?? false)));
+        if (web)
+            server.registerTool('cocos_analyze_batches', {
+                description: 'Capture the 2D draw batches of the next rendered frame: the node that starts each batch and why the previous batch broke (TEXTURE, MATERIAL, MASK, STENCIL, LAYER, BUFFER, MODEL, MIDDLEWARE, ...). Wraps engine batcher methods for that one frame only; the game must be running. tintMs overlays each batch\'s nodes in its own color for that long.',
+                inputSchema: z.object({ pageUrl, limit: z.number().int().min(1).max(500).optional(), tintMs: z.number().int().min(100).max(30_000).optional() }).strict(),
+                annotations: { ...runtimeMutation, idempotentHint: false },
+            }, input => execute({ action: 'analyzeBatches', limit: input.limit, tintMs: input.tintMs }, input.pageUrl));
         for (const action of ['pause', 'resume']) {
             server.registerTool(`cocos_${action}`, {
                 description: `${action === 'pause' ? 'Pause' : 'Resume'} the Cocos director through its public API.`,
@@ -214,11 +221,12 @@ 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));
+        if (web)
+            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_set_time_scale', {
             description: 'Speed up or slow down the whole game by scaling the delta time of every frame (components, scheduler, tweens, animation, physics). 1 restores normal speed; omit scale to read it.',
             inputSchema: z.object({ pageUrl, scale: z.number().gt(0).max(100).optional() }).strict(),
@@ -229,34 +237,35 @@ export function createServer(browser, options = {}) {
             inputSchema: z.object({ pageUrl, visible: z.boolean() }).strict(),
             annotations: runtimeMutation,
         }, input => execute({ action: 'showStats', visible: input.visible }, input.pageUrl));
-        server.registerTool('cocos_emulate_device', {
-            description: 'Emulate a mobile device (viewport, DPR, touch, user agent, orientation) and optionally slow the CPU or network, like the Chrome device toolbar. Settings merge across calls and last until reset or server disconnect; reload lets the game re-detect touch and user agent.',
-            inputSchema: z.object({
-                pageUrl,
-                reset: z.boolean().optional(),
-                preset: z.enum(devicePresetNames).optional(),
-                width: z.number().int().min(200).max(4_000).optional(),
-                height: z.number().int().min(200).max(4_000).optional(),
-                deviceScaleFactor: z.number().min(1).max(4).optional(),
-                mobile: z.boolean().optional(),
-                orientation: z.enum(['portrait', 'landscape']).optional(),
-                cpuSlowdown: z.number().min(1).max(20).optional(),
-                network: z.enum(networkProfileNames).optional(),
-                reload: z.boolean().optional(),
-            }).strict()
-                .refine(value => (value.width === undefined) === (value.height === undefined), 'Provide width and height together')
-                .refine(value => !(value.preset && value.width !== undefined), 'Provide preset or width and height, not both')
-                .refine(value => value.width !== undefined || (value.deviceScaleFactor === undefined && value.mobile === undefined), 'deviceScaleFactor and mobile need width and height')
-                .refine(value => !value.reset || Object.keys(value).every(key => ['pageUrl', 'reset', 'reload'].includes(key)), 'reset accepts only pageUrl and reload'),
-            annotations: { ...runtimeMutation, idempotentHint: false },
-        }, async (input) => {
-            try {
-                return response(await emulateDevice(await browser.page(input.pageUrl), input));
-            }
-            catch (error) {
-                return failure(error);
-            }
-        });
+        if (web)
+            server.registerTool('cocos_emulate_device', {
+                description: 'Emulate a mobile device (viewport, DPR, touch, user agent, orientation) and optionally slow the CPU or network, like the Chrome device toolbar. Settings merge across calls and last until reset or server disconnect; reload lets the game re-detect touch and user agent.',
+                inputSchema: z.object({
+                    pageUrl,
+                    reset: z.boolean().optional(),
+                    preset: z.enum(devicePresetNames).optional(),
+                    width: z.number().int().min(200).max(4_000).optional(),
+                    height: z.number().int().min(200).max(4_000).optional(),
+                    deviceScaleFactor: z.number().min(1).max(4).optional(),
+                    mobile: z.boolean().optional(),
+                    orientation: z.enum(['portrait', 'landscape']).optional(),
+                    cpuSlowdown: z.number().min(1).max(20).optional(),
+                    network: z.enum(networkProfileNames).optional(),
+                    reload: z.boolean().optional(),
+                }).strict()
+                    .refine(value => (value.width === undefined) === (value.height === undefined), 'Provide width and height together')
+                    .refine(value => !(value.preset && value.width !== undefined), 'Provide preset or width and height, not both')
+                    .refine(value => value.width !== undefined || (value.deviceScaleFactor === undefined && value.mobile === undefined), 'deviceScaleFactor and mobile need width and height')
+                    .refine(value => !value.reset || Object.keys(value).every(key => ['pageUrl', 'reset', 'reload'].includes(key)), 'reset accepts only pageUrl and reload'),
+                annotations: { ...runtimeMutation, idempotentHint: false },
+            }, async (input) => {
+                try {
+                    return response(await emulateDevice(await browser.page(input.pageUrl), input));
+                }
+                catch (error) {
+                    return failure(error);
+                }
+            });
     }
     server.registerTool('cocos_explain_click', {
         description: 'Explain whether a tap on a node (or at viewport x/y) reaches it, replaying the engine touch dispatch order without dispatching: which node would claim the touch, the hit stack, and reasons such as INACTIVE, BUTTON_NOT_INTERACTABLE, BLOCKED_BY_BLOCK_INPUT_EVENTS, COVERED_BY_OTHER_NODE, NO_TOUCH_LISTENER, or OUTSIDE_VIEWPORT.',
@@ -306,33 +315,38 @@ export function createServer(browser, options = {}) {
             description: 'List recent console messages and uncaught page errors since the server attached (newest last). Secret-like values, JWTs, and bearer tokens are masked; text is untrusted page output.',
             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 () => consoleMessages(await browser.page(input.pageUrl), input)));
-        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)));
+        }, 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_get_selection', {
-        description: 'Return the node the user last Alt+clicked on the game canvas. The first call installs the picker; Alt+clicks are kept from the game, other input is untouched. disable removes the picker, overlay, and selection.',
-        inputSchema: z.object({ pageUrl, disable: z.boolean().optional() }).strict(),
-        // Installs a page-level listener and DOM overlay only; never touches the Cocos graph.
-        annotations: { ...readOnly, readOnlyHint: false },
-    }, input => execute({ action: 'selection', disable: input.disable }, input.pageUrl));
-    server.registerTool('cocos_highlight_node', {
-        description: 'Temporarily draw a pointer-transparent DOM overlay around one Cocos UI node.',
-        inputSchema: z.object({ pageUrl, ...target, durationMs: z.number().int().min(100).max(10_000).optional() }).strict().refine(oneTarget, oneTargetMessage),
-        annotations: temporaryMutation,
-    }, input => executeNode(input, uuid => ({ action: 'highlightNode', uuid, durationMs: input.durationMs })));
+    if (web)
+        server.registerTool('cocos_get_selection', {
+            description: 'Return the node the user last Alt+clicked on the game canvas. The first call installs the picker; Alt+clicks are kept from the game, other input is untouched. disable removes the picker, overlay, and selection.',
+            inputSchema: z.object({ pageUrl, disable: z.boolean().optional() }).strict(),
+            // Installs a page-level listener and DOM overlay only; never touches the Cocos graph.
+            annotations: { ...readOnly, readOnlyHint: false },
+        }, input => execute({ action: 'selection', disable: input.disable }, input.pageUrl));
+    if (web)
+        server.registerTool('cocos_highlight_node', {
+            description: 'Temporarily draw a pointer-transparent DOM overlay around one Cocos UI node.',
+            inputSchema: z.object({ pageUrl, ...target, durationMs: z.number().int().min(100).max(10_000).optional() }).strict().refine(oneTarget, oneTargetMessage),
+            annotations: temporaryMutation,
+        }, input => executeNode(input, uuid => ({ action: 'highlightNode', uuid, durationMs: input.durationMs })));
     return server;
 }

package/package.json

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