devlens-mcp 0.4.1 → 0.5.2

package/docs/tool-reference.md

@@ -1,6 +1,6 @@
 # DevLens Tool Reference
 
-Complete reference for all **37** DevLens MCP tools, organized by category.
+Complete reference for all **43** 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.
 
@@ -100,8 +100,6 @@ List all installed third-party apps.
 |-------|------|----------|-------------|
 | `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`. |
-| `scope` | "screen" \| "component" | No | "screen" (default) captures full tree. "component" captures only the subtree of `componentRef`. |
-| `componentRef` | string | No | Element ref to scope to (e.g., `"e5"`). Only used when `scope: "component"`. Reduces token usage for targeted checks. |
 
 **Example response:**
 ```
@@ -436,10 +434,6 @@ Returns similarity score, diff pixel count, and diff image (same format as `devl
 | `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 |
-| `layoutReport` | boolean | No | Run per-element layout analysis (default: `true`). Requires `devlens_snapshot` first. |
-| `depth` | "quick" \| "standard" \| "thorough" | No | `"quick"`: skip layout report, loose threshold. `"standard"` (default): normal behavior. `"thorough"`: per-element analysis + property summary. |
-| `excludeSystemBars` | "auto" \| "ios" \| "android" \| "none" | No | Exclude status/nav bar from comparison (default: `"auto"`). |
-| `preprocessReference` | boolean | No | Remove Figma artifacts — rounded corners, backgrounds (default: `true`). |
 
 > Provide either `figmaUrl`, or both `fileKey` and `nodeId`.
 
@@ -454,54 +448,6 @@ devlens_compare_with_figma(
 
 ---
 
-### devlens_compare_properties
-**Per-component property comparison.** Compares ALL measurable design properties (text sizes, colors, spacing, dimensions, layout direction, padding) between a Figma design and the live device. Returns per-component mismatches with exact expected vs actual values.
-
-More detailed than pixel comparison — use after `devlens_compare_with_figma` to catch every property difference. Requires `devlens_snapshot` to have been called first.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `figmaUrl` | string | No | Full Figma URL |
-| `fileKey` | string | No | Figma file key (alternative to figmaUrl) |
-| `nodeId` | string | No | Figma node ID (use with fileKey) |
-| `includeColors` | boolean | No | Extract and compare colors from screenshot (default: `true`) |
-| `tolerances` | object | No | Override defaults: `{ dimensions: 2, fontSize: 0.2, color: 15, spacing: 2 }` |
-
-**Properties compared per component:**
-
-| Property | Source (Figma) | Source (Device) | Tolerance |
-|----------|----------------|-----------------|-----------|
-| Text content | `characters` | accessibility `text` | Exact |
-| Width / Height | `absoluteBoundingBox` | accessibility `bounds` | ±2px |
-| Font size | `style.fontSize` | height × 0.75 estimate | ±20% |
-| Fill color | `fills[0].color` | screenshot sampling | ΔE ≤ 15 |
-| Layout direction | `layoutMode` | inferred from children | Exact |
-| Item spacing | `itemSpacing` | measured child gaps | ±2px |
-| Padding | `padding*` | inferred from bounds | ±2px |
-| Corner radius | `cornerRadius` | — | Info only |
-| Opacity | `opacity` | — | Info only |
-
-**Example output:**
-```
-=== COMPONENT PROPERTY COMPARISON ===
-Compared: 47 properties | Match rate: 78% (37/47)
-
-CRITICAL (2):
-  [e5] Screen > Header > Title
-    fontSize: expected 24px, actual ~33px
-    → Adjust font size from ~33px to 24px
-
-WARNING (3):
-  [e8] Screen > Body > Card
-    width: expected 358px, actual 390px
-    → Adjust width from 390px to 358px
-  [e12] Screen > Footer > TabBar
-    itemSpacing: expected 0px, actual 12px
-    → Adjust item spacing from 12px to 0px
-```
-
----
-
 ## React Native / Metro (6)
 
 ### devlens_metro_status
@@ -705,6 +651,137 @@ Issues: 3 (0 critical, 2 major, 1 minor)
 
 ---
 
+## Prototype Explorer (3)
+
+### `devlens_check_prototype`
+
+Smart prototype detection with bidirectional prompting. Accepts any URL (Figma design, Figma prototype, or web-hosted mock) and returns the type, screen count, and flow summary. Always includes an ACTION NEEDED prompt asking for the complementary link.
+
+**Parameters:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `url` | string | yes | Any URL — Figma design, Figma prototype, or web prototype/mock |
+
+**Bidirectional prompting:**
+- Figma design link given → asks for prototype/mock URL
+- Prototype/mock URL given → asks for Figma design link
+- Having both = near-100% build accuracy
+
+**Example:**
+```
+devlens_check_prototype(url: "https://productprototype.vercel.app")
+→ "Web prototype detected! 12 screens found: /, /memories/, /ai-magic/, ...
+   ACTION NEEDED: Provide the Figma design link for exact specs."
+
+devlens_check_prototype(url: "https://figma.com/design/ABC123/MyApp?node-id=10-200")
+→ "Figma design detected! Prototype connections found (8 screens).
+   ACTION NEEDED: Provide the prototype sharing link."
+```
+
+### `devlens_explore_prototype`
+
+Full browser-based prototype exploration. Opens a headless Chrome browser, navigates through all screens, captures high-res screenshots, and extracts colours, typography, components, and flow connections.
+
+**Parameters:**
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `prototypeUrl` | string | yes | — | Prototype URL (web or Figma /proto/) |
+| `figmaUrl` | string | no | — | Figma design URL for enriched specs |
+| `maxScreens` | number | no | 15 | Max screens to explore |
+| `captureDelay` | number | no | 1500 | Wait ms after each navigation |
+| `viewportWidth` | number | no | 390 | Viewport width (iPhone 14) |
+| `viewportHeight` | number | no | 844 | Viewport height |
+| `scrollCapture` | boolean | no | true | Capture scroll-position screenshots |
+| `extractDesignTokens` | boolean | no | true | Extract colour/typography/spacing |
+
+**Returns:** Flow report with per-screen screenshots (base64), colour palettes, typography, component inventory, flow diagram, and design tokens.
+
+**Example:**
+```
+devlens_explore_prototype(
+  prototypeUrl: "https://productprototype.vercel.app",
+  figmaUrl: "https://figma.com/design/XYZ/JioAICloud?node-id=5-100",
+  maxScreens: 20
+)
+```
+
+### `devlens_prototype_screen`
+
+Deep single-screen analysis for pixel-perfect implementation.
+
+**Parameters:**
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `url` | string | yes | — | URL of the specific screen/route |
+| `figmaUrl` | string | no | — | Figma design URL for exact specs |
+| `viewportWidth` | number | no | 390 | Viewport width |
+| `viewportHeight` | number | no | 844 | Viewport height |
+| `scrollDepth` | number | no | 5000 | How far to scroll (px) |
+
+**Returns:** Element-level detail: bounds, colours, text, nesting, interactive elements, component patterns.
+
+---
+
+## Multi-Device Testing (4)
+
+### devlens_list_profiles
+List available device profiles with screen dimensions and scale factors.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `platform` | string | No | Filter: `"ios"`, `"android"`, or `"all"` (default) |
+
+**Returns:** Table of device profiles: ID, name, platform, screen dimensions, scale factor, and size category.
+
+**Available profiles:**
+- **iOS:** iPhone SE (375x667 @2x), iPhone 15 (393x852 @3x), iPhone 15 Pro Max (430x932 @3x), iPad mini (744x1133 @2x), iPad Pro 13" (1032x1376 @2x)
+- **Android:** Pixel 4a (393x851 @2.75x), Pixel 7 (360x780 @3x), Pixel 7 Pro (412x892 @3.5x), Pixel Tablet (1280x800 @2x)
+
+---
+
+### devlens_boot_device
+Boot a single simulator/emulator by profile ID.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `profile` | string | Yes | Profile ID from `devlens_list_profiles` (e.g., `"iphone-15"`, `"pixel-7"`) |
+
+**Returns:** Device ID and boot confirmation. DevLens-created devices are prefixed with `DevLens-` for easy identification and cleanup.
+
+---
+
+### devlens_multi_capture
+Capture screenshots and snapshots across multiple devices with adaptive batching.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `profiles` | string[] | No | Profile IDs to capture. Defaults to platform's test matrix (small + medium + large). |
+| `platform` | string | No | `"ios"`, `"android"`, or `"both"` (default: `"ios"`) |
+| `includeScreenshots` | boolean | No | Include screenshots (default: true) |
+| `includeSnapshots` | boolean | No | Include accessibility snapshots (default: true) |
+| `shutdownAfter` | boolean | No | Shutdown devices after capture (default: true) |
+
+**Adaptive batching:** Automatically detects system RAM and CPU cores. On 16GB Macs, boots 2-3 iOS simulators per batch with delays between batches. On 32GB+ Macs, boots 4-6 at once. Android emulators use smaller batch sizes due to higher memory usage.
+
+**Returns:** Cross-device report with:
+- Per-device screenshots and snapshots
+- Pixel similarity matrix (every device vs every other)
+- Layout consistency analysis
+- Responsive issue detection (missing elements, alignment drift)
+
+---
+
+### devlens_multi_shutdown
+Shutdown and optionally delete all DevLens-created simulators/emulators.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `deleteCreated` | boolean | No | Also delete DevLens-created simulator/AVD entries (default: false) |
+
+**Returns:** List of devices shut down and/or deleted.
+
+---
+
 ## Quick Reference Table
 
 | # | Tool | Category | Key Params |
@@ -716,7 +793,7 @@ Issues: 3 (0 critical, 2 major, 1 minor)
 | 5 | `devlens_terminate_app` | App | appId |
 | 6 | `devlens_install_app` | App | path |
 | 7 | `devlens_list_apps` | App | — |
-| 8 | `devlens_snapshot` | Snapshot | mode?, validate?, scope?, componentRef? |
+| 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? |
@@ -733,16 +810,22 @@ Issues: 3 (0 critical, 2 major, 1 minor)
 | 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?, depth?, excludeSystemBars? |
-| 26 | `devlens_compare_properties` | Visual | figmaUrl?, fileKey?, nodeId?, includeColors?, tolerances? |
-| 27 | `devlens_metro_status` | Metro | — |
-| 28 | `devlens_metro_logs` | Metro | level?, since? |
-| 29 | `devlens_component_tree` | Metro | depth? |
-| 30 | `devlens_hot_reload` | Metro | — |
-| 31 | `devlens_network_requests` | Metro | urlPattern? |
-| 32 | `devlens_dismiss_overlays` | Metro | suppressLogBox?, pressBack? |
-| 33 | `devlens_open_url` | Navigation | url |
-| 34 | `devlens_go_back` | Navigation | — |
-| 35 | `devlens_ds_context` | Design System | — |
-| 36 | `devlens_analyze` | Analysis | scope, targetRefs?, referenceImagePath?, referenceImageBase64?, figmaUrl?, threshold? |
-| 37 | `devlens_vqa_validate` | VQA | figmaUrl?, fileKey?, nodeId?, scale?, checkCategories?, enableAutoFix?, preprocessReference? |
+| 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 | — |
+| 34 | `devlens_ds_context` | Design System | — |
+| 35 | `devlens_analyze` | Analysis | scope, targetRefs?, referenceImagePath?, referenceImageBase64?, figmaUrl?, threshold? |
+| 36 | `devlens_vqa_validate` | VQA | figmaUrl?, fileKey?, nodeId?, scale?, checkCategories?, enableAutoFix?, preprocessReference? |
+| 37 | `devlens_check_prototype` | Prototype | url |
+| 38 | `devlens_explore_prototype` | Prototype | prototypeUrl, figmaUrl?, maxScreens?, captureDelay?, viewportWidth?, viewportHeight?, scrollCapture?, extractDesignTokens? |
+| 39 | `devlens_prototype_screen` | Prototype | url, figmaUrl?, viewportWidth?, viewportHeight?, scrollDepth? |
+| 40 | `devlens_list_profiles` | Multi-Device | platform? |
+| 41 | `devlens_boot_device` | Multi-Device | profile |
+| 42 | `devlens_multi_capture` | Multi-Device | profiles?, platform?, includeScreenshots?, includeSnapshots?, shutdownAfter? |
+| 43 | `devlens_multi_shutdown` | Multi-Device | deleteCreated? |

package/install.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+#
+# DevLens MCP — One-Command Installer
+#
+# Copy-paste this entire script into your terminal and press Enter.
+# You'll be prompted for your Azure DevOps PAT once, then everything is automatic.
+#
+# What it does:
+#   - Authenticates npm with Azure Artifacts
+#   - Installs devlens-mcp globally
+#   - Configures Cursor IDE
+#   - Verifies everything works
+#
+
+set -e
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo ""
+echo -e "${BLUE}╔══════════════════════════════════════════╗${NC}"
+echo -e "${BLUE}║       DevLens MCP — Quick Installer       ║${NC}"
+echo -e "${BLUE}╚══════════════════════════════════════════╝${NC}"
+echo ""
+
+# Check Node.js
+if ! command -v node &>/dev/null; then
+  echo -e "${RED}✗ Node.js not found. Install from https://nodejs.org${NC}"
+  exit 1
+fi
+
+NODE_VERSION=$(node -v | sed 's/v//')
+NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d. -f1)
+if [ "$NODE_MAJOR" -lt 18 ]; then
+  echo -e "${RED}✗ Node.js $NODE_VERSION — v18+ required${NC}"
+  exit 1
+fi
+echo -e "${GREEN}✓ Node.js $NODE_VERSION${NC}"
+
+# Get PAT
+echo ""
+echo "Create a PAT at: https://dev.azure.com/JioOmni/_usersSettings/tokens"
+echo "Required scope: Packaging → Read"
+echo ""
+read -rsp "Paste your Azure DevOps PAT: " PAT
+echo ""
+
+if [ ${#PAT} -lt 20 ]; then
+  echo -e "${RED}✗ PAT too short${NC}"
+  exit 1
+fi
+
+# Configure npm
+echo ""
+echo "Configuring npm..."
+TOKEN=$(echo -n "$PAT" | base64)
+REGISTRY_KEY="//pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/"
+
+npm config set "${REGISTRY_KEY}:username" "JioOmni" 2>/dev/null
+npm config set "${REGISTRY_KEY}:_password" "$TOKEN" 2>/dev/null
+npm config set "${REGISTRY_KEY}:email" "npm@jio.com" 2>/dev/null
+
+echo -e "${GREEN}✓ npm authenticated${NC}"
+
+# Install DevLens globally
+echo ""
+echo "Installing DevLens..."
+if npm install -g devlens-mcp@latest --registry=https://pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/ 2>&1 | grep -q "devlens-mcp@"; then
+  VERSION=$(devlens-mcp --version 2>/dev/null || echo "installed")
+  echo -e "${GREEN}✓ DevLens $VERSION installed${NC}"
+else
+  echo -e "${RED}✗ Installation failed - check PAT permissions${NC}"
+  exit 1
+fi
+
+# Configure Cursor (global)
+echo ""
+echo "Configuring Cursor..."
+CURSOR_CONFIG="$HOME/.cursor/mcp.json"
+mkdir -p "$HOME/.cursor"
+
+if [ -f "$CURSOR_CONFIG" ]; then
+  EXISTING=$(cat "$CURSOR_CONFIG")
+else
+  EXISTING="{}"
+fi
+
+# Merge DevLens into existing config
+cat > "$CURSOR_CONFIG" << EOF
+$(node -e "
+const config = JSON.parse(process.argv[1] || '{}');
+if (!config.mcpServers) config.mcpServers = {};
+config.mcpServers.devlens = {
+  command: 'devlens-mcp',
+  args: [],
+  env: { METRO_PORT: '8081' }
+};
+console.log(JSON.stringify(config, null, 2));
+" "$EXISTING")
+EOF
+
+echo -e "${GREEN}✓ Cursor configured at $CURSOR_CONFIG${NC}"
+
+# Done
+echo ""
+echo -e "${GREEN}╔══════════════════════════════════════════╗${NC}"
+echo -e "${GREEN}║          Installation Complete!           ║${NC}"
+echo -e "${GREEN}╚══════════════════════════════════════════╝${NC}"
+echo ""
+echo "Next steps:"
+echo "  1. Restart Cursor"
+echo "  2. Open your React Native project"
+echo "  3. Ask the AI: \"List running devices\""
+echo ""
+echo "Verify: devlens-mcp --version"
+echo ""

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "devlens-mcp",
-  "version": "0.4.1",
+  "version": "0.5.2",
   "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"
+    "devlens-mcp": "dist/bin/cli.js",
+    "devlens-setup": "dist/bin/setup.js"
   },
   "scripts": {
     "build": "tsc",
@@ -29,6 +30,7 @@
     "emulator",
     "simulator",
     "figma",
+    "prototype",
     "devtools",
     "testing"
   ],
@@ -42,6 +44,7 @@
     "fast-xml-parser": "^4.5.0",
     "pixelmatch": "^5.3.0",
     "pngjs": "^7.0.0",
+    "puppeteer": "^24.38.0",
     "sharp": "^0.33.0",
     "ws": "^8.18.0",
     "zod": "^3.23.0"