devlens-mcp 0.3.2 → 0.4.0

package/docs/setup-guide.md

@@ -1,123 +1,207 @@
 # DevLens Setup Guide
 
-Get DevLens running in under 5 minutes. This guide covers prerequisites, installation, configuration, and verification.
+## 1-Minute Install (Cursor IDE)
 
----
+Add this to `~/.cursor/mcp.json` and restart Cursor:
 
-## Prerequisites
+```json
+{
+  "mcpServers": {
+    "devlens": {
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
+      "env": {
+        "METRO_PORT": "8081"
+      }
+    }
+  }
+}
+```
 
-### For Android Development
-1. **Android Studio** installed with SDK
-2. **Android Emulator** running (start one from Android Studio > Device Manager)
-3. **ADB** accessible in PATH (comes with Android SDK)
+That's it. DevLens tools will appear in Cursor's MCP panel after restart.
 
-Verify:
-```bash
-adb devices
-# Should show your running emulator, e.g.:
-# emulator-5554   device
-```
+> **v0.4.0 Auto-Detection**: DevLens now automatically detects your shell (bash/zsh/fish) and `node`/`npx` path on every startup. If it finds a misconfigured command or path in your MCP config JSON, it patches it automatically (with backup). Check startup logs for `[devlens] Patched` or `[devlens] Config OK` messages.
+>
+> **Why `/bin/zsh -l`?** Cursor doesn't load your shell profile, so `node` from nvm/fnm isn't in PATH. Using `/bin/zsh -l` loads your login profile first. DevLens v0.4.0+ handles this automatically — if you put `/bin/bash` but use zsh, it will auto-correct.
 
-### For iOS Development (macOS only)
-1. **Xcode** installed with Command Line Tools
-2. **iOS Simulator** booted (open from Xcode > Window > Devices & Simulators)
+---
 
-Verify:
-```bash
-xcrun simctl list devices | grep Booted
-# Should show your booted simulator, e.g.:
-# iPhone 16 (XXXX-XXXX) (Booted)
-```
+## Installation for Other Clients
 
-### For React Native Metro Integration
-1. **Metro bundler** running:
+### Claude Code
 ```bash
-cd your-rn-project
-npx react-native start
-# or
-npx expo start
+claude mcp add devlens -- npx devlens-mcp@latest
 ```
+> Claude Code loads shell profiles automatically, so no `/bin/zsh` wrapper needed.
 
----
-
-## Installation
-
-### Option 1: Cursor IDE
-Add to `~/.cursor/mcp.json`:
+### Claude Desktop
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
     "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
-      "env": {
-        "METRO_PORT": "8081",
-        "FIGMA_TOKEN": "figd_xxxxx",
-        "DEVLENS_CONFIG": "/path/to/your-app/devlens.config.json"
-      }
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
+      "env": { "METRO_PORT": "8081" }
     }
   }
 }
 ```
 
-Restart Cursor after saving. DevLens tools will appear in the MCP tools panel.
+### Local Development (Build from Source)
+```bash
+git clone https://JioOmni@dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
+cd mcp-devlens && npm install && npm run build
+npm run register   # auto-registers with Claude Code
+```
+
+For Cursor with local build, use `"command": "node"` and `"args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"]` instead of the zsh wrapper.
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **Android**: Android SDK with `adb` in PATH (via Android Studio)
+- **iOS** (macOS only): Xcode with Command Line Tools
+- **React Native**: Metro bundler running (`npx react-native start`)
 
-### Option 2: Claude Code
+Quick checks:
 ```bash
