DevLens

Playwright-style MCP server for React Native mobile development

DevLens gives AI agents the ability to see, interact with, and verify your mobile app running on a simulator or emulator. It bridges the gap between "AI writes code" and "AI confirms the code works" — enabling a fully automated design-to-code-to-verification loop.

Figma Design  ──►  AI Agent  ──►  Code Changes  ──►  Hot Reload  ──►  Screenshot  ──►  Compare
                       ▲                                                                   │
                       └───────────────── Fix & repeat until > 95% match ──────────────────┘

Quick Start

Claude Code

claude mcp add devlens -- npx devlens-mcp@latest

Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "devlens": {
      "command": "npx",
      "args": ["devlens-mcp@latest"],
      "env": {
        "METRO_PORT": "8081",
        "FIGMA_TOKEN": "figd_xxxxx"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "devlens": {
      "command": "npx",
      "args": ["devlens-mcp@latest"],
      "env": {
        "METRO_PORT": "8081",
        "FIGMA_TOKEN": "figd_xxxxx"
      }
    }
  }
}

Restart your AI client after editing the config.

What Problems Does It Solve?

Without DevLens, AI agents resort to manual, error-prone workflows:

| Without DevLens (Manual) | With DevLens | |---|---| | adb exec-out screencap -p > /tmp/screenshot.png | devlens_screenshot | | adb shell input tap 100 180 (coordinate guessing) | devlens_tap(ref: "e5") (element refs) | | Visually comparing screenshot to Figma export | devlens_compare_with_figma(figmaUrl: "...") | | adb shell am force-stop + am start | devlens_terminate_app + devlens_launch_app | | curl http://localhost:8081/status | devlens_metro_status | | Multiple manual reload attempts | devlens_hot_reload | | Guessing if an element rendered | devlens_find_element + devlens_snapshot(validate: true) | | sleep 3 && adb screencap loops | devlens_wait_for_screen | | Grep-reading token files and component interfaces | devlens_ds_context |

New in v0.3.1

• Layout-Aware Comparison — devlens_compare_with_figma now reports per-element similarity scores using the accessibility tree. Instead of a single misleading global pixel-diff number, you get "Header: 94%, ChatInput: 61%, ToolsGrid: 44% ← investigate". Set layoutReport: false to disable.
• Design System Context — new devlens_ds_context tool reads your design token file, component interfaces, and scans actual usage patterns in .tsx files. AI agents use this to write correct DS-compliant code instead of guessing token names.
• Moved/Resized Element Detection — incremental snapshot diffs now distinguish elements that moved from elements that were removed and re-added:

  MOVED:
    -> Button "Sign In" moved by (+0, +16)px
  RESIZED:
    <> LinearLayout 1080x200 → 1080x248

• Side-by-Side Comparison Output — devlens_compare_with_figma now returns three images: device screenshot, Figma reference, and pixel diff — so the AI sees both sides simultaneously.

New in v0.3.0

• Direct Figma Comparison — devlens_compare_with_figma fetches a Figma design via REST API and compares against the device in a single call. No more broken base64 piping.
• Debug Overlay Dismissal — devlens_dismiss_overlays suppresses React Native LogBox banners and debug menus that ruin screenshots
• Batch Flow Capture — devlens_capture_flow executes a sequence of actions (tap → screenshot → back) and returns all labeled screenshots in one call
• Region Comparison — devlens_compare_screenshot now accepts cropRef or region to compare a specific element or area instead of the full screen
• Type Filter — devlens_find_element(type: "Button") searches by element type (Button, ScrollView, EditText, etc.)
• Auto-Reset Incremental Snapshots — Navigation actions (tap, swipe, go_back) automatically reset incremental snapshot state
• A/B Image Comparison — devlens_compare_images compares any two saved screenshots (before/after)

Tools (34)

Device Management (3)

| Tool | Description | |------|-------------| | devlens_list_devices | List running simulators/emulators | | devlens_device_info | Screen size, OS version, orientation | | devlens_set_orientation | Set portrait/landscape |

App Management (4)

| Tool | Description | |------|-------------| | devlens_launch_app | Launch app by bundle/package ID | | devlens_terminate_app | Force stop an app | | devlens_install_app | Install .apk/.app/.ipa | | devlens_list_apps | List installed apps |

