devlens-mcp 0.4.0 → 0.4.1

package/README.md

@@ -100,7 +100,7 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 
 ---
 
-## Tools (36)
+## Tools (37)
 
 ### Device Management (3)
 | Tool | Description |
@@ -138,7 +138,7 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 | `devlens_fill_form` | Fill multiple fields at once |
 | `devlens_capture_flow` | Batch execute actions + capture labeled screenshots |
 
-### Screenshots & Visual (5)
+### Screenshots & Visual (6)
 | Tool | Description |
 |------|-------------|
 | `devlens_screenshot` | Take screenshot (base64 + file) |
@@ -146,6 +146,7 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 | `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 |
+| `devlens_compare_properties` | Compare ALL design properties (text sizes, colors, spacing, dimensions) per component against Figma |
 
 ### React Native / Metro (6)
 | Tool | Description |
@@ -204,9 +205,10 @@ DevLens integrates with Figma to create an automated design verification loop:
 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. **Quick check** — `devlens_compare_with_figma(figmaUrl: "...", depth: "quick")` for fast iteration
-9. **VQA validation** — `devlens_vqa_validate(figmaUrl: "...")` runs full VQA: spacing, colors, alignment, sizing, missing elements
-10. **Fix issues** — AI reads VQA report with per-issue fix suggestions and applies fixes
-11. **Repeat** — Run VQA again until status is `PASS` (zero VQA issues for designers)
+9. **Property comparison** — `devlens_compare_properties(figmaUrl: "...")` for per-component mismatches (font size, color, spacing, dimensions)
+10. **VQA validation** — `devlens_vqa_validate(figmaUrl: "...")` runs full VQA: spacing, colors, alignment, sizing, missing elements
+11. **Fix issues** — AI reads VQA/property reports with fix suggestions and applies fixes
+12. **Repeat** — Run VQA again until status is `PASS` (zero VQA issues for designers)
 
 ---
 

package/RELEASE_NOTES.md

@@ -165,14 +165,15 @@ Four improvements that eliminate the 5% false-positive gap:
 
 ---
 
-## New Tools (2)
+## New Tools (3)
 
 | Tool | Description |
 |------|-------------|
 | `devlens_analyze` | Smart analysis with configurable scope (minimal/targeted/full) |
 | `devlens_vqa_validate` | VQA validator — checks spacing, color, alignment, sizing, missing elements against Figma |
+| `devlens_compare_properties` | Per-component property comparison — text sizes, colors, spacing, dimensions, layout direction with exact expected vs actual values and configurable tolerances |
 
-**Total tools: 36** (up from 34 in v0.3.3)
+**Total tools: 37** (up from 34 in v0.3.3)
 
 ---
 
@@ -188,7 +189,7 @@ Four improvements that eliminate the 5% false-positive gap:
 
 ## Files Changed
 
-### New (6 files)
+### New (9 files)
 | File | Purpose |
 |------|---------|
 | `src/setup/shell-detector.ts` | Shell type & node path detection |
@@ -197,6 +198,9 @@ Four improvements that eliminate the 5% false-positive gap:
 | `src/tools/vqa-tools.ts` | `devlens_vqa_validate` tool |
 | `src/visual/vqa-analyzer.ts` | VQA engine: spacing, sizing, alignment, color, missing checks |
 | `src/visual/color-extractor.ts` | Dominant color extraction & Delta-E comparison |
+| `src/figma/figma-properties.ts` | Extract all comparable design properties from Figma REST API |
+| `src/snapshot/device-properties.ts` | Extract comparable properties from device snapshot + screenshot |
+| `src/visual/property-comparator.ts` | Per-property comparison engine with tolerances and severity |
 
 ### Modified (11 files)
 | File | What changed |

package/docs/figma-workflow.md

@@ -237,12 +237,15 @@ When you use any of the prompts above, the AI agent automatically runs this sequ
 3. devlens_hot_reload                          ← Push changes to device
 4. devlens_wait_for_screen(stableMs: 1500)     ← Wait for render
 5. devlens_snapshot(validate: true)            ← Get element tree + catch invisible bugs
-6. devlens_vqa_validate(                       ← Run VQA
+6. devlens_compare_properties(                 ← Per-component property check
+     figmaUrl: "https://figma.com/design/..."
+   )
+7. devlens_vqa_validate(                       ← Run VQA
      figmaUrl: "https://figma.com/design/...",
      checkCategories: ["spacing", "color", "alignment", "sizing", "missing"]
    )
-7. (AI reads VQA report, applies fix suggestions to code)
-8. Repeat steps 3-7 until VQA status = PASS
+8. (AI reads property + VQA reports, applies fix suggestions to code)
+9. Repeat steps 3-8 until VQA status = PASS
 ```
 
 ---

package/docs/setup-guide.md

@@ -174,7 +174,7 @@ For the full VQA workflow guide with report format details, see [Figma Workflow]
 
 ## Figma Token Setup
 
-Required only for `devlens_compare_with_figma`.
+Required for `devlens_compare_with_figma`, `devlens_compare_properties`, and `devlens_vqa_validate`.
 
 1. Go to [figma.com/settings](https://www.figma.com/settings)
 2. Scroll to **Personal access tokens** → **Generate new token**
@@ -343,7 +343,7 @@ Then restart Cursor. npx will re-download the latest version.
 
 ## What's Available
 
-DevLens provides **36 tools** across 9 categories:
+DevLens provides **37 tools** across 9 categories:
 
 | Category | Tools | Count |
 |----------|-------|-------|
@@ -351,7 +351,7 @@ DevLens provides **36 tools** across 9 categories:
 | App Management | launch_app, terminate_app, install_app, list_apps | 4 |
 | Snapshot & Elements | snapshot, find_element, wait_for_element, wait_for_screen, element_info | 5 |
 | Interaction | tap, type, swipe, scroll, long_press, press_button, fill_form, capture_flow | 8 |
-| Screenshots & Visual | screenshot, compare_screenshot, element_screenshot, compare_images, compare_with_figma | 5 |
+| Screenshots & Visual | screenshot, compare_screenshot, element_screenshot, compare_images, compare_with_figma, compare_properties | 6 |
 | React Native / Metro | metro_status, metro_logs, component_tree, hot_reload, network_requests, dismiss_overlays | 6 |
 | Navigation | open_url, go_back | 2 |
 | Design System | ds_context | 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
@@ -662,7 +716,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? |
+| 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? |
@@ -679,15 +733,16 @@ 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? |
-| 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? |
+| 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.4.0",
+  "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",