npm - devlens-mcp - Versions diffs - 0.3.2 → 0.3.3 - Mend

devlens-mcp 0.3.2 → 0.3.3

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 (4) hide show

package/INSTALLATION_GUIDE.md CHANGED Viewed

@@ -1,354 +1,3 @@
-# DevLens MCP - Installation Guide for Developers
+# Installation Guide
-## What is DevLens?
-DevLens is a Playwright-style MCP (Model Context Protocol) server that gives AI agents the ability to **see, interact with, and verify** mobile apps running on simulators/emulators. It enables automated React Native development workflows with Figma design verification.
----
-## Prerequisites
-Before installing DevLens, ensure you have:
-- **Node.js** >= 18
-- **For Android**: Android SDK with `adb` in PATH (installed via Android Studio)
-- **For iOS** (macOS only): Xcode with Command Line Tools
-- **React Native**: Metro bundler running (`npx react-native start`)
----
-## Installation Methods
-### Method 1: Cursor IDE (Recommended for Cursor users)
-#### Step 1: Create or Edit MCP Configuration
-Navigate to your project root and create/edit `.cursor/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
-      "env": {
-        "METRO_PORT": "8081",
-        "FIGMA_TOKEN": "figd_xxxxx"
-      }
-    }
-  }
-}
-```
-#### Step 2: Configure Environment Variables
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `METRO_PORT` | No | Metro bundler port (default: 8081) |
-| `FIGMA_TOKEN` | Yes* | Figma personal access token (required for Figma comparison) |
-| `DEVLENS_CONFIG` | No | Path to `devlens.config.json` for design system context |
-| `DEVICE_ID` | No | Target specific device (defaults to first available) |
-*Required only if using `devlens_compare_with_figma`
-#### Step 3: Get Figma Token (if needed)
-1. Go to https://www.figma.com/settings
-2. Scroll to "Personal access tokens"
-3. Click "Create new token"
-4. Give it a name (e.g., "DevLens")
-5. Required scope: **File content: Read**
-6. Copy the token (starts with `figd_`)
-7. Add to `mcp.json` as shown above
-#### Step 4: Restart Cursor
-Close and reopen Cursor IDE. DevLens tools will be available in the AI agent context.
----
-### Method 2: Claude Code CLI (Recommended for Claude Code)
-#### One Command Install:
-```bash
-claude mcp add devlens -- npx devlens-mcp@latest
-```
-This automatically configures DevLens in your Claude Code environment.
-#### Manual Configuration:
-If the command above doesn't work, edit `~/.config/claude/claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
-      "env": {
-        "METRO_PORT": "8081",
-        "FIGMA_TOKEN": "figd_xxxxx"
-      }
-    }
-  }
-}
-```
----
-### Method 3: Claude Desktop App
-#### Step 1: Locate Config File
-**macOS:**
-```
-~/Library/Application Support/Claude/claude_desktop_config.json
-```
-**Windows:**
-```
-%APPDATA%/Claude/claude_desktop_config.json
-```
-**Linux:**
-```
-~/.config/Claude/claude_desktop_config.json
-```
-#### Step 2: Edit Configuration
-```json
-{
-  "mcpServers": {
-    "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
-      "env": {
-        "METRO_PORT": "8081",
-        "FIGMA_TOKEN": "figd_xxxxx"
-      }
-    }
-  }
-}
-```
-#### Step 3: Restart Claude Desktop
-Completely quit and restart the Claude Desktop app.
----
-### Method 4: Local Development (For Contributors)
-If you want to modify DevLens or use it from source:
-```bash
-# Clone the repository
-git clone https://dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
-cd mcp-devlens
-# Install dependencies
-npm install
-# Build the project
-npm run build
-# Auto-register with Claude Code (if installed)
-npm run register
-```
-#### For Cursor (Local Development):
-Create `.cursor/mcp.json` in your project:
-```json
-{
-  "mcpServers": {
-    "devlens": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"],
-      "env": {
-        "METRO_PORT": "8081",
-        "FIGMA_TOKEN": "figd_xxxxx"
-      }
-    }
-  }
-}
-```
-Replace `/absolute/path/to/mcp-devlens` with your actual path.
----
-## Verification
-### Test if DevLens is Working
-1. Start your Android emulator or iOS simulator
-2. Launch your React Native app
-3. In Cursor/Claude, ask the AI: "List running devices"
-4. The AI should use `devlens_list_devices` and show your device
-### Example Commands to Test:
-- "Take a screenshot of the app"
-- "Show me the UI element tree"
-- "What elements are on the screen?"
-- "Compare the current screen with this Figma design: [URL]"
----
-## Configuration Files
-### Design System Context (Optional)
-To enable `devlens_ds_context` for design token awareness, create `devlens.config.json` in your app root:
-```json
-{
-  "designSystem": {
-    "tokensFile": "src/theme/tokens.ts",
-    "componentsDir": "src/components/designSystem",
-    "usagePatterns": {
-      "include": ["src/**/*.tsx"],
-      "exclude": ["node_modules/**", "**/*.test.tsx"]
-    }
-  }
-}
-```
-Then set the environment variable:
-```json
-{
-  "mcpServers": {
-    "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
-      "env": {
-        "DEVLENS_CONFIG": "/absolute/path/to/your/app/devlens.config.json",
-        "METRO_PORT": "8081",
-        "FIGMA_TOKEN": "figd_xxxxx"
-      }
-    }
-  }
-}
-```
----
-## Troubleshooting
-### Issue: "No running simulators or emulators"
-**Solution:** Start a device from Android Studio or Xcode before using DevLens.
-```bash
-# Android
-emulator -avd <your_avd_name>
-# iOS (macOS)
-xcrun simctl boot <device_uuid>
-```
-### Issue: "Could not connect to Metro bundler"
-**Solution:** Ensure Metro is running:
-```bash
-npx react-native start
-```
-Check that `METRO_PORT` matches your Metro port (usually 8081).
-### Issue: "ADB command not found"
-**Solution:** Add Android SDK platform-tools to your PATH:
-```bash
-# Add to ~/.zshrc or ~/.bashrc
-export ANDROID_HOME=$HOME/Library/Android/sdk
-export PATH=$PATH:$ANDROID_HOME/platform-tools
-```
-### Issue: "simctl not found" (iOS)
-**Solution:** Install Xcode Command Line Tools:
-```bash
-xcode-select --install
-```
-### Issue: DevLens tools not showing in Cursor/Claude
-**Solutions:**
-1. Check MCP config file syntax (valid JSON)
-2. Restart Cursor/Claude completely
-3. Check Console/Logs for MCP connection errors
-4. For local development, verify the path is absolute and correct
-5. Run `npx devlens-mcp@latest` in terminal to verify it works standalone
-### Issue: "Invalid token" on Figma compare
-**Solution:**
-- Use a personal access token (starts with `figd_`), not OAuth
-- Required scope: **File content: Read**
-- Generate at https://www.figma.com/settings
-### Issue: "File not exportable" on Figma compare
-**Solution:** In Figma, disable "Prevent viewers from copying and exporting" in share settings.
----
-## What's Next?
-### Basic Workflow
-1. **Check Metro**: Ask AI to check if Metro is healthy
-2. **Take Screenshots**: Capture current app state
-3. **Interact**: Tap buttons, fill forms, navigate
-4. **Verify**: Compare with Figma designs
-5. **Iterate**: Make code changes, hot reload, repeat
-### Advanced Workflows
-- **Figma-to-Code Loop**: Automated design implementation with visual verification
-- **Design System Integration**: Use `devlens_ds_context` for token-aware code generation
-- **Flow Testing**: Use `devlens_capture_flow` for multi-step interaction capture
-- **Layout Debugging**: Per-element comparison scores to pinpoint UI issues
-### Example AI Prompts
-- "Take a screenshot and compare it with this Figma design: [URL]"
-- "Navigate to the login screen and verify all elements are present"
-- "Fill out the registration form with test data"
-- "Show me the design system tokens and components available"
-- "Capture a flow of: tap login → enter credentials → tap submit"
----
-## Support
-- **Documentation**: See [README.md](./README.md) for full tool reference
-- **Issues**: Report issues to your team's Azure DevOps
-- **Updates**: Run `npx devlens-mcp@latest` to always get the latest version
----
-## Quick Reference
-### Available Tools (34 total)
-- **Device Management** (3): list_devices, device_info, set_orientation
-- **App Management** (4): launch_app, terminate_app, install_app, list_apps
-- **Snapshot & Elements** (5): snapshot, find_element, wait_for_element, wait_for_screen, element_info
-- **Interaction** (8): tap, type, swipe, scroll, long_press, press_button, fill_form, capture_flow
-- **Screenshots & Visual** (5): screenshot, compare_screenshot, element_screenshot, compare_images, compare_with_figma
-- **React Native / Metro** (6): metro_status, metro_logs, component_tree, hot_reload, network_requests, dismiss_overlays
-- **Navigation** (2): open_url, go_back
-- **Design System** (1): ds_context
-See full documentation in [README.md](./README.md) for detailed tool descriptions.
+This file has moved. See **[docs/setup-guide.md](./docs/setup-guide.md)** for all installation, configuration, and troubleshooting instructions.

package/QUICK_START.md CHANGED Viewed

@@ -1,153 +1,3 @@
-# DevLens MCP - Quick Start Guide
+# Quick Start
-## 🚀 Pushing Code to Azure DevOps
-### Option 1: Using the Script (Easiest)
-```bash
-./PUSH_COMMANDS.sh
-```
-The script will guide you through:
-1. Generating a Personal Access Token (PAT)
-2. Configuring the remote
-3. Pushing the code
-### Option 2: Manual Steps
-1. **Generate PAT**: Visit https://dev.azure.com/JioOmni/_usersSettings/tokens
-   - Click "New Token"
-   - Name: "DevLens MCP"
-   - Permissions: Code → Read & Write
-   - Copy the token
-2. **Push Code**:
-   ```bash
-   git remote set-url origin https://JioOmni:YOUR_PAT@dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
-   git push -u origin main
-   ```
-3. **Verify**: https://dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
----
-## 👥 How Developers Install DevLens
-### For Cursor IDE Users
-Add to `.cursor/mcp.json` in their project root:
-```json
-{
-  "mcpServers": {
-    "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
-      "env": {
-        "METRO_PORT": "8081",
-        "FIGMA_TOKEN": "figd_xxxxx"
-      }
-    }
-  }
-}
-```
-Then restart Cursor.
-### For Claude Desktop Users
-**macOS**: Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: Edit `%APPDATA%/Claude/claude_desktop_config.json`
-Add the same configuration as above, then restart Claude Desktop.
-### For Claude Code CLI Users
-```bash
-claude mcp add devlens -- npx devlens-mcp@latest
-```
----
-## 🔧 What Developers Need
-### Prerequisites
-- Node.js >= 18
-- Android SDK (for Android) OR Xcode (for iOS on macOS)
-- React Native app with Metro running
-### Environment Variables
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `FIGMA_TOKEN` | Optional* | Figma personal access token (for design comparison) |
-| `METRO_PORT` | No | Default: 8081 |
-| `DEVLENS_CONFIG` | No | Path to design system config |
-*Required only for Figma comparison features
-### Getting Figma Token
-1. Go to https://www.figma.com/settings
-2. Create new token with "File content: Read" scope
-3. Copy token (starts with `figd_`)
-4. Add to MCP config
----
-## 📚 Key Documentation Files
-- **INSTALLATION_GUIDE.md** - Complete installation instructions for all platforms
-- **README.md** - Full tool reference and features
-- **AZURE_DEVOPS_SETUP.md** - Detailed push instructions
-- **docs/setup-guide.md** - Design system configuration
-- **docs/figma-workflow.md** - Figma integration guide
----
-## ✅ Testing the Installation
-After installation, developers can test by asking the AI:
-1. "List running devices" → Should show their emulator/simulator
-2. "Take a screenshot" → Should capture the app screen
-3. "Show the element tree" → Should display UI hierarchy
----
-## 🎯 Key Features to Share
-- **34 Tools** for mobile app automation
-- **Figma Design Comparison** with per-element similarity scores
-- **React Native Integration** with Metro bundler
-- **Playwright-style API** with element references (no coordinate guessing)
-- **Design System Context** for token-aware code generation
-- **Works with Android & iOS**
----
-## 📞 Quick Links
-- **Azure Repo**: https://dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
-- **Figma Settings**: https://www.figma.com/settings
-- **Azure PAT Creation**: https://dev.azure.com/JioOmni/_usersSettings/tokens
----
-## 🐛 Common Issues
-### "No devices found"
-Start emulator/simulator first
-### "Metro not connected"
-Run `npx react-native start`
-### "Invalid Figma token"
-Use personal token (figd_), not OAuth
-### "DevLens tools not showing"
-Restart Cursor/Claude completely
-See INSTALLATION_GUIDE.md for detailed troubleshooting.
+This file has moved. See **[docs/setup-guide.md](./docs/setup-guide.md)** for all installation, configuration, and troubleshooting instructions.

package/docs/setup-guide.md CHANGED Viewed

@@ -1,74 +1,90 @@
 # 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": "npx",
+      "args": ["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.
-Verify:
-```bash
-adb devices
-# Should show your running emulator, e.g.:
-# emulator-5554   device
-```
+> **Getting `env: node: No such file or directory`?** Jump to [Fix: nvm/PATH issue](#fix-nvmpath-issue-env-node-no-such-file-or-directory).
-### 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
 ```
