devlens-mcp 0.4.2 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/README.md +211 -35
  2. package/RELEASE_NOTES.md +3 -7
  3. package/dist/bin/cli.js +41 -14
  4. package/dist/bin/cli.js.map +1 -1
  5. package/dist/bin/setup.d.ts +14 -0
  6. package/dist/bin/setup.d.ts.map +1 -0
  7. package/dist/bin/setup.js +272 -0
  8. package/dist/bin/setup.js.map +1 -0
  9. package/dist/src/figma/figma-api.d.ts +108 -0
  10. package/dist/src/figma/figma-api.d.ts.map +1 -0
  11. package/dist/src/figma/figma-api.js +284 -0
  12. package/dist/src/figma/figma-api.js.map +1 -0
  13. package/dist/src/figma/figma-cache.d.ts +57 -0
  14. package/dist/src/figma/figma-cache.d.ts.map +1 -0
  15. package/dist/src/figma/figma-cache.js +266 -0
  16. package/dist/src/figma/figma-cache.js.map +1 -0
  17. package/dist/src/figma/figma-client.d.ts +62 -0
  18. package/dist/src/figma/figma-client.d.ts.map +1 -0
  19. package/dist/src/figma/figma-client.js +224 -0
  20. package/dist/src/figma/figma-client.js.map +1 -0
  21. package/dist/src/figma/figma-rate-limiter.d.ts +46 -0
  22. package/dist/src/figma/figma-rate-limiter.d.ts.map +1 -0
  23. package/dist/src/figma/figma-rate-limiter.js +153 -0
  24. package/dist/src/figma/figma-rate-limiter.js.map +1 -0
  25. package/dist/src/figma/figma-retry.d.ts +19 -0
  26. package/dist/src/figma/figma-retry.d.ts.map +1 -0
  27. package/dist/src/figma/figma-retry.js +57 -0
  28. package/dist/src/figma/figma-retry.js.map +1 -0
  29. package/dist/src/figma/figma-structure.d.ts +1 -1
  30. package/dist/src/figma/figma-structure.d.ts.map +1 -1
  31. package/dist/src/figma/figma-structure.js +11 -1
  32. package/dist/src/figma/figma-structure.js.map +1 -1
  33. package/dist/src/figma/figma-types.d.ts +54 -0
  34. package/dist/src/figma/figma-types.d.ts.map +1 -0
  35. package/dist/src/figma/figma-types.js +33 -0
  36. package/dist/src/figma/figma-types.js.map +1 -0
  37. package/dist/src/figma/url-parser.d.ts +40 -0
  38. package/dist/src/figma/url-parser.d.ts.map +1 -0
  39. package/dist/src/figma/url-parser.js +107 -0
  40. package/dist/src/figma/url-parser.js.map +1 -0
  41. package/dist/src/platform/device-manager.d.ts +5 -0
  42. package/dist/src/platform/device-manager.d.ts.map +1 -1
  43. package/dist/src/platform/device-manager.js +18 -0
  44. package/dist/src/platform/device-manager.js.map +1 -1
  45. package/dist/src/platform/device-pool.d.ts +105 -0
  46. package/dist/src/platform/device-pool.d.ts.map +1 -0
  47. package/dist/src/platform/device-pool.js +328 -0
  48. package/dist/src/platform/device-pool.js.map +1 -0
  49. package/dist/src/platform/device-profiles.d.ts +50 -0
  50. package/dist/src/platform/device-profiles.d.ts.map +1 -0
  51. package/dist/src/platform/device-profiles.js +155 -0
  52. package/dist/src/platform/device-profiles.js.map +1 -0
  53. package/dist/src/platform/ios/ios-device.d.ts +0 -2
  54. package/dist/src/platform/ios/ios-device.d.ts.map +1 -1
  55. package/dist/src/platform/ios/ios-device.js +8 -18
  56. package/dist/src/platform/ios/ios-device.js.map +1 -1
  57. package/dist/src/platform/ios/simctl.d.ts +0 -5
  58. package/dist/src/platform/ios/simctl.d.ts.map +1 -1
  59. package/dist/src/platform/ios/simctl.js +0 -4
  60. package/dist/src/platform/ios/simctl.js.map +1 -1
  61. package/dist/src/platform/simulator-factory.d.ts +85 -0
  62. package/dist/src/platform/simulator-factory.d.ts.map +1 -0
  63. package/dist/src/platform/simulator-factory.js +396 -0
  64. package/dist/src/platform/simulator-factory.js.map +1 -0
  65. package/dist/src/platform/system-resources.d.ts +44 -0
  66. package/dist/src/platform/system-resources.d.ts.map +1 -0
  67. package/dist/src/platform/system-resources.js +103 -0
  68. package/dist/src/platform/system-resources.js.map +1 -0
  69. package/dist/src/prototype/browser-engine.d.ts +62 -0
  70. package/dist/src/prototype/browser-engine.d.ts.map +1 -0
  71. package/dist/src/prototype/browser-engine.js +199 -0
  72. package/dist/src/prototype/browser-engine.js.map +1 -0
  73. package/dist/src/prototype/figma-navigator.d.ts +40 -0
  74. package/dist/src/prototype/figma-navigator.d.ts.map +1 -0
  75. package/dist/src/prototype/figma-navigator.js +95 -0
  76. package/dist/src/prototype/figma-navigator.js.map +1 -0
  77. package/dist/src/prototype/flow-reporter.d.ts +47 -0
  78. package/dist/src/prototype/flow-reporter.d.ts.map +1 -0
  79. package/dist/src/prototype/flow-reporter.js +255 -0
  80. package/dist/src/prototype/flow-reporter.js.map +1 -0
  81. package/dist/src/prototype/screen-analyzer.d.ts +31 -0
  82. package/dist/src/prototype/screen-analyzer.d.ts.map +1 -0
  83. package/dist/src/prototype/screen-analyzer.js +114 -0
  84. package/dist/src/prototype/screen-analyzer.js.map +1 -0
  85. package/dist/src/prototype/web-crawler.d.ts +31 -0
  86. package/dist/src/prototype/web-crawler.d.ts.map +1 -0
  87. package/dist/src/prototype/web-crawler.js +88 -0
  88. package/dist/src/prototype/web-crawler.js.map +1 -0
  89. package/dist/src/reports/cross-device-report.d.ts +84 -0
  90. package/dist/src/reports/cross-device-report.d.ts.map +1 -0
  91. package/dist/src/reports/cross-device-report.js +342 -0
  92. package/dist/src/reports/cross-device-report.js.map +1 -0
  93. package/dist/src/server.d.ts.map +1 -1
  94. package/dist/src/server.js +9 -1
  95. package/dist/src/server.js.map +1 -1
  96. package/dist/src/snapshot/formatter.d.ts +5 -13
  97. package/dist/src/snapshot/formatter.d.ts.map +1 -1
  98. package/dist/src/snapshot/formatter.js +19 -28
  99. package/dist/src/snapshot/formatter.js.map +1 -1
  100. package/dist/src/tools/interaction-tools.d.ts +6 -6
  101. package/dist/src/tools/interaction-tools.d.ts.map +1 -1
  102. package/dist/src/tools/interaction-tools.js +2 -12
  103. package/dist/src/tools/interaction-tools.js.map +1 -1
  104. package/dist/src/tools/metro-tools.d.ts +2 -2
  105. package/dist/src/tools/multi-device-tools.d.ts +133 -0
  106. package/dist/src/tools/multi-device-tools.d.ts.map +1 -0
  107. package/dist/src/tools/multi-device-tools.js +365 -0
  108. package/dist/src/tools/multi-device-tools.js.map +1 -0
  109. package/dist/src/tools/navigation-tools.d.ts.map +1 -1
  110. package/dist/src/tools/navigation-tools.js +1 -6
  111. package/dist/src/tools/navigation-tools.js.map +1 -1
  112. package/dist/src/tools/prototype-tools.d.ts +102 -0
  113. package/dist/src/tools/prototype-tools.d.ts.map +1 -0
  114. package/dist/src/tools/prototype-tools.js +391 -0
  115. package/dist/src/tools/prototype-tools.js.map +1 -0
  116. package/dist/src/tools/screenshot-tools.d.ts +7 -74
  117. package/dist/src/tools/screenshot-tools.d.ts.map +1 -1
  118. package/dist/src/tools/screenshot-tools.js +19 -286
  119. package/dist/src/tools/screenshot-tools.js.map +1 -1
  120. package/dist/src/tools/vqa-tools.d.ts +2 -2
  121. package/dist/src/tools/vqa-tools.d.ts.map +1 -1
  122. package/dist/src/tools/vqa-tools.js +4 -69
  123. package/dist/src/tools/vqa-tools.js.map +1 -1
  124. package/docs/figma-workflow.md +58 -6
  125. package/docs/installation-guide.md +302 -0
  126. package/docs/setup-guide.md +77 -79
  127. package/docs/tool-reference.md +152 -69
  128. package/install.sh +119 -0
  129. package/package.json +5 -2
  130. package/setup.sh +320 -0
  131. package/tsconfig.json +1 -1
