devlens-mcp 0.4.1 → 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.
- package/README.md +211 -35
- package/RELEASE_NOTES.md +3 -7
- package/dist/bin/cli.js +47 -13
- package/dist/bin/cli.js.map +1 -1
- package/dist/bin/setup.d.ts +14 -0
- package/dist/bin/setup.d.ts.map +1 -0
- package/dist/bin/setup.js +272 -0
- package/dist/bin/setup.js.map +1 -0
- package/dist/src/figma/figma-api.d.ts +108 -0
- package/dist/src/figma/figma-api.d.ts.map +1 -0
- package/dist/src/figma/figma-api.js +284 -0
- package/dist/src/figma/figma-api.js.map +1 -0
- package/dist/src/figma/figma-cache.d.ts +57 -0
- package/dist/src/figma/figma-cache.d.ts.map +1 -0
- package/dist/src/figma/figma-cache.js +266 -0
- package/dist/src/figma/figma-cache.js.map +1 -0
- package/dist/src/figma/figma-client.d.ts +62 -0
- package/dist/src/figma/figma-client.d.ts.map +1 -0
- package/dist/src/figma/figma-client.js +224 -0
- package/dist/src/figma/figma-client.js.map +1 -0
- package/dist/src/figma/figma-rate-limiter.d.ts +46 -0
- package/dist/src/figma/figma-rate-limiter.d.ts.map +1 -0
- package/dist/src/figma/figma-rate-limiter.js +153 -0
- package/dist/src/figma/figma-rate-limiter.js.map +1 -0
- package/dist/src/figma/figma-retry.d.ts +19 -0
- package/dist/src/figma/figma-retry.d.ts.map +1 -0
- package/dist/src/figma/figma-retry.js +57 -0
- package/dist/src/figma/figma-retry.js.map +1 -0
- package/dist/src/figma/figma-structure.d.ts +1 -1
- package/dist/src/figma/figma-structure.d.ts.map +1 -1
- package/dist/src/figma/figma-structure.js +11 -1
- package/dist/src/figma/figma-structure.js.map +1 -1
- package/dist/src/figma/figma-types.d.ts +54 -0
- package/dist/src/figma/figma-types.d.ts.map +1 -0
- package/dist/src/figma/figma-types.js +33 -0
- package/dist/src/figma/figma-types.js.map +1 -0
- package/dist/src/figma/url-parser.d.ts +40 -0
- package/dist/src/figma/url-parser.d.ts.map +1 -0
- package/dist/src/figma/url-parser.js +107 -0
- package/dist/src/figma/url-parser.js.map +1 -0
- package/dist/src/platform/device-manager.d.ts +5 -0
- package/dist/src/platform/device-manager.d.ts.map +1 -1
- package/dist/src/platform/device-manager.js +18 -0
- package/dist/src/platform/device-manager.js.map +1 -1
- package/dist/src/platform/device-pool.d.ts +105 -0
- package/dist/src/platform/device-pool.d.ts.map +1 -0
- package/dist/src/platform/device-pool.js +328 -0
- package/dist/src/platform/device-pool.js.map +1 -0
- package/dist/src/platform/device-profiles.d.ts +50 -0
- package/dist/src/platform/device-profiles.d.ts.map +1 -0
- package/dist/src/platform/device-profiles.js +155 -0
- package/dist/src/platform/device-profiles.js.map +1 -0
- package/dist/src/platform/ios/ios-device.d.ts +0 -2
- package/dist/src/platform/ios/ios-device.d.ts.map +1 -1
- package/dist/src/platform/ios/ios-device.js +8 -18
- package/dist/src/platform/ios/ios-device.js.map +1 -1
- package/dist/src/platform/ios/simctl.d.ts +0 -5
- package/dist/src/platform/ios/simctl.d.ts.map +1 -1
- package/dist/src/platform/ios/simctl.js +0 -4
- package/dist/src/platform/ios/simctl.js.map +1 -1
- package/dist/src/platform/simulator-factory.d.ts +85 -0
- package/dist/src/platform/simulator-factory.d.ts.map +1 -0
- package/dist/src/platform/simulator-factory.js +396 -0
- package/dist/src/platform/simulator-factory.js.map +1 -0
- package/dist/src/platform/system-resources.d.ts +44 -0
- package/dist/src/platform/system-resources.d.ts.map +1 -0
- package/dist/src/platform/system-resources.js +103 -0
- package/dist/src/platform/system-resources.js.map +1 -0
- package/dist/src/prototype/browser-engine.d.ts +62 -0
- package/dist/src/prototype/browser-engine.d.ts.map +1 -0
- package/dist/src/prototype/browser-engine.js +199 -0
- package/dist/src/prototype/browser-engine.js.map +1 -0
- package/dist/src/prototype/figma-navigator.d.ts +40 -0
- package/dist/src/prototype/figma-navigator.d.ts.map +1 -0
- package/dist/src/prototype/figma-navigator.js +95 -0
- package/dist/src/prototype/figma-navigator.js.map +1 -0
- package/dist/src/prototype/flow-reporter.d.ts +47 -0
- package/dist/src/prototype/flow-reporter.d.ts.map +1 -0
- package/dist/src/prototype/flow-reporter.js +255 -0
- package/dist/src/prototype/flow-reporter.js.map +1 -0
- package/dist/src/prototype/screen-analyzer.d.ts +31 -0
- package/dist/src/prototype/screen-analyzer.d.ts.map +1 -0
- package/dist/src/prototype/screen-analyzer.js +114 -0
- package/dist/src/prototype/screen-analyzer.js.map +1 -0
- package/dist/src/prototype/web-crawler.d.ts +31 -0
- package/dist/src/prototype/web-crawler.d.ts.map +1 -0
- package/dist/src/prototype/web-crawler.js +88 -0
- package/dist/src/prototype/web-crawler.js.map +1 -0
- package/dist/src/reports/cross-device-report.d.ts +84 -0
- package/dist/src/reports/cross-device-report.d.ts.map +1 -0
- package/dist/src/reports/cross-device-report.js +342 -0
- package/dist/src/reports/cross-device-report.js.map +1 -0
- package/dist/src/server.d.ts.map +1 -1
- package/dist/src/server.js +9 -1
- package/dist/src/server.js.map +1 -1
- package/dist/src/snapshot/formatter.d.ts +5 -13
- package/dist/src/snapshot/formatter.d.ts.map +1 -1
- package/dist/src/snapshot/formatter.js +19 -28
- package/dist/src/snapshot/formatter.js.map +1 -1
- package/dist/src/tools/interaction-tools.d.ts +6 -6
- package/dist/src/tools/interaction-tools.d.ts.map +1 -1
- package/dist/src/tools/interaction-tools.js +2 -12
- package/dist/src/tools/interaction-tools.js.map +1 -1
- package/dist/src/tools/metro-tools.d.ts +2 -2
- package/dist/src/tools/multi-device-tools.d.ts +133 -0
- package/dist/src/tools/multi-device-tools.d.ts.map +1 -0
- package/dist/src/tools/multi-device-tools.js +365 -0
- package/dist/src/tools/multi-device-tools.js.map +1 -0
- package/dist/src/tools/navigation-tools.d.ts.map +1 -1
- package/dist/src/tools/navigation-tools.js +1 -6
- package/dist/src/tools/navigation-tools.js.map +1 -1
- package/dist/src/tools/prototype-tools.d.ts +102 -0
- package/dist/src/tools/prototype-tools.d.ts.map +1 -0
- package/dist/src/tools/prototype-tools.js +391 -0
- package/dist/src/tools/prototype-tools.js.map +1 -0
- package/dist/src/tools/screenshot-tools.d.ts +7 -74
- package/dist/src/tools/screenshot-tools.d.ts.map +1 -1
- package/dist/src/tools/screenshot-tools.js +19 -286
- package/dist/src/tools/screenshot-tools.js.map +1 -1
- package/dist/src/tools/vqa-tools.d.ts +2 -2
- package/dist/src/tools/vqa-tools.d.ts.map +1 -1
- package/dist/src/tools/vqa-tools.js +4 -69
- package/dist/src/tools/vqa-tools.js.map +1 -1
- package/docs/figma-workflow.md +58 -6
- package/docs/installation-guide.md +302 -0
- package/docs/setup-guide.md +77 -79
- package/docs/tool-reference.md +152 -69
- package/install.sh +119 -0
- package/package.json +5 -2
- package/setup.sh +320 -0
- 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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
23
|
-
|
|
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": "
|
|
29
|
-
"args": [
|
|
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
|
|
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
|
-
>
|
|
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 (
|
|
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 (
|
|
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. **
|
|
209
|
-
10. **
|
|
210
|
-
11. **
|
|
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
|
-
|
|
|
327
|
-
|
|
|
328
|
-
|
|
|
329
|
-
| "
|
|
330
|
-
|
|
|
331
|
-
| "
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
|
336
|
-
|
|
337
|
-
|
|
|
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/
|
|
344
|
-
- **[docs/
|
|
345
|
-
- **[docs/
|
|
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
|
-
##
|
|
517
|
+
## For Contributors
|
|
348
518
|
|
|
349
|
-
|
|
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 (
|
|
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:
|
|
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 (
|
|
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
|
@@ -1,22 +1,56 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
"use strict";
|
|
3
3
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
|
+
const fs_1 = require("fs");
|
|
5
|
+
const path_1 = require("path");
|
|
4
6
|
const index_js_1 = require("../src/index.js");
|
|
5
7
|
const config_patcher_js_1 = require("../src/setup/config-patcher.js");
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
process.
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.resolve)(__dirname, "..", "..", "package.json"), "utf-8"));
|
|
9
|
+
if (process.argv.includes("--version") || process.argv.includes("-v")) {
|
|
10
|
+
console.log(`devlens-mcp v${pkg.version}`);
|
|
11
|
+
process.exit(0);
|
|
12
|
+
}
|
|
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);
|
|
12
17
|
});
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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);
|
|
16
54
|
});
|
|
17
55
|
}
|
|
18
|
-
main().catch((error) => {
|
|
19
|
-
console.error("DevLens failed to start:", error);
|
|
20
|
-
process.exit(1);
|
|
21
|
-
});
|
|
22
56
|
//# sourceMappingURL=cli.js.map
|
package/dist/bin/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":";;;AAEA,8CAA+C;AAC/C,sEAAsE;AAEtE,KAAK,UAAU,IAAI;
|
|
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"}
|