@sensaiorg/adapter-android 0.1.0

package/dist/tools/hot-reload.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Hot Reload Tool - Trigger Metro bundler hot or full reload.
+ *
+ * Communicates with the Metro dev server to trigger a reload of the
+ * JavaScript bundle, either incremental (hot) or full.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHotReloadTools = registerHotReloadTools;
+const zod_1 = require("zod");
+/** Default Metro bundler port. */
+const METRO_PORT = 8081;
+function registerHotReloadTools(server, cm) {
+    server.tool("hot_reload", "Trigger a React Native reload via the Metro bundler. 'hot' performs a fast refresh (preserves state), 'full' performs a complete bundle reload. Works by sending key events or hitting the Metro dev server endpoint.", {
+        type: zod_1.z
+            .enum(["hot", "full"])
+            .optional()
+            .describe("Reload type: 'hot' for fast refresh (default), 'full' for complete reload"),
+    }, async (params) => {
+        const reloadType = params.type ?? "hot";
+        try {
+            if (reloadType === "full") {
+                // Method 1: Send "RR" key sequence (double-tap R in dev menu)
+                // This triggers a full reload in React Native dev mode
+                try {
+                    await cm.adb.shell("input keyevent 46 46"); // R R
+                }
+                catch {
+                    // Method 2: Hit Metro /reload endpoint
+                    try {
+                        await cm.adb.shell(`curl -s http://localhost:${METRO_PORT}/reload`);
+                    }
+                    catch {
+                        // Method 3: Send the menu key then look for reload option
+                        await cm.adb.shell("input keyevent 82"); // MENU key opens RN dev menu
+                    }
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                type: "full",
+                                message: "Full reload triggered. The app will reload the JS bundle from Metro.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            else {
+                // Hot reload: trigger via Metro /message endpoint
+                try {
+                    // Send HMR trigger through ADB reverse + Metro
+                    await cm.adb.shell(`curl -s -X POST http://localhost:${METRO_PORT}/message -H "Content-Type: application/json" -d '{"method":"reload"}'`);
+                }
+                catch {
+                    // Fallback: the shake gesture or menu key
+                    // On emulators, Ctrl+M or MENU key opens dev menu
+                    await cm.adb.shell("input keyevent 82");
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                type: "hot",
+                                message: "Hot reload triggered. Fast Refresh will apply changes without losing state.",
+                            }),
+                        },
+                    ],
+                };
+            }
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                            hints: [
+                                "Ensure Metro bundler is running (npx react-native start)",
+                                "Ensure ADB reverse port forwarding is set up: adb reverse tcp:8081 tcp:8081",
+                                "Ensure the app is in dev mode (not a release build)",
+                            ],
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=hot-reload.js.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAe5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,iBAAiB,GAAG,IAAI,CAc/E"}

package/dist/tools/index.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Tool Registry - Registers all EmuDebug MCP tools with the server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAllTools = registerAllTools;
+const ui_tree_js_1 = require("./ui-tree.js");
+const accessibility_js_1 = require("./accessibility.js");
+const logcat_js_1 = require("./logcat.js");
+const rn_tools_js_1 = require("./rn-tools.js");
+const app_state_js_1 = require("./app-state.js");
+const network_js_1 = require("./network.js");
+const interaction_js_1 = require("./interaction.js");
+const performance_js_1 = require("./performance.js");
+const adb_js_1 = require("./adb.js");
+const diagnose_js_1 = require("./diagnose.js");
+const hot_reload_js_1 = require("./hot-reload.js");
+const smart_actions_js_1 = require("./smart-actions.js");
+const recording_js_1 = require("./recording.js");
+/**
+ * Register all 26 EmuDebug tools with the MCP server.
+ *
+ * Tools registered:
+ *  1. get_ui_tree         - UI hierarchy as JSON
+ *  2. get_screen_text     - Visible text extraction
+ *  3. get_element_details - Deep element inspection
+ *  4. get_accessibility   - Accessibility tree
+ *  5. get_logcat          - Filtered Android logs
+ *  6. get_crash_info      - JS exceptions, native crashes, ANRs
+ *  7. get_rn_component_tree - React Native component tree (Phase 2)
+ *  8. get_rn_bridge       - TurboModule / bridge inspection (Phase 2)
+ *  9. get_app_state       - AsyncStorage, query cache, nav, auth, etc.
+ * 10. get_network         - HTTP traffic inspection
+ * 11. tap                 - Tap by text/resourceId/coordinates
+ * 12. type_text           - Type into focused field
+ * 13. swipe               - Swipe gesture
+ * 14. press_key           - Android key events
+ * 15. long_press          - Long press (press and hold)
+ * 16. get_performance     - FPS, memory, CPU, bridge metrics
+ * 17. run_adb             - Safe ADB command passthrough
+ * 18. diagnose_screen     - Composite screen diagnosis (parallelized)
+ * 19. hot_reload          - Metro bundler hot/full reload
+ * 20. wait_for_text       - Poll until text appears on screen
+ * 21. scroll_to_text      - Scroll until element is visible
+ * 22. fill_form           - Batch fill multiple form fields
+ * 23. tap_and_wait        - Tap element then wait for text
+ * 24. assert_screen       - Quick screen assertions
+ * 25. open_deep_link      - Open app via deep link URL
+ * 26. take_screenshot     - Capture screen as base64 PNG
+ */
+function registerAllTools(server, cm) {
+    (0, ui_tree_js_1.registerUiTreeTools)(server, cm); // 3 tools: get_ui_tree, get_screen_text, get_element_details
+    (0, accessibility_js_1.registerAccessibilityTools)(server, cm); // 1 tool:  get_accessibility
+    (0, logcat_js_1.registerLogcatTools)(server, cm); // 2 tools: get_logcat, get_crash_info
+    (0, rn_tools_js_1.registerRnTools)(server, cm); // 2 tools: get_rn_component_tree, get_rn_bridge
+    (0, app_state_js_1.registerAppStateTools)(server, cm); // 1 tool:  get_app_state
+    (0, network_js_1.registerNetworkTools)(server, cm); // 1 tool:  get_network
+    (0, interaction_js_1.registerInteractionTools)(server, cm); // 5 tools: tap, type_text, swipe, press_key, long_press
+    (0, performance_js_1.registerPerformanceTools)(server, cm); // 1 tool:  get_performance
+    (0, adb_js_1.registerAdbTools)(server, cm); // 1 tool:  run_adb
+    (0, diagnose_js_1.registerDiagnoseTools)(server, cm); // 1 tool:  diagnose_screen
+    (0, hot_reload_js_1.registerHotReloadTools)(server, cm); // 1 tool:  hot_reload
+    (0, smart_actions_js_1.registerSmartActionTools)(server, cm); // 7 tools: wait_for_text, scroll_to_text, fill_form, tap_and_wait, assert_screen, open_deep_link, take_screenshot
+    (0, recording_js_1.registerRecordingTools)(server, cm); // 2 tools: start_recording, stop_recording
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction.d.ts","sourceRoot":"","sources":["../../src/tools/interaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAmE5E,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,iBAAiB,GAAG,IAAI,CA+WvF"}

package/dist/tools/interaction.js

@@ -0,0 +1,395 @@
+"use strict";
+/**
+ * Interaction Tools - Simulate user input on the device.
+ *
+ * Provides:
+ * - tap: Tap by text, resourceId, contentDescription, or coordinates
+ * - type_text: Enter text into the focused field
+ * - swipe: Swipe gesture between two points
+ * - press_key: Press Android key events (BACK, HOME, ENTER, etc.)
+ * - long_press: Long press (press and hold) on element or coordinates
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerInteractionTools = registerInteractionTools;
+const zod_1 = require("zod");
+const ui_tree_parser_js_1 = require("../util/ui-tree-parser.js");
+const ui_tree_js_1 = require("./ui-tree.js");
+/** Android key event codes for common keys. */
+const KEY_CODES = {
+    BACK: 4,
+    HOME: 3,
+    ENTER: 66,
+    DELETE: 67,
+    TAB: 61,
+    ESCAPE: 111,
+    VOLUME_UP: 24,
+    VOLUME_DOWN: 25,
+    POWER: 26,
+    MENU: 82,
+    SEARCH: 84,
+    DPAD_UP: 19,
+    DPAD_DOWN: 20,
+    DPAD_LEFT: 21,
+    DPAD_RIGHT: 22,
+    DPAD_CENTER: 23,
+    APP_SWITCH: 187,
+};
+/**
+ * Find element coordinates by searching the UI tree (uses cache).
+ */
+async function findElementCenter(cm, selector) {
+    const tree = await (0, ui_tree_js_1.getCachedTree)(cm, { visibleOnly: true, includeSystemUI: false });
+    const flat = (0, ui_tree_parser_js_1.flattenTree)(tree);
+    for (const node of flat) {
+        let matched = false;
+        let matchedBy = "";
+        if (selector.text && node.text.toLowerCase().includes(selector.text.toLowerCase())) {
+            matched = true;
+            matchedBy = `text="${node.text}"`;
+        }
+        if (selector.resourceId && node.resourceId.includes(selector.resourceId)) {
+            matched = true;
+            matchedBy = `resourceId="${node.resourceId}"`;
+        }
+        if (selector.contentDescription &&
+            node.contentDescription.toLowerCase().includes(selector.contentDescription.toLowerCase())) {
+            matched = true;
+            matchedBy = `contentDescription="${node.contentDescription}"`;
+        }
+        if (matched && node.bounds) {
+            return {
+                x: Math.round((node.bounds.left + node.bounds.right) / 2),
+                y: Math.round((node.bounds.top + node.bounds.bottom) / 2),
+                matched: matchedBy,
+            };
+        }
+    }
+    return null;
+}
+function registerInteractionTools(server, cm) {
+    /**
+     * tap - Tap on an element or coordinates.
+     */
+    server.tool("tap", "Tap on a UI element found by text, resourceId, or contentDescription; or tap directly at x,y coordinates. The element is found in the current UI hierarchy and tapped at its center.", {
+        text: zod_1.z.string().optional().describe("Find and tap element containing this text"),
+        resourceId: zod_1.z.string().optional().describe("Find and tap element with this resource ID"),
+        contentDescription: zod_1.z.string().optional().describe("Find and tap element with this content description"),
+        x: zod_1.z.number().optional().describe("X coordinate for direct tap"),
+        y: zod_1.z.number().optional().describe("Y coordinate for direct tap"),
+    }, async (params) => {
+        try {
+            let tapX;
+            let tapY;
+            let matchInfo = "";
+            if (params.x !== undefined && params.y !== undefined) {
+                // Direct coordinate tap
+                tapX = params.x;
+                tapY = params.y;
+                matchInfo = `direct coordinates (${tapX}, ${tapY})`;
+            }
+            else if (params.text || params.resourceId || params.contentDescription) {
+                // Find element by selector
+                const result = await findElementCenter(cm, {
+                    text: params.text,
+                    resourceId: params.resourceId,
+                    contentDescription: params.contentDescription,
+                });
+                if (!result) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: "Element not found",
+                                    selector: {
+                                        text: params.text,
+                                        resourceId: params.resourceId,
+                                        contentDescription: params.contentDescription,
+                                    },
+                                    hint: "Use get_screen_text or get_ui_tree to see available elements.",
+                                }),
+                            },
+                        ],
+                    };
+                }
+                tapX = result.x;
+                tapY = result.y;
+                matchInfo = result.matched;
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: false,
+                                error: "No target specified. Provide text, resourceId, contentDescription, or x/y coordinates.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            // Invalidate cache — screen will change after tap
+            cm.uiCache.invalidate();
+            await cm.adb.shell(`input tap ${tapX} ${tapY}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            tapped: { x: tapX, y: tapY },
+                            matchedBy: matchInfo,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error performing tap: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * type_text - Type text into the currently focused input field.
+     */
+    server.tool("type_text", "Type text into the currently focused input field on the device. Special characters are escaped for ADB input.", {
+        text: zod_1.z.string().describe("Text to type"),
+        clearFirst: zod_1.z.boolean().optional().describe("Clear the field before typing (default: false)"),
+    }, async (params) => {
+        try {
+            // Optionally clear existing text
+            if (params.clearFirst) {
+                // Most reliable approach for React Native TextInput:
+                // Move to end, then send batch DEL key events to clear everything.
+                // Ctrl+A doesn't work reliably in RN, and shift+home is fragile.
+                await cm.adb.shell("input keyevent 123"); // KEYCODE_MOVE_END
+                // Send 50 DEL events in one call (enough for any reasonable field)
+                await cm.adb.shell("input keyevent " + Array(50).fill("67").join(" "));
+            }
+            // Escape special characters for ADB input text
+            const escaped = params.text
+                .replace(/\\/g, "\\\\")
+                .replace(/ /g, "%s")
+                .replace(/'/g, "\\'")
+                .replace(/"/g, '\\"')
+                .replace(/&/g, "\\&")
+                .replace(/</g, "\\<")
+                .replace(/>/g, "\\>")
+                .replace(/\|/g, "\\|")
+                .replace(/;/g, "\\;")
+                .replace(/\(/g, "\\(")
+                .replace(/\)/g, "\\)")
+                .replace(/\$/g, "\\$")
+                .replace(/`/g, "\\`");
+            // Invalidate cache — screen content changes after typing
+            cm.uiCache.invalidate();
+            await cm.adb.shell(`input text ${escaped}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: true }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error typing text: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * swipe - Perform a swipe gesture.
+     */
+    server.tool("swipe", "Perform a swipe gesture on the device from (startX, startY) to (endX, endY) over the specified duration.", {
+        startX: zod_1.z.number().describe("Start X coordinate"),
+        startY: zod_1.z.number().describe("Start Y coordinate"),
+        endX: zod_1.z.number().describe("End X coordinate"),
+        endY: zod_1.z.number().describe("End Y coordinate"),
+        durationMs: zod_1.z.number().optional().describe("Swipe duration in milliseconds (default: 300)"),
+    }, async (params) => {
+        try {
+            const duration = params.durationMs ?? 300;
+            // Invalidate cache — screen will change after swipe
+            cm.uiCache.invalidate();
+            await cm.adb.shell(`input swipe ${params.startX} ${params.startY} ${params.endX} ${params.endY} ${duration}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: true }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error performing swipe: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * press_key - Press an Android key event.
+     */
+    server.tool("press_key", "Press an Android key event. Supports named keys (BACK, HOME, ENTER, etc.) or numeric key codes.", {
+        key: zod_1.z
+            .string()
+            .describe(`Key name or numeric code. Named keys: ${Object.keys(KEY_CODES).join(", ")}`),
+    }, async (params) => {
+        try {
+            const keyUpper = params.key.toUpperCase();
+            const keyCode = KEY_CODES[keyUpper] ?? parseInt(params.key, 10);
+            if (isNaN(keyCode)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Unknown key: ${params.key}`,
+                                availableKeys: Object.keys(KEY_CODES),
+                            }),
+                        },
+                    ],
+                };
+            }
+            // Invalidate cache — key press may change screen
+            cm.uiCache.invalidate();
+            await cm.adb.shell(`input keyevent ${keyCode}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: true }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error pressing key: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * long_press - Long press (press and hold) on an element or coordinates.
+     */
+    server.tool("long_press", "Long press (press and hold) at coordinates or on an element found by text. Useful for context menus and drag initiation.", {
+        text: zod_1.z.string().optional().describe("Visible text to long-press"),
+        resourceId: zod_1.z.string().optional().describe("Resource ID to long-press"),
+        contentDescription: zod_1.z.string().optional().describe("Content description to long-press"),
+        x: zod_1.z.number().optional().describe("X coordinate"),
+        y: zod_1.z.number().optional().describe("Y coordinate"),
+        durationMs: zod_1.z.number().optional().describe("Hold duration in ms (default: 1500)"),
+    }, async (params) => {
+        try {
+            let pressX;
+            let pressY;
+            let matchInfo = "";
+            if (params.x !== undefined && params.y !== undefined) {
+                pressX = params.x;
+                pressY = params.y;
+                matchInfo = `direct coordinates (${pressX}, ${pressY})`;
+            }
+            else if (params.text || params.resourceId || params.contentDescription) {
+                const result = await findElementCenter(cm, {
+                    text: params.text,
+                    resourceId: params.resourceId,
+                    contentDescription: params.contentDescription,
+                });
+                if (!result) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: "Element not found",
+                                    selector: {
+                                        text: params.text,
+                                        resourceId: params.resourceId,
+                                        contentDescription: params.contentDescription,
+                                    },
+                                    hint: "Use get_screen_text or get_ui_tree to see available elements.",
+                                }),
+                            },
+                        ],
+                    };
+                }
+                pressX = result.x;
+                pressY = result.y;
+                matchInfo = result.matched;
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: false,
+                                error: "No target specified. Provide text, resourceId, contentDescription, or x/y coordinates.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const duration = params.durationMs ?? 1500;
+            // A zero-distance swipe = long press
+            cm.uiCache.invalidate();
+            await cm.adb.shell(`input swipe ${pressX} ${pressY} ${pressX} ${pressY} ${duration}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            longPressed: { x: pressX, y: pressY },
+                            durationMs: duration,
+                            matchedBy: matchInfo,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error performing long press: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=interaction.js.map

package/dist/tools/logcat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logcat.d.ts","sourceRoot":"","sources":["../../src/tools/logcat.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AA4B5E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,iBAAiB,GAAG,IAAI,CAqNlF"}