package/README.md CHANGED
@@ -12,33 +12,151 @@ Figma Design ──► AI Agent ──► Code Changes ──► Hot Reloa
12
12
 
13
13
  ---
14
14
 
15
- ## Quick Start
15
+ ## Installation (2 minutes)
16
+
17
+ ### One-Command Installer (Recommended)
18
+
19
+ Copy-paste this entire block into your terminal, press Enter, and follow the prompt:
20
+
21
+ ```bash
22
+ bash <(cat << 'DEVLENS_INSTALL'
23
+ #!/usr/bin/env bash
24
+ set -e
25
+ echo "Create PAT at: https://dev.azure.com/JioOmni/_usersSettings/tokens (scope: Packaging → Read)"
26
+ read -rsp "Paste your Azure PAT: " PAT && echo
27
+ TOKEN=$(echo -n "$PAT" | base64)
28
+ REGISTRY_KEY="//pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/"
29
+ npm config set "${REGISTRY_KEY}:username" "JioOmni"
30
+ npm config set "${REGISTRY_KEY}:_password" "$TOKEN"
31
+ npm config set "${REGISTRY_KEY}:email" "npm@jio.com"
32
+ echo "Installing DevLens..."
33
+ npm install -g devlens-mcp@latest --registry=https://pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/
34
+ mkdir -p ~/.cursor
35
+ node -e "
36
+ const fs = require('fs');
37
+ const p = require('path').join(require('os').homedir(), '.cursor', 'mcp.json');
38
+ let cfg = {};
39
+ try { cfg = JSON.parse(fs.readFileSync(p, 'utf-8')); } catch {}
40
+ if (!cfg.mcpServers) cfg.mcpServers = {};
41
+ cfg.mcpServers.devlens = { command: 'devlens-mcp', args: [], env: { METRO_PORT: '8081' } };
42
+ fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + '\n');
43
+ "
44
+ echo "✅ Done! Run: devlens-mcp --version to verify, then restart Cursor."
45
+ DEVLENS_INSTALL
46
+ )
47
+ ```
48
+
49
+ **That's it!** Restart Cursor after the script completes.
50
+
51
+ ---
52
+
53
+ ### Manual Setup (If You Prefer)
54
+
55
+ <details>
56
+ <summary>Step 1 — Authenticate npm (one-time)</summary>
57
+
58
+ Create a PAT at https://dev.azure.com/JioOmni/_usersSettings/tokens with **Packaging → Read** scope, then:
59
+
60
+ ```bash
61
+ TOKEN=$(echo -n "YOUR_PAT" | base64)
62
+ npm config set //pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/:username "JioOmni"
63
+ npm config set //pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/:_password "$TOKEN"
64
+ npm config set //pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/:email "you@ril.com"
65
+ ```
66
+
67
+ </details>
68
+
69
+ <details>
70
+ <summary>Step 2 — Install DevLens globally</summary>
16
71
 
