devlens-mcp 0.3.0

package/src/platform/ios/simctl.ts

@@ -0,0 +1,244 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Wrapper around `xcrun simctl` for iOS Simulator interaction.
+ */
+export class Simctl {
+  constructor(private deviceId: string) {}
+
+  /** Execute a simctl command */
+  async exec(...args: string[]): Promise<string> {
+    const { stdout } = await execFileAsync(
+      "xcrun",
+      ["simctl", ...args],
+      { maxBuffer: 10 * 1024 * 1024, timeout: 30000 }
+    );
+    return stdout;
+  }
+
+  /** Take a screenshot and return PNG buffer */
+  async screenshot(): Promise<Buffer> {
+    const tmpPath = `/tmp/devlens-screenshot-${Date.now()}.png`;
+    await this.exec("io", this.deviceId, "screenshot", tmpPath);
+
+    const { readFile, unlink } = await import("fs/promises");
+    const buffer = await readFile(tmpPath);
+    unlink(tmpPath).catch(() => {});
+    return buffer;
+  }
+
+  /** Get the accessibility tree using simctl's accessibility audit */
+  async getAccessibilityTree(): Promise<string> {
+    // Use simctl ui to get the accessibility hierarchy
+    try {
+      const output = await this.exec(
+        "ui",
+        this.deviceId,
+        "accessibility",
+      );
+      return output;
+    } catch {
+      // Fallback: use the description command for view hierarchy
+      return this.getViewHierarchyViaXctest();
+    }
+  }
+
+  /**
+   * Fallback: Get view hierarchy by running a small XCTest snippet.
+   * This uses `simctl launch` with a debugger approach, but the simplest
+   * method is to use the accessibility description from the simulator.
+   */
+  private async getViewHierarchyViaXctest(): Promise<string> {
+    // Use the simctl subprocess to query the UI
+    // We'll use `simctl ui <device> describe` to get the UI hierarchy
+    try {
+      const output = await this.exec("ui", this.deviceId, "describe");
+      return output;
+    } catch {
+      throw new Error(
+        "Could not extract accessibility tree from iOS Simulator. " +
+          "Ensure the simulator is booted and has an app running."
+      );
+    }
+  }
+
+  /** Get device info from simctl */
+  async getDeviceInfo(): Promise<{
+    name: string;
+    runtime: string;
+    state: string;
+  }> {
+    const { stdout } = await execFileAsync("xcrun", [
+      "simctl",
+      "list",
+      "devices",
+      "--json",
+    ]);
+    const data = JSON.parse(stdout);
+
+    for (const [runtime, devices] of Object.entries(
+      data.devices as Record<string, Array<{ udid: string; name: string; state: string }>>
+    )) {
+      for (const device of devices) {
+        if (device.udid === this.deviceId) {
+          return {
+            name: device.name,
+            runtime: runtime
+              .replace(/^com\.apple\.CoreSimulator\.SimRuntime\./, "")
+              .replace(/-/g, "."),
+            state: device.state,
+          };
+        }
+      }
+    }
+    throw new Error(`Device ${this.deviceId} not found in simctl list`);
+  }
+
+  /** Get screen size of the simulator */
+  async getScreenSize(): Promise<{ width: number; height: number }> {
+    // Take a tiny screenshot and check its dimensions via sharp
+    const tmpPath = `/tmp/devlens-size-check-${Date.now()}.png`;
+    await this.exec("io", this.deviceId, "screenshot", tmpPath);
+
+    try {
+      const sharp = (await import("sharp")).default;
+      const metadata = await sharp(tmpPath).metadata();
+      const { unlink } = await import("fs/promises");
+      unlink(tmpPath).catch(() => {});
+
+      return {
+        width: metadata.width || 390,
+        height: metadata.height || 844,
+      };
+    } catch {
+      // Fallback defaults (iPhone 14)
+      return { width: 390, height: 844 };
+    }
+  }
+
+  /** Tap at coordinates using simctl */
+  async tap(x: number, y: number): Promise<void> {
+    // simctl doesn't have a direct tap command, so we use the io command
+    // with the AppleScript approach or the simctl interact command
+    try {
+      await this.exec(
+        "io",
+        this.deviceId,
+        "tap",
+        String(Math.round(x)),
+        String(Math.round(y))
+      );
+    } catch {
+      // Fallback: use AppleScript to tap on the simulator
+      await execFileAsync("osascript", [
+        "-e",
+        `tell application "Simulator" to activate`,
+      ]);
+      // Use cliclick or similar for coordinate-based tapping
+      throw new Error(
+        "Direct tap not supported on this simctl version. Consider using a newer Xcode."
+      );
+    }
+  }
+
+  /** Swipe on the simulator */
+  async swipe(
+    startX: number,
+    startY: number,
+    endX: number,
+    endY: number
+  ): Promise<void> {
+    try {
+      await this.exec(
+        "io",
+        this.deviceId,
+        "swipe",
+        String(Math.round(startX)),
+        String(Math.round(startY)),
+        String(Math.round(endX)),
+        String(Math.round(endY))
+      );
+    } catch {
+      throw new Error("Swipe not supported on this simctl version.");
+    }
+  }
+
+  /** Type text using simctl keyboard input */
+  async typeText(text: string): Promise<void> {
+    await this.exec("io", this.deviceId, "keyboard", "type", text);
+  }
+
+  /** Press a key using simctl */
+  async pressKey(key: string): Promise<void> {
+    await this.exec("io", this.deviceId, "keyboard", "key", key);
+  }
+
+  /** Launch an app */
+  async launchApp(bundleId: string): Promise<void> {
+    await this.exec("launch", this.deviceId, bundleId);
+  }
+
+  /** Terminate an app */
+  async terminateApp(bundleId: string): Promise<void> {
+    await this.exec("terminate", this.deviceId, bundleId);
+  }
+
+  /** Install an app (.app bundle or .ipa) */
+  async installApp(path: string): Promise<void> {
+    await this.exec("install", this.deviceId, path);
+  }
+
+  /** List installed apps */
+  async listApps(): Promise<Array<{ bundleId: string; name: string }>> {
+    try {
+      const output = await this.exec(
+        "listapps",
+        this.deviceId,
+      );
+      // Parse the plist/json output
+      const apps: Array<{ bundleId: string; name: string }> = [];
+      const bundleIdMatches = output.matchAll(
+        /"CFBundleIdentifier"\s*=\s*"([^"]+)"/g
+      );
+      const nameMatches = output.matchAll(
+        /"CFBundleDisplayName"\s*=\s*"([^"]+)"/g
+      );
+      const bundleIds = [...bundleIdMatches].map((m) => m[1]);
+      const names = [...nameMatches].map((m) => m[1]);
+
+      for (let i = 0; i < bundleIds.length; i++) {
+        apps.push({
+          bundleId: bundleIds[i],
+          name: names[i] || bundleIds[i],
+        });
+      }
+      return apps;
+    } catch {
+      return [];
+    }
+  }
+
+  /** Open a URL */
+  async openUrl(url: string): Promise<void> {
+    await this.exec("openurl", this.deviceId, url);
+  }
+
+  /** Set device orientation */
+  async setOrientation(orientation: "portrait" | "landscape"): Promise<void> {
+    // simctl doesn't have a direct orientation command
+    // Use the Simulator menu via AppleScript
+    const rotation = orientation === "portrait" ? "0" : "90";
+    try {
+      await execFileAsync("osascript", [
+        "-e",
+        `tell application "System Events" to tell process "Simulator" to ` +
+          `click menu item "Rotate ${orientation === "landscape" ? "Right" : "Left"}" of menu "Device" of menu bar 1`,
+      ]);
+    } catch {
+      // Orientation setting may not be available in all environments
+    }
+  }
+}

