devlens-mcp 0.3.0 → 0.3.1

package/src/server.ts

@@ -1,228 +0,0 @@
-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

@@ -1,102 +0,0 @@
-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) + "...";
-}

package/src/snapshot/ref-registry.ts

@@ -1,230 +0,0 @@
-import type { SnapshotNode, Bounds } from "../platform/device.js";
-
-/**
- * RefRegistry — the Playwright-style ref assignment system.
- *
- * Assigns monotonically increasing refs (e1, e2, ...) to every interactive
- * or meaningful node in the accessibility tree. Maintains a map from ref
- * to node info (bounds, center coords) so interaction tools can resolve
- * "tap ref=e5" to actual screen coordinates.
- */
-
-export interface RefEntry {
-  ref: string;
-  node: SnapshotNode;
-  centerX: number;
-  centerY: number;
-  bounds: Bounds;
-}
-
-export interface ValidationIssue {
-  type: "zero-size" | "invisible" | "empty-container";
-  nodeType: string;
-  text?: string;
-  label?: string;
-  resourceId?: string;
-  bounds: Bounds;
-  detail: string;
-}
-
-export interface ValidationReport {
-  issues: ValidationIssue[];
-  totalNodes: number;
-  visibleNodes: number;
-  zeroSizeNodes: number;
-  interactiveNodes: number;
-}
-
-export class RefRegistry {
-  private refMap: Map<string, RefEntry> = new Map();
-  private counter: number = 0;
-
-  /** Clear all refs and reset counter (call before each new snapshot) */
-  reset(): void {
-    this.refMap.clear();
-    this.counter = 0;
-  }
-
-  /**
-   * Walk the snapshot tree and assign refs to all interactive or content-bearing nodes.
-   * Returns a new tree with refs attached (as annotations in the formatter output).
-   */
-  assignRefs(root: SnapshotNode): Map<SnapshotNode, string> {
-    this.reset();
-    const nodeToRef = new Map<SnapshotNode, string>();
-    this.walkAndAssign(root, nodeToRef);
-    return nodeToRef;
-  }
-
-  private walkAndAssign(
-    node: SnapshotNode,
-    nodeToRef: Map<SnapshotNode, string>
-  ): void {
-    if (this.shouldAssignRef(node)) {
-      const ref = `e${++this.counter}`;
-      const centerX = node.bounds.x + node.bounds.width / 2;
-      const centerY = node.bounds.y + node.bounds.height / 2;
-
-      this.refMap.set(ref, {
-        ref,
-        node,
-        centerX,
-        centerY,
-        bounds: node.bounds,
-      });
-      nodeToRef.set(node, ref);
-    }
-
-    for (const child of node.children) {
-      this.walkAndAssign(child, nodeToRef);
-    }
-  }
-
-  /** Determine if a node should get a ref */
-  private shouldAssignRef(node: SnapshotNode): boolean {
-    // Skip invisible/zero-size elements
-    if (node.bounds.width === 0 || node.bounds.height === 0) return false;
-
-    // Always assign refs to interactive elements
-    if (node.interactive) return true;
-
-    // Assign refs to elements with meaningful text content
-    if (node.text && node.text.trim().length > 0) return true;
-
-    // Assign refs to elements with accessibility labels
-    if (node.label && node.label.trim().length > 0) return true;
-
-    // Skip purely structural containers
-    return false;
-  }
-
-  /** Resolve a ref string to its entry (coordinates + node info) */
-  resolve(ref: string): RefEntry | undefined {
-    return this.refMap.get(ref);
-  }
-
-  /** Get all current ref entries */
-  getAllRefs(): RefEntry[] {
-    return Array.from(this.refMap.values());
-  }
-
-  /** Get the total number of assigned refs */
-  get size(): number {
-    return this.refMap.size;
-  }
-
-  /**
-   * Validate the snapshot tree for visibility issues.
-   * Flags zero-size elements that should be visible, explicitly invisible elements,
-   * and empty containers that might indicate missing content.
-   */
-  validateTree(root: SnapshotNode): ValidationReport {
-    const issues: ValidationIssue[] = [];
-    let totalNodes = 0;
-    let visibleNodes = 0;
-    let interactiveNodes = 0;
-    let zeroSizeNodes = 0;
-
-    const walk = (node: SnapshotNode): void => {
-      totalNodes++;
-
-      const isZeroSize =
-        node.bounds.width === 0 || node.bounds.height === 0;
-
-      if (isZeroSize) {
-        zeroSizeNodes++;
-        // Only flag if the node has content that SHOULD be visible
-        if (node.text || node.label || node.interactive) {
-          issues.push({
-            type: "zero-size",
-            nodeType: node.type,
-            text: node.text,
-            label: node.label,
-            resourceId: node.resourceId,
-            bounds: node.bounds,
-            detail:
-              `${node.type}${node.text ? ` "${node.text}"` : ""}${node.label ? ` label="${node.label}"` : ""}` +
-              ` has zero size (${node.bounds.width}x${node.bounds.height}) — renders as invisible`,
-          });
-        }
-      } else {
-        visibleNodes++;
-      }
-
-      if (node.visible === false) {
-        issues.push({
-          type: "invisible",
-          nodeType: node.type,
-          text: node.text,
-          label: node.label,
-          resourceId: node.resourceId,
-          bounds: node.bounds,
-          detail:
-            `${node.type}${node.text ? ` "${node.text}"` : ""} has visible=false`,
-        });
-      }
-
-      if (node.interactive) interactiveNodes++;
-
-      // Empty container with a resource ID — likely an intentional component
-      // that should have content (e.g., missing icon, empty image)
-      if (
-        node.children.length === 0 &&
-        node.resourceId &&
-        !node.text &&
-        !node.label &&
-        !isZeroSize
-      ) {
-        issues.push({
-          type: "empty-container",
-          nodeType: node.type,
-          resourceId: node.resourceId,
-          bounds: node.bounds,
-          detail:
-            `${node.type} id="${node.resourceId}" is an empty container (no children, no text) — may be a missing icon or placeholder`,
-        });
-      }
-
-      for (const child of node.children) {
-        walk(child);
-      }
-    };
-
-    walk(root);
-    return { issues, totalNodes, visibleNodes, zeroSizeNodes, interactiveNodes };
-  }
-
-  /**
-   * Search the full snapshot tree (including zero-size nodes) for text/label matches.
-   * Used by find_element to detect invisible elements that the refMap skips.
-   */
-  findInTree(
-    root: SnapshotNode,
-    query: { text?: string; label?: string }
-  ): SnapshotNode[] {
-    const matches: SnapshotNode[] = [];
-    const walk = (node: SnapshotNode): void => {
-      const isZeroSize =
-        node.bounds.width === 0 || node.bounds.height === 0;
-      if (isZeroSize) {
-        let matched = false;
-        if (query.text && node.text) {
-          matched = node.text
-            .toLowerCase()
-            .includes(query.text.toLowerCase());
-        }
-        if (query.label && node.label) {
-          matched =
-            matched ||
-            node.label.toLowerCase().includes(query.label.toLowerCase());
-        }
-        if (matched) matches.push(node);
-      }
-      for (const child of node.children) {
-        walk(child);
-      }
-    };
-    walk(root);
-    return matches;
-  }
-}