17
- ### Claude Code
18
72
  ```bash
19
- claude mcp add devlens -- npx devlens-mcp@latest
73
+ npm install -g devlens-mcp@latest --registry=https://pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/
74
+ devlens-mcp --version # verify it works
20
75
  ```
21
76
 
22
- ### Cursor IDE / Claude Desktop
23
- Add to `~/.cursor/mcp.json` (Cursor) or `~/Library/Application Support/Claude/claude_desktop_config.json` (Desktop):
77
+ </details>
78
+
79
+ <details>
80
+ <summary>Step 3 — Configure Cursor</summary>
81
+
82
+ Create or edit `~/.cursor/mcp.json`:
83
+
24
84
  ```json
25
85
  {
26
86
  "mcpServers": {
27
87
  "devlens": {
28
- "command": "/bin/zsh",
29
- "args": ["-l", "-c", "npx devlens-mcp@latest"],
88
+ "command": "devlens-mcp",
89
+ "args": [],
30
90
  "env": {
31
- "METRO_PORT": "8081",
32
- "FIGMA_TOKEN": "figd_xxxxx"
91
+ "METRO_PORT": "8081"
33
92
  }
34
93
  }
35
94
  }
36
95
  }
37
96
  ```
38
97
 
39
- Restart your AI client after editing the config.
98
+ Restart Cursor.
99
+
100
+ </details>
101
+
102
+ <details>
103
+ <summary>Claude Desktop</summary>
104
+
105
+ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
106
+
107
+ ```json
108
+ {
109
+ "mcpServers": {
110
+ "devlens": {
111
+ "command": "devlens-mcp",
112
+ "args": []
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ Restart Claude Desktop.
119
+
120
+ </details>
40
121
 
41
- > **v0.4.0+**: DevLens now auto-detects your shell and `node` path on startup. It will patch MCP config files automatically if it detects a misconfigured shell or node path. See [setup guide](./docs/setup-guide.md) for details.
122
+ <details>
123
+ <summary>Advanced: Using npx (not recommended)</summary>
124
+
125
+ If you can't install globally, you can use npx, but it's slower and may have cache issues:
126
+
127
+ ```json
128
+ {
129
+ "mcpServers": {
130
+ "devlens": {
131
+ "command": "npx",
132
+ "args": ["--registry=https://pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/", "devlens-mcp@latest"]
133
+ }
134
+ }
135
+ }
136
+ ```
137
+
138
+ If you hit npx cache errors, clear the cache: `rm -rf ~/.npm/_npx`
139
+
140
+ </details>
141
+
142
+ ---
143
+
144
+ ### Optional: Figma Token
145
+
146
+ For Figma comparison features (`devlens_compare_with_figma`, `devlens_vqa_validate`), add a Figma token to your MCP config:
147
+
148
+ 1. Get token at https://www.figma.com/settings (scope: **File content: Read**)
149
+ 2. Add to MCP config: `"FIGMA_TOKEN": "figd_xxxxx"` in the `env` section
150
+
151
+ ---
152
+
153
+ ### Verify Installation
154
+
155
+ ```bash
156
+ devlens-mcp --version # should show: devlens-mcp v0.5.2
157
+ ```
158
+
159
+ In Cursor, ask the AI: "List running devices" — DevLens should respond.
42
160
 
43
161
  ---
44
162
 
@@ -60,6 +178,19 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
60
178
 
61
179
  ---
62
180
 
181
+ ## New in v0.5.0
182
+
183
+ - **Multi-Device Testing** — Four new tools (`devlens_list_profiles`, `devlens_boot_device`, `devlens_multi_capture`, `devlens_multi_shutdown`) for testing your UI across multiple screen sizes simultaneously. Includes 9 preset device profiles (iPhone SE through iPad Pro, Pixel 4a through Pixel Tablet). Auto-adaptive batching detects available RAM/CPU and boots devices in safe batches — works on 16GB Macs without overloading.
184
+ - **Cross-Device Report** — `devlens_multi_capture` generates a comprehensive comparison report: pixel similarity matrix, layout consistency analysis, and responsive issue detection across all captured devices.
185
+ - **Prototype Explorer** — Three new tools (`devlens_check_prototype`, `devlens_explore_prototype`, `devlens_prototype_screen`) that bring full prototype/mock exploration to DevLens.
186
+ - **Bidirectional Smart Prompting** — Give DevLens a Figma link and it asks for the prototype URL. Give it a prototype URL and it asks for the Figma design link. Both together = near-100% build accuracy.
187
+ - **Web Prototype Support** — Point DevLens at any web-hosted prototype (Vercel, Netlify, etc.) and it opens a headless browser, BFS-crawls all routes, captures high-res screenshots, and extracts colours, typography, and component patterns.
188
+ - **Figma Prototype Navigation** — Figma prototype links are opened in a headless browser; the flow graph from the Figma REST API guides navigation through each screen.
189
+ - **Comprehensive Flow Reports** — Every exploration returns: per-screen screenshots, colour palettes, typography, component inventory, interactive element maps, flow diagrams, and design token extraction.
190
+ - **Shared Figma Utilities** — URL parsing and image resolution logic extracted into `src/figma/url-parser.ts` and `src/figma/figma-api.ts`, eliminating duplication across screenshot and VQA tools.
191
+
192
+ ---
193
+
63
194
  ## New in v0.4.0
64
195
 
65
196
  - **Auto-Detect Shell & Node Path** — DevLens now auto-detects your shell (bash/zsh/fish), finds the correct `node`/`npx` path, and auto-patches MCP config files if they are misconfigured. No more "node not found" errors.
@@ -100,7 +231,7 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
100
231
 
101
232
  ---
102
233
 
103
- ## Tools (37)
234
+ ## Tools (43)
104
235
 
105
236
  ### Device Management (3)
106
237
  | Tool | Description |
@@ -138,7 +269,7 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
138
269
  | `devlens_fill_form` | Fill multiple fields at once |
139
270
  | `devlens_capture_flow` | Batch execute actions + capture labeled screenshots |
140
271
 
141
- ### Screenshots & Visual (6)
272
+ ### Screenshots & Visual (5)
142
273
  | Tool | Description |
143
274
  |------|-------------|
144
275
  | `devlens_screenshot` | Take screenshot (base64 + file) |
@@ -146,7 +277,6 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
146
277
  | `devlens_element_screenshot` | Screenshot a specific element |
147
278
  | `devlens_compare_images` | A/B compare two saved screenshots |
148
279
  | `devlens_compare_with_figma` | Compare device screen against Figma design with per-element layout report |
149
- | `devlens_compare_properties` | Compare ALL design properties (text sizes, colors, spacing, dimensions) per component against Figma |
150
280
 
151
281
  ### React Native / Metro (6)
152
282
  | Tool | Description |
@@ -175,6 +305,21 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
175
305
  | `devlens_analyze` | Smart analysis with configurable depth (minimal/targeted/full). Respects scope of request — minimal changes get minimal analysis. |
176
306
  | `devlens_vqa_validate` | Run VQA validation against Figma. Checks spacing, color, alignment, sizing, missing elements. Returns issues + fix suggestions. |
177
307
 
308
+ ### Prototype Explorer (3)
309
+ | Tool | Description |
310
+ |------|-------------|
311
+ | `devlens_check_prototype` | Smart detection with bidirectional prompting. Give any URL (Figma or web) and it detects the type, summarises screens, and asks for the complementary link. |
312
+ | `devlens_explore_prototype` | Full browser exploration. Opens prototype in headless Chrome, crawls all screens, captures screenshots, extracts design tokens, builds flow report. |
313
+ | `devlens_prototype_screen` | Deep single-screen analysis. Element-level detail with bounds, colours, text, nesting for pixel-perfect implementation. |
314
+
315
+ ### Multi-Device Testing (4)
316
+ | Tool | Description |
317
+ |------|-------------|
318
+ | `devlens_list_profiles` | List preset device profiles (iPhone SE, iPhone 15, Pixel 7, etc.) with screen sizes and scale factors |
319
+ | `devlens_boot_device` | Boot a single simulator/emulator by profile ID |
320
+ | `devlens_multi_capture` | Adaptive multi-device capture — auto-batches based on system RAM/CPU, boots devices, captures screenshots + snapshots, generates cross-device report |
321
+ | `devlens_multi_shutdown` | Shutdown all DevLens-created simulators/emulators and optionally delete them |
322
+
178
323
  ---
179
324
 
180
325
  ## The Figma Verification Workflow
@@ -205,10 +350,9 @@ DevLens integrates with Figma to create an automated design verification loop:
205
350
  6. **Wait for stability** — `devlens_wait_for_screen` waits until UI stops changing
206
351
  7. **Validate elements** — `devlens_snapshot(validate: true)` catches invisible/zero-size elements
207
352
  8. **Quick check** — `devlens_compare_with_figma(figmaUrl: "...", depth: "quick")` for fast iteration
208
- 9. **Property comparison** — `devlens_compare_properties(figmaUrl: "...")` for per-component mismatches (font size, color, spacing, dimensions)
209
- 10. **VQA validation** — `devlens_vqa_validate(figmaUrl: "...")` runs full VQA: spacing, colors, alignment, sizing, missing elements
210
- 11. **Fix issues** — AI reads VQA/property reports with fix suggestions and applies fixes
211
- 12. **Repeat** — Run VQA again until status is `PASS` (zero VQA issues for designers)
353
+ 9. **VQA validation** — `devlens_vqa_validate(figmaUrl: "...")` runs full VQA: spacing, colors, alignment, sizing, missing elements
354
+ 10. **Fix issues** — AI reads VQA report with per-issue fix suggestions and applies fixes
355
+ 11. **Repeat** — Run VQA again until status is `PASS` (zero VQA issues for designers)
212
356
 
213
357
  ---
214
358
 
@@ -321,32 +465,64 @@ Configure via `devlens.config.json` in your app root (see [Setup Guide](./docs/s
321
465
 
322
466
  ## Troubleshooting
323
467
 
468
+ ### Installation Issues
469
+
324
470
  | Problem | Solution |
325
471
  |---------|----------|
326
- | "No running simulators or emulators" | Start a device from Android Studio or Xcode |
327
- | "Could not connect to Metro bundler" | Run `npx react-native start` and check `METRO_PORT` |
328
- | "ADB command not found" | Set `ANDROID_HOME` or add `platform-tools` to PATH |
329
- | "simctl not found" | Install Xcode Command Line Tools: `xcode-select --install` |
330
- | DevLens tools not available | Run `npm run register` (local dev) or check MCP config |
331
- | "Invalid token" on Figma compare | Use a personal access token (`figd_...`), not an OAuth token. Required scope: **File content: Read**. |
332
- | "File not exportable" on Figma compare | Disable "Prevent viewers from copying and exporting" in Figma share settings |
333
- | `devlens_ds_context` returns empty | Set `DEVLENS_CONFIG` env var to your `devlens.config.json` path |
334
- | Comparison similarity always low | Run `devlens_snapshot` first so layout report has element bounds to work with |
335
- | Status bar causing false diffs | Use `excludeSystemBars: "auto"` (default in v0.4.0) or `"ios"`/`"android"` |
336
- | VQA report empty | Run `devlens_snapshot` first to populate element refs before `devlens_vqa_validate` |
337
- | Shell/node path wrong in MCP config | v0.4.0 auto-patches on startup; check logs for `[devlens] Patched` messages |
472
+ | **DevLens tools not showing** | Run `devlens-mcp --version` to verify installation. If command not found, reinstall: `npm install -g devlens-mcp@latest --registry=https://pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/` |
473
+ | **npm ERR! 401/403 Unauthorized** | PAT needs **Packaging Read** scope. Create new PAT at https://dev.azure.com/JioOmni/_usersSettings/tokens |
474
+ | **npx cache/permission errors** | Use global install instead. Clear cache: `rm -rf ~/.npm/_npx` then install globally |
475
+ | **"command not found: devlens-mcp"** | Check global npm bin is in PATH: `npm bin -g` should be in your PATH. Or use full path in MCP config |
476
+ | **Cursor not detecting DevLens** | Verify `~/.cursor/mcp.json` exists with correct config. Completely quit and restart Cursor (not just reload window) |
477
+ | **"Failed to spawn"** | Check MCP config command path. Use `"command": "devlens-mcp"` (global) not `"command": "npx"` |
478
+
479
+ ### Runtime Issues
480
+
481
+ | Problem | Solution |
482
+ |---------|----------|
483
+ | **"No running simulators or emulators"** | Start a device from Android Studio or Xcode |
484
+ | **"Could not connect to Metro bundler"** | Run `npx react-native start` and check `METRO_PORT` |
485
+ | **"ADB command not found"** | Set `ANDROID_HOME` or add `platform-tools` to PATH |
486
+ | **"simctl not found"** | Install Xcode Command Line Tools: `xcode-select --install` |
487
+ | **"Invalid token" on Figma compare** | Use a personal access token (`figd_...`), not an OAuth token. Required scope: **File content: Read**. |
488
+ | **"File not exportable" on Figma compare** | Disable "Prevent viewers from copying and exporting" in Figma share settings |
489
+ | **`devlens_ds_context` returns empty** | Set `DEVLENS_CONFIG` env var to your `devlens.config.json` path |
490
+ | **Comparison similarity always low** | Run `devlens_snapshot` first so layout report has element bounds to work with |
491
+ | **Status bar causing false diffs** | Use `excludeSystemBars: "auto"` (default in v0.4.0) or `"ios"`/`"android"` |
492
+ | **VQA report empty** | Run `devlens_snapshot` first to populate element refs before `devlens_vqa_validate` |
493
+ | **Shell/node path wrong in MCP config** | v0.4.0 auto-patches on startup; check logs for `[devlens] Patched` messages |
494
+
495
+ ### Updating DevLens
496
+
497
+ ```bash
498
+ # Update to latest version
499
+ npm update -g devlens-mcp --registry=https://pkgs.dev.azure.com/JioOmni/_packaging/devlens/npm/registry/
500
+
501
+ # Check version
502
+ devlens-mcp --version
503
+ ```
504
+
505
+ Then restart your IDE.
338
506
 
