cocos-web-inspector-mcp 2.0.1 → 2.2.0

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

@@ -0,0 +1,23 @@
+import type { Page } from 'playwright-core';
+export declare function isSensitiveKey(key: string): boolean;
+export declare function redactText(text: string, limit?: number): string;
+export declare function redactUrl(raw: string): string;
+export declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
+/** Redacts a body: JSON by key, form data by field, anything else as text. */
+export declare function redactBody(text: string): {
+    body: string;
+    truncated: boolean;
+};
+export declare function consoleMessages(page: Page, options: {
+    types?: string[] | undefined;
+    textContains?: string | undefined;
+    limit?: number | undefined;
+}): Promise<unknown>;
+export declare function networkRequests(page: Page, options: {
+    urlContains?: string | undefined;
+    resourceType?: string | undefined;
+    failedOnly?: boolean | undefined;
+    limit?: number | undefined;
+}): Promise<unknown>;
+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>;

package/dist/src/browser-data.js

@@ -0,0 +1,166 @@
+import { InspectorError } from './browser.js';
+// Browser data tools (console, network, storage) run only behind --allow-browser-data.
+// Redaction is best effort: secret-like keys, auth headers, cookie values, JWTs, and bearer tokens are masked; free text can still leak.
+const REDACTED = '[redacted]';
+const MAX_TEXT = 2_000;
+const MAX_BODY = 20_000;
+const sensitiveParts = ['token', 'cookie', 'authorization', 'password', 'passwd', 'secret', 'credential', 'jwt', 'apikey', 'privatekey', 'accesskey', 'signingkey', 'authheader', 'signature', 'otp', 'pin'];
+const sensitiveHeaders = new Set(['authorization', 'proxy-authorization', 'cookie', 'set-cookie', 'x-api-key', 'x-auth-token', 'x-csrf-token', 'x-xsrf-token']);
+export function isSensitiveKey(key) {
+    const normalized = key.toLowerCase().replace(/[^a-z]/g, '');
+    return sensitiveParts.some(part => part === 'pin' || part === 'otp' ? normalized === part : normalized.includes(part))
+        || normalized.includes('bearer')
+        || normalized.startsWith('session') && ['id', 'key', 'token'].some(part => normalized.includes(part));
+}
+export function redactText(text, limit = MAX_TEXT) {
+    return text
+        .replace(/eyJ[\w-]{5,}\.[\w-]{5,}\.[\w-]{5,}/g, '[redacted-jwt]')
+        .replace(/\b(Bearer|Basic)\s+[\w.~+/=-]{8,}/gi, '$1 [redacted]')
+        .replace(/((?:^|[?&;\s"'{,])([\w-]+)["']?\s*[=:]\s*["']?)([^&;\s"',}]+)/g, (match, prefix, key) => isSensitiveKey(key) ? `${prefix}${REDACTED}` : match)
+        .slice(0, limit);
+}
+export function redactUrl(raw) {
+    try {
+        const url = new URL(raw);
+        url.username = '';
+        url.password = '';
+        for (const key of [...url.searchParams.keys()])
+            if (isSensitiveKey(key))
+                url.searchParams.set(key, REDACTED);
+        return redactText(url.toString());
+    }
+    catch {
+        return redactText(raw);
+    }
+}
+export function redactHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).slice(0, 100).map(([name, value]) => [name, sensitiveHeaders.has(name.toLowerCase()) || isSensitiveKey(name) ? REDACTED : redactText(value, 500)]));
+}
+function redactJson(value, depth = 0) {
+    if (typeof value === 'string')
+        return redactText(value);
+    if (!value || typeof value !== 'object')
+        return value;
+    if (depth > 20)
+        return '[MaxDepth]';
+    if (Array.isArray(value))
+        return value.slice(0, 500).map(item => redactJson(item, depth + 1));
+    return Object.fromEntries(Object.entries(value).slice(0, 500).map(([key, item]) => [key, isSensitiveKey(key) ? REDACTED : redactJson(item, depth + 1)]));
+}
+/** Redacts a body: JSON by key, form data by field, anything else as text. */
+export function redactBody(text) {
+    let body;
+    try {
+        body = JSON.stringify(redactJson(JSON.parse(text)));
+    }
+    catch {
+        body = /^[\w.%+-]+=[^&]*(&[\w.%+-]+=[^&]*)*$/.test(text.trim())
+            ? text.split('&').map(pair => { const [key = '', ...rest] = pair.split('='); return isSensitiveKey(decodeURIComponent(key)) ? `${key}=${REDACTED}` : `${key}=${rest.join('=')}`; }).join('&')
+            : redactText(text, Number.MAX_SAFE_INTEGER);
+    }
+    return { body: body.slice(0, MAX_BODY), truncated: body.length > MAX_BODY };
+}
+export async function consoleMessages(page, options) {
+    const limit = options.limit ?? 50;
+    const messages = (await page.consoleMessages()).filter(message => !options.types?.length || options.types.includes(message.type()));
+    const errors = (await page.pageErrors()).map(error => ({ type: 'pageerror', text: `${error.name}: ${error.message}`, location: (error.stack ?? '').split('\n')[1]?.trim().slice(0, 300) }));
+    const items = [
+        ...messages.map(message => {
+            const location = message.location();
+            return { type: message.type(), text: message.text(), location: location.url ? `${redactUrl(location.url)}:${location.lineNumber}:${location.columnNumber}` : undefined };
+        }),
+        ...(!options.types?.length || options.types.includes('pageerror') ? errors : []),
+    ].filter(item => !options.textContains || item.text.includes(options.textContains));
+    const selected = items.slice(-limit).map(item => ({ ...item, text: redactText(item.text) }));
+    return { messages: selected, matched: items.length, truncated: items.length > limit, note: 'Messages since this server attached to the page (Playwright keeps the last 200); reload the page to capture startup logs.' };
+}
+// Playwright Request objects carry no stable id; number them per page as they are first listed.
+const requestIds = new WeakMap();
+let nextRequestId = 1;
+const idOf = (request) => {
+    let id = requestIds.get(request);
+    if (id === undefined)
+        requestIds.set(request, id = nextRequestId++);
+    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;
+        const timing = request.timing();
+        return {
+            id: idOf(request),
+            method: request.method(),
+            url: redactUrl(request.url()),
+            resourceType: request.resourceType(),
+            status: response?.status() ?? null,
+            ...(failure ? { failure: failure.slice(0, 300) } : {}),
+            ...(timing.responseEnd > 0 ? { durationMs: Math.round(timing.responseEnd) } : {}),
+        };
+    }));
+    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.' };
+}
+export async function networkRequest(page, id, includeBody) {
+    const request = (await page.requests()).find(candidate => requestIds.get(candidate) === id);
+    if (!request)
+        throw new InspectorError('REQUEST_NOT_FOUND', `Request ${id} not found; list requests again, older entries are dropped`);
+    const response = await request.response().catch(() => null);
+    const post = request.postData();
+    let responseBody;
+    if (includeBody && response) {
+        const type = (await response.headerValue('content-type').catch(() => null)) ?? '';
+        responseBody = /json|text|javascript|xml|x-www-form-urlencoded/.test(type)
+            ? await response.text().then(redactBody, () => ({ unavailable: 'BODY_EVICTED' }))
+            : { unavailable: `BINARY ${type.slice(0, 100)}` };
+    }
+    return {
+        id,
+        method: request.method(),
+        url: redactUrl(request.url()),
+        resourceType: request.resourceType(),
+        requestHeaders: redactHeaders(await request.allHeaders().catch(() => request.headers())),
+        ...(includeBody && post ? { requestBody: redactBody(post) } : {}),
+        ...(response ? { status: response.status(), statusText: response.statusText().slice(0, 200), responseHeaders: redactHeaders(await response.allHeaders().catch(() => response.headers())) } : {}),
+        ...(request.failure() ? { failure: request.failure().errorText.slice(0, 300) } : {}),
+        ...(responseBody ? { responseBody } : {}),
+        timing: request.timing(),
+    };
+}
+export async function storage(page, area, keyContains, limit = 100) {
+    if (area === 'cookies') {
+        // 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 {
+            area,
+            entries: cookies.slice(0, limit).map(cookie => ({ name: cookie.name, value: REDACTED, domain: cookie.domain, path: cookie.path, expires: cookie.expires, httpOnly: cookie.httpOnly, secure: cookie.secure, sameSite: cookie.sameSite })),
+            matched: cookies.length,
+            truncated: cookies.length > limit,
+        };
+    }
+    const entries = await page.evaluate(store => {
+        const target = store === 'local' ? localStorage : sessionStorage;
+        const out = [];
+        for (let index = 0; index < target.length && index < 5_000; index++) {
+            const key = target.key(index);
+            if (key !== null)
+                out.push([key, String(target.getItem(key) ?? '').slice(0, 200_000)]);
+        }
+        return out;
+    }, area);
+    const matched = entries.filter(([key]) => !keyContains || key.includes(keyContains));
+    return {
+        area,
+        entries: matched.slice(0, limit).map(([key, value]) => {
+            if (isSensitiveKey(key))
+                return { key, value: REDACTED, bytes: value.length };
+            const { body, truncated } = redactBody(value);
+            return { key, value: body.slice(0, MAX_TEXT), bytes: value.length, ...(truncated || body.length > MAX_TEXT ? { truncated: true } : {}) };
+        }),
+        matched: matched.length,
+        truncated: matched.length > limit,
+    };
+}