package/src/server.ts

@@ -0,0 +1,228 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { DeviceManager } from "./platform/device-manager.js";
+import { RefRegistry } from "./snapshot/ref-registry.js";
+import { loadDevLensConfig } from "./config/devlens-config.js";
+import { dsToolSchemas, createDsToolHandlers } from "./tools/ds-tools.js";
+import {
+  deviceToolSchemas,
+  createDeviceToolHandlers,
+} from "./tools/device-tools.js";
+import {
+  snapshotToolSchemas,
+  createSnapshotToolHandlers,
+} from "./tools/snapshot-tools.js";
+import {
+  interactionToolSchemas,
+  createInteractionToolHandlers,
+} from "./tools/interaction-tools.js";
+import {
+  screenshotToolSchemas,
+  createScreenshotToolHandlers,
+} from "./tools/screenshot-tools.js";
+import {
+  appToolSchemas,
+  createAppToolHandlers,
+} from "./tools/app-tools.js";
+import {
+  metroToolSchemas,
+  createMetroToolHandlers,
+} from "./tools/metro-tools.js";
+import {
+  navigationToolSchemas,
+  createNavigationToolHandlers,
+} from "./tools/navigation-tools.js";
+
+export async function startServer(): Promise<Server> {
+  const server = new Server(
+    {
+      name: "devlens-mcp",
+      version: "0.3.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Load config (from DEVLENS_CONFIG env var or ./devlens.config.json)
+  const devlensConfig = await loadDevLensConfig();
+
+  // Shared state
+  const deviceManager = new DeviceManager();
+  const refRegistry = new RefRegistry();
+  const metroPort = parseInt(process.env.METRO_PORT || "8081", 10);
+
+  // Create tool handlers
+  const dsHandlers = createDsToolHandlers(devlensConfig.designSystem);
+  const deviceHandlers = createDeviceToolHandlers(deviceManager);
+  const { handlers: snapshotHandlers, resetPreviousSnapshot } =
+    createSnapshotToolHandlers(deviceManager, refRegistry);
+  const interactionHandlers = createInteractionToolHandlers(
+    deviceManager,
+    refRegistry,
+    resetPreviousSnapshot
+  );
+  const screenshotHandlers = createScreenshotToolHandlers(
+    deviceManager,
+    refRegistry
+  );
+  const appHandlers = createAppToolHandlers(deviceManager);
+  const metroHandlers = createMetroToolHandlers(metroPort, deviceManager);
+  const navigationHandlers = createNavigationToolHandlers(
+    deviceManager,
+    refRegistry,
+    resetPreviousSnapshot
+  );
+
+  // Merge all tool schemas
+  const allSchemas: Record<string, { description: string; parameters: any }> = {
+    ...dsToolSchemas,
+    ...deviceToolSchemas,
+    ...snapshotToolSchemas,
+    ...interactionToolSchemas,
+    ...screenshotToolSchemas,
+    ...appToolSchemas,
+    ...metroToolSchemas,
+    ...navigationToolSchemas,
+  };
+
+  // Merge all handlers
+  const allHandlers: Record<string, (params: any) => Promise<any>> = {
+    ...dsHandlers,
+    ...deviceHandlers,
+    ...snapshotHandlers,
+    ...interactionHandlers,
+    ...screenshotHandlers,
+    ...appHandlers,
+    ...metroHandlers,
+    ...navigationHandlers,
+  };
+
+  // Register tools/list handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: Object.entries(allSchemas).map(([name, schema]) => ({
+        name,
+        description: schema.description,
+        inputSchema: zodToJsonSchema(schema.parameters),
+      })),
+    };
+  });
+
+  // Register tools/call handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    const handler = allHandlers[name];
+    if (!handler) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Unknown tool: ${name}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      // Validate params with Zod schema
+      const schema = allSchemas[name];
+      const validatedArgs = schema.parameters.parse(args || {});
+      return await handler(validatedArgs);
+    } catch (error: any) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error: ${error.message || String(error)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // Connect via stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  return server;
+}
+
+/**
+ * Convert a Zod schema to JSON Schema for MCP tool registration.
+ * This is a simplified converter that handles the common cases.
+ */
+function zodToJsonSchema(schema: any): Record<string, any> {
+  // Use Zod's built-in JSON schema support if available
+  if (schema._def) {
+    return convertZodDef(schema._def);
+  }
+  return { type: "object", properties: {} };
+}
+
+function convertZodDef(def: any): Record<string, any> {
+  switch (def.typeName) {
+    case "ZodObject": {
+      const properties: Record<string, any> = {};
+      const required: string[] = [];
+
+      for (const [key, value] of Object.entries(def.shape()) as Array<
+        [string, any]
+      >) {
+        const propDef = value._def;
+        if (propDef.typeName === "ZodOptional" || propDef.typeName === "ZodDefault") {
+          properties[key] = convertZodDef(
+            propDef.typeName === "ZodDefault" ? propDef.innerType._def : propDef.innerType._def
+          );
+        } else {
+          properties[key] = convertZodDef(propDef);
+          required.push(key);
+        }
+        // Add description from Zod describe()
+        if (propDef.description) {
+          properties[key].description = propDef.description;
+        } else if (value.description) {
+          properties[key].description = value.description;
+        }
+      }
+
+      return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+      };
+    }
+    case "ZodString":
+      return { type: "string", ...(def.description ? { description: def.description } : {}) };
+    case "ZodNumber":
+      return { type: "number", ...(def.description ? { description: def.description } : {}) };
+    case "ZodBoolean":
+      return { type: "boolean", ...(def.description ? { description: def.description } : {}) };
+    case "ZodEnum":
+      return { type: "string", enum: def.values, ...(def.description ? { description: def.description } : {}) };
+    case "ZodArray":
+      return {
+        type: "array",
+        items: convertZodDef(def.type._def),
+        ...(def.description ? { description: def.description } : {}),
+      };
+    case "ZodDefault":
+      return {
+        ...convertZodDef(def.innerType._def),
+        default: def.defaultValue(),
+      };
+    case "ZodOptional":
+      return convertZodDef(def.innerType._def);
+    default:
+      return {};
+  }
+}

