devlens-mcp 0.3.3 → 0.4.1

package/docs/tool-reference.md

@@ -1,6 +1,6 @@
 # DevLens Tool Reference
 
-Complete reference for all **33** DevLens MCP tools, organized by category.
+Complete reference for all **37** 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,6 +100,8 @@ 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:**
 ```
@@ -434,6 +436,10 @@ 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`.
 
@@ -448,6 +454,54 @@ 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
@@ -583,6 +637,74 @@ On Android: presses system Back button. On iOS: performs back swipe.
 
 ---
 
+## Analysis & VQA Tools
+
+### devlens_analyze
+Smart analysis tool with configurable depth. Respects scope of request — if a user asks for a minimal check, it performs minimal analysis.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `scope` | `"minimal"` \| `"targeted"` \| `"full"` | No | `"full"` | `"minimal"`: quick pixel diff, no layout report. `"targeted"`: compare specific refs only. `"full"`: complete analysis. |
+| `targetRefs` | string[] | No | — | Element refs to focus on (for `"targeted"` scope). E.g., `["e1", "e5"]`. |
+| `referenceImagePath` | string | No | — | Path or URL to reference image. |
+| `referenceImageBase64` | string | No | — | Base64-encoded reference image. |
+| `figmaUrl` | string | No | — | Figma URL for reference. |
+| `threshold` | number | No | `0.1` | Color difference threshold (0-1). |
+
+**Scope behaviors:**
+- **minimal**: Captures screenshot, runs quick pixel diff with perceptual mode and system bar exclusion. Skips layout report. Fast.
+- **targeted**: Takes full snapshot but only inspects the specified refs. Returns bounds and properties for targeted elements.
+- **full**: Complete snapshot + optional layout report + comparison with reference.
+
+---
+
+### devlens_vqa_validate
+Run Visual Quality Assurance validation against a Figma design. Returns structured VQA report with issues and fix suggestions.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `figmaUrl` | string | No | — | Full Figma URL (e.g., `"https://figma.com/design/ABC123/MyApp?node-id=10-200"`). |
+| `fileKey` | string | No | — | Figma file key (use instead of figmaUrl). |
+| `nodeId` | string | No | — | Figma node ID (e.g., `"10:200"`). |
+| `scale` | number | No | `2` | Figma export scale. |
+| `checkCategories` | string[] | No | `["spacing","color","alignment","sizing","missing"]` | VQA categories to check. Options: `spacing`, `color`, `typography`, `alignment`, `missing`, `extra`, `sizing`. |
+| `enableAutoFix` | boolean | No | `true` | Generate fix suggestions for each issue. |
+| `preprocessReference` | boolean | No | `true` | Remove Figma artifacts before comparison. |
+
+**VQA Check Categories:**
+- **spacing**: Verifies margins/paddings between adjacent elements match Figma specs
+- **color**: Extracts dominant colors per region and compares with design reference
+- **alignment**: Checks element center/edge alignment against Figma positions
+- **sizing**: Verifies element dimensions match Figma within tolerance
+- **missing**: Detects regions with very low visual match (possible missing content)
+- **extra**: Detects extra elements on device not in Figma
+- **typography**: Font size/weight checks via accessibility metadata
+
+**VQA Report format:**
+```
+=== VQA Report: PASS/WARNING/FAIL ===
+Overall Score: 94.2%
+Issues: 3 (0 critical, 2 major, 1 minor)
+
+--- Issues ---
+  1. [MAJOR] [spacing] Vertical gap between [e3] and [e5] differs from Figma.
+     Expected: 12px gap
+     Actual:   20px gap (8px off)
+  2. [MAJOR] [color] Color mismatch on [e7]: Significant color mismatch...
+     Expected: #1A73E8
+     Actual:   #2196F3
+  3. [minor] [alignment] Element [e2] is misaligned from Figma position.
+     Expected: center (215, 120)
+     Actual:   center (218, 122) — off by (3, 2)px
+
+--- Suggested Fixes ---
+  1. [high] Adjust margin/padding on element [e3] to match Figma specs: 12px gap.
+  2. [high] Update color value for [e7]. Expected: #1A73E8. Check design token mapping.
+  3. [medium] Fix alignment of [e2]. Adjust flex alignment or positioning.
+```
+
+---
+
 ## Quick Reference Table
 
 | # | Tool | Category | Key Params |
@@ -594,7 +716,7 @@ On Android: presses system Back button. On iOS: performs back swipe.
 | 5 | `devlens_terminate_app` | App | appId |
 | 6 | `devlens_install_app` | App | path |
 | 7 | `devlens_list_apps` | App | — |
-| 8 | `devlens_snapshot` | Snapshot | mode?, validate? |
+| 8 | `devlens_snapshot` | Snapshot | mode?, validate?, scope?, componentRef? |
 | 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? |
@@ -611,12 +733,16 @@ On Android: presses system Back button. On iOS: performs back swipe.
 | 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 | — |
+| 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? |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlens-mcp",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "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",

package/tsconfig.json

@@ -16,5 +16,5 @@
     "sourceMap": true
   },
   "include": ["src/**/*", "bin/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
+  "exclude": ["node_modules", "dist", "tests", "src/jds-tokens"]
 }

package/INSTALLATION_GUIDE.md

@@ -1,3 +0,0 @@
-# Installation Guide
-
-This file has moved. See **[docs/setup-guide.md](./docs/setup-guide.md)** for all installation, configuration, and troubleshooting instructions.

package/QUICK_START.md

@@ -1,3 +0,0 @@
-# Quick Start
-
-This file has moved. See **[docs/setup-guide.md](./docs/setup-guide.md)** for all installation, configuration, and troubleshooting instructions.