devlens-mcp 0.3.0

package/.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git remote set-url origin \"https://JioOmni@dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens\")",
+      "Bash(git add README.md docs/setup-guide.md)",
+      "Bash(PAT=\"9Myzk2VeYmr8RfL9i7uJbfQvMWnqy7M5NVkB8cIDEB2u9njYt19yJQQJ99CBACAAAAAUmMaZAAASAZDO1XcC\")",
+      "Bash(GIT_TERMINAL_PROMPT=0 git -c credential.helper= pull --rebase origin main)",
+      "Bash(GIT_TERMINAL_PROMPT=0 git -c credential.helper= push -u origin main)",
+      "Bash(npm whoami)"
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(wc:*)",
+      "Bash(npx tsc:*)",
+      "Bash(sips:*)",
+      "Bash(npm run build)",
+      "Bash(npm run register)",
+      "Bash(claude mcp list)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:developers.figma.com)",
+      "WebFetch(domain:sharp.pixelplumbing.com)",
+      "WebFetch(domain:forum.figma.com)",
+      "Bash(ls /Users/siddhant1.singh/StudioProjects/devlens/*.md)"
+    ]
+  }
+}

package/INSTALLATION_GUIDE.md

@@ -0,0 +1,354 @@
+# DevLens MCP - Installation Guide for Developers
+
+## 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.

package/QUICK_START.md

@@ -0,0 +1,153 @@
+# DevLens MCP - Quick Start Guide
+
+## 🚀 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.