@sensaiorg/adapter-android 0.1.0

package/src/tools/diagnose.ts

@@ -0,0 +1,146 @@
+/**
+ * Diagnose Tool - Composite screen diagnosis.
+ *
+ * Combines multiple data sources into a single comprehensive report:
+ * screen name, all visible text, interactive elements, recent errors,
+ * and app state summary. Ideal for understanding the current app state
+ * in one call.
+ *
+ * Optimized: runs independent ADB calls in parallel to minimize latency.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+import { flattenTree } from "../util/ui-tree-parser.js";
+import { extractTextStrings } from "../util/text-extractor.js";
+import { parseLogcat, filterByLevel } from "../util/logcat-parser.js";
+import { getCachedTree } from "./ui-tree.js";
+
+export function registerDiagnoseTools(server: McpServer, cm: ConnectionManager): void {
+  server.tool(
+    "diagnose_screen",
+    "Comprehensive screen diagnosis: returns the current screen/activity name, all visible text, interactive elements (buttons, inputs), recent errors from logcat, and a summary of app state. One-stop tool for understanding what's on screen.",
+    {},
+    async () => {
+      const targetPackage = process.env.TARGET_PACKAGE ?? "com.emudebug.target";
+      const diagnosis: Record<string, unknown> = {};
+
+      // Run independent data fetches in PARALLEL for speed
+      const [activityResult, treeResult, logcatResult, processResult] = await Promise.allSettled([
+        // 1. Current activity
+        cm.adb.shell("dumpsys activity activities | grep mResumedActivity"),
+        // 2. UI tree (uses cache if fresh)
+        getCachedTree(cm, { visibleOnly: true, includeSystemUI: false }),
+        // 3. Recent logcat + PID lookup (chained)
+        (async () => {
+          const [raw, pidOutput] = await Promise.allSettled([
+            cm.adb.shell("logcat -d -v threadtime -t 500", 10_000),
+            cm.adb.shell(`pidof ${targetPackage}`),
+          ]);
+          return {
+            raw: raw.status === "fulfilled" ? raw.value : "",
+            pid: pidOutput.status === "fulfilled" ? pidOutput.value.trim() : null,
+          };
+        })(),
+        // 4. Process state
+        cm.adb.shell(`ps -A | grep ${targetPackage}`),
+      ]);
+
+      // Process activity result
+      if (activityResult.status === "fulfilled") {
+        const match = activityResult.value.match(/u0\s+(.+?)\s+\w+/);
+        diagnosis.currentActivity = match ? match[1].trim() : activityResult.value.trim();
+      } else {
+        diagnosis.currentActivity = "unknown";
+      }
+
+      // Process UI tree result
+      if (treeResult.status === "fulfilled") {
+        const tree = treeResult.value;
+        const flat = flattenTree(tree);
+
+        diagnosis.screenText = extractTextStrings(tree);
+
+        diagnosis.interactiveElements = flat
+          .filter((n) => n.clickable || n.focusable || n.scrollable)
+          .map((n) => ({
+            type: n.className.split(".").pop(),
+            text: n.text || n.contentDescription || n.resourceId || "(unnamed)",
+            resourceId: n.resourceId,
+            clickable: n.clickable,
+            enabled: n.enabled,
+            bounds: n.bounds,
+            center: n.bounds
+              ? {
+                  x: Math.round((n.bounds.left + n.bounds.right) / 2),
+                  y: Math.round((n.bounds.top + n.bounds.bottom) / 2),
+                }
+              : null,
+          }));
+
+        diagnosis.uiSummary = {
+          totalNodes: flat.length,
+          textNodes: flat.filter((n) => n.text).length,
+          clickableNodes: flat.filter((n) => n.clickable).length,
+          inputFields: flat.filter(
+            (n) =>
+              n.className.includes("EditText") || n.className.includes("TextInput"),
+          ).length,
+          scrollableContainers: flat.filter((n) => n.scrollable).length,
+        };
+      } else {
+        diagnosis.uiError = `Failed to get UI tree: ${treeResult.reason}`;
+      }
+
+      // Process logcat result
+      if (logcatResult.status === "fulfilled") {
+        const { raw, pid } = logcatResult.value;
+        if (raw) {
+          const entries = parseLogcat(raw);
+          const errors = filterByLevel(entries, "E");
+
+          const appErrors = pid
+            ? errors.filter((e) => e.pid === pid)
+            : errors.filter(
+                (e) =>
+                  e.tag.includes("ReactNativeJS") ||
+                  e.tag.includes("ReactNative") ||
+                  e.tag.includes(targetPackage),
+              );
+
+          diagnosis.recentErrors = appErrors.slice(-10).map((e) => ({
+            timestamp: e.timestamp,
+            tag: e.tag,
+            message: e.message,
+          }));
+          diagnosis.errorCount = appErrors.length;
+        } else {
+          diagnosis.recentErrors = [];
+          diagnosis.errorCount = 0;
+        }
+      } else {
+        diagnosis.recentErrors = [];
+        diagnosis.errorCount = 0;
+      }
+
+      // Process state result
+      if (processResult.status === "fulfilled") {
+        diagnosis.processInfo = processResult.value.trim() || "App not running";
+      } else {
+        diagnosis.processInfo = "Unable to determine process state";
+      }
+
+      // Agent status (synchronous)
+      diagnosis.agentConnected = cm.agent.isConnected();
+      if (!cm.agent.isConnected()) {
+        diagnosis.agentNote =
+          "On-device agent not connected. Some data (RN components, app state, network) " +
+          "is limited to ADB-based inspection.";
+      }
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(diagnosis) }],
+      };
+    },
+  );
+}

package/src/tools/hot-reload.ts

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+
+/** Default Metro bundler port. */
+const METRO_PORT = 8081;
+
+export function registerHotReloadTools(server: McpServer, cm: ConnectionManager): void {
+  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: 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" as const,
+                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" as const,
+                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" as const,
+              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,
+        };
+      }
+    },
+  );
+}

