@sensaiorg/adapter-android 0.1.0

package/src/tools/interaction.ts

@@ -0,0 +1,448 @@
+/**
+ * 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
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+import { flattenTree } from "../util/ui-tree-parser.js";
+import { getCachedTree } from "./ui-tree.js";
+
+/** Android key event codes for common keys. */
+const KEY_CODES: Record<string, number> = {
+  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: ConnectionManager,
+  selector: { text?: string; resourceId?: string; contentDescription?: string },
+): Promise<{ x: number; y: number; matched: string } | null> {
+  const tree = await getCachedTree(cm, { visibleOnly: true, includeSystemUI: false });
+  const flat = 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;
+}
+
+export function registerInteractionTools(server: McpServer, cm: ConnectionManager): void {
+  /**
+   * 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: z.string().optional().describe("Find and tap element containing this text"),
+      resourceId: z.string().optional().describe("Find and tap element with this resource ID"),
+      contentDescription: z.string().optional().describe("Find and tap element with this content description"),
+      x: z.number().optional().describe("X coordinate for direct tap"),
+      y: z.number().optional().describe("Y coordinate for direct tap"),
+    },
+    async (params) => {
+      try {
+        let tapX: number;
+        let tapY: number;
+        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" as const,
+                  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" as const,
+                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" as const,
+              text: JSON.stringify({
+                success: true,
+                tapped: { x: tapX, y: tapY },
+                matchedBy: matchInfo,
+              }),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              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: z.string().describe("Text to type"),
+      clearFirst: 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" as const,
+              text: JSON.stringify({ ok: true }),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              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: z.number().describe("Start X coordinate"),
+      startY: z.number().describe("Start Y coordinate"),
+      endX: z.number().describe("End X coordinate"),
+      endY: z.number().describe("End Y coordinate"),
+      durationMs: 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" as const,
+              text: JSON.stringify({ ok: true }),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              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: 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" as const,
+                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" as const,
+              text: JSON.stringify({ ok: true }),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              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: z.string().optional().describe("Visible text to long-press"),
+      resourceId: z.string().optional().describe("Resource ID to long-press"),
+      contentDescription: z.string().optional().describe("Content description to long-press"),
+      x: z.number().optional().describe("X coordinate"),
+      y: z.number().optional().describe("Y coordinate"),
+      durationMs: z.number().optional().describe("Hold duration in ms (default: 1500)"),
+    },
+    async (params) => {
+      try {
+        let pressX: number;
+        let pressY: number;
+        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" as const,
+                  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" as const,
+                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" as const,
+              text: JSON.stringify({
+                success: true,
+                longPressed: { x: pressX, y: pressY },
+                durationMs: duration,
+                matchedBy: matchInfo,
+              }),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error performing long press: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/logcat.ts

@@ -0,0 +1,252 @@
+/**
+ * Logcat Tools - Read and filter Android system logs.
+ *
+ * Provides:
+ * - get_logcat: Filtered log retrieval with level/tag/grep/since/maxLines
+ * - get_crash_info: Extract crash reports (JS exceptions, native crashes, ANRs)
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+import {
+  parseLogcat,
+  filterByLevel,
+  filterByTag,
+  filterByGrep,
+  formatEntry,
+  type LogLevel,
+} from "../util/logcat-parser.js";
+
+/** Tags commonly associated with React Native errors. */
+const RN_ERROR_TAGS = [
+  "ReactNativeJS",
+  "ReactNative",
+  "hermes",
+  "HermesVM",
+  "com.facebook.react",
+];
+
+/** Tags for native Android crashes. */
+const CRASH_TAGS = [
+  "AndroidRuntime",
+  "FATAL",
+  "DEBUG",
+  "tombstoned",
+  "crash_dump",
+];
+
+export function registerLogcatTools(server: McpServer, cm: ConnectionManager): void {
+  /**
+   * get_logcat - Retrieve filtered Android logs.
+   */
+  server.tool(
+    "get_logcat",
+    "Get Android logcat entries with optional filtering by log level, tag, text pattern, and time range. Returns structured log entries.",
+    {
+      level: z
+        .enum(["V", "D", "I", "W", "E", "F"])
+        .optional()
+        .describe("Minimum log level (V=verbose, D=debug, I=info, W=warn, E=error, F=fatal)"),
+      tag: z.string().optional().describe("Filter by tag (case-insensitive substring)"),
+      since: z.string().optional().describe("Only logs since this time (e.g., '5s', '1m', '30m', '1h')"),
+      grep: z.string().optional().describe("Regex pattern to filter log messages"),
+      maxLines: z.number().optional().describe("Maximum number of entries to return (default: 200)"),
+      packageOnly: z.boolean().optional().describe("Only show logs from the target package"),
+      deduplicate: z.boolean().optional().describe("Collapse consecutive identical messages into '[repeated Nx] message' (default: true)"),
+    },
+    async (params) => {
+      try {
+        const maxLines = params.maxLines ?? 200;
+        const shouldDeduplicate = params.deduplicate !== false; // default: true
+        const targetPackage = process.env.TARGET_PACKAGE ?? "com.emudebug.target";
+
+        // Build logcat command
+        const cmdParts = ["logcat", "-d", "-v", "threadtime"];
+
+        // Time filter
+        if (params.since) {
+          cmdParts.push("-T", `'${params.since}'`);
+        }
+
+        // Package filter via PID
+        let pid: string | null = null;
+        if (params.packageOnly) {
+          try {
+            const pidOutput = await cm.adb.shell(`pidof ${targetPackage}`);
+            pid = pidOutput.trim();
+          } catch {
+            // Package might not be running
+          }
+        }
+
+        const raw = await cm.adb.shell(cmdParts.join(" "), 15_000);
+        let entries = parseLogcat(raw);
+
+        // Apply filters
+        if (pid) {
+          entries = entries.filter((e) => e.pid === pid);
+        }
+        if (params.level) {
+          entries = filterByLevel(entries, params.level as LogLevel);
+        }
+        if (params.tag) {
+          entries = filterByTag(entries, params.tag);
+        }
+        if (params.grep) {
+          entries = filterByGrep(entries, params.grep);
+        }
+
+        // Deduplicate consecutive identical messages
+        let deduplicatedCount = 0;
+        if (shouldDeduplicate && entries.length > 0) {
+          const deduped: typeof entries = [];
+          let repeatCount = 1;
+
+          for (let i = 0; i < entries.length; i++) {
+            const next = entries[i + 1];
+            if (next && entries[i].message === next.message && entries[i].tag === next.tag) {
+              repeatCount++;
+              deduplicatedCount++;
+            } else {
+              if (repeatCount > 1) {
+                deduped.push({
+                  ...entries[i],
+                  message: `[repeated ${repeatCount}x] ${entries[i].message}`,
+                });
+              } else {
+                deduped.push(entries[i]);
+              }
+              repeatCount = 1;
+            }
+          }
+          entries = deduped;
+        }
+
+        // Limit results (take most recent)
+        const limited = entries.slice(-maxLines);
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  totalMatches: entries.length,
+                  returned: limited.length,
+                  truncated: entries.length > maxLines,
+                  deduplicated: deduplicatedCount,
+                  entries: limited,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error reading logcat: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  /**
+   * get_crash_info - Extract crash reports from logs.
+   */
+  server.tool(
+    "get_crash_info",
+    "Extract crash information from Android logs: JavaScript exceptions (React Native), native crashes (tombstones), and ANRs. Focuses on the target app.",
+    {
+      since: z.string().optional().describe("Only crashes since this time (e.g., '5m', '1h')"),
+      includeAllApps: z.boolean().optional().describe("Include crashes from all apps, not just the target"),
+    },
+    async (params) => {
+      try {
+        const targetPackage = process.env.TARGET_PACKAGE ?? "com.emudebug.target";
+
+        // Get recent logcat
+        const cmdParts = ["logcat", "-d", "-v", "threadtime"];
+        if (params.since) {
+          cmdParts.push("-T", `'${params.since}'`);
+        }
+        const raw = await cm.adb.shell(cmdParts.join(" "), 15_000);
+        const allEntries = parseLogcat(raw);
+
+        // Find target app PID(s) for filtering
+        let targetPids = new Set<string>();
+        if (!params.includeAllApps) {
+          try {
+            const pidOutput = await cm.adb.shell(`pidof ${targetPackage}`);
+            pidOutput.trim().split(/\s+/).forEach((p) => targetPids.add(p));
+          } catch {
+            // If no PID found, we'll still look for tagged entries
+          }
+        }
+
+        // Extract JS exceptions (React Native)
+        const jsErrors = allEntries.filter((e) => {
+          const isRnTag = RN_ERROR_TAGS.some((t) => e.tag.includes(t));
+          const isError = e.level === "E" || e.level === "F";
+          const isTargetPid = targetPids.size === 0 || targetPids.has(e.pid);
+          return isRnTag && isError && (params.includeAllApps || isTargetPid);
+        });
+
+        // Extract native crashes
+        const nativeCrashes = allEntries.filter((e) => {
+          const isCrashTag = CRASH_TAGS.some((t) => e.tag.includes(t));
+          const isError = e.level === "E" || e.level === "F";
+          return isCrashTag && isError;
+        });
+
+        // Extract ANRs
+        const anrs = allEntries.filter(
+          (e) => e.tag === "ActivityManager" && e.message.includes("ANR in"),
+        );
+
+        // Check for ANR traces file
+        let anrTraces = "";
+        if (anrs.length > 0) {
+          try {
+            anrTraces = await cm.adb.shell("cat /data/anr/traces.txt | head -100");
+          } catch {
+            anrTraces = "(ANR traces not accessible without root)";
+          }
+        }
+
+        const result = {
+          summary: {
+            jsExceptions: jsErrors.length,
+            nativeCrashes: nativeCrashes.length,
+            anrs: anrs.length,
+          },
+          jsExceptions: jsErrors.map(formatEntry),
+          nativeCrashes: nativeCrashes.map(formatEntry),
+          anrs: anrs.map(formatEntry),
+          anrTraces: anrTraces || undefined,
+        };
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error getting crash info: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+}