339
507
  ---
340
508
 
341
509
  ## Documentation
342
510
 
343
- - **[docs/setup-guide.md](./docs/setup-guide.md)** - Full setup guide: prerequisites, Figma token, design system config
344
- - **[docs/figma-workflow.md](./docs/figma-workflow.md)** - Figma integration workflow
345
- - **[docs/tool-reference.md](./docs/tool-reference.md)** - Detailed tool API reference
511
+ - **[docs/installation-guide.md](./docs/installation-guide.md)** — Step-by-step visual installation guide (with screenshots)
512
+ - **[docs/setup-guide.md](./docs/setup-guide.md)** Prerequisites, Figma token, design system configuration
513
+ - **[docs/figma-workflow.md](./docs/figma-workflow.md)** Figma integration workflow
514
+ - **[docs/tool-reference.md](./docs/tool-reference.md)** — Detailed tool API reference
515
+ - **[RELEASE_NOTES.md](./RELEASE_NOTES.md)** — Version history and changelog
346
516
 
347
- ## Repository
517
+ ## For Contributors
348
518
 
349
- - **Azure DevOps**: https://dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
519
+ ```bash
520
+ git clone https://JioOmni@dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
521
+ cd mcp-devlens
522
+ npm install
523
+ npm run build
524
+ npm run register # auto-registers with Claude Code
525
+ ```
350
526
 