package/src/tools/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Tool Registry - Registers all EmuDebug MCP tools with the server.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+import { registerUiTreeTools } from "./ui-tree.js";
+import { registerAccessibilityTools } from "./accessibility.js";
+import { registerLogcatTools } from "./logcat.js";
+import { registerRnTools } from "./rn-tools.js";
+import { registerAppStateTools } from "./app-state.js";
+import { registerNetworkTools } from "./network.js";
+import { registerInteractionTools } from "./interaction.js";
+import { registerPerformanceTools } from "./performance.js";
+import { registerAdbTools } from "./adb.js";
+import { registerDiagnoseTools } from "./diagnose.js";
+import { registerHotReloadTools } from "./hot-reload.js";
+import { registerSmartActionTools } from "./smart-actions.js";
+import { registerRecordingTools } from "./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
+ */
+export function registerAllTools(server: McpServer, cm: ConnectionManager): void {
+  registerUiTreeTools(server, cm);         // 3 tools: get_ui_tree, get_screen_text, get_element_details
+  registerAccessibilityTools(server, cm);  // 1 tool:  get_accessibility
+  registerLogcatTools(server, cm);         // 2 tools: get_logcat, get_crash_info
+  registerRnTools(server, cm);             // 2 tools: get_rn_component_tree, get_rn_bridge
+  registerAppStateTools(server, cm);       // 1 tool:  get_app_state
+  registerNetworkTools(server, cm);        // 1 tool:  get_network
+  registerInteractionTools(server, cm);    // 5 tools: tap, type_text, swipe, press_key, long_press
+  registerPerformanceTools(server, cm);    // 1 tool:  get_performance
+  registerAdbTools(server, cm);            // 1 tool:  run_adb
+  registerDiagnoseTools(server, cm);       // 1 tool:  diagnose_screen
+  registerHotReloadTools(server, cm);      // 1 tool:  hot_reload
+  registerSmartActionTools(server, cm);    // 7 tools: wait_for_text, scroll_to_text, fill_form, tap_and_wait, assert_screen, open_deep_link, take_screenshot
+  registerRecordingTools(server, cm);      // 2 tools: start_recording, stop_recording
+}