package/dist/src/browser.d.ts

@@ -1,5 +1,5 @@
 import { type Browser, type Page } from 'playwright-core';
-export type InspectorErrorCode = 'CDP_UNAVAILABLE' | 'NO_LOCAL_PAGE' | 'MULTIPLE_PAGES' | 'PAGE_NOT_FOUND' | 'COCOS_NOT_FOUND' | 'SCENE_NOT_READY' | 'NODE_NOT_FOUND' | 'COMPONENT_NOT_FOUND' | 'AMBIGUOUS_COMPONENT' | 'MUTATION_DISABLED' | 'INVALID_MUTATION' | 'OUTPUT_TRUNCATED';
+export type InspectorErrorCode = 'CDP_UNAVAILABLE' | 'NO_LOCAL_PAGE' | 'MULTIPLE_PAGES' | 'PAGE_NOT_FOUND' | 'COCOS_NOT_FOUND' | 'SCENE_NOT_READY' | 'NODE_NOT_FOUND' | 'COMPONENT_NOT_FOUND' | 'AMBIGUOUS_COMPONENT' | 'AMBIGUOUS_NODE' | 'MUTATION_DISABLED' | 'INVALID_MUTATION' | 'OUTPUT_TRUNCATED' | 'REQUEST_NOT_FOUND';
 export declare class InspectorError extends Error {
     readonly code: InspectorErrorCode;
     constructor(code: InspectorErrorCode, message: string);

package/dist/src/index.js

@@ -1,16 +1,28 @@
 #!/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;
     for (let index = 0; index < args.length; index++) {
         const arg = args[index];
         if (arg === '--allow-runtime-mutation') {
             allowRuntimeMutation = true;
             continue;
         }
+        if (arg === '--allow-browser-data') {
+            allowBrowserData = true;
+            continue;
+        }
+        if (arg === '--allow-method-call') {
+            allowMethodCall = true;
+            continue;
+        }
         if (arg === '--cdp-endpoint') {
             const value = args[++index];
             if (!value)
@@ -18,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 };
+    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 });
+    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,5 +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;