-claude mcp add devlens -- npx devlens-mcp@latest
+node -v          # Should print v18+
+adb devices      # Should list your emulator
+xcrun simctl list devices | grep Booted   # (iOS) Should list simulator
 ```
 
-### Option 3: Claude Desktop
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+---
+
+## Environment Variables
+
+Add any of these to the `"env"` block in your MCP config:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `METRO_PORT` | No | `8081` | Port where Metro bundler is running |
+| `FIGMA_TOKEN` | For Figma compare | — | Figma personal access token. [How to get one](#figma-token-setup). |
+| `DEVLENS_CONFIG` | For DS context | — | Absolute path to `devlens.config.json`. [Details](#design-system-configuration). |
+| `ANDROID_HOME` | No | auto-detect | Android SDK path |
+| `DEVICE_ID` | No | first available | Target a specific device by ID |
+
+Full example with all optional vars:
 ```json
 {
   "mcpServers": {
     "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx",
-        "DEVLENS_CONFIG": "/path/to/your-app/devlens.config.json"
+        "DEVLENS_CONFIG": "/Users/you/your-app/devlens.config.json"
       }
     }
   }
 }
 ```
 
-> **Note:** `npx` downloads and runs DevLens automatically on first use. No clone or build step needed.
+---
+
+## Verify It Works
+
+Start your emulator/simulator and Metro, then ask your AI:
+
+| Step | What to say | Expected |
+|------|-------------|----------|
+| 1 | "List running devices" | Your emulator/simulator listed |
+| 2 | "Take a screenshot" | Device screenshot as inline image |
+| 3 | "Take a snapshot with validation" | Accessibility tree with `ref=eN` IDs |
+| 4 | "Show Metro logs" | Console output from your app |
+| 5 | "Run VQA on this screen against Figma: `<url>`" | VQA report with PASS/WARNING/FAIL |
+
+If step 1 works, DevLens is running correctly.
 
 ---
 
-## Configuration
+## VQA Workflow — Quick Reference for Developers
+
+DevLens v0.4.0 includes a VQA (Visual Quality Assurance) validator. Use it to catch design issues **before** designers see the build — zero VQA tickets.
 
-### Environment Variables
+### Copy-paste prompts you can use in Cursor:
 
-Set these in the `env` section of your MCP config, or export them in your shell:
+**Build a new screen + VQA:**
+```
+Build the HomeScreen component based on this Figma design:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `FIGMA_TOKEN` | — | Figma personal access token. Required for `devlens_compare_with_figma`. Generate at [figma.com/developers](https://www.figma.com/developers/api#access-tokens). Required scope: **File content: Read**. |
-| `DEVLENS_CONFIG` | — | Absolute path to your `devlens.config.json`. Enables the `devlens_ds_context` tool. |
-| `METRO_PORT` | `8081` | Port where Metro bundler is running |
-| `ANDROID_HOME` | auto-detect | Path to Android SDK (e.g., `/Users/you/Library/Android/sdk`) |
-| `ANDROID_SDK_ROOT` | auto-detect | Alternative to `ANDROID_HOME` |
-| `DEVICE_ID` | first available | Target a specific device by ID |
+After building, run VQA validation to make sure there are ZERO issues.
+Fix any spacing, color, alignment, or sizing issues automatically.
+Keep running VQA until the report shows PASS.
+```
 
-### Multiple Devices
+**Run VQA on an already-built screen:**
+```
+Take a snapshot of the current screen, then run VQA validation against this Figma:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
 
-If you have multiple emulators/simulators running, DevLens auto-selects the first one. To target a specific device:
+Show me the full VQA report. If there are any issues, fix them and re-run until PASS.
+```
+
+**Quick check after a small CSS change:**
+```
+I just changed the padding on the header. Do a minimal VQA check — only check
+spacing and alignment against this Figma:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+```
+
+**Full implementation + zero VQA guarantee:**
+```
+I need to implement this Figma screen and hand it to the designer with ZERO VQA issues:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+
+Steps:
+1. Load the design system context first
+2. Build the component using correct DS tokens
+3. Hot reload and wait for screen to stabilize
+4. Run full VQA validation (spacing, colors, alignment, sizing, missing elements)
+5. Fix every issue the VQA report finds
+6. Re-run VQA until the report says PASS with 0 issues
+7. Show me the final VQA report as proof
+```
+
+For the full VQA workflow guide with report format details, see [Figma Workflow](./figma-workflow.md#vqa-workflow--zero-designer-tickets-v040).
+
+---
+
+## Figma Token Setup
+
+Required only for `devlens_compare_with_figma`.
+
+1. Go to [figma.com/settings](https://www.figma.com/settings)
+2. Scroll to **Personal access tokens** → **Generate new token**
+3. Name: `devlens` (or anything)
+4. Scope: **File content → Read** (only scope needed)
+5. Copy the token (starts with `figd_`)
+
+Verify it works:
+```bash
+curl -H "X-Figma-Token: figd_yourtoken" "https://api.figma.com/v1/me"
+# Should return your account info
+```
 
-1. Run `devlens_list_devices` to see all available devices
-2. Pass `deviceId` to any tool: `devlens_device_info(deviceId: "emulator-5554")`
+Add to your MCP config:
+```json
+"env": {
+  "FIGMA_TOKEN": "figd_yourtoken"
+}
+```
 
-Or set `DEVICE_ID=emulator-5554` in your environment.
+> **Security:** Never paste your PAT in chat messages or commit it to git.
 
 ---
 
 ## Design System Configuration
 
-DevLens can read your design tokens and component interfaces to give the AI accurate context when writing or fixing UI code. This is configured via a `devlens.config.json` file in your app root.
+Optional. Enables `devlens_ds_context` for design-token-aware code generation.
 
 ### 1. Create `devlens.config.json` in your app root
 
@@ -135,22 +219,20 @@ DevLens can read your design tokens and component interfaces to give the AI accu
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `name` | Yes | Design system identifier (e.g. `"jds3"`, `"my-ds"`) |
-| `projectRoot` | Yes | Absolute path to your app root |
-| `tokensFile` | Yes | Path to your token constants file, relative to `projectRoot` |
-| `componentsDir` | No | Path to generated component interface directory, relative to `projectRoot` |
+| `name` | Yes | Design system identifier (e.g. `"jds3"`) |
+| `projectRoot` | Yes | **Absolute** path to your app root |
+| `tokensFile` | Yes | Token file, relative to `projectRoot` |
+| `componentsDir` | No | Generated component interfaces directory |
 | `componentsGlob` | No | Glob for component source files (default: `"src/**/*.tsx"`) |
 
-### 2. Point DevLens to the config via the MCP env block
-
-Add `DEVLENS_CONFIG` to your `~/.cursor/mcp.json` (or equivalent):
+### 2. Point to it in your MCP config
 
 ```json
 {
   "mcpServers": {
     "devlens": {
-      "command": "node",
-      "args": ["/path/to/devlens/dist/bin/cli.js"],
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx",
@@ -161,195 +243,107 @@ Add `DEVLENS_CONFIG` to your `~/.cursor/mcp.json` (or equivalent):
 }
 ```
 
-The `devlens.config.json` file lives in your consumer app repository so it stays version-controlled alongside the app it describes.
-
-### 3. Verify with `devlens_ds_context`
+### 3. Verify
 
-After restarting your AI client, ask:
-
-> *"Load the design system context"*
-
-`devlens_ds_context` will return:
-- All token names and values from your tokens file (colors, spacing, typography, etc.)
-- Component prop interfaces from `componentsDir`
-- Real usage patterns scanned from your `.tsx` files
+Ask your AI: *"Load the design system context"* — it should return token names, component interfaces, and usage patterns.
 
 ---
 
-## Figma Token Setup
-
-`devlens_compare_with_figma` requires a Figma personal access token (PAT).
-
-### Generate a PAT
-
-1. Go to [figma.com](https://www.figma.com) → your profile icon → **Settings**
-2. Scroll to **Personal access tokens** → **Generate new token**
-3. Give it a name (e.g. `devlens`)
-4. Set scope: **File content → Read** (this is the only scope needed)
-5. Copy the token — it starts with `figd_`
+## Troubleshooting
 
-### Verify the token works
+### Fix: Used `node` as command with shell flags (`-l`, `-c`)
 
-```bash
-curl -H "X-Figma-Token: figd_yourtoken" "https://api.figma.com/v1/me"
-# Expected: {"id":"...","email":"you@example.com","handle":"..."}
+If your old config looked like this:
+```json
+{
+  "command": "/opt/homebrew/bin/node",
+  "args": ["-l", "-c", "npx devlens-mcp@latest"]
+}
 ```
+This is incorrect — `-l` and `-c` are shell flags (zsh/bash), not node flags. Node ignores or errors on them.
 
-### Add to MCP config
+**v0.4.0 auto-fix:** DevLens detects this misconfiguration on startup and patches `command` to your actual shell (`/bin/zsh`, `/bin/bash`, etc.) automatically. Check logs for `[devlens] Patched`.
 
+**Manual fix:** Replace `node` with `/bin/zsh`:
 ```json
-"env": {
-  "FIGMA_TOKEN": "figd_yourtoken"
+{
+  "command": "/bin/zsh",
+  "args": ["-l", "-c", "npx devlens-mcp@latest"]
 }
 ```
 
-> **Security note:** Never paste your PAT in a chat or commit it to source control. Use environment variables or a secrets manager.
-
 ---
 
-## Verifying Setup
-
-After configuration, start a conversation with your AI assistant and try these commands in order:
-
-### 1. Check Metro Health
-
-> **Say:** *"Check if Metro is running"*
->
-> **Tool called:** `devlens_metro_status`
->
-> **Expected:** Running: `true`, Port: `8081`
-
-### 2. List Devices
-
-> **Say:** *"List my devices"*
->
-> **Tool called:** `devlens_list_devices`
->
-> **Expected:** Your running emulators/simulators listed with IDs
-
-### 3. Take a Screenshot
+### Fix: `env: node: No such file or directory`
 
-> **Say:** *"Take a screenshot of the device"*
->
-> **Tool called:** `devlens_screenshot`
->
-> **Expected:** Device screenshot returned as an inline image
-
-### 4. Take a Snapshot
-
-> **Say:** *"Take a snapshot of the screen with validation"*
->
-> **Tool called:** `devlens_snapshot(validate: true)`
->
-> **Expected:** Accessibility tree with `ref=eN` IDs + validation report
-
-### 5. Test Metro Logs
-
-> **Say:** *"Show me the Metro logs"*
->
-> **Tool called:** `devlens_metro_logs`
->
-> **Expected:** Console output from your React Native app
-
-### 6. Compare with Figma (optional — requires FIGMA_TOKEN)
-
-> **Say:** *"Compare the current screen with this Figma frame: [your Figma URL]"*
->
-> **Tool called:** `devlens_compare_with_figma`
->
-> **Expected:** Three images (device, Figma reference, diff) + layout region report
+This means Cursor can't find `node`. It happens when Node is installed via nvm/fnm and the MCP config uses `"command": "npx"` directly.
 
-### 7. Design System Context (optional — requires DEVLENS_CONFIG)
+**Fix:** Use the `/bin/zsh -l` wrapper as shown in the install section above:
+```json
+{
+  "command": "/bin/zsh",
+  "args": ["-l", "-c", "npx devlens-mcp@latest"]
+}
+```
 
-> **Say:** *"Load the design system context"*
->
-> **Tool called:** `devlens_ds_context`
->
-> **Expected:** Token list, component interfaces, and usage patterns
+The `-l` flag loads your login shell profile (where nvm/fnm initialize), making `node` available. This is the default recommended config and works for everyone on macOS. DevLens v0.4.0 auto-detects and patches this if misconfigured.
 
-If steps 1–5 succeed, DevLens is fully operational. Steps 6–7 require the optional env vars.
+**Alternative:** If you prefer not to use the zsh wrapper, you can use the full absolute path to `npx`:
+1. Run `which npx` in Terminal
+2. Use that full path as `"command"` (e.g. `"/Users/you/.nvm/versions/node/v20.12.2/bin/npx"`)
 
 ---
 
-## Troubleshooting
+### Fix: "No server info found" / DevLens tools not showing
 
-### "No running simulators or emulators found"
-- Start an Android emulator from Android Studio, or boot an iOS Simulator from Xcode
-- Verify with `adb devices` (Android) or `xcrun simctl list devices | grep Booted` (iOS)
-- If the device was recently started, DevLens may have a stale cache — the retry system will auto-reconnect
+This means Cursor couldn't start the MCP server. Check these in order:
 
-### "Could not connect to Metro bundler"
-- Ensure Metro is running: `npx react-native start` or `npx expo start`
-- Check the port: default is 8081, set `METRO_PORT` if different
-- Metro must be running on the same machine as DevLens
-- Use `devlens_metro_status` to diagnose — it gives actionable error messages
+1. **Is the JSON valid?** Paste your `~/.cursor/mcp.json` into [jsonlint.com](https://jsonlint.com) to check for syntax errors (trailing commas, missing quotes, etc.)
 
-### "ADB command not found"
-- Set `ANDROID_HOME` to your Android SDK path
-- Or add `$ANDROID_HOME/platform-tools` to your PATH
+2. **Is it `"command": "npx"`?** Not `"command": "node"`. Using `"node"` makes it look for a local file instead of downloading the package.
 
-### iOS "simctl not found"
-- Install Xcode Command Line Tools: `xcode-select --install`
-- Ensure Xcode is installed (not just CLT)
+3. **Does `npx devlens-mcp@latest` work in Terminal?**
+   ```bash
+   npx devlens-mcp@latest
+   ```
+   - If this hangs (no output) — that's correct, it's waiting for MCP input via stdin. Press `Ctrl+C`.
+   - If it errors with `env: node: No such file` — see the [nvm/PATH fix](#fix-nvmpath-issue-env-node-no-such-file-or-directory) above.
+   - If it errors with `Cannot find module` — clear the npx cache: `rm -rf ~/.npm/_npx/*devlens*` and try again.
 
-### Screenshots return empty or black
-- The app might not be in the foreground; use `devlens_launch_app` first
-- Wait a moment after navigation for the screen to render
-- Use `devlens_wait_for_screen(stableMs: 2000)` to wait for screen stability
+4. **Restart Cursor completely** (quit and reopen, not just reload window).
 
-### "Invalid token" when using Figma comparison
-- Make sure you're using a **personal access token** (`figd_...`), not an OAuth token
-- Verify it has the **File content: Read** scope
-- Test with: `curl -H "X-Figma-Token: YOUR_TOKEN" "https://api.figma.com/v1/me"`
+---
 
-### "File not exportable" when using Figma comparison
-- The Figma file has export restrictions enabled
-- Ask the file owner to go to **Share → Anyone with link → Uncheck "Prevent viewers from copying and exporting"**
+### Fix: Stale npx cache after update
 
-### Layout report is empty or missing in Figma comparison
-- Run `devlens_snapshot` on the current screen before `devlens_compare_with_figma` — the layout report uses element bounds from the snapshot
-- If refs are stale (screen changed), take a fresh snapshot first
+If you were on an older version and get `Cannot find module` errors:
 
-### `devlens_ds_context` returns empty or fails
-- Check that `DEVLENS_CONFIG` points to a valid `devlens.config.json` with an absolute `projectRoot`
-- Verify the `tokensFile` path is correct relative to `projectRoot`
-- The tool logs warnings to stderr — check your MCP server logs
+```bash
+rm -rf ~/.npm/_npx/*devlens*
+```
 
-### "env: node: No such file or directory" when using npx
-This happens on macOS when Node.js is installed via `nvm`, `fnm`, or a version manager. Cursor (and other GUI apps) don't load shell profiles, so `node` isn't in their PATH even though `npx` is found.
+Then restart Cursor. npx will re-download the latest version.
 
-**Fix:** Use the full absolute path to `npx` instead of just `npx`.
+---
 
-1. Open Terminal and run:
-   ```bash
-   which npx
-   # e.g. /Users/yourname/.nvm/versions/node/v23.10.0/bin/npx
-   ```
-2. Replace `"command": "npx"` in `~/.cursor/mcp.json` with that full path:
-   ```json
-   {
-     "mcpServers": {
-       "devlens": {
-         "command": "/Users/yourname/.nvm/versions/node/v23.10.0/bin/npx",
-         "args": ["devlens-mcp@latest"],
-         "env": { "METRO_PORT": "8081", "FIGMA_TOKEN": "figd_xxxxx" }
-       }
-     }
-   }
-   ```
-3. Restart Cursor.
+### Other Issues
 
-### DevLens tools not available in AI assistant
-- Verify `"command": "npx"` (not `"command": "node"`) in your MCP config
-- If you see `env: node: No such file or directory`, see the section above
-- Restart your AI client after any config change
-- Check `~/.cursor/mcp.json` or your IDE's MCP config for a `devlens` entry
+| 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" (iOS) | Run `xcode-select --install` |
+| "Invalid token" on Figma compare | Use a personal access token (`figd_...`) with **File content: Read** scope |
+| "File not exportable" on Figma compare | Ask file owner to uncheck "Prevent copying and exporting" in Figma share settings |
+| Layout report empty in Figma compare | Run `devlens_snapshot` first — layout report needs element bounds from the snapshot |
+| `devlens_ds_context` returns empty | Verify `DEVLENS_CONFIG` path and that `projectRoot` is absolute |
 
 ---
 
 ## What's Available
 
-DevLens provides **34 tools** across 8 categories:
+DevLens provides **36 tools** across 9 categories:
 
 | Category | Tools | Count |
 |----------|-------|-------|
@@ -361,5 +355,6 @@ DevLens provides **34 tools** across 8 categories:
 | 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 |
+| Analysis & VQA | analyze, vqa_validate | 2 |
 
-See the [Tool Reference](./tool-reference.md) for detailed documentation of every tool and parameter.
+See the [Tool Reference](./tool-reference.md) for detailed parameter docs.

package/docs/tool-reference.md

@@ -583,6 +583,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 |
@@ -620,3 +688,6 @@ On Android: presses system Back button. On iOS: performs back swipe.
 | 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? |

package/package.json

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