devlens-mcp 0.3.0

package/docs/tool-reference.md

@@ -0,0 +1,622 @@
+# DevLens Tool Reference
+
+Complete reference for all **33** DevLens MCP tools, organized by category.
+
+> **Tip:** Use `devlens_metro_status` at the start of every session to verify Metro is healthy before invoking Metro-dependent tools.
+
+---
+
+## Device Management (3)
+
+### devlens_list_devices
+List all running iOS Simulators and Android Emulators.
+
+**Parameters:** None
+
+**Returns:** Device IDs, names, platforms, OS versions, and boot status.
+
+**Example response:**
+```
+Found 2 device(s):
+
+● Pixel 7 (android, 14) — id: emulator-5554
+● iPhone 16 (ios, 18.0) — id: ABCD-1234-EFGH
+```
+
+---
+
+### devlens_device_info
+Get detailed information about a device.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `deviceId` | string | No | Device ID. Uses first available if omitted. |
+
+**Example response:**
+```
+Device: Pixel 7
+Platform: android
+OS Version: 14
+Screen: 1080x2400
+Orientation: portrait
+ID: emulator-5554
+```
+
+---
+
+### devlens_set_orientation
+Set device orientation.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `orientation` | "portrait" \| "landscape" | Yes | Target orientation |
+
+---
+
+## App Management (4)
+
+### devlens_launch_app
+Launch an installed app.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appId` | string | Yes | Bundle ID (iOS) or package name (Android) |
+
+**Example:** `devlens_launch_app(appId: "com.example.myapp")`
+
+---
+
+### devlens_terminate_app
+Force stop a running app.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appId` | string | Yes | Bundle ID or package name |
+
+---
+
+### devlens_install_app
+Install an app from local file.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `path` | string | Yes | Path to .apk (Android) or .app/.ipa (iOS) |
+
+---
+
+### devlens_list_apps
+List all installed third-party apps.
+
+**Parameters:** None
+
+---
+
+## Snapshot & Elements (5)
+
+### devlens_snapshot
+**The core tool.** Captures the accessibility tree with Playwright-style ref IDs.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `mode` | "full" \| "incremental" | No | "full" (default) returns entire tree. "incremental" returns only changes since last snapshot. |
+| `validate` | boolean | No | When `true`, appends a **Validation Report** that flags zero-size elements, invisible nodes, and empty containers. Default: `false`. |
+
+**Example response:**
+```
+- FrameLayout
+  - LinearLayout
+    - ImageView "Logo" [ref=e1]
+    - TextView "Welcome to MyApp" [ref=e2]
+    - EditText "Email" [ref=e3] [focused] [id="email_input"]
+    - EditText "Password" [ref=e4] [id="password_input"]
+    - Button "Sign In" [ref=e5]
+    - TextView "Forgot Password?" [ref=e6]
+  - BottomNavigationView
+    - MenuItem "Home" [ref=e7]
+    - MenuItem "Profile" [ref=e8]
+
+8 elements with refs assigned.
+```
+
+**With `validate: true`:**
+```
+...tree output...
+
+=== Validation Report ===
+Total: 42 nodes | Visible: 38 | Zero-size: 4 | Interactive: 12
+
+⚠ Issues found:
+• ImageView "BrandLogo" has zero size (0x0) — renders as invisible
+• View id="divider_line" is an empty container (no children, no text)
+```
+
+Use the `ref=eN` values with interaction tools (`devlens_tap`, `devlens_type`, etc.).
+
+---
+
+### devlens_find_element
+Find elements matching text, accessibility label, or element type.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `text` | string | No | Text content to search (partial match) |
+| `label` | string | No | Accessibility label to search (partial match) |
+| `type` | string | No | Element type to search (partial, case-insensitive). E.g., "Button", "ScrollView", "EditText" |
+
+At least one of `text`, `label`, or `type` must be provided. When `type` is combined with `text`/`label`, elements must match the type AND one of text/label.
+
+**Invisible element detection:** If no visible matches are found, DevLens also searches zero-size (invisible) nodes. If a match is found there, a warning is returned:
+
+```
+No visible elements found for "BrandLogo", but found 1 invisible match:
+⚠ ImageView "BrandLogo" exists but has zero size (0x0) — it renders as invisible.
+  This usually means the image source is missing, the style sets width/height to 0,
+  or a parent container is collapsing.
+```
+
+---
+
+### devlens_wait_for_element
+Wait for an element to appear on screen.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `text` | string | No | Text to wait for |
+| `label` | string | No | Label to wait for |
+| `timeout` | number | No | Max wait in ms (default: 10000) |
+
+---
+
+### devlens_wait_for_screen
+Wait for the screen to stabilize or for specific content to appear. **Replaces manual sleep+screenshot loops.**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `text` | string | No | Wait until this text appears on screen |
+| `label` | string | No | Wait until this label appears on screen |
+| `stableMs` | number | No | Stability window in ms — screen must remain unchanged for this duration (default: 1000) |
+| `timeoutMs` | number | No | Max wait time in ms (default: 10000) |
+
+**Two modes:**
+
+1. **Content mode** (when `text` or `label` is provided): Polls every 500ms until the specified text/label appears in the snapshot.
+2. **Stability mode** (when neither is provided): Takes periodic snapshots and waits until the screen stops changing (no diff for `stableMs` milliseconds).
+
+**Returns:** The current snapshot with ref IDs on success. Returns `isError: true` with the latest snapshot on timeout.
+
+**Example usage:**
+```
+# Wait for a specific screen after navigation
+devlens_wait_for_screen(text: "Welcome Back")
+
+# Wait for screen to stop animating/loading
+devlens_wait_for_screen(stableMs: 2000)
+```
+
+---
+
+### devlens_element_info
+Get detailed info about an element by ref, including **inferred layout direction**.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ref` | string | Yes | Element ref (e.g., "e5") |
+
+**Response includes:**
+- Element type, text, label, resource ID
+- Bounds (x, y, width, height)
+- Interactive status, focused status, visibility
+- Children count
+- **Inferred Layout** (for containers with children): `row`, `column`, `stacked`, `wrap`, or `unknown`
+
+**Example response (container):**
+```
+Element [e3]: LinearLayout
+  Bounds: 0,200 1080x400
+  Interactive: false
+  Children: 4
+  Inferred Layout: row (children arranged left-to-right)
+    1. ImageView "icon" — x:12, y:210
+    2. TextView "Title" — x:60, y:210
+    3. TextView "Subtitle" — x:400, y:210
+    4. Button "Action" — x:800, y:210
+```
+
+---
+
+## Interaction (8)
+
+### devlens_tap
+Tap an element. Like Playwright's `browser_click`.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ref` | string | Yes | Element ref from devlens_snapshot |
+| `element` | string | Yes | Human description (e.g., "Submit button") |
+
+Returns updated snapshot after tap.
+
+---
+
+### devlens_type
+Type text into an input.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ref` | string | Yes | Input element ref |
+| `text` | string | Yes | Text to type |
+| `submit` | boolean | No | Press Enter after typing (default: false) |
+
+Automatically taps the element to focus it first.
+
+---
+
+### devlens_swipe
+Swipe gesture.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `direction` | "up" \| "down" \| "left" \| "right" | Yes | Direction |
+| `ref` | string | No | Swipe from this element's center |
+| `distance` | number | No | Distance in pixels (default: 500) |
+
+---
+
+### devlens_scroll
+Scroll a scrollable container.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ref` | string | Yes | Scrollable container ref |
+| `direction` | "up" \| "down" | Yes | Scroll direction |
+
+---
+
+### devlens_long_press
+Long press an element.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ref` | string | Yes | Element ref |
+| `duration` | number | No | Duration in ms (default: 1000) |
+
+---
+
+### devlens_press_button
+Press a hardware/system button.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `button` | "home" \| "back" \| "enter" | Yes | Button to press |
+
+---
+
+### devlens_fill_form
+Fill multiple form fields at once.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fields` | Array<{ref, value}> | Yes | Fields to fill |
+
+**Example:**
+```json
+{
+  "fields": [
+    { "ref": "e3", "value": "user@example.com" },
+    { "ref": "e4", "value": "password123" }
+  ]
+}
+```
+
+---
+
+### devlens_capture_flow
+Execute a sequence of actions and capture labeled screenshots. Batch-verify multiple screens in a single call.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `steps` | Array | Yes | Sequence of step objects |
+
+**Step object:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | "tap" \| "screenshot" \| "go_back" \| "swipe" \| "wait" \| "press_button" | Yes | Action to perform |
+| `ref` | string | No | Element ref for tap/swipe |
+| `element` | string | No | Human description for tap |
+| `label` | string | No | Label for screenshot steps |
+| `direction` | "up" \| "down" \| "left" \| "right" | No | Direction for swipe |
+| `button` | "home" \| "back" \| "enter" | No | Button for press_button |
+| `ms` | number | No | Wait duration in ms (default: 1000) |
+
+**Example — verify 3 tabs:**
+```json
+{
+  "steps": [
+    { "action": "tap", "ref": "e5", "element": "Chats tab" },
+    { "action": "screenshot", "label": "chats-screen" },
+    { "action": "tap", "ref": "e6", "element": "Tools tab" },
+    { "action": "screenshot", "label": "tools-screen" },
+    { "action": "tap", "ref": "e7", "element": "Media tab" },
+    { "action": "screenshot", "label": "media-screen" }
+  ]
+}
+```
+
+Returns all labeled screenshots + a final snapshot with refs.
+
+---
+
+## Screenshots & Visual Comparison (5)
+
+### devlens_screenshot
+Take a screenshot of the current screen.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `filename` | string | No | Save path (defaults to /tmp/devlens-screenshot-{timestamp}.png) |
+
+Returns base64-encoded image + saved file path.
+
+---
+
+### devlens_compare_screenshot
+Compare current screen against a reference image from a file path, HTTP URL, or base64 data. Supports region cropping.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `referenceImagePath` | string | No | Path to reference PNG, or an HTTP/HTTPS URL to fetch it from |
+| `referenceImageBase64` | string | No | Base64-encoded PNG data (without `data:` prefix) |
+| `threshold` | number | No | Color threshold 0-1 (default: 0.1, lower = stricter) |
+| `resizeStrategy` | "fit" \| "scale" \| "crop" | No | How to handle dimension mismatches (default: "fit") |
+| `cropRef` | string | No | Crop device screenshot to this element's bounds before comparing |
+| `region` | {x, y, width, height} | No | Crop device screenshot to this pixel region before comparing |
+
+> At least one of `referenceImagePath` or `referenceImageBase64` must be provided.
+
+**Resize strategies:**
+- **`fit`** (default) — Resize both images to the smaller dimensions. Best for general comparison.
+- **`scale`** — Resize the smaller image up to match the larger. Use when the reference is lower resolution.
+- **`crop`** — Extract the overlapping region from both images. Use when comparing a section of the screen.
+
+**Returns:**
+- `similarity`: 0.0 to 1.0 (percentage match)
+- `diffPixels`: Number of different pixels
+- `diffImagePath`: Path to diff image (red highlights = differences)
+- `summary`: Human-readable assessment
+- Both the current screenshot and diff image as base64
+
+**Example — compare just a component:**
+```
+devlens_snapshot()  # get refs
+devlens_compare_screenshot(
+  referenceImagePath: "./design-refs/header.png",
+  cropRef: "e3"  # only compare the header element
+)
+```
+
+---
+
+### devlens_element_screenshot
+Screenshot a specific element.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ref` | string | Yes | Element ref |
+| `filename` | string | No | Save path |
+
+---
+
+### devlens_compare_images
+Compare two saved images (A/B comparison). Useful for before/after screenshots.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `imageA` | string | Yes | Path or HTTP URL of the first image |
+| `imageB` | string | Yes | Path or HTTP URL of the second image |
+| `threshold` | number | No | Color threshold 0-1 (default: 0.1) |
+| `resizeStrategy` | "fit" \| "scale" \| "crop" | No | Dimension mismatch handling (default: "fit") |
+
+Returns similarity score, diff pixel count, and diff image (same format as `devlens_compare_screenshot`).
+
+---
+
+### devlens_compare_with_figma
+**The Figma verification tool.** Compare the device screen directly against a Figma design. Fetches the Figma frame via REST API and runs pixel comparison. Requires `FIGMA_TOKEN` environment variable.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `figmaUrl` | string | No | Full Figma URL (e.g., `https://figma.com/design/ABC/MyApp?node-id=10-200`) |
+| `fileKey` | string | No | Figma file key (alternative to figmaUrl) |
+| `nodeId` | string | No | Figma node ID e.g., "10:200" (use with fileKey) |
+| `scale` | number | No | Export scale (default: 2) |
+| `threshold` | number | No | Color threshold 0-1 (default: 0.1) |
+| `resizeStrategy` | "fit" \| "scale" \| "crop" | No | Dimension mismatch handling (default: "fit") |
+| `cropRef` | string | No | Crop device screenshot to element bounds |
+| `region` | {x, y, width, height} | No | Crop device screenshot to pixel region |
+
+> Provide either `figmaUrl`, or both `fileKey` and `nodeId`.
+
+**Example:**
+```
+devlens_compare_with_figma(
+  figmaUrl: "https://figma.com/design/ABC123/MyApp?node-id=10-200"
+)
+→ Similarity: 94.2%
+→ Diff image highlighting mismatches
+```
+
+---
+
+## React Native / Metro (6)
+
+### devlens_metro_status
+**Health check tool.** Check if the Metro bundler is running and healthy. Call this at the start of every session and before any Metro-dependent operation.
+
+**Parameters:** None
+
+**Returns:** Metro health report including running status, port, packager status, and CDP connection state.
+
+**Example responses:**
+
+When Metro is running:
+```
+Metro Bundler Status:
+  Running: true
+  Port: 8081
+  Packager: packager-status:running
+  CDP Connected: false
+
+Metro is healthy. You can use hot reload and other Metro tools.
+```
+
+When Metro is down:
+```
+Metro Bundler Status:
+  Running: false
+  Port: 8081
+  Packager: —
+  CDP Connected: false
+  Error: Cannot reach Metro on port 8081: fetch failed
+
+Metro is NOT running. Start it with:
+  cd your-project && npx react-native start
+```
+
+---
+
+### devlens_metro_logs
+Get console output from the React Native app.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `level` | "error" \| "warn" \| "info" \| "debug" | No | Minimum log level |
+| `since` | string | No | ISO timestamp — only show logs after this time |
+
+**Example response:**
+```
+Metro logs (5 entries):
+
+[14:32:01.123] LOG   User navigated to HomeScreen
+[14:32:02.456] LOG   API call: GET /api/products
+[14:32:03.789] WARN  Image component has no alt text
+[14:32:04.012] ERROR Network request failed: timeout
+[14:32:05.345] LOG   Rendered 24 products
+```
+
+---
+
+### devlens_component_tree
+Get the React component hierarchy.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `depth` | number | No | Max tree depth (default: 10) |
+
+Shows component names, props, and nesting. Requires `__DEV__` mode.
+
+---
+
+### devlens_hot_reload
+Trigger a hot reload / fast refresh.
+
+**Parameters:** None
+
+Call this after modifying React Native source files. Waits 1.5s for the reload to take effect.
+
+---
+
+### devlens_network_requests
+List network requests made by the app.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `urlPattern` | string | No | Filter by URL substring |
+
+**Example response:**
+```
+Network requests (3 total):
+
+GET 200 145ms 12.3KB https://api.example.com/products
+POST 201 89ms 0.5KB https://api.example.com/cart
+GET 404 23ms 0.1KB https://api.example.com/user/avatar
+```
+
+---
+
+### devlens_dismiss_overlays
+Dismiss React Native debug overlays (LogBox warnings, dev menu banners) that interfere with screenshots.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `suppressLogBox` | boolean | No | Suppress LogBox via JavaScript injection (default: true) |
+| `pressBack` | boolean | No | Press Back button to close modal overlays (default: false) |
+
+**Example:**
+```
+devlens_dismiss_overlays()
+→ LogBox suppressed; LogBox uninstalled
+
+devlens_dismiss_overlays(pressBack: true)
+→ LogBox suppressed; Back button pressed (dismiss modal overlay)
+```
+
+---
+
+## Navigation (2)
+
+### devlens_open_url
+Open a URL or deep link.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `url` | string | Yes | URL or deep link (e.g., "myapp://profile") |
+
+---
+
+### devlens_go_back
+Navigate back.
+
+**Parameters:** None
+
+On Android: presses system Back button. On iOS: performs back swipe.
+
+---
+
+## Quick Reference Table
+
+| # | Tool | Category | Key Params |
+|---|------|----------|------------|
+| 1 | `devlens_list_devices` | Device | — |
+| 2 | `devlens_device_info` | Device | deviceId? |
+| 3 | `devlens_set_orientation` | Device | orientation |
+| 4 | `devlens_launch_app` | App | appId |
+| 5 | `devlens_terminate_app` | App | appId |
+| 6 | `devlens_install_app` | App | path |
+| 7 | `devlens_list_apps` | App | — |
+| 8 | `devlens_snapshot` | Snapshot | mode?, validate? |
+| 9 | `devlens_find_element` | Snapshot | text?, label?, type? |
+| 10 | `devlens_wait_for_element` | Snapshot | text?, label?, timeout? |
+| 11 | `devlens_wait_for_screen` | Snapshot | text?, label?, stableMs?, timeoutMs? |
+| 12 | `devlens_element_info` | Snapshot | ref |
+| 13 | `devlens_tap` | Interaction | ref, element |
+| 14 | `devlens_type` | Interaction | ref, text, submit? |
+| 15 | `devlens_swipe` | Interaction | direction, ref?, distance? |
+| 16 | `devlens_scroll` | Interaction | ref, direction |
+| 17 | `devlens_long_press` | Interaction | ref, duration? |
+| 18 | `devlens_press_button` | Interaction | button |
+| 19 | `devlens_fill_form` | Interaction | fields |
+| 20 | `devlens_capture_flow` | Interaction | steps |
+| 21 | `devlens_screenshot` | Visual | filename? |
+| 22 | `devlens_compare_screenshot` | Visual | referenceImagePath?, referenceImageBase64?, cropRef?, region? |
+| 23 | `devlens_element_screenshot` | Visual | ref, filename? |
+| 24 | `devlens_compare_images` | Visual | imageA, imageB, threshold?, resizeStrategy? |
+| 25 | `devlens_compare_with_figma` | Visual | figmaUrl?, fileKey?, nodeId?, cropRef?, region? |
+| 26 | `devlens_metro_status` | Metro | — |
+| 27 | `devlens_metro_logs` | Metro | level?, since? |
+| 28 | `devlens_component_tree` | Metro | depth? |
+| 29 | `devlens_hot_reload` | Metro | — |
+| 30 | `devlens_network_requests` | Metro | urlPattern? |
+| 31 | `devlens_dismiss_overlays` | Metro | suppressLogBox?, pressBack? |
+| 32 | `devlens_open_url` | Navigation | url |
+| 33 | `devlens_go_back` | Navigation | — |

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "devlens-mcp",
+  "version": "0.3.0",
+  "description": "DevLens — Playwright-style MCP server for mobile development. Take screenshots, compare with Figma designs, interact with iOS Simulators & Android Emulators, and access Metro bundler logs.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "devlens-mcp": "dist/bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "node dist/bin/register.js",
+    "dev": "tsc --watch",
+    "start": "node dist/bin/cli.js",
+    "register": "node dist/bin/register.js --register",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mobile",
+    "react-native",
+    "playwright",
+    "automation",
+    "ios",
+    "android",
+    "emulator",
+    "simulator",
+    "figma",
+    "devtools",
+    "testing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "fast-xml-parser": "^4.5.0",
+    "pixelmatch": "^5.3.0",
+    "pngjs": "^7.0.0",
+    "sharp": "^0.33.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}