Snapshot & Elements (5)

| Tool | Description | |------|-------------| | devlens_snapshot | Accessibility tree with ref IDs + optional validation | | devlens_find_element | Find elements by text, label, or type (warns about invisible matches) | | devlens_wait_for_element | Wait for element to appear | | devlens_wait_for_screen | Wait for screen stability or specific content | | devlens_element_info | Detailed info + inferred layout direction |

Interaction (8)

| Tool | Description | |------|-------------| | devlens_tap | Tap element by ref | | devlens_type | Type text into input | | devlens_swipe | Swipe gesture | | devlens_scroll | Scroll a container | | devlens_long_press | Long press element | | devlens_press_button | Home/Back/Enter | | devlens_fill_form | Fill multiple fields at once | | devlens_capture_flow | Batch execute actions + capture labeled screenshots |

Screenshots & Visual (5)

| Tool | Description | |------|-------------| | devlens_screenshot | Take screenshot (base64 + file) | | devlens_compare_screenshot | Compare with reference (file, URL, base64) + cropRef/region support | | devlens_element_screenshot | Screenshot a specific element | | devlens_compare_images | A/B compare two saved screenshots | | devlens_compare_with_figma | Compare device screen against Figma design with per-element layout report |

React Native / Metro (6)

| Tool | Description | |------|-------------| | devlens_metro_status | Check if Metro is running and healthy | | devlens_metro_logs | Console.log/warn/error from Metro | | devlens_component_tree | React component hierarchy | | devlens_hot_reload | Trigger fast refresh | | devlens_network_requests | Fetch/XHR requests from the app | | devlens_dismiss_overlays | Dismiss React Native debug banners and LogBox |

Navigation (2)

| Tool | Description | |------|-------------| | devlens_open_url | Open URL / deep link | | devlens_go_back | Navigate back |

Design System (1)

| Tool | Description | |------|-------------| | devlens_ds_context | Load design tokens, component interfaces, and usage patterns from your codebase |

The Figma Verification Workflow

DevLens integrates with Figma to create an automated design verification loop:

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Figma   │────►│   AI     │────►│  Code    │────►│  Device  │
│  Design  │     │  Agent   │     │  Editor  │     │  Screen  │
└──────────┘     └──────┬───┘     └──────────┘     └────┬─────┘
                        │                                │
                        │◄─── devlens_compare ───────────┘
                        │     (similarity < 95%?)
                        │              │
                        ▼              ▼
                   Fix Code ◄─── Layout Report
                                (per-element scores)

Step-by-step:

1. Check Metro — devlens_metro_status to verify Metro is healthy
2. Dismiss overlays — devlens_dismiss_overlays to remove debug banners
3. Load DS context — devlens_ds_context so the AI knows token names and component props
4. Generate code — AI creates/updates the React Native component using correct DS tokens
5. Hot reload — devlens_hot_reload triggers Metro fast refresh
6. Wait for stability — devlens_wait_for_screen waits until UI stops changing
7. Validate elements — devlens_snapshot(validate: true) catches invisible/zero-size elements
8. Compare with Figma — devlens_compare_with_figma(figmaUrl: "...") returns device screenshot, Figma reference, diff image, and per-element layout scores
9. Analyze diff — AI reads which elements are poor/partial and fixes those specifically
10. Fix & repeat — Adjust code until overall similarity > 95%

How It Works

Architecture

AI Agent  ──(MCP JSON-RPC over stdio)──►  DevLens Server  ──(ADB/simctl)──►  Device
                                               │
                                               ├──(CDP WebSocket)──►  Metro Bundler
                                               │
                                               └──(fs/regex)──►  Design System Files

AI Agent  ◄──(accessibility tree + refs)──  DevLens Server  ◄──(UI hierarchy)──  Device

Playwright-style Ref System

Every interactive element gets a unique ref (e1, e2, e3...). Instead of guessing pixel coordinates, AI agents use refs:

- LinearLayout
  - TextView "Welcome to MyApp" [ref=e1]
  - EditText "Email" [ref=e2] [focused]
  - EditText "Password" [ref=e3]
  - Button "Sign In" [ref=e4]

