@srmorete/mobile-device-mcp 0.1.0

package/src/server/ports.ts

@@ -0,0 +1,190 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { allDevices } from "./devices.js";
+
+const BASE_PORT_IOS = parseInt(process.env.MDMS_PORT_IOS || "19000", 10);
+const BASE_PORT_ANDROID = parseInt(process.env.MDMS_PORT_ANDROID || "18000", 10);
+const LOCK_DIR = join(homedir(), ".mdms", "ports");
+
+// Pending ports: tracked during bootstrap, released after health check
+const pendingPorts = new Set<number>();
+
+export function addPendingPort(port: number): void {
+  pendingPorts.add(port);
+}
+
+export function releasePendingPort(port: number): void {
+  pendingPorts.delete(port);
+}
+
+function registryPorts(): Set<number> {
+  const ports = new Set<number>();
+  for (const device of allDevices()) {
+    ports.add(device.port);
+  }
+  return ports;
+}
+
+// ── Android port allocation ──
+
+async function getADBForwardedPorts(): Promise<Set<number>> {
+  const ports = new Set<number>();
+  try {
+    const proc = Bun.spawn(["adb", "forward", "--list"], { stdout: "pipe", stderr: "pipe" });
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+    // Lines: <serial> tcp:<hostPort> <deviceSpec>
+    // Only track the host-side port (second column)
+    for (const line of output.split("\n")) {
+      const match = line.match(/^\S+\s+tcp:(\d+)/);
+      if (match) {
+        ports.add(parseInt(match[1], 10));
+      }
+    }
+  } catch { /* adb not available */ }
+  return ports;
+}
+
+export async function allocateAndroidPort(): Promise<number> {
+  const adbPorts = await getADBForwardedPorts();
+  const regPorts = registryPorts();
+  const usedPorts = new Set([...pendingPorts, ...regPorts, ...adbPorts]);
+
+  let port = BASE_PORT_ANDROID;
+  while (usedPorts.has(port)) port++;
+
+  if (port > 65535) {
+    throw new Error("No available ports for Android device server");
+  }
+  return port;
+}
+
+// ── iOS port allocation ──
+
+async function isPortListening(port: number): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["lsof", "-i", `TCP:${port}`, "-sTCP:LISTEN"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+    return output.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function ensureLockDir(): void {
+  mkdirSync(LOCK_DIR, { recursive: true, mode: 0o700 });
+  // Always verify the result is not a symlink (prevents symlink attacks)
+  const stat = lstatSync(LOCK_DIR);
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Lock directory is a symlink — refusing to use it`);
+  }
+}
+
+function tryLockPort(port: number): boolean {
+  ensureLockDir();
+
+  const lockFile = `${LOCK_DIR}/${port}`;
+  try {
+    // Try exclusive create
+    writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+    return true;
+  } catch {
+    // File exists — check if the owning process is alive
+    try {
+      const pid = parseInt(readFileSync(lockFile, "utf-8").trim(), 10);
+      if (isNaN(pid)) {
+        // Invalid content, reclaim
+        unlinkSync(lockFile);
+        writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+        return true;
+      }
+      try {
+        process.kill(pid, 0); // check if alive
+        return false; // alive, lock fails
+      } catch {
+        // Dead process, reclaim
+        unlinkSync(lockFile);
+        writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+        return true;
+      }
+    } catch {
+      return false;
+    }
+  }
+}
+
+export function unlockPort(port: number): void {
+  try {
+    unlinkSync(`${LOCK_DIR}/${port}`);
+  } catch { /* file may not exist */ }
+}
+
+export async function allocateIOSPort(): Promise<number> {
+  const regPorts = registryPorts();
+  const usedPorts = new Set([...pendingPorts, ...regPorts]);
+
+  let port = BASE_PORT_IOS;
+  while (port <= 65535) {
+    if (!usedPorts.has(port) && !(await isPortListening(port)) && tryLockPort(port)) {
+      return port;
+    }
+    port++;
+  }
+  throw new Error("No available ports for iOS device server");
+}
+
+// ── Stale port cleanup ──
+
+export async function killPortListener(port: number): Promise<void> {
+  try {
+    const proc = Bun.spawn(
+      ["lsof", "-ti", `TCP:${port}`, "-sTCP:LISTEN"],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+    for (const line of output.trim().split("\n")) {
+      const pid = parseInt(line.trim(), 10);
+      if (!isNaN(pid) && pid > 0) {
+        try { process.kill(pid, "SIGKILL"); } catch { /* already dead */ }
+      }
+    }
+  } catch { /* lsof not available */ }
+}
+
+export async function cleanupStalePorts(): Promise<void> {
+  let files: string[];
+  try {
+    files = readdirSync(LOCK_DIR);
+  } catch {
+    return; // lock dir doesn't exist yet
+  }
+
+  for (const file of files) {
+    const port = parseInt(file, 10);
+    if (isNaN(port)) continue;
+
+    const lockFile = join(LOCK_DIR, file);
+    let ownerAlive = false;
+    try {
+      const pid = parseInt(readFileSync(lockFile, "utf-8").trim(), 10);
+      if (!isNaN(pid)) {
+        try {
+          process.kill(pid, 0);
+          ownerAlive = true;
+        } catch { /* dead */ }
+      }
+    } catch { continue; }
+
+    if (ownerAlive) continue;
+
+    // Owner MCP is dead — kill whatever is still listening on this port
+    await killPortListener(port);
+    try { unlinkSync(lockFile); } catch { /* */ }
+  }
+}

package/src/server/proxy.ts

@@ -0,0 +1,119 @@
+import type { RegisteredDevice } from "./types.js";
+import { ensureDevice } from "./bootstrap.js";
+import { removeDevice, cleanupDevice } from "./devices.js";
+
+function isConnectionError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message;
+  return (
+    msg.includes("ECONNREFUSED") ||
+    msg.includes("ECONNRESET") ||
+    msg.includes("fetch failed") ||
+    msg.includes("socket") ||
+    msg.includes("Unable to connect") ||
+    msg.includes("timed out") ||
+    msg.includes("ETIMEDOUT")
+  );
+}
+
+function buildUrl(port: number, path: string, queryParams?: Record<string, string | number>): string {
+  let url = `http://127.0.0.1:${port}${path}`;
+  if (queryParams && Object.keys(queryParams).length > 0) {
+    const parts = Object.entries(queryParams).map(
+      ([key, val]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(val))}`,
+    );
+    url += `?${parts.join("&")}`;
+  }
+  return url;
+}
+
+type ProxyRequest =
+  | { method: "GET"; path: string; binary?: false }
+  | { method: "GET"; path: string; binary: true }
+  | { method: "POST"; path: string; queryParams: Record<string, string | number> }
+  | { method: "POST"; path: string; body: string };
+
+function authHeaders(device: RegisteredDevice): Record<string, string> {
+  return { "Authorization": `Bearer ${device.authToken}` };
+}
+
+const REQUEST_TIMEOUT = 30_000; // 30s — long enough for screenshots, short enough to detect dead servers
+
+async function executeRequest(device: RegisteredDevice, req: ProxyRequest): Promise<Response> {
+  const headers = authHeaders(device);
+  const signal = AbortSignal.timeout(REQUEST_TIMEOUT);
+  if (req.method === "GET") {
+    return fetch(buildUrl(device.port, req.path), { headers, signal });
+  }
+  if ("queryParams" in req) {
+    return fetch(buildUrl(device.port, req.path, req.queryParams), { method: "POST", headers, signal });
+  }
+  // POST with body
+  return fetch(buildUrl(device.port, req.path), {
+    method: "POST",
+    headers: { ...headers, "Content-Type": "text/plain" },
+    body: req.body,
+    signal,
+  });
+}
+
+export async function proxyRequest(
+  deviceId: string,
+  req: ProxyRequest,
+): Promise<string | Buffer> {
+  let device = await ensureDevice(deviceId);
+
+  const attempt = async (dev: RegisteredDevice): Promise<string | Buffer> => {
+    const res = await executeRequest(dev, req);
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(
+        `${req.method} ${req.path} failed: ${res.status} ${res.statusText} — ${body.slice(0, 500)}`,
+      );
+    }
+    if (req.method === "GET" && "binary" in req && req.binary) {
+      const arrayBuffer = await res.arrayBuffer();
+      return Buffer.from(arrayBuffer);
+    }
+    return res.text();
+  };
+
+  try {
+    return await attempt(device);
+  } catch (err) {
+    if (isConnectionError(err)) {
+      // Remove device, re-bootstrap, retry once
+      const old = removeDevice(deviceId);
+      if (old) await cleanupDevice(old);
+      device = await ensureDevice(deviceId);
+      return attempt(device);
+    }
+    throw err;
+  }
+}
+
+// Convenience wrappers
+
+export async function proxyGet(deviceId: string, path: string): Promise<string> {
+  return proxyRequest(deviceId, { method: "GET", path }) as Promise<string>;
+}
+
+export async function proxyGetBinary(deviceId: string, path: string): Promise<Buffer> {
+  return proxyRequest(deviceId, { method: "GET", path, binary: true }) as Promise<Buffer>;
+}
+
+export async function proxyPost(
+  deviceId: string,
+  path: string,
+  queryParams: Record<string, string | number>,
+): Promise<string> {
+  return proxyRequest(deviceId, { method: "POST", path, queryParams }) as Promise<string>;
+}
+
+export async function proxyPostBody(
+  deviceId: string,
+  path: string,
+  body: string,
+): Promise<string> {
+  return proxyRequest(deviceId, { method: "POST", path, body }) as Promise<string>;
+}

package/src/server/tools.ts

@@ -0,0 +1,303 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { discoverDevices, getDevice } from "./devices.js";
+import { proxyGet, proxyGetBinary, proxyPost, proxyPostBody } from "./proxy.js";
+import { ensureDevice } from "./bootstrap.js";
+import { filterUITree } from "../filter/filter.js";
+import type { FilteredElement } from "../filter/types.js";
+
+function textResult(text: string): CallToolResult {
+  return { content: [{ type: "text", text }] };
+}
+
+function imageResult(base64: string, mimeType: string): CallToolResult {
+  return { content: [{ type: "image", data: base64, mimeType }] };
+}
+
+function errorResult(message: string): CallToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+export function registerTools(server: McpServer): void {
+  // ── 2.2.1 list_devices ──
+  server.tool(
+    "list_devices",
+    "Lists available mobile devices",
+    {},
+    async () => {
+      const devices = await discoverDevices();
+      return textResult(JSON.stringify(devices, null, 2));
+    },
+  );
+
+  // ── 2.2.2 tap ──
+  server.tool(
+    "tap",
+    "Taps at coordinates on the device screen",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      x: z.number(),
+      y: z.number(),
+    },
+    async ({ device_id, x, y }) => {
+      try {
+        const text = await proxyPost(device_id, "/tap", { x, y });
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.3 double_tap ──
+  server.tool(
+    "double_tap",
+    "Double-taps at coordinates on the device screen",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      x: z.number(),
+      y: z.number(),
+    },
+    async ({ device_id, x, y }) => {
+      try {
+        const text = await proxyPost(device_id, "/doubleTap", { x, y });
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.4 long_press ──
+  server.tool(
+    "long_press",
+    "Long-presses at coordinates on the device screen",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      x: z.number(),
+      y: z.number(),
+      duration: z.number().min(1).max(10000).optional(),
+    },
+    async ({ device_id, x, y, duration }) => {
+      try {
+        const params: Record<string, string | number> = { x, y };
+        if (duration !== undefined) {
+          params.duration = duration;
+        }
+        const text = await proxyPost(device_id, "/longPress", params);
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.5 scroll ──
+  server.tool(
+    "scroll",
+    "Scrolls on the device screen from start to end coordinates",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      startX: z.number(),
+      startY: z.number(),
+      endX: z.number(),
+      endY: z.number(),
+    },
+    async ({ device_id, startX, startY, endX, endY }) => {
+      try {
+        const text = await proxyPost(device_id, "/scroll", { startX, startY, endX, endY });
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.6 type_text ──
+  server.tool(
+    "type_text",
+    "Types text on the device",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      text: z.string().max(10_000),
+    },
+    async ({ device_id, text }) => {
+      try {
+        const result = await proxyPost(device_id, "/type", { text });
+        return textResult(result);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.7 press_button ──
+  server.tool(
+    "press_button",
+    "Presses a hardware/navigation button on the device",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      button: z.enum([
+        "home",
+        "back",
+        "volumeUp",
+        "volumeDown",
+        "enter",
+        "dpadUp",
+        "dpadDown",
+        "dpadLeft",
+        "dpadRight",
+        "dpadCenter",
+      ]),
+    },
+    async ({ device_id, button }) => {
+      try {
+        const text = await proxyPost(device_id, "/press", { button });
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.8 screenshot ──
+  server.tool(
+    "screenshot",
+    "Takes a screenshot of the device screen",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+    },
+    async ({ device_id }) => {
+      try {
+        const buf = await proxyGetBinary(device_id, "/screenshot");
+        if (buf.length === 0) {
+          return errorResult("Empty screenshot response from device");
+        }
+        const base64 = buf.toString("base64");
+        // Detect actual image format from magic bytes
+        const mimeType = (buf[0] === 0xFF && buf[1] === 0xD8) ? "image/jpeg" : "image/png";
+        return imageResult(base64, mimeType);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.9 uitree ──
+  server.tool(
+    "uitree",
+    "Returns the UI element tree of the device screen",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      search: z.string().optional(),
+      limit: z.number().int().min(1).optional(),
+    },
+    async ({ device_id, search, limit }) => {
+      try {
+        // 1. GET /uitree and parse
+        const rawJson = await proxyGet(device_id, "/uitree");
+        const rawTree = JSON.parse(rawJson);
+
+        // 2. Filter through UI tree filter
+        let elements: FilteredElement[] = filterUITree(rawTree);
+
+        // 3. Search: case-insensitive substring on text
+        if (search) {
+          const lower = search.toLowerCase();
+          elements = elements.filter((el) => (el.text ?? "").toLowerCase().includes(lower));
+        }
+
+        // 4. Limit
+        const total = elements.length;
+        let suffix = "";
+        if (limit !== undefined && total > limit) {
+          elements = elements.slice(0, limit);
+          suffix = `\n(showing ${limit} of ${total} elements, use 'search' to narrow results)`;
+        }
+
+        // 5. Serialize as JSONL
+        const jsonl = elements.map((el) => JSON.stringify(el)).join("\n") + suffix;
+        return textResult(jsonl);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.10 launch_app ──
+  server.tool(
+    "launch_app",
+    "Launches an app on the device",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      app_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+    },
+    async ({ device_id, app_id }) => {
+      try {
+        const device = await ensureDevice(device_id);
+        const paramKey = device.platform === "ios" ? "bundleId" : "packageName";
+        const text = await proxyPost(device_id, "/launchApp", { [paramKey]: app_id });
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.11 terminate_app ──
+  server.tool(
+    "terminate_app",
+    "Terminates an app on the device",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      app_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+    },
+    async ({ device_id, app_id }) => {
+      try {
+        const device = await ensureDevice(device_id);
+        const paramKey = device.platform === "ios" ? "bundleId" : "packageName";
+        const text = await proxyPost(device_id, "/terminateApp", { [paramKey]: app_id });
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.12 list_apps ──
+  server.tool(
+    "list_apps",
+    "Lists installed apps on the device",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+    },
+    async ({ device_id }) => {
+      try {
+        const text = await proxyGet(device_id, "/listApps");
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+  // ── 2.2.13 run_code ──
+  server.tool(
+    "run_code",
+    "Execute test automation code on the device",
+    {
+      device_id: z.string().regex(/^[\w\-.:]{1,256}$/),
+      code: z.string().max(100_000),
+    },
+    async ({ device_id, code }) => {
+      try {
+        const text = await proxyPostBody(device_id, "/exec", code);
+        return textResult(text);
+      } catch (err) {
+        return errorResult((err as Error).message);
+      }
+    },
+  );
+
+}

package/src/server/types.ts

@@ -0,0 +1,22 @@
+import type { Subprocess } from "bun";
+
+export type Platform = "android" | "ios";
+export type DeviceType = "simulator" | "device";
+
+export interface DiscoveredDevice {
+  id: string;
+  platform: Platform;
+  name: string;
+  state: string;
+  deviceType?: DeviceType; // iOS only
+}
+
+export interface RegisteredDevice {
+  id: string;
+  platform: Platform;
+  deviceType?: DeviceType;
+  port: number;
+  authToken: string;
+  serverProcess: Subprocess;
+  tunnelProcess?: Subprocess; // iOS real devices only
+}