devlens-mcp 0.3.0 → 0.3.2

package/README.md

@@ -14,26 +14,19 @@ Figma Design  ──►  AI Agent  ──►  Code Changes  ──►  Hot Reloa
 
 ## Quick Start
 
-### Step 1 — Clone and build
-
+### Claude Code
 ```bash
-git clone https://JioOmni@dev.azure.com/JioOmni/OmniAI/_git/mcp-devlens
-cd mcp-devlens
-npm install
-npm run build
+claude mcp add devlens -- npx devlens-mcp@latest
 ```
 
-Note the **absolute path** to the cloned folder — you'll need it in the next step (e.g. `/Users/yourname/mcp-devlens`).
-
-### Step 2 — Add to your AI client
-
-**Cursor IDE** — edit `~/.cursor/mcp.json`:
+### Cursor IDE
+Add to `~/.cursor/mcp.json`:
 ```json
 {
   "mcpServers": {
     "devlens": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"],
+      "command": "npx",
+      "args": ["devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx"
@@ -43,18 +36,14 @@ Note the **absolute path** to the cloned folder — you'll need it in the next s
 }
 ```
 
-**Claude Code**:
-```bash
-claude mcp add devlens -- node /absolute/path/to/mcp-devlens/dist/bin/cli.js
-```
-
-**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+### Claude Desktop
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
     "devlens": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"],