package/src/snapshot/formatter.ts

@@ -0,0 +1,102 @@
+import type { SnapshotNode } from "../platform/device.js";
+
+/**
+ * Formats a SnapshotNode tree into a YAML-like text representation
+ * that LLMs can easily parse and reason about.
+ *
+ * Output format (inspired by Playwright MCP):
+ *
+ * - FrameLayout
+ *   - LinearLayout
+ *     - TextView "Hello World" [ref=e1]
+ *     - Button "Submit" [ref=e2]
+ *     - EditText "Email" [ref=e3] [focused]
+ *   - RecyclerView [ref=e4]
+ *     - CardView
+ *       - TextView "Item 1" [ref=e5]
+ */
+export function formatSnapshot(
+  root: SnapshotNode,
+  nodeToRef: Map<SnapshotNode, string>
+): string {
+  const lines: string[] = [];
+  formatNode(root, nodeToRef, 0, lines);
+  return lines.join("\n");
+}
+
+function formatNode(
+  node: SnapshotNode,
+  nodeToRef: Map<SnapshotNode, string>,
+  depth: number,
+  lines: string[]
+): void {
+  const indent = "  ".repeat(depth);
+  const parts: string[] = [];
+
+  // Type
+  parts.push(node.type);
+
+  // Text content
+  if (node.text) {
+    parts.push(`"${truncate(node.text, 60)}"`);
+  }
+
+  // Accessibility label (if different from text)
+  if (node.label && node.label !== node.text) {
+    parts.push(`label="${truncate(node.label, 40)}"`);
+  }
+
+  // Annotations
+  const annotations: string[] = [];
+
+  // Ref
+  const ref = nodeToRef.get(node);
+  if (ref) {
+    annotations.push(`ref=${ref}`);
+  }
+
+  // State annotations
+  if (node.focused) annotations.push("focused");
+  if (node.value) annotations.push(`value="${node.value}"`);
+  if (node.enabled === false) annotations.push("disabled");
+  if (node.resourceId) {
+    const shortId = node.resourceId.includes("/")
+      ? node.resourceId.split("/").pop()!
+      : node.resourceId;
+    annotations.push(`id="${shortId}"`);
+  }
+
+  if (annotations.length > 0) {
+    parts.push(`[${annotations.join("] [")}]`);
+  }
+
+  // Build the line
+  const line = `${indent}- ${parts.join(" ")}`;
+
+  // Only include nodes that have refs, text, labels, or children with refs
+  if (ref || node.text || node.label || hasRefInSubtree(node, nodeToRef)) {
+    lines.push(line);
+  }
+
+  // Recurse into children
+  for (const child of node.children) {
+    formatNode(child, nodeToRef, depth + 1, lines);
+  }
+}
+
+/** Check if any descendant has a ref assigned */
+function hasRefInSubtree(
+  node: SnapshotNode,
+  nodeToRef: Map<SnapshotNode, string>
+): boolean {
+  for (const child of node.children) {
+    if (nodeToRef.has(child)) return true;
+    if (hasRefInSubtree(child, nodeToRef)) return true;
+  }
+  return false;
+}
+
+function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}