----
-## 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"
-      }
+      "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 `npx`.
+---
-### Option 2: Claude Code
+## 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`)
+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": {
@@ -78,46 +94,60 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
       "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.
 ---
-## Configuration
+## Verify It Works
-### Environment Variables
+Start your emulator/simulator and Metro, then ask your AI:
-Set these in the `env` section of your MCP config, or export them in your shell:
+| 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 |
-| 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 |
+If step 1 works, DevLens is running correctly.
-### Multiple Devices
+---
-If you have multiple emulators/simulators running, DevLens auto-selects the first one. To target a specific device:
+## Figma Token Setup
-1. Run `devlens_list_devices` to see all available devices
-2. Pass `deviceId` to any tool: `devlens_device_info(deviceId: "emulator-5554")`
+Required only for `devlens_compare_with_figma`.
-Or set `DEVICE_ID=emulator-5554` in your environment.
+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
+```
+Add to your MCP config:
+```json
+"env": {
+  "FIGMA_TOKEN": "figd_yourtoken"
+}
+```
+> **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 +165,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": "npx",
+      "args": ["devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx",
@@ -161,189 +189,92 @@ 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
+## Troubleshooting
-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_`
+### Fix: nvm/PATH issue (`env: node: No such file or directory`)
-### Verify the token works
+**This is the most common issue on macOS.** It happens because Cursor (and other GUI apps) don't load your shell profile, so `node` isn't in their PATH even though `npx` works in your terminal.
-```bash
-curl -H "X-Figma-Token: figd_yourtoken" "https://api.figma.com/v1/me"
-# Expected: {"id":"...","email":"you@example.com","handle":"..."}
-```
+**Fix — use the full path to `npx`:**
-### Add to MCP config
+1. Open **Terminal** and run:
+   ```bash
+   which npx
+   ```
+   This prints something like:
+   ```
+   /Users/yourname/.nvm/versions/node/v20.12.2/bin/npx
+   ```
-```json
-"env": {
-  "FIGMA_TOKEN": "figd_yourtoken"
-}
-```
+2. Copy that full path and replace `"command": "npx"` in `~/.cursor/mcp.json`:
+   ```json
+   {
+     "mcpServers": {
+       "devlens": {
+         "command": "/Users/yourname/.nvm/versions/node/v20.12.2/bin/npx",
+         "args": ["devlens-mcp@latest"],
+         "env": {
+           "METRO_PORT": "8081"
+         }
+       }
+     }
+   }
+   ```
-> **Security note:** Never paste your PAT in a chat or commit it to source control. Use environment variables or a secrets manager.
+3. **Restart Cursor.** This fixes it permanently.
 ---
