@synnode/expo-metro-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Sanders
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @synnode/expo-metro-mcp
+
+MCP server that connects to a running Expo/Metro dev server and exposes its logs to Claude Code.
+
+Uses the **Chrome DevTools Protocol (CDP)** inspector endpoint that Metro exposes — the same channel that React Native DevTools uses. Works with Expo SDK 50+ including the new architecture (Bridgeless/JSI).
+
+## Installation
+
+```bash
+cd expo-metro-mcp
+npm install && npm run build
+
+# Register with Claude Code CLI
+claude mcp add expo-metro node /absolute/path/to/expo-metro-mcp/dist/index.js
+```
+
+Restart Claude Code after adding the server.
+
+## Requirements
+
+- Expo / Metro dev server running (`npx expo start`)
+- A device or emulator connected to Metro (the app must be running for logs to appear)
+
+## Configuration
+
+```bash
+# Defaults — only override if needed
+METRO_PORT=8081
+METRO_HOST=localhost
+LOG_BUFFER_SIZE=1000
+```
+
+If Metro runs on a different port:
+
+```bash
+claude mcp add expo-metro --env METRO_PORT=8082 node /path/to/dist/index.js
+```
+
+## Available tools
+
+| Tool | Description |
+|---|---|
+| `get_logs` | Recent logs from the buffer. Optional: `lines`, `level` (`error`/`warn`/`info`/`log`/`debug`), `since` (e.g. `"30s"`, `"2m"`, unix timestamp) |
+| `get_errors` | Errors with stack traces from the buffer. Optional: `lines` |
+| `get_status` | Connection status, device name, and buffer statistics |
+| `clear_logs` | Clear the log buffer |
+| `watch_logs` | Poll for incoming logs for a time window. Optional: `duration` (e.g. `"10s"`, max `"30s"`), `level` |
+| `connect` | Grab the CDP connection from Metro. Use after `disconnect` or when `get_status` shows disconnected |
+| `disconnect` | Release the CDP connection so React Native DevTools can connect freely |
+| `reload` | Reload the React Native app via Metro |
+| `resolve_stack` | Resolve a stack trace against the Metro source map, showing original file/line instead of bundle offsets |
+| `list_devices` | List active iOS simulators and Android emulators |
+| `screenshot` | Take a screenshot of the active simulator/emulator. Returns the image directly. Optional: `platform`, `device_id` |
+| `tap` | Tap at x,y coordinates on the active simulator/emulator. Optional: `platform`, `device_id` |
+| `swipe` | Swipe from one coordinate to another. Optional: `duration_ms`, `platform`, `device_id` |
+
+## Screenshot & UI automation
+
+`screenshot`, `tap`, and `swipe` interact directly with your running simulator or emulator — no extra packages or paid plans needed.
+
+**Requirements:**
+- **iOS screenshots**: macOS with Xcode installed (`xcrun simctl` must be available)
+- **iOS tap/swipe**: `idb` — Facebook's iOS Development Bridge
+  ```bash
+  brew tap facebook/fb && brew install idb-companion
+  pip3 install fb-idb
+  ```
+- **Android**: `adb` in your PATH (part of Android SDK platform-tools) — tap, swipe and screenshot all work out of the box
+
+**Notes:**
+- If multiple devices are running, use `list_devices` to find the ID and pass it via `device_id`
+- Coordinates are in points (iOS logical pixels) or pixels (Android)
+- iOS screenshots work without idb — only tap/swipe require it
+
+## Using alongside React Native DevTools
+
+CDP only allows one client at a time. The MCP server does **not** auto-reconnect, so you can freely switch between it and DevTools:
+
+1. Use `disconnect` to release the connection before opening DevTools
+2. Open React Native DevTools as usual
+3. When done, close DevTools and call `connect` to reattach the MCP server
+
+`get_status` always shows whether the MCP is currently connected.
+
+## How it works
+
+Metro exposes a CDP WebSocket at `/inspector/debug`. On `connect`, the server calls `/json/list` to discover the active device target, then attaches via CDP and enables `Runtime.consoleAPICalled` events. Metro build errors (`build_failed`, `bundling_error`) are captured separately via the `/events` WebSocket, which reconnects automatically.
+
+## Notes
+
+- If Metro is not reachable on startup: the server starts normally, `get_status` returns `connected: false`. Call `connect` once your dev server is up.
+- Memory is bounded by `LOG_BUFFER_SIZE` (circular buffer, oldest entries dropped first).
+- The CDP connection may show an "unsupported debugging client" notice in Metro's terminal — this is harmless.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,1049 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/metro-client.ts
+import WebSocket from "ws";
+import http from "http";
+var METRO_PORT = parseInt(process.env.METRO_PORT ?? "8081", 10);
+var METRO_HOST = process.env.METRO_HOST ?? "localhost";
+var LOG_BUFFER_SIZE = parseInt(process.env.LOG_BUFFER_SIZE ?? "1000", 10);
+var MAX_BACKOFF_MS = 3e4;
+var INITIAL_BACKOFF_MS = 1e3;
+var CDP_TYPE_MAP = {
+  log: "log",
+  info: "info",
+  warning: "warn",
+  warn: "warn",
+  error: "error",
+  debug: "debug",
+  dir: "log",
+  dirxml: "log",
+  table: "log",
+  assert: "error"
+};
+function formatArgs(args) {
+  return args.map((a) => {
+    if (a.value !== void 0 && a.value !== null) return String(a.value);
+    if (a.description) return a.description;
+    return "";
+  }).filter(Boolean).join(" ");
+}
+async function fetchTargets(host, port) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://${host}:${port}/json/list`, (res) => {
+      let body = "";
+      res.on("data", (chunk) => body += chunk);
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(body);
+          if (Array.isArray(parsed)) {
+            resolve(parsed);
+          } else {
+            resolve([]);
+          }
+        } catch {
+          resolve([]);
+        }
+      });
+    });
+    req.on("error", () => resolve([]));
+    req.setTimeout(2e3, () => {
+      req.destroy();
+      resolve([]);
+    });
+  });
+}
+var MetroClient = class {
+  buffer = [];
+  cdpWs = null;
+  eventsWs = null;
+  _connected = false;
+  _currentTargetId = null;
+  _lastConnectedAt = null;
+  _totalReceived = 0;
+  _stopped = false;
+  _eventsBackoff = INITIAL_BACKOFF_MS;
+  _deviceTitle = null;
+  host = METRO_HOST;
+  port = METRO_PORT;
+  get connected() {
+    return this._connected;
+  }
+  get lastConnectedAt() {
+    return this._lastConnectedAt;
+  }
+  get totalReceived() {
+    return this._totalReceived;
+  }
+  get bufferedEntries() {
+    return this.buffer.length;
+  }
+  get deviceTitle() {
+    return this._deviceTitle;
+  }
+  start() {
+    this._stopped = false;
+    this.connectEvents();
+  }
+  stop() {
+    this._stopped = true;
+    if (this.cdpWs) {
+      this.cdpWs.terminate();
+      this.cdpWs = null;
+    }
+    if (this.eventsWs) {
+      this.eventsWs.terminate();
+      this.eventsWs = null;
+    }
+  }
+  disconnect() {
+    if (this.cdpWs) {
+      this.cdpWs.terminate();
+      this.cdpWs = null;
+    }
+    this._connected = false;
+    this._currentTargetId = null;
+    this._deviceTitle = null;
+  }
+  getEntries(options = {}) {
+    let entries = this.buffer;
+    if (options.since !== void 0) {
+      entries = entries.filter((e) => e.timestamp >= options.since);
+    }
+    if (options.level) {
+      entries = entries.filter((e) => e.level === options.level);
+    }
+    const lines = options.lines ?? 50;
+    return entries.slice(-lines);
+  }
+  clearBuffer() {
+    const count = this.buffer.length;
+    this.buffer = [];
+    return count;
+  }
+  async grabConnection() {
+    await this.checkForNewTarget();
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    if (this._connected) {
+      return `Connected to ${this._deviceTitle ?? "device"}.`;
+    }
+    return "No device found. Is Metro running with a connected device?";
+  }
+  addEntry(entry) {
+    this._totalReceived++;
+    this.buffer.push(entry);
+    if (this.buffer.length > LOG_BUFFER_SIZE) {
+      this.buffer.shift();
+    }
+  }
+  async checkForNewTarget() {
+    const targets = await fetchTargets(this.host, this.port);
+    if (!targets.length) {
+      if (this._connected) {
+        this._connected = false;
+        this._currentTargetId = null;
+        this._deviceTitle = null;
+      }
+      return;
+    }
+    const target = targets[0];
+    if (target.id === this._currentTargetId && this.cdpWs?.readyState === WebSocket.OPEN) {
+      return;
+    }
+    this.connectCdp(target);
+  }
+  connectCdp(target) {
+    if (this.cdpWs) {
+      this.cdpWs.terminate();
+      this.cdpWs = null;
+    }
+    this._currentTargetId = target.id;
+    this._deviceTitle = target.title ?? null;
+    const ws = new WebSocket(target.webSocketDebuggerUrl);
+    this.cdpWs = ws;
+    ws.on("open", () => {
+      this._connected = true;
+      this._lastConnectedAt = /* @__PURE__ */ new Date();
+      ws.send(JSON.stringify({ id: 1, method: "Runtime.enable", params: {} }));
+    });
+    ws.on("message", (data) => {
+      let msg;
+      try {
+        msg = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      if (msg.method === "Runtime.consoleAPICalled" && msg.params) {
+        this.handleConsoleEvent(msg.params);
+      }
+    });
+    ws.on("close", () => {
+      if (this.cdpWs === ws) {
+        this._connected = false;
+        this.cdpWs = null;
+        this._currentTargetId = null;
+        this._deviceTitle = null;
+      }
+    });
+    ws.on("error", () => {
+    });
+  }
+  handleConsoleEvent(params) {
+    const type = typeof params.type === "string" ? params.type : "log";
+    const level = CDP_TYPE_MAP[type] ?? "log";
+    const args = Array.isArray(params.args) ? params.args : [];
+    const message = formatArgs(args);
+    const ts = typeof params.timestamp === "number" ? Math.round(params.timestamp) : Date.now();
+    if (!message) return;
+    const stackTrace = params.stackTrace;
+    const rawFrames = stackTrace?.callFrames?.filter((f) => f.url && !f.url.startsWith("native")).map((f) => ({
+      functionName: f.functionName ?? "(anonymous)",
+      url: f.url,
+      line: f.lineNumber ?? 0,
+      col: f.columnNumber ?? 0
+    }));
+    const rawMessage = message.includes("http://") ? message : void 0;
+    this.addEntry({ timestamp: ts, level, message, rawMessage, rawFrames: rawFrames?.length ? rawFrames : void 0 });
+  }
+  // Also listen to /events for Metro build errors (build_failed, bundling_error)
+  connectEvents() {
+    if (this._stopped) return;
+    const url = `ws://${this.host}:${this.port}/events`;
+    let ws;
+    try {
+      ws = new WebSocket(url);
+    } catch {
+      this.scheduleEventsReconnect();
+      return;
+    }
+    this.eventsWs = ws;
+    ws.on("open", () => {
+      this._eventsBackoff = INITIAL_BACKOFF_MS;
+    });
+    ws.on("message", (data) => {
+      let event = null;
+      try {
+        event = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      if (event.type === "build_failed" || event.type === "bundling_error") {
+        this.addEntry({
+          timestamp: Date.now(),
+          level: "error",
+          message: event.message ?? event.type
+        });
+      }
+    });
+    ws.on("close", () => {
+      if (this.eventsWs === ws) {
+        this.eventsWs = null;
+        this.scheduleEventsReconnect();
+      }
+    });
+    ws.on("error", () => {
+    });
+  }
+  scheduleEventsReconnect() {
+    if (this._stopped) return;
+    setTimeout(() => {
+      this._eventsBackoff = Math.min(this._eventsBackoff * 2, MAX_BACKOFF_MS);
+      this.connectEvents();
+    }, this._eventsBackoff);
+  }
+};
+var metroClient = new MetroClient();
+
+// src/tools/get-logs.ts
+import { z } from "zod";
+
+// src/tools/format.ts
+var BUNDLE_URL_RE = /\(https?:\/\/[^)]+\.bundle[^)]*:(\d+:\d+)\)/g;
+function cleanMessage(message) {
+  return message.replace(BUNDLE_URL_RE, "(:$1)");
+}
+function formatTime(ts) {
+  const d = new Date(ts);
+  const hh = String(d.getHours()).padStart(2, "0");
+  const mm = String(d.getMinutes()).padStart(2, "0");
+  const ss = String(d.getSeconds()).padStart(2, "0");
+  return `${hh}:${mm}:${ss}`;
+}
+
+// src/tools/get-logs.ts
+var GetLogsSchema = z.object({
+  lines: z.coerce.number().int().min(1).max(500).optional().default(50),
+  level: z.enum(["error", "warn", "info", "log", "debug"]).optional(),
+  since: z.string().optional()
+});
+function parseSince(since) {
+  const asNum = Number(since);
+  if (!isNaN(asNum) && asNum > 1e9) {
+    return asNum < 1e12 ? asNum * 1e3 : asNum;
+  }
+  const match = since.match(/^(\d+(?:\.\d+)?)(s|m|h)$/);
+  if (match) {
+    const value = parseFloat(match[1]);
+    const unit = match[2];
+    const multipliers = { s: 1e3, m: 6e4, h: 36e5 };
+    return Date.now() - value * multipliers[unit];
+  }
+  return asNum;
+}
+function getLogs(params) {
+  const since = params.since ? parseSince(params.since) : void 0;
+  const entries = metroClient.getEntries({
+    lines: params.lines,
+    level: params.level,
+    since
+  });
+  if (entries.length === 0) {
+    return "No log entries found.";
+  }
+  return entries.map((e) => `[${formatTime(e.timestamp)}] [${e.level.toUpperCase()}] ${cleanMessage(e.message)}`).join("\n");
+}
+
+// src/tools/get-errors.ts
+import { z as z2 } from "zod";
+var GetErrorsSchema = z2.object({
+  lines: z2.coerce.number().int().min(1).max(200).optional().default(20)
+});
+function getErrors(params) {
+  const entries = metroClient.getEntries({ level: "error", lines: params.lines });
+  if (entries.length === 0) {
+    return "No errors in buffer.";
+  }
+  return entries.map((e) => `[${formatTime(e.timestamp)}] [ERROR]
+${cleanMessage(e.message)}`).join("\n\n---\n\n");
+}
+
+// src/tools/get-status.ts
+function getStatus() {
+  const status = {
+    connected: metroClient.connected,
+    host: metroClient.host,
+    port: metroClient.port,
+    device: metroClient.deviceTitle,
+    buffered_entries: metroClient.bufferedEntries,
+    last_connected_at: metroClient.lastConnectedAt?.toISOString() ?? null,
+    total_received: metroClient.totalReceived,
+    expo_sdk_version: null
+  };
+  return JSON.stringify(status, null, 2);
+}
+
+// src/tools/clear-logs.ts
+function clearLogs() {
+  const count = metroClient.clearBuffer();
+  return `Cleared ${count} log ${count === 1 ? "entry" : "entries"} from the buffer.`;
+}
+
+// src/tools/watch-logs.ts
+import { z as z3 } from "zod";
+var WatchLogsSchema = z3.object({
+  duration: z3.string().optional().default("10s"),
+  level: z3.enum(["error", "warn", "info", "log", "debug"]).optional()
+});
+function parseDurationMs(duration) {
+  const match = duration.match(/^(\d+(?:\.\d+)?)(s|m)$/);
+  if (!match) return 1e4;
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+  const ms = unit === "m" ? value * 6e4 : value * 1e3;
+  return Math.min(ms, 3e4);
+}
+var POLL_INTERVAL_MS = 500;
+async function watchLogs(params) {
+  if (!metroClient.connected) {
+    return "Metro is not connected. Start Expo dev server and try again.";
+  }
+  const durationMs = parseDurationMs(params.duration);
+  const startBufferSize = metroClient.bufferedEntries;
+  const startTime = Date.now();
+  const levelFilter = params.level;
+  await new Promise((resolve) => {
+    const interval = setInterval(() => {
+      if (Date.now() - startTime >= durationMs) {
+        clearInterval(interval);
+        resolve();
+      }
+    }, POLL_INTERVAL_MS);
+  });
+  const all = metroClient.getEntries({ lines: metroClient.bufferedEntries });
+  const newEntries = all.slice(startBufferSize);
+  const filtered = levelFilter ? newEntries.filter((e) => e.level === levelFilter) : newEntries;
+  if (filtered.length === 0) {
+    return `No logs received during ${params.duration} window.`;
+  }
+  return filtered.map((e) => `[${formatTime(e.timestamp)}] [${e.level.toUpperCase()}] ${cleanMessage(e.message)}`).join("\n");
+}
+
+// src/tools/reload.ts
+import http2 from "http";
+var METRO_PORT2 = parseInt(process.env.METRO_PORT ?? "8081", 10);
+var METRO_HOST2 = process.env.METRO_HOST ?? "localhost";
+async function reload() {
+  return new Promise((resolve) => {
+    const req = http2.request(
+      { hostname: METRO_HOST2, port: METRO_PORT2, path: "/reload", method: "POST" },
+      (res) => {
+        res.resume();
+        if (res.statusCode === 200) {
+          resolve("App reloaded.");
+        } else {
+          resolve(`Reload failed: HTTP ${res.statusCode}`);
+        }
+      }
+    );
+    req.on("error", (e) => resolve(`Reload failed: ${e.message}`));
+    req.setTimeout(3e3, () => {
+      req.destroy();
+      resolve("Reload failed: timeout");
+    });
+    req.end();
+  });
+}
+
+// src/tools/resolve-stack.ts
+import { z as z4 } from "zod";
+import http3 from "http";
+import { SourceMapConsumer } from "source-map";
+var ResolveStackSchema = z4.object({
+  message: z4.string().optional()
+});
+var cache = /* @__PURE__ */ new Map();
+var CACHE_TTL_MS = 6e4;
+function toLocalhostUrl(url, host, port) {
+  return url.replace(/^https?:\/\/[^/]+/, `http://${host}:${port}`);
+}
+function toSourceMapUrl(bundleUrl) {
+  const paramsMatch = bundleUrl.match(/(?:\/\/&|\?)(.+)$/);
+  const params = paramsMatch ? paramsMatch[1] : "dev=true&minify=false";
+  const mapBase = bundleUrl.replace(/(\/[^/?]+)\.bundle.*$/, "$1.map");
+  return `${mapBase}?${params}`;
+}
+async function fetchSourceMap(mapUrl) {
+  const cached = cache.get(mapUrl);
+  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+    return cached.consumer;
+  }
+  return new Promise((resolve) => {
+    const url = new URL(mapUrl);
+    const req = http3.get({ hostname: url.hostname, port: Number(url.port) || 8081, path: url.pathname + url.search }, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", async () => {
+        if (res.statusCode !== 200) {
+          resolve(null);
+          return;
+        }
+        try {
+          const raw = JSON.parse(Buffer.concat(chunks).toString());
+          const consumer = await SourceMapConsumer.with(raw, null, (c) => c);
+          cache.set(mapUrl, { consumer, fetchedAt: Date.now() });
+          resolve(consumer);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.setTimeout(1e4, () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+function invalidateSourceMapCache() {
+  cache.forEach((v) => v.consumer.destroy());
+  cache.clear();
+}
+function parseMessageFrames(rawMessage) {
+  const re = /at\s+([\w$.<>[\] ]+?)\s+\((https?:\/\/[^)]+\.bundle[^)]*):(\d+):(\d+)\)/g;
+  const frames = [];
+  let m;
+  while ((m = re.exec(rawMessage)) !== null) {
+    frames.push({
+      functionName: m[1].trim(),
+      url: m[2],
+      line: parseInt(m[3]) - 1,
+      // convert to 0-indexed
+      col: parseInt(m[4])
+    });
+  }
+  return frames;
+}
+async function resolveFrames(frames, fallbackMapUrl) {
+  const lines = [];
+  const byMap = /* @__PURE__ */ new Map();
+  for (const frame of frames) {
+    const local = toLocalhostUrl(frame.url, metroClient.host, metroClient.port);
+    const mapUrl = toSourceMapUrl(local);
+    if (!byMap.has(mapUrl)) byMap.set(mapUrl, []);
+    byMap.get(mapUrl).push(frame);
+  }
+  const consumers = /* @__PURE__ */ new Map();
+  await Promise.all([...byMap.keys()].map(async (mapUrl) => {
+    consumers.set(mapUrl, await fetchSourceMap(mapUrl));
+  }));
+  for (const frame of frames) {
+    const local = toLocalhostUrl(frame.url, metroClient.host, metroClient.port);
+    const mapUrl = toSourceMapUrl(local);
+    const consumer = consumers.get(mapUrl) ?? null;
+    if (consumer) {
+      const pos = consumer.originalPositionFor({ line: frame.line + 1, column: frame.col });
+      if (pos.source) {
+        const src = pos.source.replace(/^.*\/\/\//, "").replace(/\?.*$/, "");
+        lines.push(`  at ${frame.functionName} (${src}:${pos.line}:${pos.column})`);
+        continue;
+      }
+    }
+    lines.push(`  at ${frame.functionName} (:${frame.line + 1}:${frame.col})`);
+  }
+  return lines;
+}
+async function resolveStack(params) {
+  const errors = metroClient.getEntries({ level: "error", lines: 50 });
+  const entry = params.message ? [...errors].reverse().find((e) => e.message.includes(params.message)) : errors.at(-1);
+  if (!entry) return "No error entries in buffer.";
+  const errorTitle = `[ERROR] ${entry.message.split("\n")[0]}`;
+  if (!entry.rawMessage) {
+    return `${errorTitle}
+
+No stack frames available.`;
+  }
+  const allFrames = parseMessageFrames(entry.rawMessage);
+  if (!allFrames.length) return `${errorTitle}
+
+No stack frames available.`;
+  const resolvedLines = await resolveFrames(allFrames);
+  const userLines = resolvedLines.filter(
+    (line) => !line.includes("node_modules") && !line.includes("(:")
+    // strip unresolved bundle offsets
+  );
+  const output = [errorTitle, ""];
+  if (userLines.length) {
+    output.push(...userLines);
+  } else {
+    output.push(...resolvedLines);
+  }
+  return output.join("\n");
+}
+
+// src/tools/screenshot.ts
+import { z as z5 } from "zod";
+import { execSync as execSync2 } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+// src/tools/devices.ts
+import { execSync } from "child_process";
+function runCommand(cmd) {
+  try {
+    return execSync(cmd, { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+  } catch {
+    return "";
+  }
+}
+function isCommandAvailable(cmd) {
+  try {
+    execSync(`which ${cmd}`, { timeout: 2e3, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function listIOSDevices() {
+  if (!isCommandAvailable("xcrun")) return [];
+  const output = runCommand("xcrun simctl list devices booted --json");
+  if (!output) return [];
+  try {
+    const json = JSON.parse(output);
+    const devices = [];
+    for (const [, sims] of Object.entries(json.devices)) {
+      for (const sim of sims) {
+        if (sim.state === "Booted") {
+          devices.push({ id: sim.udid, name: sim.name, platform: "ios" });
+        }
+      }
+    }
+    return devices;
+  } catch {
+    return [];
+  }
+}
+function listAndroidDevices() {
+  if (!isCommandAvailable("adb")) return [];
+  const output = runCommand("adb devices -l");
+  if (!output) return [];
+  const devices = [];
+  const lines = output.split("\n").slice(1);
+  for (const line of lines) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 2 || parts[1] !== "device") continue;
+    const id = parts[0];
+    const modelMatch = line.match(/model:(\S+)/);
+    const name = modelMatch ? modelMatch[1].replace(/_/g, " ") : id;
+    devices.push({ id, name, platform: "android" });
+  }
+  return devices;
+}
+function listAllDevices() {
+  return [...listIOSDevices(), ...listAndroidDevices()];
+}
+function pickDevice(platform, deviceId) {
+  const all = listAllDevices();
+  if (!all.length) return null;
+  if (deviceId) {
+    return all.find((d) => d.id === deviceId || d.name.toLowerCase().includes(deviceId.toLowerCase())) ?? null;
+  }
+  if (platform === "ios") {
+    return all.find((d) => d.platform === "ios") ?? null;
+  }
+  if (platform === "android") {
+    return all.find((d) => d.platform === "android") ?? null;
+  }
+  return all.find((d) => d.platform === "ios") ?? all[0];
+}
+
+// src/tools/screenshot.ts
+var ScreenshotSchema = z5.object({
+  device_id: z5.string().optional(),
+  platform: z5.enum(["ios", "android"]).optional()
+});
+function getIosScaleFactor(imagePath) {
+  try {
+    const output = execSync2(`sips -g pixelWidth -g pixelHeight "${imagePath}"`, {
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).toString();
+    const widthMatch = output.match(/pixelWidth:\s*(\d+)/);
+    const heightMatch = output.match(/pixelHeight:\s*(\d+)/);
+    if (!widthMatch || !heightMatch) return 1;
+    const pixelWidth = parseInt(widthMatch[1]);
+    const pixelHeight = parseInt(heightMatch[1]);
+    const longSide = Math.max(pixelWidth, pixelHeight);
+    if (longSide >= 2500 && pixelWidth % 3 === 0) return 3;
+    if (longSide >= 2500) return 3;
+    if (longSide >= 1334) return 2;
+    return 1;
+  } catch {
+    return 1;
+  }
+}
+function captureIOS(deviceId, outputPath) {
+  execSync2(`xcrun simctl io "${deviceId}" screenshot "${outputPath}"`, {
+    timeout: 1e4,
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  const scale = getIosScaleFactor(outputPath);
+  if (scale > 1) {
+    try {
+      const sipsOut = execSync2(`sips -g pixelWidth -g pixelHeight "${outputPath}"`, {
+        timeout: 5e3,
+        stdio: ["ignore", "pipe", "ignore"]
+      }).toString();
+      const wMatch = sipsOut.match(/pixelWidth:\s*(\d+)/);
+      const hMatch = sipsOut.match(/pixelHeight:\s*(\d+)/);
+      if (wMatch && hMatch) {
+        const logicalWidth = Math.round(parseInt(wMatch[1]) / scale);
+        const logicalHeight = Math.round(parseInt(hMatch[1]) / scale);
+        const resizedPath = outputPath.replace(".png", "-points.png");
+        execSync2(`sips -z ${logicalHeight} ${logicalWidth} "${outputPath}" --out "${resizedPath}"`, {
+          timeout: 1e4,
+          stdio: "ignore"
+        });
+        fs.renameSync(resizedPath, outputPath);
+      }
+    } catch {
+    }
+  }
+}
+function captureAndroid(deviceId, outputPath) {
+  const tmpDevice = `/sdcard/mcp_screenshot_${Date.now()}.png`;
+  execSync2(`adb -s "${deviceId}" shell screencap -p "${tmpDevice}"`, {
+    timeout: 1e4,
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  execSync2(`adb -s "${deviceId}" pull "${tmpDevice}" "${outputPath}"`, {
+    timeout: 1e4,
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  execSync2(`adb -s "${deviceId}" shell rm "${tmpDevice}"`, {
+    timeout: 5e3,
+    stdio: "ignore"
+  });
+}
+function screenshot(params) {
+  const devices = listAllDevices();
+  if (!devices.length) {
+    return {
+      type: "text",
+      text: "No active simulators or emulators found. Start a simulator (iOS) or emulator (Android) first."
+    };
+  }
+  const device = pickDevice(params.platform, params.device_id);
+  if (!device) {
+    return {
+      type: "text",
+      text: `No matching device found. Available: ${devices.map((d) => `${d.name} (${d.platform})`).join(", ")}`
+    };
+  }
+  const outputPath = path.join(os.tmpdir(), `expo-mcp-screenshot-${Date.now()}.png`);
+  try {
+    if (device.platform === "ios") {
+      captureIOS(device.id, outputPath);
+    } else {
+      captureAndroid(device.id, outputPath);
+    }
+    const imageData = fs.readFileSync(outputPath).toString("base64");
+    fs.unlinkSync(outputPath);
+    return {
+      type: "image",
+      data: imageData,
+      mimeType: "image/png"
+    };
+  } catch (err) {
+    try {
+      fs.unlinkSync(outputPath);
+    } catch {
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return { type: "text", text: `Screenshot failed: ${msg}` };
+  }
+}
+
+// src/tools/tap.ts
+import { z as z6 } from "zod";
+import { execSync as execSync3 } from "child_process";
+
+// src/tools/idb-companion.ts
+import { spawn } from "child_process";
+var companionProcess = null;
+var companionUdid = null;
+function ensureIdbCompanion(udid) {
+  if (companionProcess && !companionProcess.killed && companionUdid === udid) {
+    return;
+  }
+  if (companionProcess && !companionProcess.killed) {
+    companionProcess.kill();
+  }
+  companionProcess = spawn("idb_companion", ["--udid", udid], {
+    detached: false,
+    stdio: "ignore"
+  });
+  companionUdid = udid;
+  companionProcess.on("exit", () => {
+    companionProcess = null;
+    companionUdid = null;
+  });
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 800);
+}
+process.on("exit", () => companionProcess?.kill());
+process.on("SIGTERM", () => {
+  companionProcess?.kill();
+  process.exit(0);
+});
+process.on("SIGINT", () => {
+  companionProcess?.kill();
+  process.exit(0);
+});
+
+// src/tools/tap.ts
+var TapSchema = z6.object({
+  x: z6.number().int().describe("X coordinate in points/pixels"),
+  y: z6.number().int().describe("Y coordinate in points/pixels"),
+  device_id: z6.string().optional(),
+  platform: z6.enum(["ios", "android"]).optional()
+});
+var SwipeSchema = z6.object({
+  x1: z6.number().int(),
+  y1: z6.number().int(),
+  x2: z6.number().int(),
+  y2: z6.number().int(),
+  duration_ms: z6.number().int().min(50).max(5e3).optional().default(300),
+  device_id: z6.string().optional(),
+  platform: z6.enum(["ios", "android"]).optional()
+});
+function isIdbAvailable() {
+  try {
+    execSync3("which idb", { timeout: 2e3, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function tapIOS(deviceId, x, y) {
+  if (isIdbAvailable()) {
+    ensureIdbCompanion(deviceId);
+    execSync3(`idb ui tap ${x} ${y} --udid "${deviceId}"`, {
+      timeout: 5e3,
+      stdio: ["ignore", "ignore", "pipe"]
+    });
+    return;
+  }
+  const touchJson = JSON.stringify({ touches: [{ x, y, action: "began" }] });
+  try {
+    execSync3(`echo '${touchJson}' | xcrun simctl io "${deviceId}" sendtouchJSON -`, {
+      timeout: 5e3,
+      stdio: ["pipe", "ignore", "pipe"]
+    });
+    return;
+  } catch {
+  }
+  throw new Error(
+    `iOS tap requires idb (Facebook iOS Development Bridge).
+Install via: brew install idb-companion && pip3 install fb-idb
+Or: brew install facebook/fb/idb-companion`
+  );
+}
+function tapAndroid(deviceId, x, y) {
+  execSync3(`adb -s "${deviceId}" shell input tap ${x} ${y}`, {
+    timeout: 5e3,
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+}
+function swipeIOS(deviceId, x1, y1, x2, y2, durationMs) {
+  if (isIdbAvailable()) {
+    ensureIdbCompanion(deviceId);
+    const durationSec = (durationMs / 1e3).toFixed(2);
+    execSync3(`idb ui swipe ${x1} ${y1} ${x2} ${y2} ${durationSec} --udid "${deviceId}"`, {
+      timeout: durationMs + 5e3,
+      stdio: ["ignore", "ignore", "pipe"]
+    });
+    return;
+  }
+  throw new Error(
+    `iOS swipe requires idb (Facebook iOS Development Bridge).
+Install via: brew install idb-companion && pip3 install fb-idb`
+  );
+}
+function swipeAndroid(deviceId, x1, y1, x2, y2, durationMs) {
+  execSync3(`adb -s "${deviceId}" shell input swipe ${x1} ${y1} ${x2} ${y2} ${durationMs}`, {
+    timeout: 1e4,
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+}
+function tap(params) {
+  const devices = listAllDevices();
+  if (!devices.length) {
+    return "No active simulators or emulators found.";
+  }
+  const device = pickDevice(params.platform, params.device_id);
+  if (!device) {
+    return `No matching device found. Available: ${devices.map((d) => `${d.name} (${d.platform})`).join(", ")}`;
+  }
+  try {
+    if (device.platform === "ios") {
+      tapIOS(device.id, params.x, params.y);
+    } else {
+      tapAndroid(device.id, params.x, params.y);
+    }
+    return `Tapped (${params.x}, ${params.y}) on ${device.name} [${device.platform}].`;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `Tap failed: ${msg}`;
+  }
+}
+function swipe(params) {
+  const devices = listAllDevices();
+  if (!devices.length) {
+    return "No active simulators or emulators found.";
+  }
+  const device = pickDevice(params.platform, params.device_id);
+  if (!device) {
+    return `No matching device found. Available: ${devices.map((d) => `${d.name} (${d.platform})`).join(", ")}`;
+  }
+  try {
+    if (device.platform === "ios") {
+      swipeIOS(device.id, params.x1, params.y1, params.x2, params.y2, params.duration_ms);
+      return `Swiped from (${params.x1}, ${params.y1}) to (${params.x2}, ${params.y2}) on ${device.name} [ios]. Note: iOS swipe simulation is limited \u2014 use Android for reliable swipe gestures.`;
+    } else {
+      swipeAndroid(device.id, params.x1, params.y1, params.x2, params.y2, params.duration_ms);
+      return `Swiped from (${params.x1}, ${params.y1}) to (${params.x2}, ${params.y2}) on ${device.name} [android] over ${params.duration_ms}ms.`;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `Swipe failed: ${msg}`;
+  }
+}
+
+// src/tools/list-devices.ts
+function listDevices() {
+  const devices = listAllDevices();
+  if (!devices.length) {
+    return "No active simulators or emulators found.\n\n- iOS: start a simulator via Xcode or `xcrun simctl boot <device>`\n- Android: start an emulator via Android Studio or `emulator -avd <name>`";
+  }
+  const lines = devices.map((d) => `- ${d.name} [${d.platform}]  id: ${d.id}`);
+  return `Active devices (${devices.length}):
+${lines.join("\n")}`;
+}
+
+// src/index.ts
+var server = new McpServer({
+  name: "expo-metro-mcp",
+  version: "0.1.0"
+});
+server.registerTool(
+  "get_logs",
+  {
+    description: "Fetch recent logs from the Metro dev server buffer. Supports filtering by level and time.",
+    inputSchema: GetLogsSchema.shape
+  },
+  async (params) => {
+    const result = getLogs(params);
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "get_errors",
+  {
+    description: "Fetch recent errors from the Metro dev server buffer, with stack traces.",
+    inputSchema: GetErrorsSchema.shape
+  },
+  async (params) => {
+    const result = getErrors(params);
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "get_status",
+  {
+    description: "Check the connection status of the Metro dev server and buffer statistics."
+  },
+  async () => {
+    const result = getStatus();
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "connect",
+  {
+    description: "Grab the CDP connection to the Metro dev server. Use this if get_status shows disconnected, or to take over the connection from React Native DevTools."
+  },
+  async () => {
+    const result = await metroClient.grabConnection();
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "disconnect",
+  {
+    description: "Release the CDP connection so React Native DevTools can connect. Use this before switching to DevTools. Call connect when you want to reattach."
+  },
+  async () => {
+    metroClient.disconnect();
+    return { content: [{ type: "text", text: "Disconnected. DevTools can now connect freely." }] };
+  }
+);
+server.registerTool(
+  "clear_logs",
+  {
+    description: "Clear the internal log buffer. Useful after resolving an issue."
+  },
+  async () => {
+    const result = clearLogs();
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "watch_logs",
+  {
+    description: "Listen for incoming logs for a short time window and return all collected entries.",
+    inputSchema: WatchLogsSchema.shape
+  },
+  async (params) => {
+    const result = await watchLogs(params);
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "reload",
+  {
+    description: "Reload the React Native app via Metro."
+  },
+  async () => {
+    invalidateSourceMapCache();
+    const result = await reload();
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "resolve_stack",
+  {
+    description: "Resolve a stack trace from the buffer against the Metro source map, showing original file:line instead of bundle offsets. Optionally filter by error message substring.",
+    inputSchema: ResolveStackSchema.shape
+  },
+  async (params) => {
+    const result = await resolveStack(params);
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "list_devices",
+  {
+    description: "List active iOS simulators and Android emulators. Use this to find available devices before taking screenshots or sending taps."
+  },
+  async () => {
+    const result = listDevices();
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "screenshot",
+  {
+    description: "Take a screenshot of the active iOS simulator or Android emulator. Returns the image directly. Optionally specify platform ('ios' or 'android') or device_id if multiple devices are running.",
+    inputSchema: ScreenshotSchema.shape
+  },
+  async (params) => {
+    const result = screenshot(params);
+    if (result.type === "image") {
+      return { content: [{ type: "image", data: result.data, mimeType: result.mimeType }] };
+    }
+    return { content: [{ type: "text", text: result.text }] };
+  }
+);
+server.registerTool(
+  "tap",
+  {
+    description: "Tap at x,y coordinates on the active simulator/emulator. Use screenshot first to determine coordinates. iOS requires idb (brew install idb-companion && pip3 install fb-idb). Android works via adb out of the box. Optionally specify platform or device_id.",
+    inputSchema: TapSchema.shape
+  },
+  async (params) => {
+    const result = tap(params);
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+server.registerTool(
+  "swipe",
+  {
+    description: "Swipe from one coordinate to another. Requires idb on iOS (brew install idb-companion && pip3 install fb-idb). Android works via adb out of the box. Useful for scrolling lists or dismissing sheets.",
+    inputSchema: SwipeSchema.shape
+  },
+  async (params) => {
+    const result = swipe(params);
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+async function main() {
+  metroClient.start();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.on("SIGINT", () => {
+    metroClient.stop();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    metroClient.stop();
+    process.exit(0);
+  });
+}
+main().catch((err) => {
+  process.stderr.write(`Fatal error: ${err}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@synnode/expo-metro-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Expo/React Native development — live logs, stack trace resolution, and simulator/emulator automation via CDP and platform CLIs.",
+  "type": "module",
+  "bin": {
+    "expo-metro-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "expo",
+    "react-native",
+    "metro",
+    "simulator",
+    "emulator",
+    "ios",
+    "android",
+    "debugging",
+    "claude",
+    "ai"
+  ],
+  "author": "Michael Sanders",
+  "license": "MIT",
+  "homepage": "https://github.com/Synnode/expo-metro-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Synnode/expo-metro-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Synnode/expo-metro-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "source-map": "^0.7.6",
+    "ws": "^8.18.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}