expo-agent-bridge 0.1.0

package/dist/server.js

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startAgentBridgeMcpServer = startAgentBridgeMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+function startAgentBridgeMcpServer(options = {}) {
+    const PLUGIN_NAME = options.pluginName ?? process.env.EXPO_AGENT_BRIDGE_PLUGIN ?? 'expo-agent-bridge';
+    const METRO_PORT = options.metroPort ?? Number(process.env.EXPO_METRO_PORT ?? 8081);
+    const PROTOCOL_VERSION = 1;
+    const COMMAND_TIMEOUT_MS = options.commandTimeoutMs ?? 30000;
+    let commandSeq = 0;
+    const pendingCommands = new Map();
+    // ─── In-memory log buffer ───────────────────────────────────────────────────
+    const recentLogs = [];
+    const MAX_LOGS = 100;
+    function addLog(entry) {
+        if (!entry)
+            return;
+        recentLogs.push(entry);
+        if (recentLogs.length > MAX_LOGS)
+            recentLogs.shift();
+    }
+    // ─── DevTools Plugin WebSocket connection ───────────────────────────────────
+    let ws = null;
+    let wsReady = false;
+    let connectionPromise = null;
+    const browserClientId = Date.now().toString();
+    function packMessage(method, payload) {
+        const messageKey = { pluginName: PLUGIN_NAME, method };
+        return JSON.stringify({ messageKey, payload });
+    }
+    function unpackMessage(data) {
+        if (typeof data === 'string')
+            return JSON.parse(data);
+        return null;
+    }
+    function sendHandshake() {
+        ws.send(JSON.stringify({
+            __isHandshakeMessages: true,
+            protocolVersion: PROTOCOL_VERSION,
+            pluginName: PLUGIN_NAME,
+            method: 'handshake',
+            browserClientId,
+        }));
+    }
+    function connectToMetro() {
+        if (connectionPromise)
+            return connectionPromise;
+        connectionPromise = new Promise((resolve, reject) => {
+            const url = `ws://localhost:${METRO_PORT}/expo-dev-plugins/broadcast`;
+            process.stderr.write(`[expo-agent-bridge] Connecting to ${url}\n`);
+            ws = new WebSocket(url);
+            ws.addEventListener('open', () => {
+                wsReady = true;
+                sendHandshake();
+                process.stderr.write('[expo-agent-bridge] Connected to DevTools broadcast channel ✓\n');
+                resolve();
+            });
+            ws.addEventListener('message', (event) => {
+                const raw = event.data;
+                let msg;
+                try {
+                    msg = unpackMessage(typeof raw === 'string' ? raw : raw.toString());
+                }
+                catch {
+                    return;
+                }
+                if (!msg)
+                    return;
+                if (msg.__isHandshakeMessages)
+                    return;
+                const { messageKey, payload } = msg;
+                if (!messageKey || messageKey.pluginName !== PLUGIN_NAME)
+                    return;
+                // Real-time log/error streamed from app
+                if (messageKey.method === 'log') {
+                    addLog(payload);
+                    return;
+                }
+                if (messageKey.method !== 'result')
+                    return;
+                const pending = pendingCommands.get(payload?.id);
+                if (!pending)
+                    return;
+                clearTimeout(pending.timer);
+                pendingCommands.delete(payload.id);
+                if (payload.error) {
+                    pending.reject(new Error(payload.error));
+                }
+                else {
+                    pending.resolve(payload);
+                }
+            });
+            ws.addEventListener('close', () => {
+                wsReady = false;
+                connectionPromise = null;
+                ws = null;
+                process.stderr.write('[expo-agent-bridge] DevTools connection closed — will reconnect on next tool call\n');
+                for (const [id, pending] of pendingCommands) {
+                    clearTimeout(pending.timer);
+                    pending.reject(new Error('Connection closed while waiting for phone response'));
+                    pendingCommands.delete(id);
+                }
+            });
+            ws.addEventListener('error', (e) => {
+                process.stderr.write(`[expo-agent-bridge] WS error: ${e?.message ?? 'connection failed'}\n`);
+                connectionPromise = null;
+                reject(e);
+            });
+        });
+        return connectionPromise;
+    }
+    async function sendCommand(action, params = {}) {
+        try {
+            await connectToMetro();
+        }
+        catch (e) {
+            throw new Error(`Cannot connect to Metro dev server on port ${METRO_PORT}. ` +
+                `Make sure 'npx expo start' is running. (${e.message})`);
+        }
+        if (!wsReady) {
+            throw new Error('DevTools connection not ready. Is expo running and the dev app open on phone/simulator?');
+        }
+        // The app-side DevTools listener needs a brief moment after the broadcast
+        // handshake before it can reliably receive the first command. The direct
+        // CLI uses the same delay; keeping both transports aligned avoids a
+        // first-call race in MCP clients.
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        const id = String(++commandSeq);
+        const cmd = { id, action, ...params };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pendingCommands.delete(id);
+                const lastError = recentLogs.slice().reverse().find((l) => l.level === 'error');
+                let msg = `Timed out after ${COMMAND_TIMEOUT_MS / 1000}s waiting for phone response. Is the dev app open?`;
+                if (lastError) {
+                    msg += `\n[Recent App Error]: ${lastError.message}`;
+                    if (lastError.stack)
+                        msg += `\n${lastError.stack}`;
+                }
+                reject(new Error(msg));
+            }, COMMAND_TIMEOUT_MS);
+            pendingCommands.set(id, { resolve, reject, timer });
+            ws.send(packMessage('command', cmd));
+        });
+    }
+    function triggerMetroReload() {
+        return new Promise((resolve) => {
+            try {
+                const reloadWs = new WebSocket(`ws://localhost:${METRO_PORT}/message`);
+                reloadWs.addEventListener('open', () => {
+                    reloadWs.send(JSON.stringify({ version: 2, method: 'reload' }));
+                    setTimeout(() => {
+                        try {
+                            reloadWs.close();
+                        }
+                        catch { }
+                        resolve();
+                    }, 300);
+                });
+                reloadWs.addEventListener('error', () => resolve());
+            }
+            catch {
+                resolve();
+            }
+        });
+    }
+    // ─── MCP Server ─────────────────────────────────────────────────────────────
+    const mcp = new mcp_js_1.McpServer({ name: 'expo-agent-bridge', version: '0.1.0' });
+    mcp.tool('get_screenshot', 'Capture the current mobile screen as a PNG. Returns base64 image data. If the app crashed or timed out, recent error logs will be included.', {}, async () => {
+        const res = await sendCommand('screenshot');
+        if (!res.data)
+            throw new Error('No image data returned from app.');
+        return { content: [{ type: 'image', data: res.data, mimeType: 'image/png' }] };
+    });
+    mcp.tool('get_logs', 'Get recent console errors, warnings, and unhandled exceptions streamed from the app.', {
+        level: zod_1.z.enum(['error', 'warn', 'all']).optional().describe('Filter by log level (default: "all")'),
+        limit: zod_1.z.number().optional().describe('Maximum entries to return (default: 30)'),
+    }, async ({ level = 'all', limit = 30 }) => {
+        let logs = recentLogs;
+        if (level === 'error')
+            logs = logs.filter((l) => l.level === 'error');
+        else if (level === 'warn')
+            logs = logs.filter((l) => l.level === 'error' || l.level === 'warn');
+        const entries = logs.slice(-limit);
+        if (entries.length === 0) {
+            return { content: [{ type: 'text', text: 'No logs recorded.' }] };
+        }
+        const text = entries
+            .map((e) => {
+            const time = new Date(e.timestamp).toLocaleTimeString();
+            let s = `[${time}] [${e.level.toUpperCase()}] ${e.message}`;
+            if (e.stack)
+                s += `\n${e.stack}`;
+            return s;
+        })
+            .join('\n\n');
+        return { content: [{ type: 'text', text }] };
+    });
+    mcp.tool('reload', 'Reload the app bundle on the phone. Triggers both Metro reload broadcast and in-app DevSettings.reload.', {}, async () => {
+        await triggerMetroReload();
+        try {
+            await sendCommand('reload');
+        }
+        catch { }
+        return { content: [{ type: 'text', text: 'App reload triggered successfully.' }] };
+    });
+    mcp.tool('get_route', 'Get the current active route, pathname, and segments from Expo Router.', {}, async () => {
+        const res = await sendCommand('get_route');
+        return { content: [{ type: 'text', text: JSON.stringify(res.route, null, 2) }] };
+    });
+    mcp.tool('get_elements', 'List all currently mounted interactive UI elements (testIDs, titles, types) on screen.', {}, async () => {
+        const res = await sendCommand('get_elements');
+        const elements = res.elements || [];
+        if (elements.length === 0) {
+            return { content: [{ type: 'text', text: 'No interactive elements registered on current screen.' }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(elements, null, 2) }] };
+    });
+    mcp.tool('get_state', 'Inspect app custom state or stores exposed to the bridge.', {}, async () => {
+        const res = await sendCommand('get_state');
+        if (res.error)
+            throw new Error(res.error);
+        return { content: [{ type: 'text', text: JSON.stringify(res.state, null, 2) }] };
+    });
+    mcp.tool('reset_storage', 'Clear AsyncStorage on the device to test clean first-time install experience.', {}, async () => {
+        const res = await sendCommand('reset_storage');
+        if (res.error)
+            throw new Error(res.error);
+        return { content: [{ type: 'text', text: 'AsyncStorage cleared.' }] };
+    });
+    mcp.tool('open_dev_menu', 'Open the developer menu on the phone without shaking the device.', {}, async () => {
+        try {
+            await sendCommand('open_dev_menu');
+        }
+        catch { }
+        return { content: [{ type: 'text', text: 'Developer menu triggered.' }] };
+    });
+    mcp.tool('navigate', 'Navigate to an Expo Router route in the app.', { route: zod_1.z.string().describe('Route path (e.g. "/settings")') }, async ({ route }) => {
+        await sendCommand('navigate', { route });
+        return { content: [{ type: 'text', text: `Navigated to ${route}` }] };
+    });
+    mcp.tool('tap', 'Tap an element by its testID prop.', { target: zod_1.z.string().describe('testID of the element') }, async ({ target }) => {
+        const res = await sendCommand('tap', { target });
+        if (!res.success)
+            throw new Error(`Element "${target}" not found or has no onPress.`);
+        return { content: [{ type: 'text', text: `Tapped "${target}"` }] };
+    });
+    mcp.tool('scroll', 'Scroll the active scroll view up or down.', {
+        direction: zod_1.z.enum(['up', 'down']),
+        amount: zod_1.z.number().optional().describe('Pixels to scroll (default 300)'),
+    }, async ({ direction, amount = 300 }) => {
+        await sendCommand('scroll', { direction, amount });
+        return { content: [{ type: 'text', text: `Scrolled ${direction} ${amount}px` }] };
+    });
+    mcp.tool('type_text', 'Type text into a TextInput by testID.', {
+        target: zod_1.z.string().describe('testID of TextInput'),
+        text: zod_1.z.string().describe('Text to type'),
+    }, async ({ target, text }) => {
+        const res = await sendCommand('type', { target, text });
+        if (!res.success)
+            throw new Error(`Input "${target}" not found or has no onChangeText handler.`);
+        return { content: [{ type: 'text', text: `Typed "${text}" into "${target}"` }] };
+    });
+    async function run() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await mcp.connect(transport);
+        process.stderr.write(`[expo-agent-bridge] MCP server running. DevTools plugin: ${PLUGIN_NAME}, Metro port: ${METRO_PORT}\n`);
+    }
+    run().catch((e) => {
+        process.stderr.write(`[expo-agent-bridge] fatal: ${e.message}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "expo-agent-bridge",
+  "version": "0.1.0",
+  "description": "Autonomous AI coding agent bridge for Expo and React Native apps. Live visual feedback, logs, navigation, and element interaction without cables.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "expo-agent-bridge": "bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test test/**/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "expo",
+    "react-native",
+    "ai",
+    "agent",
+    "mcp",
+    "devtools",
+    "ui-ux",
+    "antigravity",
+    "cursor",
+    "claude-code",
+    "windsurf"
+  ],
+  "author": "Fs02",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Fs02/expo-agent-bridge"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.24.0 || ^4.0.0"
+  },
+  "peerDependencies": {
+    "@expo/devtools": ">=50.0.0",
+    "expo": ">=50.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.73.0",
+    "react-native-view-shot": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-router": {
+      "optional": true
+    },
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.2.0 || ^19.0.0",
+    "@types/react-native": "^0.73.0",
+    "typescript": "^5.3.0"
+  }
+}

package/skills/expo-agent-bridge/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: expo-agent-bridge
+description: >-
+  Use when doing UI/UX work on Expo & React Native apps. Teaches how to use the agent
+  dev bridge to see live mobile screens, stream console logs & errors, and interact over Wi-Fi or
+  WSL+--tunnel — screenshot, logs, reload, navigate, tap, scroll — no cables.
+---
+
+# Expo Agent Dev Bridge
+
+Live visual feedback and interactive UI loop for React Native & Expo apps.
+Uses Expo's DevTools Plugin broadcast channel — zero native cables, zero extra tunnels, works over WSL.
+
+## Server Ownership
+
+Assume the developer already started Expo/Metro and has the dev app open. Attach to that existing
+server first; do **not** run `expo start`, restart Metro, or create a second dev server unless the
+developer explicitly asks. If the bridge cannot connect, report the connection failure and ask the
+developer to start or expose the server.
+
+## Transport fallback
+
+Use the MCP tools when they are available. If an MCP call is unavailable, times
+out, or cannot reach the Expo server, immediately use the equivalent direct CLI
+command below. Do not create a temporary JavaScript client. Both transports use
+the same `expo-agent-bridge` protocol and control the same running app.
+
+## Direct CLI Commands
+
+For one-off shell actions, use the installed CLI instead of creating a temporary
+JavaScript client:
+
+```bash
+npx --no-install expo-agent-bridge screenshot /tmp/screen.png
+npx --no-install expo-agent-bridge logs
+npx --no-install expo-agent-bridge navigate /settings
+npx --no-install expo-agent-bridge scroll down 300
+```
+
+If multiple Expo apps are running, each app must use a distinct Metro port. For
+example, initialize this project with `npx --no-install expo-agent-bridge init
+--metro-port 8082` and start Expo with `npx expo start --port 8082`.
+
+| CLI command | Description |
+|---|---|
+| `screenshot [file]` | Captures the current mobile screen as a PNG |
+| `logs` | Streams recent errors, warnings, and exceptions |
+| `reload` | Reloads the app bundle on the device |
+| `route` | Returns the current route |
+| `elements` | Lists mounted interactive elements |
+| `state` | Inspects custom app state |
+| `reset-storage` | Clears AsyncStorage |
+| `dev-menu` | Opens the developer menu |
+| `navigate <route>` | Navigates to an Expo Router route |
+| `tap <testID>` | Presses an element by test ID |
+| `scroll <up\|down> [amount]` | Scrolls the active view |
+| `type-text <testID> <text>` | Types into a TextInput |
+
+## Standard Agentic UI/UX Loop
+
+1. `get_screenshot()` — observe current screen
+2. Edit code
+3. Wait 3s for Fast Refresh (or call `reload()` if stuck)
+4. `get_screenshot()` — verify visual changes
+5. Iterate or commit