-## 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
+### Fix: "No server info found" / DevLens tools not showing
-### 3. Take a Screenshot
+This means Cursor couldn't start the MCP server. Check these in order:
-> **Say:** *"Take a screenshot of the device"*
->
-> **Tool called:** `devlens_screenshot`
->
-> **Expected:** Device screenshot returned as an inline image
+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.)
-### 4. Take a Snapshot
+2. **Is it `"command": "npx"`?** Not `"command": "node"`. Using `"node"` makes it look for a local file instead of downloading the package.
-> **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
-### 7. Design System Context (optional — requires DEVLENS_CONFIG)
-> **Say:** *"Load the design system context"*
->
-> **Tool called:** `devlens_ds_context`
->
-> **Expected:** Token list, component interfaces, and usage patterns
+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.
-If steps 1–5 succeed, DevLens is fully operational. Steps 6–7 require the optional env vars.
+4. **Restart Cursor completely** (quit and reopen, not just reload window).
 ---
-## Troubleshooting
-### "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
-### "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
-### "ADB command not found"
-- Set `ANDROID_HOME` to your Android SDK path
-- Or add `$ANDROID_HOME/platform-tools` to your PATH
-### iOS "simctl not found"
-- Install Xcode Command Line Tools: `xcode-select --install`
-- Ensure Xcode is installed (not just CLT)
-### 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
-### "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 |
 ---
@@ -362,4 +293,4 @@ DevLens provides **34 tools** across 8 categories:
 | Navigation | open_url, go_back | 2 |
 | Design System | ds_context | 1 |
-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/package.json CHANGED Viewed

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