@srmorete/mobile-device-mcp 0.1.0

package/src/server/bootstrap.ts

@@ -0,0 +1,367 @@
+import { readdirSync } from "fs";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import type { Subprocess } from "bun";
+import type { RegisteredDevice, DeviceType } from "./types.js";
+import {
+  getDevice,
+  setDevice,
+  removeDevice,
+  cleanupDevice,
+  detectPlatform,
+} from "./devices.js";
+import {
+  allocateAndroidPort,
+  allocateIOSPort,
+  addPendingPort,
+  releasePendingPort,
+  unlockPort,
+  cleanupStalePorts,
+  killPortListener,
+} from "./ports.js";
+
+const HEALTH_POLL_INTERVAL = 500;
+const HEALTH_TIMEOUT = 45_000;
+
+// Drivers root relative to project
+const PROJECT_ROOT = join(import.meta.dir, "..", "..");
+const DRIVERS_ANDROID = join(PROJECT_ROOT, "drivers", "android");
+const DRIVERS_IOS_SIM = join(PROJECT_ROOT, "drivers", "ios");
+const DRIVERS_IOS_DEVICE = join(PROJECT_ROOT, "drivers", "ios-device");
+
+// ── Promise chains for per-device serialization ──
+const bootstrapChains = new Map<string, Promise<void>>();
+
+export async function ensureDevice(deviceId: string): Promise<RegisteredDevice> {
+  // Fast path: already registered — but verify server is still alive
+  const existing = getDevice(deviceId);
+  if (existing) {
+    if (existing.serverProcess.exitCode !== null) {
+      const old = removeDevice(deviceId);
+      if (old) await cleanupDevice(old);
+    } else {
+      return existing;
+    }
+  }
+
+  // Serialize bootstrap per device
+  const chain = (bootstrapChains.get(deviceId) ?? Promise.resolve()).catch(() => {});
+  const next = chain.then(async () => {
+    // Re-check after waiting (a prior bootstrap may have succeeded)
+    const found = getDevice(deviceId);
+    if (found) return;
+    await bootstrapDevice(deviceId);
+  });
+  bootstrapChains.set(deviceId, next);
+  await next;
+
+  const device = getDevice(deviceId);
+  if (!device) throw new Error(`Bootstrap failed for device ${deviceId}`);
+  return device;
+}
+
+async function bootstrapDevice(deviceId: string): Promise<void> {
+  const { platform, deviceType } = await detectPlatform(deviceId);
+
+  if (platform === "android") {
+    await bootstrapAndroid(deviceId);
+  } else {
+    await bootstrapIOS(deviceId, deviceType!);
+  }
+}
+
+// ── Android bootstrap ──
+
+async function bootstrapAndroid(deviceId: string): Promise<void> {
+  // Clean up stale state from a previous MCP instance (e.g. after Claude Code restart)
+  await cleanupStaleAndroid(deviceId);
+
+  const port = await allocateAndroidPort();
+  const authToken = randomBytes(32).toString("hex");
+  addPendingPort(port);
+
+  let serverProcess: Subprocess | undefined;
+  let cdpPort: number | undefined;
+  try {
+    // Install APKs
+    const apks = readdirSync(DRIVERS_ANDROID).filter((f) => f.endsWith(".apk"));
+    for (const apk of apks) {
+      const proc = Bun.spawn(["adb", "-s", deviceId, "install", "-r", "-g", join(DRIVERS_ANDROID, apk)], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      await proc.exited;
+    }
+
+    // Forward host port to device server
+    await runAdb(deviceId, "forward", `tcp:${port}`, `tcp:${port}`);
+
+    // CDP forwarding: route device:9222 → host:cdpPort → device Chrome abstract socket
+    // ADB daemon bypasses SELinux app-to-app restrictions (CdpBridge.kt couldn't)
+    cdpPort = await setupCdpForwarding(deviceId);
+
+    // Write auth token to device file (avoids exposing in process args / ps output)
+    await runAdb(deviceId, "shell", `echo -n ${authToken} > /data/local/tmp/.mds_auth_${port}`);
+
+    // Spawn instrumentation
+    serverProcess = Bun.spawn(
+      [
+        "adb", "-s", deviceId, "shell", "am", "instrument", "-w", "-r",
+        "-e", "class", "dev.uitreeserver.UITreeServer#startServer",
+        "-e", "port", String(port),
+        "dev.uitreeserver.test/androidx.test.runner.AndroidJUnitRunner",
+      ],
+      { stdout: "ignore", stderr: "ignore" },
+    );
+
+    // Health poll
+    await healthPoll(port, serverProcess);
+
+    // Register
+    setDevice({
+      id: deviceId,
+      platform: "android",
+      port,
+      authToken,
+      serverProcess,
+    });
+  } catch (err) {
+    // Cleanup on failure
+    if (serverProcess) {
+      try { serverProcess.kill(9); } catch { /* */ }
+    }
+    try { await runAdb(deviceId, "forward", "--remove", `tcp:${port}`); } catch { /* */ }
+    if (cdpPort) {
+      try { await runAdb(deviceId, "forward", "--remove", `tcp:${cdpPort}`); } catch { /* */ }
+    }
+    try { await runAdb(deviceId, "reverse", "--remove", "tcp:9222"); } catch { /* */ }
+    try { await runAdb(deviceId, "shell", `rm -f /data/local/tmp/.mds_auth_${port}`); } catch { /* */ }
+    throw err;
+  } finally {
+    releasePendingPort(port);
+  }
+}
+
+async function cleanupStaleAndroid(deviceId: string): Promise<void> {
+  // Kill any leftover instrumentation from a previous MCP instance
+  await runAdb(deviceId, "shell", "am", "force-stop", "dev.uitreeserver.test");
+  // Remove stale CDP reverse (device:9222 → host)
+  try { await runAdb(deviceId, "reverse", "--remove", "tcp:9222"); } catch { /* no reverse to remove */ }
+  // Remove all stale adb forwards for this device
+  try {
+    const proc = Bun.spawn(["adb", "-s", deviceId, "forward", "--list"], { stdout: "pipe", stderr: "pipe" });
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+    for (const line of output.split("\n")) {
+      // adb forward --list returns ALL devices; only remove ours
+      if (!line.startsWith(deviceId + " ")) continue;
+      const match = line.match(/^\S+\s+(tcp:\d+)/);
+      if (match) {
+        await runAdb(deviceId, "forward", "--remove", match[1]);
+      }
+    }
+  } catch { /* adb not available */ }
+  // Clean up any leftover auth token files
+  await runAdb(deviceId, "shell", "rm -f /data/local/tmp/.mds_auth_*");
+}
+
+async function setupCdpForwarding(deviceId: string): Promise<number> {
+  // Let ADB pick a free host port (tcp:0) that tunnels to Chrome's abstract socket
+  const fwdProc = Bun.spawn(
+    ["adb", "-s", deviceId, "forward", "tcp:0", "localabstract:chrome_devtools_remote"],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const cdpPort = parseInt((await new Response(fwdProc.stdout).text()).trim(), 10);
+  await fwdProc.exited;
+  if (isNaN(cdpPort)) {
+    throw new Error("Failed to allocate CDP forward port");
+  }
+  // Reverse: device:9222 → host:cdpPort (so on-device CdpClient reaches Chrome)
+  try {
+    await runAdb(deviceId, "reverse", "tcp:9222", `tcp:${cdpPort}`);
+  } catch (err) {
+    try { await runAdb(deviceId, "forward", "--remove", `tcp:${cdpPort}`); } catch { /* */ }
+    throw err;
+  }
+  return cdpPort;
+}
+
+async function runAdb(deviceId: string, ...args: string[]): Promise<void> {
+  const proc = Bun.spawn(["adb", "-s", deviceId, ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  await proc.exited;
+}
+
+// ── iOS bootstrap ──
+
+async function bootstrapIOS(deviceId: string, deviceType: DeviceType): Promise<void> {
+  // Clean up stale state from a previous MCP instance (e.g. after Claude Code restart)
+  await cleanupStalePorts();
+
+  const port = await allocateIOSPort();
+  const authToken = randomBytes(32).toString("hex");
+  addPendingPort(port);
+
+  let serverProcess: Subprocess | undefined;
+  let tunnelProcess: Subprocess | undefined;
+  try {
+    if (deviceType === "simulator") {
+      serverProcess = await bootstrapIOSSimulator(deviceId, port, authToken);
+    } else {
+      const result = await bootstrapIOSDevice(deviceId, port, authToken);
+      serverProcess = result.serverProcess;
+      tunnelProcess = result.tunnelProcess;
+    }
+
+    // Health poll
+    await healthPoll(port, serverProcess);
+
+    // Register
+    setDevice({
+      id: deviceId,
+      platform: "ios",
+      deviceType,
+      port,
+      authToken,
+      serverProcess,
+      tunnelProcess,
+    });
+  } catch (err) {
+    // Cleanup on failure
+    if (serverProcess) {
+      try { serverProcess.kill(9); } catch { /* */ }
+    }
+    if (tunnelProcess) {
+      try { tunnelProcess.kill(9); } catch { /* */ }
+    }
+    // For simulators, the spawn handle kill above doesn't kill the real server —
+    // kill whatever is actually listening on the port to prevent orphans.
+    if (deviceType === "simulator") {
+      await killPortListener(port);
+    }
+    unlockPort(port);
+    throw err;
+  } finally {
+    releasePendingPort(port);
+  }
+}
+
+// ── iOS simulator: simctl install + spawn (bypasses xcodebuild orchestration) ──
+
+async function bootstrapIOSSimulator(deviceId: string, port: number, authToken: string): Promise<Subprocess> {
+  const buildDir = join(DRIVERS_IOS_SIM, "Debug-iphonesimulator");
+  const runnerApp = readdirSync(buildDir).find((f) => f.endsWith("-Runner.app"));
+  if (!runnerApp) {
+    throw new Error("No Runner.app found in iOS simulator drivers");
+  }
+  const runnerAppPath = join(buildDir, runnerApp);
+  const binaryName = runnerApp.replace(/\.app$/, "");
+
+  // Read bundle ID from Info.plist
+  const plistProc = Bun.spawn(
+    ["/usr/libexec/PlistBuddy", "-c", "Print :CFBundleIdentifier", join(runnerAppPath, "Info.plist")],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const bundleId = (await new Response(plistProc.stdout).text()).trim();
+  await plistProc.exited;
+  if (!bundleId) {
+    throw new Error("Could not read bundle ID from Runner.app Info.plist");
+  }
+
+  // Install the app on the simulator
+  const installProc = Bun.spawn(
+    ["xcrun", "simctl", "install", deviceId, runnerAppPath],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const installExit = await installProc.exited;
+  if (installExit !== 0) {
+    const stderr = await new Response(installProc.stderr).text();
+    throw new Error(`simctl install failed: ${stderr}`);
+  }
+
+  // Get installed app container path
+  const containerProc = Bun.spawn(
+    ["xcrun", "simctl", "get_app_container", deviceId, bundleId],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const containerPath = (await new Response(containerProc.stdout).text()).trim();
+  await containerProc.exited;
+  if (!containerPath) {
+    throw new Error("Could not get app container path after install");
+  }
+
+  // Spawn the runner binary inside the simulator (no foreground, no SpringBoard)
+  return Bun.spawn(
+    ["xcrun", "simctl", "spawn", deviceId, join(containerPath, binaryName)],
+    {
+      stdout: "ignore",
+      stderr: "ignore",
+      env: {
+        ...process.env,
+        SIMCTL_CHILD_PORT: String(port),
+        SIMCTL_CHILD_AUTH_TOKEN: authToken,
+      },
+    },
+  );
+}
+
+// ── iOS real device: xcodebuild (still required for testmanagerd handshake) ──
+
+async function bootstrapIOSDevice(
+  deviceId: string, port: number, authToken: string,
+): Promise<{ serverProcess: Subprocess; tunnelProcess: Subprocess }> {
+  const xctestrunFile = readdirSync(DRIVERS_IOS_DEVICE).find((f) => f.endsWith(".xctestrun"));
+  if (!xctestrunFile) {
+    throw new Error("No .xctestrun driver found for iOS device");
+  }
+
+  const serverProcess = Bun.spawn(
+    [
+      "xcodebuild", "test-without-building",
+      "-xctestrun", join(DRIVERS_IOS_DEVICE, xctestrunFile),
+      "-destination", `platform=iOS,id=${deviceId}`,
+      "-parallel-testing-enabled", "NO",
+      "-allowProvisioningUpdates",
+    ],
+    {
+      stdout: "ignore",
+      stderr: "ignore",
+      env: {
+        ...process.env,
+        TEST_RUNNER_PORT: String(port),
+        TEST_RUNNER_AUTH_TOKEN: authToken,
+      },
+    },
+  );
+
+  const tunnelProcess = Bun.spawn(
+    ["iproxy", String(port), String(port), "-u", deviceId, "-l", "127.0.0.1"],
+    { stdout: "ignore", stderr: "ignore" },
+  );
+
+  return { serverProcess, tunnelProcess };
+}
+
+// ── Health poll ──
+
+async function healthPoll(port: number, serverProcess: Subprocess): Promise<void> {
+  const deadline = Date.now() + HEALTH_TIMEOUT;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/health`);
+      if (res.ok) return;
+    } catch {
+      // Connection not ready yet
+    }
+    // Check if the process died
+    if (serverProcess.exitCode !== null) {
+      throw new Error(`Server process exited with code ${serverProcess.exitCode} before becoming healthy`);
+    }
+    await Bun.sleep(HEALTH_POLL_INTERVAL);
+  }
+  // Timeout: kill and throw
+  try { serverProcess.kill(9); } catch { /* */ }
+  throw new Error(`Health check timed out after ${HEALTH_TIMEOUT}ms on port ${port}`);
+}

package/src/server/devices.ts

@@ -0,0 +1,262 @@
+import { unlinkSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import type { RegisteredDevice, DiscoveredDevice, Platform, DeviceType } from "./types.js";
+import { killPortListener } from "./ports.js";
+
+const LOCK_DIR = join(homedir(), ".mdms", "ports");
+
+// ── Device registry ──
+
+const registry = new Map<string, RegisteredDevice>();
+
+export function getDevice(id: string): RegisteredDevice | undefined {
+  return registry.get(id);
+}
+
+export function setDevice(device: RegisteredDevice): void {
+  registry.set(device.id, device);
+}
+
+export function removeDevice(id: string): RegisteredDevice | undefined {
+  const device = registry.get(id);
+  if (device) registry.delete(id);
+  return device;
+}
+
+export function allDevices(): RegisteredDevice[] {
+  return Array.from(registry.values());
+}
+
+// ── Discovery ──
+
+async function runCommand(cmd: string[]): Promise<string> {
+  const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+  const text = await new Response(proc.stdout).text();
+  await proc.exited;
+  return text;
+}
+
+async function discoverAndroid(): Promise<DiscoveredDevice[]> {
+  try {
+    const output = await runCommand(["adb", "devices", "-l"]);
+    const devices: DiscoveredDevice[] = [];
+    for (const line of output.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("List of")) continue;
+      // Format: <serial> <state> <info...>
+      const parts = trimmed.split(/\s+/);
+      if (parts.length < 2) continue;
+      const id = parts[0];
+      const state = parts[1];
+      let name = id;
+      for (const part of parts.slice(2)) {
+        if (part.startsWith("model:")) {
+          name = part.slice("model:".length);
+          break;
+        }
+      }
+      devices.push({ id, platform: "android", name, state });
+    }
+    return devices;
+  } catch (err) {
+    console.error("Android discovery failed:", err);
+    return [];
+  }
+}
+
+async function discoverIOSSimulators(): Promise<DiscoveredDevice[]> {
+  try {
+    const output = await runCommand(["xcrun", "simctl", "list", "devices", "booted", "-j"]);
+    const json = JSON.parse(output);
+    const devices: DiscoveredDevice[] = [];
+    const runtimes = json.devices || {};
+    for (const runtime of Object.keys(runtimes)) {
+      for (const device of runtimes[runtime]) {
+        if (device.state !== "Booted") continue;
+        devices.push({
+          id: device.udid,
+          platform: "ios",
+          name: device.name,
+          state: device.state,
+          deviceType: "simulator",
+        });
+      }
+    }
+    return devices;
+  } catch (err) {
+    console.error("iOS simulator discovery failed:", err);
+    return [];
+  }
+}
+
+async function discoverIOSRealDevices(): Promise<DiscoveredDevice[]> {
+  try {
+    const output = await runCommand(["xcrun", "devicectl", "list", "devices", "--json-output", "/dev/stdout"]);
+    const json = JSON.parse(output);
+    const devices: DiscoveredDevice[] = [];
+    const result = json.result?.devices || [];
+    for (const device of result) {
+      // Only include USB-connected devices
+      if (device.connectionProperties?.transportType !== "wired") continue;
+      devices.push({
+        id: device.identifier,
+        platform: "ios",
+        name: device.deviceProperties?.name || device.identifier,
+        state: "connected",
+        deviceType: "device",
+      });
+    }
+    return devices;
+  } catch (err) {
+    console.error("iOS real device discovery failed:", err);
+    return [];
+  }
+}
+
+export async function discoverDevices(): Promise<DiscoveredDevice[]> {
+  const [android, iosSim, iosDevice] = await Promise.all([
+    discoverAndroid(),
+    discoverIOSSimulators(),
+    discoverIOSRealDevices(),
+  ]);
+  return [...android, ...iosSim, ...iosDevice];
+}
+
+export type DetectedPlatformInfo = {
+  platform: Platform;
+  deviceType?: DeviceType;
+};
+
+export async function detectPlatform(deviceId: string): Promise<DetectedPlatformInfo> {
+  // Check Android first
+  try {
+    const output = await runCommand(["adb", "devices"]);
+    for (const line of output.split("\n")) {
+      const serial = line.split("\t")[0];
+      if (serial === deviceId) {
+        return { platform: "android" };
+      }
+    }
+  } catch { /* adb not available */ }
+
+  // Check iOS simulators
+  try {
+    const output = await runCommand(["xcrun", "simctl", "list", "devices", "booted", "-j"]);
+    const json = JSON.parse(output);
+    const runtimes = json.devices || {};
+    for (const runtime of Object.keys(runtimes)) {
+      for (const device of runtimes[runtime]) {
+        if (device.udid === deviceId && device.state === "Booted") {
+          return { platform: "ios", deviceType: "simulator" };
+        }
+      }
+    }
+  } catch { /* simctl not available */ }
+
+  // Check iOS real devices
+  try {
+    const output = await runCommand(["xcrun", "devicectl", "list", "devices", "--json-output", "/dev/stdout"]);
+    const json = JSON.parse(output);
+    const result = json.result?.devices || [];
+    for (const device of result) {
+      if (device.identifier === deviceId && device.connectionProperties?.transportType === "wired") {
+        return { platform: "ios", deviceType: "device" };
+      }
+    }
+  } catch { /* devicectl not available */ }
+
+  throw new Error(`Device ${deviceId} not found in adb, simctl, or devicectl`);
+}
+
+// ── Cleanup ──
+
+export async function cleanupDevice(device: RegisteredDevice): Promise<void> {
+  // Kill server process (SIGKILL, try process group first)
+  try {
+    if (device.serverProcess.pid && device.serverProcess.pid > 0) {
+      process.kill(-device.serverProcess.pid, "SIGKILL");
+    }
+  } catch {
+    try {
+      device.serverProcess.kill(9);
+    } catch { /* already dead */ }
+  }
+
+  // Kill tunnel process if present (iOS real devices)
+  if (device.tunnelProcess) {
+    try {
+      if (device.tunnelProcess.pid && device.tunnelProcess.pid > 0) {
+        process.kill(-device.tunnelProcess.pid, "SIGKILL");
+      }
+    } catch {
+      try {
+        device.tunnelProcess.kill(9);
+      } catch { /* already dead */ }
+    }
+  }
+
+  // Platform-specific cleanup
+  if (device.platform === "android") {
+    // Force-stop the test package
+    const forceStop = Bun.spawn(["adb", "-s", device.id, "shell", "am", "force-stop", "dev.uitreeserver.test"], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    await forceStop.exited;
+
+    // Remove auth token file from device
+    const rmAuth = Bun.spawn(
+      ["adb", "-s", device.id, "shell", `rm -f /data/local/tmp/.mds_auth_${device.port}`],
+      { stdout: "ignore", stderr: "ignore" },
+    );
+    await rmAuth.exited;
+
+    // Remove CDP reverse (device:9222 → host)
+    const rmReverse = Bun.spawn(
+      ["adb", "-s", device.id, "reverse", "--remove", "tcp:9222"],
+      { stdout: "ignore", stderr: "ignore" },
+    );
+    await rmReverse.exited;
+
+    // Remove ALL ADB forwards for this device (not just registered ports)
+    try {
+      const listProc = Bun.spawn(["adb", "-s", device.id, "forward", "--list"], { stdout: "pipe", stderr: "ignore" });
+      const output = await new Response(listProc.stdout).text();
+      await listProc.exited;
+      const removes: Promise<number>[] = [];
+      for (const line of output.split("\n")) {
+        // adb forward --list returns ALL devices; only remove ours
+        if (!line.startsWith(device.id + " ")) continue;
+        const match = line.match(/^\S+\s+(tcp:\d+)/);
+        if (match) {
+          removes.push(
+            Bun.spawn(["adb", "-s", device.id, "forward", "--remove", match[1]], {
+              stdout: "ignore", stderr: "ignore",
+            }).exited,
+          );
+        }
+      }
+      await Promise.allSettled(removes);
+    } catch { /* adb not available */ }
+  } else if (device.platform === "ios") {
+    // For simulators, kill the actual server inside the simulator.
+    // serverProcess is just the simctl spawn handle — the real server
+    // runs under the simulator's launchd and survives handle death.
+    if (device.deviceType === "simulator") {
+      await killPortListener(device.port);
+    }
+    // Delete port lock file
+    try {
+      unlinkSync(join(LOCK_DIR, String(device.port)));
+    } catch { /* file may not exist */ }
+  }
+}
+
+export async function cleanupAll(): Promise<void> {
+  const devices = allDevices();
+  await Promise.allSettled(devices.map((device) => cleanupDevice(device)));
+  for (const device of devices) {
+    registry.delete(device.id);
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,41 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { cleanupAll } from "./devices.js";
+import pkg from "../../package.json";
+
+// ── Shutdown ──
+
+let shuttingDown = false;
+
+async function shutdown(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.error("Shutting down, cleaning up devices...");
+  await cleanupAll();
+  process.exit(0);
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+// ── Main ──
+
+async function main(): Promise<void> {
+  const server = new McpServer(
+    { name: pkg.name, version: pkg.version },
+    { capabilities: { tools: {} } },
+  );
+
+  registerTools(server);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP server running on stdio");
+}
+
+main().catch(async (err) => {
+  console.error("Fatal error:", err);
+  await cleanupAll();
+  process.exit(1);
+});