351
527
  ## License
352
528
 
package/RELEASE_NOTES.md CHANGED
@@ -165,15 +165,14 @@ Four improvements that eliminate the 5% false-positive gap:
165
165
 
166
166
  ---
167
167
 
168
- ## New Tools (3)
168
+ ## New Tools (2)
169
169
 
170
170
  | Tool | Description |
171
171
  |------|-------------|
172
172
  | `devlens_analyze` | Smart analysis with configurable scope (minimal/targeted/full) |
173
173
  | `devlens_vqa_validate` | VQA validator — checks spacing, color, alignment, sizing, missing elements against Figma |
174
- | `devlens_compare_properties` | Per-component property comparison — text sizes, colors, spacing, dimensions, layout direction with exact expected vs actual values and configurable tolerances |
175
174
 
176
- **Total tools: 37** (up from 34 in v0.3.3)
175
+ **Total tools: 36** (up from 34 in v0.3.3)
177
176
 
178
177
  ---
179
178
 
@@ -189,7 +188,7 @@ Four improvements that eliminate the 5% false-positive gap:
189
188
 
190
189
  ## Files Changed
191
190
 
192
- ### New (9 files)
191
+ ### New (6 files)
193
192
  | File | Purpose |
194
193
  |------|---------|
195
194
  | `src/setup/shell-detector.ts` | Shell type & node path detection |
