@sensaiorg/adapter-android 0.1.0

package/src/tools/network.ts

@@ -0,0 +1,145 @@
+/**
+ * Network Tool - Inspect HTTP network traffic from the target app.
+ *
+ * Supports two modes:
+ * - "history": Retrieve past network requests (from agent buffer)
+ * - "capture": Start/stop live capture with filters
+ *
+ * Phase 1 fallback: parse logcat for OkHttp/Retrofit logging.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+import { parseLogcat, filterByGrep } from "../util/logcat-parser.js";
+
+export function registerNetworkTools(server: McpServer, cm: ConnectionManager): void {
+  server.tool(
+    "get_network",
+    "Inspect HTTP network traffic from the target app. In 'history' mode, returns recent requests. In 'capture' mode, starts/stops live capture. Supports URL and status code filtering.",
+    {
+      mode: z
+        .enum(["history", "capture_start", "capture_stop"])
+        .describe("history = past requests, capture_start = begin live capture, capture_stop = end and return captured"),
+      urlFilter: z.string().optional().describe("Only include requests matching this URL pattern (substring)"),
+      statusFilter: z
+        .number()
+        .optional()
+        .describe("Only include responses with this HTTP status code"),
+      maxEntries: z.number().optional().describe("Maximum entries to return (default: 50)"),
+      includeBody: z.boolean().optional().describe("Include request/response bodies (default: false, can be large)"),
+    },
+    async (params) => {
+      const maxEntries = params.maxEntries ?? 50;
+
+      // Phase 2: full network interception via agent
+      if (cm.agent.isConnected()) {
+        try {
+          const result = await cm.agent.call("getNetwork", {
+            mode: params.mode,
+            urlFilter: params.urlFilter,
+            statusFilter: params.statusFilter,
+            maxEntries,
+            includeBody: params.includeBody ?? false,
+          });
+
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Agent network error: ${err instanceof Error ? err.message : String(err)}. Falling back to logcat.`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      // Phase 1: parse logcat for network-related logs
+      if (params.mode === "capture_start" || params.mode === "capture_stop") {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                error: "agent_not_connected",
+                message:
+                  "Live network capture requires the on-device agent (Phase 2). " +
+                  "Use mode='history' to see network logs from logcat.",
+              }),
+            },
+          ],
+        };
+      }
+
+      try {
+        // Look for OkHttp, Retrofit, and generic HTTP logs
+        const raw = await cm.adb.shell("logcat -d -v threadtime", 15_000);
+        let entries = parseLogcat(raw);
+
+        // Filter for network-related tags
+        const networkTags = ["OkHttp", "Retrofit", "HttpURLConnection", "NetworkClient", "API", "Volley"];
+        entries = entries.filter((e) =>
+          networkTags.some((tag) => e.tag.includes(tag)) ||
+          e.message.includes("HTTP") ||
+          e.message.includes("http://") ||
+          e.message.includes("https://"),
+        );
+
+        // Apply URL filter
+        if (params.urlFilter) {
+          entries = filterByGrep(entries, params.urlFilter);
+        }
+
+        // Apply status filter by searching for the status code in the message
+        if (params.statusFilter) {
+          entries = entries.filter((e) =>
+            e.message.includes(String(params.statusFilter)),
+          );
+        }
+
+        const limited = entries.slice(-maxEntries);
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  phase1Mode: true,
+                  note:
+                    "Network data extracted from logcat. For full request/response inspection " +
+                    "with headers and bodies, install the on-device agent (Phase 2). " +
+                    "Ensure your app uses OkHttp logging interceptor for better logcat data.",
+                  totalMatches: entries.length,
+                  returned: limited.length,
+                  entries: limited.map((e) => ({
+                    timestamp: e.timestamp,
+                    tag: e.tag,
+                    message: e.message,
+                  })),
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error getting network data: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/performance.ts

@@ -0,0 +1,169 @@
+/**
+ * Performance Tool - Monitor app performance metrics.
+ *
+ * Collects FPS, memory usage, CPU usage, and (via agent) React Native
+ * bridge metrics. Phase 1 uses ADB dumpsys; Phase 2 adds real-time
+ * frame timing and bridge throughput.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+
+/** Parsed memory info from dumpsys meminfo. */
+interface MemoryInfo {
+  totalPss: number;
+  javaHeap: number;
+  nativeHeap: number;
+  code: number;
+  stack: number;
+  graphics: number;
+  summary: string;
+}
+
+/** Parse `dumpsys meminfo <package>` output. */
+function parseMeminfo(raw: string): MemoryInfo {
+  const parseLine = (label: string): number => {
+    const re = new RegExp(`${label}[:\\s]+(\\d+)`, "i");
+    const match = raw.match(re);
+    return match ? parseInt(match[1], 10) : 0;
+  };
+
+  return {
+    totalPss: parseLine("TOTAL PSS"),
+    javaHeap: parseLine("Java Heap"),
+    nativeHeap: parseLine("Native Heap"),
+    code: parseLine("Code"),
+    stack: parseLine("Stack"),
+    graphics: parseLine("Graphics"),
+    summary: raw.split("\n").slice(0, 20).join("\n"),
+  };
+}
+
+export function registerPerformanceTools(server: McpServer, cm: ConnectionManager): void {
+  server.tool(
+    "get_performance",
+    "Get performance metrics for the target app: memory usage, CPU, frame rate (FPS), and bridge metrics. Uses ADB dumpsys in Phase 1; on-device agent provides real-time FPS and bridge throughput in Phase 2.",
+    {
+      metrics: z
+        .array(z.enum(["fps", "memory", "cpu", "bridge"]))
+        .optional()
+        .describe("Which metrics to collect (default: all)"),
+      durationSec: z
+        .number()
+        .optional()
+        .describe("Duration for FPS/CPU sampling in seconds (default: 2, max: 10)"),
+    },
+    async (params) => {
+      const metrics = params.metrics ?? ["fps", "memory", "cpu", "bridge"];
+      const targetPackage = process.env.TARGET_PACKAGE ?? "com.emudebug.target";
+      const durationSec = Math.min(params.durationSec ?? 2, 10);
+
+      // Phase 2: agent provides rich metrics
+      if (cm.agent.isConnected()) {
+        try {
+          const result = await cm.agent.call("getPerformance", {
+            metrics,
+            durationSec,
+          });
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+          };
+        } catch {
+          // Fall through to ADB
+        }
+      }
+
+      // Phase 1: ADB-based metrics
+      const result: Record<string, unknown> = {};
+
+      // Memory via dumpsys
+      if (metrics.includes("memory")) {
+        try {
+          const raw = await cm.adb.shell(`dumpsys meminfo ${targetPackage}`);
+          result.memory = parseMeminfo(raw);
+        } catch (err) {
+          result.memory = {
+            error: `Failed to get memory info: ${err instanceof Error ? err.message : String(err)}`,
+          };
+        }
+      }
+
+      // CPU via top (single snapshot)
+      if (metrics.includes("cpu")) {
+        try {
+          const raw = await cm.adb.shell(
+            `top -b -n 1 -d ${durationSec} | grep -i "${targetPackage}"`,
+          );
+          const lines = raw.trim().split("\n").filter(Boolean);
+          const cpuEntries = lines.map((line) => {
+            const parts = line.trim().split(/\s+/);
+            return {
+              pid: parts[0],
+              cpu: parts.length > 8 ? parts[8] : "?",
+              mem: parts.length > 9 ? parts[9] : "?",
+              raw: line.trim(),
+            };
+          });
+          result.cpu = { processes: cpuEntries };
+        } catch (err) {
+          result.cpu = {
+            error: `Failed to get CPU info: ${err instanceof Error ? err.message : String(err)}`,
+          };
+        }
+      }
+
+      // FPS via dumpsys gfxinfo
+      if (metrics.includes("fps")) {
+        try {
+          // Reset gfxinfo, wait, then read
+          await cm.adb.shell(`dumpsys gfxinfo ${targetPackage} reset`);
+          // Brief wait for frame data to accumulate
+          await new Promise((r) => setTimeout(r, durationSec * 1000));
+          const raw = await cm.adb.shell(`dumpsys gfxinfo ${targetPackage}`);
+
+          // Parse frame stats
+          const totalFramesMatch = raw.match(/Total frames rendered:\s*(\d+)/);
+          const jankyMatch = raw.match(/Janky frames:\s*(\d+)/);
+          const p50Match = raw.match(/50th percentile:\s*(\d+)ms/);
+          const p90Match = raw.match(/90th percentile:\s*(\d+)ms/);
+          const p95Match = raw.match(/95th percentile:\s*(\d+)ms/);
+          const p99Match = raw.match(/99th percentile:\s*(\d+)ms/);
+
+          const totalFrames = totalFramesMatch ? parseInt(totalFramesMatch[1], 10) : 0;
+          const jankyFrames = jankyMatch ? parseInt(jankyMatch[1], 10) : 0;
+
+          result.fps = {
+            totalFrames,
+            jankyFrames,
+            jankyPercentage: totalFrames > 0 ? ((jankyFrames / totalFrames) * 100).toFixed(1) + "%" : "N/A",
+            percentiles: {
+              p50: p50Match ? `${p50Match[1]}ms` : "N/A",
+              p90: p90Match ? `${p90Match[1]}ms` : "N/A",
+              p95: p95Match ? `${p95Match[1]}ms` : "N/A",
+              p99: p99Match ? `${p99Match[1]}ms` : "N/A",
+            },
+            sampleDurationSec: durationSec,
+            note: "For real-time FPS monitoring, install the on-device agent (Phase 2).",
+          };
+        } catch (err) {
+          result.fps = {
+            error: `Failed to get FPS data: ${err instanceof Error ? err.message : String(err)}`,
+          };
+        }
+      }
+
+      // Bridge metrics require agent
+      if (metrics.includes("bridge")) {
+        result.bridge = {
+          note: "React Native bridge metrics require the on-device agent (Phase 2). " +
+            "Use get_rn_bridge for logcat-based bridge inspection.",
+        };
+      }
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result) }],
+      };
+    },
+  );
+}