Then: devlens_tap(ref="e4") — no coordinate math, no misses.

Incremental Snapshots

In incremental mode, DevLens only sends what changed since the last snapshot — saving 60-80% tokens in iterative workflows. Elements that move are now tracked as moved, not as a remove+add pair:

[Incremental update]
CHANGED:
  ~ Button "Submit": text: "Submit" → "Save"
ADDED:
  + TextView "Changes saved!"
MOVED:
  -> Button "Sign In" moved by (+0, +16)px
RESIZED:
  <> LinearLayout 1080x200 → 1080x248

Layout-Aware Visual Comparison

devlens_compare_with_figma uses the accessibility tree to compare per UI region instead of the full screen:

• Scales each element's device-space bounds into Figma image space using scaleX = figmaW / screenW
• Crops both images to the scaled region and runs pixelmatch independently per element
• Returns a weighted similarity score per element plus an area-weighted overall score
• Elements with area < 3000px² are skipped (too small for reliable comparison)

Example output:

--- Layout Region Analysis ---
Device: 1080x2400px  |  Figma: 430x932px  |  Scale: 2.51x
Regions: 8 analyzed, 12 too small

  [✓] [e2] "Welcome Back": 94.1%
  [~] [e7] "Sign In" (Button): 83.2%
  [!] [e3] AssistantCards: 61.4%  <- investigate (312 diff pixels)
  [X] [e5] ToolsGrid: 44.2%  <- investigate (1,089 diff pixels)

Overall (area-weighted): 68.7%

Design System Context

devlens_ds_context reads directly from your codebase — no build step, no separate service:

• Tokens — regex-parsed from your token constants file (e.g. FIGMA_COLORS, FIGMA_SPACING)
• Component interfaces — reads generated TypeScript prop types from componentsDir
• Usage patterns — scans .tsx files for <JDS*>, <Icon>, <Chip> with their actual prop values

Configure via devlens.config.json in your app root (see Setup Guide).

Prerequisites

• Node.js >= 18
• Android: Android SDK with adb in PATH (Android Studio)
• iOS (macOS only): Xcode with Command Line Tools
• React Native: Metro bundler running (npx react-native start)

Configuration

| Variable | Default | Description | |----------|---------|-------------| | FIGMA_TOKEN | — | Figma personal access token (required for devlens_compare_with_figma). Needs File content: Read scope. | | DEVLENS_CONFIG | — | Absolute path to devlens.config.json. Enables devlens_ds_context. | | METRO_PORT | 8081 | Metro bundler port | | ANDROID_HOME | auto-detect | Android SDK path | | ANDROID_SDK_ROOT | auto-detect | Alternative to ANDROID_HOME | | DEVICE_ID | first available | Target a specific device |

Platform Support

| Feature | Android Emulator | iOS Simulator | |---------|-----------------|---------------| | Accessibility snapshots | UI Automator | simctl + a11y API | | Screenshots | ADB screencap | simctl screenshot | | Tap/Type/Swipe | ADB input | simctl io | | App management | ADB + pm | simctl | | Metro integration | CDP WebSocket | CDP WebSocket |

Troubleshooting

| Problem | Solution | |---------|----------| | "No running simulators or emulators" | Start a device from Android Studio or Xcode | | "Could not connect to Metro bundler" | Run npx react-native start and check METRO_PORT | | "ADB command not found" | Set ANDROID_HOME or add platform-tools to PATH | | "simctl not found" | Install Xcode Command Line Tools: xcode-select --install | | DevLens tools not available | Run npm run register (local dev) or check MCP config | | "Invalid token" on Figma compare | Use a personal access token (figd_...), not an OAuth token. Required scope: File content: Read. | | "File not exportable" on Figma compare | Disable "Prevent viewers from copying and exporting" in Figma share settings | | devlens_ds_context returns empty | Set DEVLENS_CONFIG env var to your devlens.config.json path | | Comparison similarity always low | Run devlens_snapshot first so layout report has element bounds to work with |

Documentation

• docs/setup-guide.md - Full setup guide: prerequisites, Figma token, design system config
• docs/figma-workflow.md - Figma integration workflow
• docs/tool-reference.md - Detailed tool API reference

Repository

• Azure DevOps: https://dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens

License

MIT