@@ -198,9 +197,6 @@ Four improvements that eliminate the 5% false-positive gap:
198
197
  | `src/tools/vqa-tools.ts` | `devlens_vqa_validate` tool |
199
198
  | `src/visual/vqa-analyzer.ts` | VQA engine: spacing, sizing, alignment, color, missing checks |
200
199
  | `src/visual/color-extractor.ts` | Dominant color extraction & Delta-E comparison |
201
- | `src/figma/figma-properties.ts` | Extract all comparable design properties from Figma REST API |
202
- | `src/snapshot/device-properties.ts` | Extract comparable properties from device snapshot + screenshot |
203
- | `src/visual/property-comparator.ts` | Per-property comparison engine with tolerances and severity |
204
200
 
205
201
  ### Modified (11 files)
206
202
  | File | What changed |
package/dist/bin/cli.js CHANGED
@@ -5,25 +5,52 @@ const fs_1 = require("fs");
5
5
  const path_1 = require("path");
6
6
  const index_js_1 = require("../src/index.js");
7
7
  const config_patcher_js_1 = require("../src/setup/config-patcher.js");
8
+ const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.resolve)(__dirname, "..", "..", "package.json"), "utf-8"));
8
9
  if (process.argv.includes("--version") || process.argv.includes("-v")) {
9
- const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.resolve)(__dirname, "..", "..", "package.json"), "utf-8"));
10
10
  console.log(`devlens-mcp v${pkg.version}`);