+      "command": "npx",
+      "args": ["devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx"

package/dist/src/server.js

@@ -18,7 +18,7 @@ const navigation_tools_js_1 = require("./tools/navigation-tools.js");
 async function startServer() {
     const server = new index_js_1.Server({
         name: "devlens-mcp",
-        version: "0.3.0",
+        version: "0.3.1",
     }, {
         capabilities: {
             tools: {},

package/docs/setup-guide.md

@@ -42,27 +42,14 @@ 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`:
+### Option 1: Cursor IDE
+Add to `~/.cursor/mcp.json`:
 ```json
 {
   "mcpServers": {
     "devlens": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"],
+      "command": "npx",
+      "args": ["devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx",
@@ -75,26 +62,19 @@ Edit `~/.cursor/mcp.json`:
 
 Restart Cursor after saving. DevLens tools will appear in the MCP tools panel.
 
-#### Claude Code
+### Option 2: Claude Code
 ```bash
-claude mcp add devlens -- node /absolute/path/to/mcp-devlens/dist/bin/cli.js
+claude mcp add devlens -- npx devlens-mcp@latest
 ```
 
-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`:
+### Option 3: Claude Desktop
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
     "devlens": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-devlens/dist/bin/cli.js"],
+      "command": "npx",
+      "args": ["devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx",
@@ -105,7 +85,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-> **Tip:** The `postbuild` script automatically prints the correct `args` path after every build, so you always know the right value to paste.
+> **Note:** `npx` downloads and runs DevLens automatically on first use. No clone or build step needed.
 
 ---
 
@@ -335,10 +315,35 @@ If steps 1–5 succeed, DevLens is fully operational. Steps 6–7 require the op
 - Verify the `tokensFile` path is correct relative to `projectRoot`
 - The tool logs warnings to stderr — check your MCP server logs
 
+### "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.
+
+**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.
+
 ### 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
+- 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
 
 ---
 

package/package.json

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

package/.claude/settings.json

@@ -1,12 +0,0 @@
-{
-  "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

@@ -1,17 +0,0 @@
-{
-  "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/bin/cli.ts

@@ -1,22 +0,0 @@
-#!/usr/bin/env node
-
-import { createServer } from "../src/index.js";
-
-async function main() {
-  const server = await createServer();
-
-  process.on("SIGINT", async () => {
-    await server.close();
-    process.exit(0);
-  });
-
-  process.on("SIGTERM", async () => {
-    await server.close();
-    process.exit(0);
-  });
-}
-
-main().catch((error) => {
-  console.error("DevLens failed to start:", error);
-  process.exit(1);
-});

package/bin/register.ts

@@ -1,96 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * DevLens MCP Registration Script
- *
- * Usage:
- *   node dist/bin/register.js          — Check status + print instructions
- *   node dist/bin/register.js --register — Actually register with Claude Code
- */
-
-import { execFile } from "child_process";
-import { promisify } from "util";
-import { resolve } from "path";
-import { existsSync, readFileSync } from "fs";
-
-const execFileAsync = promisify(execFile);
-
-async function register(): Promise<void> {
-  const cliPath = resolve(__dirname, "cli.js");
-
-  if (!existsSync(cliPath)) {
-    console.error("Error: dist/bin/cli.js not found. Run 'npm run build' first.");
-    process.exit(1);
-  }
-
-  const autoRegister = process.argv.includes("--register");
-
-  // Check common config locations for existing registration
-  const home = process.env.HOME || process.env.USERPROFILE || "~";
-  const configPaths = [
-    resolve(home, ".claude", "mcp.json"),
-    resolve(home, ".claude", "settings.json"),
-    resolve(home, ".config", "claude", "mcp.json"),
-  ];
-
-  let alreadyRegistered = false;
-  for (const configPath of configPaths) {
-    if (existsSync(configPath)) {
-      try {
-        const content = readFileSync(configPath, "utf-8");
-        if (content.includes("devlens")) {
-          alreadyRegistered = true;
-          console.log(`DevLens already registered in: ${configPath}`);
-          break;
-        }
-      } catch {
-        // Ignore read errors
-      }
-    }
-  }
-
-  if (alreadyRegistered) {
-    console.log("DevLens MCP server is already registered. No action needed.");
-    return;
-  }
-
-  const command = `claude mcp add devlens -- node ${cliPath}`;
-
-  if (autoRegister) {
-    console.log("Registering DevLens MCP server...");
-    console.log(`Running: ${command}`);
-    try {
-      const { stdout, stderr } = await execFileAsync("claude", [
-        "mcp",
-        "add",
-        "devlens",
-        "--",
-        "node",
-        cliPath,
-      ]);
-      if (stdout) console.log(stdout);
-      if (stderr) console.error(stderr);
-      console.log("DevLens registered successfully!");
-    } catch (error: any) {
-      console.error(`Registration failed: ${error.message}`);
-      console.log(`\nPlease register manually:\n  ${command}`);
-      process.exit(1);
-    }
-  } else {
-    console.log("");
-    console.log("=== DevLens MCP Registration ===");
-    console.log("");
-    console.log("DevLens is not registered as an MCP tool.");
-    console.log("To register, run one of these commands:");
-    console.log("");
-    console.log(`  npm run register`);
-    console.log(`  # or manually:`);
-    console.log(`  ${command}`);
-    console.log("");
-  }
-}
-
-register().catch((err) => {
-  console.error("Registration error:", err);
-  process.exit(1);
-});

package/src/config/devlens-config.ts

@@ -1,76 +0,0 @@
-import { z } from "zod";
-import { readFile } from "fs/promises";
-import { resolve } from "path";
-
-/**
- * DevLens configuration file support.
- *
- * Loaded from (in priority order):
- *   1. Path pointed to by DEVLENS_CONFIG env var
- *   2. ./devlens.config.json in CWD
- *
- * Place devlens.config.json in your consumer app root and point to it
- * via the MCP env block:
- *
- *   "env": {
- *     "METRO_PORT": "8081",
- *     "FIGMA_TOKEN": "figd_xxx",
- *     "DEVLENS_CONFIG": "/path/to/your-app/devlens.config.json"
- *   }
- */
-
-export const DesignSystemConfigSchema = z.object({
-  /** Design system identifier, e.g. "jds3" */
-  name: z.string(),
-  /** Absolute or CWD-relative path to the consumer app root */
-  projectRoot: z.string(),
-  /** Relative path from projectRoot to the tokens file, e.g. "src/constants/figmaTokens.ts" */
-  tokensFile: z.string(),
-  /** Relative path from projectRoot to the generated component interface directory */
-  componentsDir: z.string().optional(),
-  /** Glob pattern for component source files (default: "src/**\/*.tsx") */
-  componentsGlob: z.string().default("src/**/*.tsx"),
-});
-
-export const DevLensConfigSchema = z.object({
-  designSystem: DesignSystemConfigSchema.optional(),
-});
-
-export type DevLensConfig = z.infer<typeof DevLensConfigSchema>;
-export type DesignSystemConfig = z.infer<typeof DesignSystemConfigSchema>;
-
-/**
- * Load DevLens config from DEVLENS_CONFIG env var path, or ./devlens.config.json in CWD.
- * Returns empty config {} if neither is found or both are invalid.
- * Never throws — invalid config is logged and skipped.
- */
-export async function loadDevLensConfig(): Promise<DevLensConfig> {
-  const candidates: string[] = [];
-
-  const envPath = process.env.DEVLENS_CONFIG;
-  if (envPath) {
-    candidates.push(resolve(envPath));
-  }
-  candidates.push(resolve(process.cwd(), "devlens.config.json"));
-
-  for (const candidate of candidates) {
-    try {
-      const raw = await readFile(candidate, "utf-8");
-      const parsed = JSON.parse(raw);
-      const result = DevLensConfigSchema.safeParse(parsed);
-      if (result.success) {
-        console.error(`[devlens] Config loaded from: ${candidate}`);
-        return result.data;
-      } else {
-        console.error(
-          `[devlens] Config at ${candidate} is invalid:`,
-          JSON.stringify(result.error.format(), null, 2)
-        );
-      }
-    } catch {
-      // File not found or JSON parse error — try next candidate
-    }
-  }
-
-  return {};
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-import { startServer } from "./server.js";
-
-export async function createServer() {
-  return startServer();
-}

package/src/metro/cdp-client.ts

@@ -1,160 +0,0 @@
-import WebSocket from "ws";
-
-/**
- * Chrome DevTools Protocol (CDP) client for communicating with the
- * Metro/Hermes debugger. Connects via WebSocket and sends JSON-RPC messages.
- *
- * Metro exposes the debugger endpoint at:
- *   ws://localhost:{METRO_PORT}/inspector/device?device=0&page=-1
- *
- * Through CDP we can:
- * - Get console logs (Console.enable → Console.messageAdded)
- * - Intercept network requests (Network.enable → Network.requestWillBeSent)
- * - Execute JavaScript in the RN context (Runtime.evaluate)
- * - Trigger hot reload (via Runtime.evaluate)
- */
-
-export interface CdpMessage {
-  id?: number;
-  method?: string;
-  params?: any;
-  result?: any;
-  error?: { message: string; code?: number };
-}
-
-type MessageHandler = (message: CdpMessage) => void;
-
-export class CdpClient {
-  private ws: WebSocket | null = null;
-  private messageId: number = 0;
-  private pendingRequests: Map<
-    number,
-    { resolve: (value: any) => void; reject: (error: Error) => void }
-  > = new Map();
-  private eventHandlers: Map<string, MessageHandler[]> = new Map();
-  private connected: boolean = false;
-
-  constructor(private endpoint: string) {}
-
-  /** Connect to the CDP endpoint */
-  async connect(): Promise<void> {
-    return new Promise((resolve, reject) => {
-      this.ws = new WebSocket(this.endpoint);
-
-      const timeout = setTimeout(() => {
-        reject(new Error(`CDP connection timeout to ${this.endpoint}`));
-      }, 5000);
-
-      this.ws.on("open", () => {
-        clearTimeout(timeout);
-        this.connected = true;
-        resolve();
-      });
-
-      this.ws.on("message", (data: WebSocket.Data) => {
-        try {
-          const message: CdpMessage = JSON.parse(data.toString());
-          this.handleMessage(message);
-        } catch {
-          // Ignore malformed messages
-        }
-      });
-
-      this.ws.on("close", () => {
-        this.connected = false;
-        // Reject all pending requests
-        for (const [, { reject }] of this.pendingRequests) {
-          reject(new Error("CDP connection closed"));
-        }
-        this.pendingRequests.clear();
-      });
-
-      this.ws.on("error", (err) => {
-        clearTimeout(timeout);
-        if (!this.connected) {
-          reject(err);
-        }
-      });
-    });
-  }
-
-  /** Send a CDP command and wait for the response */
-  async send(method: string, params?: any): Promise<any> {
-    if (!this.ws || !this.connected) {
-      throw new Error("CDP client not connected");
-    }
-
-    const id = ++this.messageId;
-    const message = JSON.stringify({ id, method, params });
-
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.pendingRequests.delete(id);
-        reject(new Error(`CDP request timeout: ${method}`));
-      }, 10000);
-
-      this.pendingRequests.set(id, {
-        resolve: (result) => {
-          clearTimeout(timeout);
-          resolve(result);
-        },
-        reject: (error) => {
-          clearTimeout(timeout);
-          reject(error);
-        },
-      });
-
-      this.ws!.send(message);
-    });
-  }
-
-  /** Register an event handler for CDP events */
-  on(method: string, handler: MessageHandler): void {
-    const handlers = this.eventHandlers.get(method) || [];
-    handlers.push(handler);
-    this.eventHandlers.set(method, handlers);
-  }
-
-  /** Remove event handlers for a method */
-  off(method: string): void {
-    this.eventHandlers.delete(method);
-  }
-
-  /** Check if connected */
-  isConnected(): boolean {
-    return this.connected;
-  }
-
-  /** Close the connection */
-  close(): void {
-    if (this.ws) {
-      this.ws.close();
-      this.ws = null;
-      this.connected = false;
-    }
-  }
-
-  private handleMessage(message: CdpMessage): void {
-    // Response to a request
-    if (message.id !== undefined) {
-      const pending = this.pendingRequests.get(message.id);
-      if (pending) {
-        this.pendingRequests.delete(message.id);
-        if (message.error) {
-          pending.reject(new Error(message.error.message));
-        } else {
-          pending.resolve(message.result);
-        }
-      }
-      return;
-    }
-
-    // Event notification
-    if (message.method) {
-      const handlers = this.eventHandlers.get(message.method) || [];
-      for (const handler of handlers) {
-        handler(message);
-      }
-    }
-  }
-}