devlens-mcp 0.3.0

package/docs/setup-guide.md

@@ -0,0 +1,360 @@
+# DevLens Setup Guide
+
+Get DevLens running in under 5 minutes. This guide covers prerequisites, installation, configuration, and verification.
+
+---
+
+## Prerequisites
+
+### 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)
+
+Verify:
+```bash
+adb devices
+# Should show your running emulator, e.g.:
+# emulator-5554   device
+```
+
+### 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)
+```
+
+### For React Native Metro Integration
+1. **Metro bundler** running:
+```bash
+cd your-rn-project
+npx react-native start
+# or
+npx expo start
+```
+
+---
+
+## Installation
+
+### Step 1 — Clone and build
+
+```bash
+git clone https://JioOmni@dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
+cd mcp-devlens
+npm install
+npm run build
+```
+
+This produces `dist/bin/cli.js`. Note the **absolute path** to this file — you'll need it below.
+
+### Step 2 — Register with your AI client
+
+#### Cursor IDE
+Edit `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "devlens": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"],
+      "env": {
+        "METRO_PORT": "8081",
+        "FIGMA_TOKEN": "figd_xxxxx",
+        "DEVLENS_CONFIG": "/path/to/your-app/devlens.config.json"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor after saving. DevLens tools will appear in the MCP tools panel.
+
+#### Claude Code
+```bash
+claude mcp add devlens -- node /absolute/path/to/mcp-devlens/dist/bin/cli.js
+```
+
+Or run the auto-registration helper from the cloned repo:
+```bash
+npm run register
+```
+
+This runs `claude mcp add devlens -- node <absolute-path>/dist/bin/cli.js` for you. If DevLens is already registered, it will detect it and skip.
+
+#### Claude Desktop
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "devlens": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"],
+      "env": {
+        "METRO_PORT": "8081",
+        "FIGMA_TOKEN": "figd_xxxxx",
+        "DEVLENS_CONFIG": "/path/to/your-app/devlens.config.json"
+      }
+    }
+  }
+}
+```
+
+> **Tip:** The `postbuild` script automatically prints the correct `args` path after every build, so you always know the right value to paste.
+
+---
+
+## Configuration
+
+### Environment Variables
+
+Set these in the `env` section of your MCP config, or export them in your shell:
+
+| 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 |
+
+### Multiple Devices
+
+If you have multiple emulators/simulators running, DevLens auto-selects the first one. To target a specific device:
+
+1. Run `devlens_list_devices` to see all available devices
+2. Pass `deviceId` to any tool: `devlens_device_info(deviceId: "emulator-5554")`
+
+Or set `DEVICE_ID=emulator-5554` in your environment.
+
+---
+
+## 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.
+
+### 1. Create `devlens.config.json` in your app root
+
+```json
+{
+  "designSystem": {
+    "name": "jds3",
+    "projectRoot": "/absolute/path/to/your-app",
+    "tokensFile": "src/constants/figmaTokens.ts",
+    "componentsDir": "src/jds-components",
+    "componentsGlob": "src/**/*.tsx"
+  }
+}
+```
+
+| 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` |
+| `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):
+
+```json
+{
+  "mcpServers": {
+    "devlens": {
+      "command": "node",
+      "args": ["/path/to/devlens/dist/bin/cli.js"],
+      "env": {
+        "METRO_PORT": "8081",
+        "FIGMA_TOKEN": "figd_xxxxx",
+        "DEVLENS_CONFIG": "/absolute/path/to/your-app/devlens.config.json"
+      }
+    }
+  }
+}
+```
+
+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`
+
+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
+
+---
+
+## Figma Token Setup
+
+`devlens_compare_with_figma` requires a Figma personal access token (PAT).
+
+### Generate a PAT
+
+1. Go to [figma.com](https://www.figma.com) → your profile icon → **Settings**
+2. Scroll to **Personal access tokens** → **Generate new token**
+3. Give it a name (e.g. `devlens`)
+4. Set scope: **File content → Read** (this is the only scope needed)
+5. Copy the token — it starts with `figd_`
+
+### Verify the token works
+
+```bash
+curl -H "X-Figma-Token: figd_yourtoken" "https://api.figma.com/v1/me"
+# Expected: {"id":"...","email":"you@example.com","handle":"..."}
+```
+
+### Add to MCP config
+
+```json
+"env": {
+  "FIGMA_TOKEN": "figd_yourtoken"
+}
+```
+
+> **Security note:** Never paste your PAT in a chat or commit it to source control. Use environment variables or a secrets manager.
+
+---
+
+## Verifying Setup
+
+After configuration, start a conversation with your AI assistant and try these commands in order:
+
+### 1. Check Metro Health
+
+> **Say:** *"Check if Metro is running"*
+>
+> **Tool called:** `devlens_metro_status`
+>
+> **Expected:** Running: `true`, Port: `8081`
+
+### 2. List Devices
+
+> **Say:** *"List my devices"*
+>
+> **Tool called:** `devlens_list_devices`
+>
+> **Expected:** Your running emulators/simulators listed with IDs
+
+### 3. Take a Screenshot
+
+> **Say:** *"Take a screenshot of the device"*
+>
+> **Tool called:** `devlens_screenshot`
+>
+> **Expected:** Device screenshot returned as an inline image
+
+### 4. Take a Snapshot
+
+> **Say:** *"Take a snapshot of the screen with validation"*
+>
+> **Tool called:** `devlens_snapshot(validate: true)`
+>
+> **Expected:** Accessibility tree with `ref=eN` IDs + validation report
+
+### 5. Test Metro Logs
+
+> **Say:** *"Show me the Metro logs"*
+>
+> **Tool called:** `devlens_metro_logs`
+>
+> **Expected:** Console output from your React Native app
+
+### 6. Compare with Figma (optional — requires FIGMA_TOKEN)
+
+> **Say:** *"Compare the current screen with this Figma frame: [your Figma URL]"*
+>
+> **Tool called:** `devlens_compare_with_figma`
+>
+> **Expected:** Three images (device, Figma reference, diff) + layout region report
+
+### 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
+
+If steps 1–5 succeed, DevLens is fully operational. Steps 6–7 require the optional env vars.
+
+---
+
+## 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"**
+
+### 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
+
+### `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
+
+### DevLens tools not available in AI assistant
+- **npx users:** Verify the MCP config JSON is correct and restart your AI assistant
+- **Local dev:** Run `npm run register` to register with Claude Code
+- Check `~/.claude/mcp.json` or your IDE's MCP config for a `devlens` entry
+
+---
+
+## What's Available
+
+DevLens provides **34 tools** across 8 categories:
+
+| Category | Tools | Count |
+|----------|-------|-------|
+| Device Management | list_devices, device_info, set_orientation | 3 |
+| App Management | launch_app, terminate_app, install_app, list_apps | 4 |
+| Snapshot & Elements | snapshot, find_element, wait_for_element, wait_for_screen, element_info | 5 |
+| Interaction | tap, type, swipe, scroll, long_press, press_button, fill_form, capture_flow | 8 |
+| Screenshots & Visual | screenshot, compare_screenshot, element_screenshot, compare_images, compare_with_figma | 5 |
+| React Native / Metro | metro_status, metro_logs, component_tree, hot_reload, network_requests, dismiss_overlays | 6 |
+| Navigation | open_url, go_back | 2 |
+| Design System | ds_context | 1 |
+
+See the [Tool Reference](./tool-reference.md) for detailed documentation of every tool and parameter.