11
11
  process.exit(0);
12
12
  }
13
- async function main() {
14
- await (0, config_patcher_js_1.detectAndPatchConfig)();
15
- const server = await (0, index_js_1.createServer)();
16
- process.on("SIGINT", async () => {
17
- await server.close();
18
- process.exit(0);
13
+ if (process.argv.includes("setup")) {
14
+ import("./setup.js").catch(() => {
15
+ console.error("Setup module not found. Run from the devlens-mcp package directory.");
16
+ process.exit(1);
19
17
  });
20
- process.on("SIGTERM", async () => {
21
- await server.close();
22
- process.exit(0);
18
+ }
19
+ else if (process.argv.includes("--help") || process.argv.includes("-h")) {
20
+ console.log(`
21
+ devlens-mcp v${pkg.version}
22
+ Playwright-style MCP server for React Native mobile development
23
+
24
+ Usage:
25
+ devlens-mcp Start the MCP server (default)
26
+ devlens-mcp setup Interactive setup wizard
27
+ devlens-mcp --version Show version
28
+ devlens-mcp --help Show this help
29
+
30
+ Environment:
31
+ METRO_PORT Metro bundler port (default: 8081)
32
+ FIGMA_TOKEN Figma personal access token
33
+ DEVLENS_CONFIG Path to devlens.config.json
34
+ DEVICE_ID Target a specific device
35
+ `);
36
+ process.exit(0);
37
+ }
38
+ else {
39
+ async function main() {
40
+ await (0, config_patcher_js_1.detectAndPatchConfig)();
41
+ const server = await (0, index_js_1.createServer)();
42
+ process.on("SIGINT", async () => {
43
+ await server.close();
44
+ process.exit(0);
45
+ });
46
+ process.on("SIGTERM", async () => {
47
+ await server.close();
48
+ process.exit(0);
49
+ });
50
+ }
51
+ main().catch((error) => {
52
+ console.error("DevLens failed to start:", error);
53
+ process.exit(1);
23
54
  });
24
55
  }
25
- main().catch((error) => {
26
- console.error("DevLens failed to start:", error);
27
- process.exit(1);
28
- });
29
56
  //# sourceMappingURL=cli.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":";;;AAEA,2BAAkC;AAClC,+BAA+B;AAC/B,8CAA+C;AAC/C,sEAAsE;AAEtE,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACtE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAY,EAAC,IAAA,cAAO,EAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9F,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAA,wCAAoB,GAAE,CAAC;IAE7B,MAAM,MAAM,GAAG,MAAM,IAAA,uBAAY,GAAE,CAAC;IAEpC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QAC/B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":";;;AAEA,2BAAkC;AAClC,+BAA+B;AAC/B,8CAA+C;AAC/C,sEAAsE;AAEtE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAY,EAAC,IAAA,cAAO,EAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AAE9F,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACtE,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,MAAM,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QAC9B,OAAO,CAAC,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IAC1E,OAAO,CAAC,GAAG,CAAC;iBACG,GAAG,CAAC,OAAO;;;;;;;;;;;;;;GAczB,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;KAAM,CAAC;IACN,KAAK,UAAU,IAAI;QACjB,MAAM,IAAA,wCAAoB,GAAE,CAAC;QAE7B,MAAM,MAAM,GAAG,MAAM,IAAA,uBAAY,GAAE,CAAC;QAEpC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YAC9B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAC/B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACrB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * DevLens MCP — Interactive Setup
4
+ *
5
+ * Configures npm authentication for Azure Artifacts and
6
+ * registers DevLens in Cursor / Claude Desktop / Claude Code.
7
+ *
8
+ * Usage:
9
+ * npx devlens-mcp-setup (after npm is configured)
10
+ * node dist/bin/setup.js (from source)
11
+ * devlens-mcp setup (if globally installed)
12
+ */
13
+ export {};
14
+ //# sourceMappingURL=setup.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../bin/setup.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}