package/src/tools/recording.ts

@@ -0,0 +1,123 @@
+/**
+ * Recording Tools - Screen recording for Android devices.
+ *
+ * Provides:
+ * - start_recording: Begin screen recording
+ * - stop_recording: Stop and retrieve recording as base64 MP4
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+import { readFile, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Track active recording state. */
+let recordingActive = false;
+const DEVICE_RECORDING_PATH = "/sdcard/sensai_recording.mp4";
+
+export function registerRecordingTools(server: McpServer, cm: ConnectionManager): void {
+  /**
+   * start_recording - Begin screen recording on the Android device.
+   */
+  server.tool(
+    "start_recording",
+    "Start recording the Android device screen. Recording runs in the background. Use stop_recording to finish and retrieve the video. Max duration 180 seconds.",
+    {
+      maxDurationSec: z.number().optional().describe("Maximum recording duration in seconds (default: 60, max: 180)"),
+    },
+    async ({ maxDurationSec }) => {
+      if (recordingActive) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: "Recording already in progress. Call stop_recording first." }) }],
+          isError: true,
+        };
+      }
+
+      const duration = Math.min(maxDurationSec ?? 60, 180);
+
+      try {
+        // Remove any leftover recording file
+        await cm.adb.shell(`rm -f ${DEVICE_RECORDING_PATH}`).catch(() => {});
+
+        // Start recording in background (screenrecord exits after duration or when killed)
+        // We run it detached so it doesn't block
+        cm.adb.shell(`screenrecord --time-limit ${duration} ${DEVICE_RECORDING_PATH}`).catch(() => {
+          // Recording finished or was killed — expected
+          recordingActive = false;
+        });
+
+        recordingActive = true;
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ ok: true, maxDurationSec: duration, path: DEVICE_RECORDING_PATH }),
+          }],
+        };
+      } catch (err) {
+        recordingActive = false;
+        return {
+          content: [{ type: "text" as const, text: `start_recording failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  /**
+   * stop_recording - Stop the active recording and retrieve the video file.
+   */
+  server.tool(
+    "stop_recording",
+    "Stop the active screen recording and retrieve the MP4 video. Returns the video as base64 data, or saves to a local path if specified.",
+    {
+      savePath: z.string().optional().describe("Local path to save the MP4 file (optional). If not provided, returns base64."),
+    },
+    async ({ savePath }) => {
+      try {
+        // Kill screenrecord process (this causes it to finalize the MP4)
+        await cm.adb.shell("pkill -SIGINT screenrecord").catch(() => {});
+
+        // Wait for file to be finalized
+        await new Promise(r => setTimeout(r, 1500));
+        recordingActive = false;
+
+        // Pull the file from device
+        const localPath = savePath ?? join(tmpdir(), `sensai-recording-${Date.now()}.mp4`);
+        await cm.adb.pull(DEVICE_RECORDING_PATH, localPath);
+
+        // Clean up device file
+        await cm.adb.shell(`rm -f ${DEVICE_RECORDING_PATH}`).catch(() => {});
+
+        if (savePath) {
+          // User wants it saved to a path
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({ ok: true, savedTo: localPath }),
+            }],
+          };
+        }
+
+        // Return as base64
+        const data = await readFile(localPath);
+        await unlink(localPath).catch(() => {});
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ ok: true, format: "mp4", sizeBytes: data.length, base64: data.toString("base64") }),
+          }],
+        };
+      } catch (err) {
+        recordingActive = false;
+        return {
+          content: [{ type: "text" as const, text: `stop_recording failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/rn-tools.ts

@@ -0,0 +1,143 @@
+/**
+ * React Native Tools - Inspect RN component tree and bridge activity.
+ *
+ * These tools require the on-device agent (Phase 2) for full functionality.
+ * In Phase 1, they provide guidance on what data will be available once
+ * the agent is installed.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ConnectionManager } from "../transport/connection-manager.js";
+
+/** Message returned when the agent is required but not connected. */
+const AGENT_REQUIRED_MSG = (tool: string) =>
+  JSON.stringify({
+    error: "agent_not_connected",
+    tool,
+    message:
+      "This tool requires the EmuDebug on-device agent (Phase 2). " +
+      "The agent provides deep React Native introspection by hooking into " +
+      "the Hermes JS engine and React fiber tree. " +
+      "Use ADB-based tools (get_ui_tree, get_logcat) for Phase 1 debugging.",
+    alternatives: [
+      "get_ui_tree - View hierarchy via uiautomator",
+      "get_screen_text - All visible text on screen",
+      "get_logcat - Filter logs by ReactNativeJS tag",
+      "get_crash_info - JS exceptions from logcat",
+    ],
+  });
+
+export function registerRnTools(server: McpServer, cm: ConnectionManager): void {
+  /**
+   * get_rn_component_tree - Get the React Native component tree via Hermes CDP.
+   */
+  server.tool(
+    "get_rn_component_tree",
+    "Get the React Native component tree from the Hermes engine. Shows component names, props, state, and hooks. Requires on-device agent (Phase 2); falls back to guidance in Phase 1.",
+    {
+      componentFilter: z.string().optional().describe("Filter by component name (substring match)"),
+      maxDepth: z.number().optional().describe("Maximum tree depth to return"),
+      includeProps: z.boolean().optional().describe("Include component props (default: true)"),
+      includeState: z.boolean().optional().describe("Include component state (default: true)"),
+    },
+    async (params) => {
+      if (!cm.agent.isConnected()) {
+        return {
+          content: [{ type: "text" as const, text: AGENT_REQUIRED_MSG("get_rn_component_tree") }],
+        };
+      }
+
+      try {
+        const result = await cm.agent.call("getRnComponentTree", {
+          componentFilter: params.componentFilter,
+          maxDepth: params.maxDepth ?? 0,
+          includeProps: params.includeProps ?? true,
+          includeState: params.includeState ?? true,
+        });
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error getting RN component tree: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  /**
+   * get_rn_bridge - Inspect React Native bridge / TurboModule activity.
+   */
+  server.tool(
+    "get_rn_bridge",
+    "Inspect React Native TurboModule calls and bridge traffic. Shows recent native module invocations and their parameters. Requires on-device agent (Phase 2).",
+    {
+      moduleName: z.string().optional().describe("Filter by native module name"),
+      maxEntries: z.number().optional().describe("Maximum entries to return (default: 50)"),
+      includeArgs: z.boolean().optional().describe("Include call arguments (default: true)"),
+    },
+    async (params) => {
+      if (!cm.agent.isConnected()) {
+        // In Phase 1, we can at least check logcat for bridge-related messages
+        try {
+          const bridgeLogs = await cm.adb.shell(
+            "logcat -d -v threadtime | grep -i 'turbo\\|bridge\\|nativemodule' | tail -30",
+          );
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(
+                  {
+                    phase1Mode: true,
+                    message:
+                      "Full bridge inspection requires the on-device agent (Phase 2). " +
+                      "Showing bridge-related logcat entries as a fallback.",
+                    logEntries: bridgeLogs.trim().split("\n").filter(Boolean),
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        } catch {
+          return {
+            content: [{ type: "text" as const, text: AGENT_REQUIRED_MSG("get_rn_bridge") }],
+          };
+        }
+      }
+
+      try {
+        const result = await cm.agent.call("getRnBridge", {
+          moduleName: params.moduleName,
+          maxEntries: params.maxEntries ?? 50,
+          includeArgs: params.includeArgs ?? true,
+        });
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error getting bridge data: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+}