nerve-mcp 0.1.0 → 0.2.0

package/dist/index.js

@@ -42,253 +42,95 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const ws_1 = __importDefault(require("ws"));
 const child_process_1 = require("child_process");
-const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-// --- Discovery ---
-function discoverSimulatorTargets() {
-    const dir = "/tmp/nerve-ports";
-    if (!fs.existsSync(dir))
-        return [];
-    const targets = [];
-    for (const file of fs.readdirSync(dir)) {
-        if (!file.endsWith(".json"))
-            continue;
-        try {
-            const info = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
-            // Check if process is still alive
-            try {
-                process.kill(info.pid, 0);
-            }
-            catch {
-                // Process is dead, clean up stale file
-                fs.unlinkSync(path.join(dir, file));
-                continue;
-            }
-            targets.push({
-                id: `sim:${info.udid}:${info.bundleId}`,
-                platform: "simulator",
-                bundleId: info.bundleId,
-                appName: info.appName,
-                port: info.port,
-                host: "127.0.0.1",
-                udid: info.udid,
-                connected: false,
-            });
-        }
-        catch {
-            // Skip malformed files
-        }
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+// --- Port Resolution ---
+// djb2 hash — must match the Swift side exactly
+function nervePort(udid, bundleId) {
+    const key = `${udid}-${bundleId}`;
+    let hash = 5381;
+    for (let i = 0; i < key.length; i++) {
+        hash = ((hash << 5) + hash + key.charCodeAt(i)) >>> 0; // djb2, unsigned 32-bit
     }
-    return targets;
+    return 10000 + (hash % 55000);
 }
-function discoverBonjourTargets() {
-    // Use dns-sd to browse for _nerve._tcp services (non-blocking check)
-    try {
-        // Quick one-shot browse with timeout
-        const result = (0, child_process_1.execSync)('dns-sd -B _nerve._tcp . 2>/dev/null & PID=$!; sleep 1; kill $PID 2>/dev/null; wait $PID 2>/dev/null', { timeout: 3000, encoding: "utf-8" });
-        const targets = [];
-        for (const line of result.split("\n")) {
-            const match = line.match(/Nerve-(\S+)/);
-            if (match) {
-                // Resolve would need another dns-sd call. For MVP, skip and rely on
-                // manual connection or iproxy.
-            }
+// Track the active target (set by nerve_run, or auto-detected from booted sims)
+let activeTarget = null;
+let requestCounter = 0;
+function resolvePort(targetId) {
+    if (targetId) {
+        // targetId format: "sim:{udid}:{bundleId}"
+        const parts = targetId.split(":");
+        if (parts.length >= 3 && parts[0] === "sim") {
+            return nervePort(parts[1], parts.slice(2).join(":"));
         }
-        return targets;
+        throw new Error(`Unknown target format: ${targetId}`);
     }
-    catch {
-        return [];
+    if (!activeTarget) {
+        throw new Error("No active target. Use nerve_run to launch an app first, or specify a target.");
     }
+    return nervePort(activeTarget.udid, activeTarget.bundleId);
 }
-// --- WebSocket Connection ---
-class NerveConnection {
-    targets = new Map();
-    pendingRequests = new Map();
-    requestCounter = 0;
-    async discover() {
-        const simTargets = discoverSimulatorTargets();
-        const bonjourTargets = discoverBonjourTargets();
-        const all = [...simTargets, ...bonjourTargets];
-        for (const target of all) {
-            const existing = this.targets.get(target.id);
-            if (!existing) {
-                // New target
-                this.targets.set(target.id, target);
-                this.connect(target);
-            }
-            else if (!existing.connected && target.port !== existing.port) {
-                // App restarted on a new port — reconnect
-                console.error(`[nerve] Re-discovered ${target.appName} on port ${target.port} (was ${existing.port})`);
-                existing.port = target.port;
-                // Cancel pending reconnect timer
-                const timer = this.reconnectTimers.get(target.id);
-                if (timer) {
-                    clearTimeout(timer);
-                    this.reconnectTimers.delete(target.id);
-                }
-                this.connect(existing);
-            }
-            else if (!existing.connected && !existing.ws) {
-                // Same port but disconnected — try reconnecting
-                const timer = this.reconnectTimers.get(target.id);
-                if (!timer) {
-                    this.connect(existing);
-                }
-            }
-        }
-        return all;
-    }
-    connect(target) {
-        const url = `ws://${target.host}:${target.port}`;
+async function send(command, params = {}, targetId, timeoutMs = 30000) {
+    const port = resolvePort(targetId);
+    const url = `ws://127.0.0.1:${port}`;
+    const id = `req_${++requestCounter}`;
+    return new Promise((resolve, reject) => {
         const ws = new ws_1.default(url);
-        let pingInterval;
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                ws.terminate();
+                reject(new Error(`Command '${command}' timed out after ${timeoutMs / 1000}s`));
+            }
+        }, timeoutMs);
         ws.on("open", () => {
-            target.ws = ws;
-            target.connected = true;
-            console.error(`[nerve] Connected to ${target.appName} (${target.platform})`);
-            // Health check: ping every 30s, force-close if no pong within 10s
-            pingInterval = setInterval(() => {
-                if (ws.readyState !== ws_1.default.OPEN)
-                    return;
-                let pongReceived = false;
-                ws.once("pong", () => { pongReceived = true; });
-                ws.ping();
-                setTimeout(() => {
-                    if (!pongReceived && ws.readyState === ws_1.default.OPEN) {
-                        console.error(`[nerve] No pong from ${target.appName} — forcing reconnect`);
-                        ws.terminate();
-                    }
-                }, 10000);
-            }, 30000);
+            ws.send(JSON.stringify({ id, command, params }));
         });
         ws.on("message", (data) => {
             try {
                 const response = JSON.parse(data.toString());
-                const pending = this.pendingRequests.get(response.id);
-                if (pending) {
-                    clearTimeout(pending.timer);
-                    this.pendingRequests.delete(response.id);
-                    if (response.ok) {
-                        pending.resolve(response.data);
-                    }
-                    else {
-                        pending.reject(new Error(response.data));
-                    }
+                if (response.id === id && !settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    ws.close();
+                    if (response.ok)
+                        resolve(response.data);
+                    else
+                        reject(new Error(response.data));
                 }
             }
-            catch {
-                // Ignore malformed messages
+            catch { /* ignore malformed */ }
+        });
+        ws.on("error", (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error(`Connection error: ${err.message}`));
             }
         });
         ws.on("close", () => {
-            if (pingInterval)
-                clearInterval(pingInterval);
-            target.connected = false;
-            target.ws = undefined;
-            console.error(`[nerve] Disconnected from ${target.appName}`);
-            this.scheduleReconnect(target);
-        });
-        ws.on("error", () => {
-            if (pingInterval)
-                clearInterval(pingInterval);
-            target.connected = false;
-            target.ws = undefined;
-            this.scheduleReconnect(target);
-        });
-    }
-    reconnectTimers = new Map();
-    scheduleReconnect(target, attempt = 0) {
-        // Don't schedule if already pending
-        if (this.reconnectTimers.has(target.id))
-            return;
-        // Give up after 60 attempts (~2 minutes)
-        if (attempt > 60) {
-            console.error(`[nerve] Gave up reconnecting to ${target.appName}`);
-            this.targets.delete(target.id);
-            return;
-        }
-        const delay = Math.min(2000, 500 + attempt * 200);
-        const timer = setTimeout(() => {
-            // Re-read port file — app may have restarted on a new port
-            if (target.platform === "simulator" && target.udid) {
-                const portFile = path.join("/tmp/nerve-ports", `${target.udid}-${target.bundleId}.json`);
-                try {
-                    const info = JSON.parse(fs.readFileSync(portFile, "utf-8"));
-                    try {
-                        process.kill(info.pid, 0);
-                    }
-                    catch {
-                        // Process dead and port file stale — wait for new one
-                        this.reconnectTimers.delete(target.id);
-                        this.scheduleReconnect(target, attempt + 1);
-                        return;
-                    }
-                    if (info.port !== target.port) {
-                        console.error(`[nerve] ${target.appName} restarted on port ${info.port} (was ${target.port})`);
-                        target.port = info.port;
-                    }
-                }
-                catch {
-                    // Port file gone — wait for app to write a new one
-                    this.reconnectTimers.delete(target.id);
-                    this.scheduleReconnect(target, attempt + 1);
-                    return;
-                }
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error("Connection closed before response"));
             }
-            this.reconnectTimers.delete(target.id);
-            this.connect(target);
-        }, delay);
-        this.reconnectTimers.set(target.id, timer);
-    }
-    getTarget(targetId) {
-        if (targetId) {
-            return this.targets.get(targetId);
-        }
-        // Auto-select if only one connected target
-        const connected = Array.from(this.targets.values()).filter(t => t.connected);
-        if (connected.length === 1)
-            return connected[0];
-        return undefined;
-    }
-    getConnectedTargets() {
-        return Array.from(this.targets.values()).filter(t => t.connected);
-    }
-    async send(command, params = {}, targetId) {
-        const target = this.getTarget(targetId);
-        if (!target?.ws || !target.connected) {
-            // Try discovery first
-            await this.discover();
-            const retryTarget = this.getTarget(targetId);
-            if (!retryTarget?.ws || !retryTarget.connected) {
-                const connected = this.getConnectedTargets();
-                if (connected.length === 0) {
-                    throw new Error("No Nerve instance found. Make sure your iOS app is running with Nerve.start() or launched via `nerve launch`.");
-                }
-                if (connected.length > 1 && !targetId) {
-                    const list = connected.map(t => `  ${t.id} — ${t.appName} (${t.platform})`).join("\n");
-                    throw new Error(`Multiple targets connected. Specify 'target' parameter:\n${list}`);
-                }
-                throw new Error("Target not found or not connected.");
-            }
-            return this.sendToTarget(retryTarget, command, params);
-        }
-        return this.sendToTarget(target, command, params);
-    }
-    sendToTarget(target, command, params) {
-        return new Promise((resolve, reject) => {
-            const id = `req_${++this.requestCounter}`;
-            const timer = setTimeout(() => {
-                this.pendingRequests.delete(id);
-                reject(new Error(`Command '${command}' timed out after 10s`));
-            }, 10000);
-            this.pendingRequests.set(id, { resolve, reject, timer });
-            const msg = JSON.stringify({ id, command, params });
-            target.ws.send(msg);
         });
-    }
+    });
+}
+function tcpProbe(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(timeoutMs);
+        socket.on("connect", () => { socket.destroy(); resolve(true); });
+        socket.on("error", () => { socket.destroy(); resolve(false); });
+        socket.on("timeout", () => { socket.destroy(); resolve(false); });
+        socket.connect(port, host);
+    });
 }
 // --- MCP Server ---
-const connection = new NerveConnection();
 const server = new index_js_1.Server({ name: "nerve", version: "0.1.0" }, {
     capabilities: { tools: {} },
     instructions: `Nerve is an in-process iOS automation framework. It lets you see, interact with, and inspect a running iOS app from within the app's process.
@@ -320,7 +162,7 @@ The tap= coordinate is the center point where the element is reliably hittable.
 - nerve_back to go back, nerve_dismiss to close modals/keyboard.
 - nerve_map to see all discovered screens. nerve_navigate to auto-navigate to a known screen.
 - nerve_deeplink to open a URL scheme directly.
-- After navigation, call nerve_view to see the new screen.
+- Interaction commands (tap, scroll, type, swipe, back, dismiss) automatically return the updated screen state — no need to call nerve_view after them.
 
 ### Interact
 - nerve_tap to press buttons and select items. Use @eN refs or #id.
@@ -334,14 +176,15 @@ The tap= coordinate is the center point where the element is reliably hittable.
 - Note: auto-wait after actions only covers UI settling (animations, transitions). For network completion, use nerve_wait_idle or nerve_network explicitly.
 
 ### Verify
-- nerve_view to see updated screen state.
+- nerve_view to see updated screen state — this is your PRIMARY inspection tool. It returns structured element data with refs, identifiers, and tap coordinates you can act on directly.
 - nerve_console with filter="[nerve]" and since="last_action" for your trace logs.
-- nerve_screenshot for visual confirmation.
+- Do NOT use nerve_screenshot unless nerve_view is insufficient (e.g., verifying colors, gradients, or visual layout). When you must screenshot, ALWAYS crop to the relevant element: nerve_screenshot with element="#my-element" instead of capturing the full screen.
 - nerve_heap to inspect live objects (e.g., check ViewModel state).
 
 ### Tips
 - Always call nerve_view before interacting — don't guess element identifiers.
 - Use @eN refs from nerve_view output to tap elements without identifiers.
+- nerve_view is lightweight (~1 line per element) and gives you everything needed to interact. NEVER use nerve_screenshot when nerve_view can answer the question.
 - If an element isn't visible, try nerve_scroll_to_find before giving up.
 - The navigation map builds automatically and persists across sessions.
 - Do NOT add sleep/delay between commands — Nerve handles waiting automatically.
@@ -384,7 +227,7 @@ const TOOLS = [
     },
     {
         name: "nerve_tap",
-        description: "Tap a UI element to press buttons, select items, navigate, or focus text fields. Use #identifier (most reliable), @label (by visible text), or x,y coordinates.",
+        description: "Tap a UI element. Response includes the updated screen state (auto-view), so you do NOT need to call nerve_view after tapping. Use #identifier, @label, or x,y coordinates.",
         inputSchema: {
             type: "object",
             properties: {
@@ -529,12 +372,16 @@ const TOOLS = [
     },
     {
         name: "nerve_screenshot",
-        description: "Capture a screenshot of the current screen. Returns base64-encoded PNG.",
+        description: "Capture a screenshot. WARNING: Screenshots consume significant tokens — use nerve_view for all normal inspection. Only use for visual checks (colors, gradients, images, layout). Use 'element' to crop to a specific element (cheapest), or 'region' to crop to a normalized area. Avoid full-screen screenshots when possible.",
         inputSchema: {
             type: "object",
             properties: {
                 target: { type: "string" },
+                element: { type: "string", description: "Crop to a specific element. Use @eN ref, #identifier, or @label from nerve_view. This is the most token-efficient way to verify visual appearance." },
+                region: { type: "string", description: "Crop to a normalized region: \"x1,y1,x2,y2\" where values are 0-1. Example: \"0,0,0.5,0.5\" for top-left quarter." },
+                padding: { type: "number", description: "Padding in points around the element crop. Default: 20." },
                 scale: { type: "number", description: "Image scale. Default: 1.0." },
+                maxDimension: { type: "number", description: "Resize so longest side fits within this value (in points). Example: 800. Overrides scale when set." },
             },
         },
     },
@@ -687,7 +534,7 @@ const TOOLS = [
     },
     {
         name: "nerve_run",
-        description: "Build, install, and launch an iOS app on the simulator. The app must include the Nerve SPM package. After launching, call nerve_view to see the initial screen, then navigate and interact as needed.",
+        description: "Build, install, and launch an iOS app on the simulator. Nerve is auto-injected if the app doesn't include it via SPM — no code changes needed. After launching, call nerve_view to see the initial screen.",
         inputSchema: {
             type: "object",
             properties: {
@@ -749,6 +596,41 @@ const TOOLS = [
             required: ["simulator"],
         },
     },
+    {
+        name: "nerve_appearance",
+        description: "Switch between light and dark mode. On simulator, uses simctl. On device or if Nerve is connected, overrides the app's window trait collection.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mode: { type: "string", enum: ["dark", "light", "toggle"], description: "Appearance mode. 'toggle' switches from current." },
+                target: { type: "string" },
+            },
+            required: ["mode"],
+        },
+    },
+    {
+        name: "nerve_run_device",
+        description: "Build, install, and launch an iOS app on a connected physical device. Requires the device to be paired and a valid code signing identity.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                scheme: { type: "string", description: "Xcode scheme to build." },
+                workspace: { type: "string", description: "Path to .xcworkspace (optional)." },
+                project: { type: "string", description: "Path to .xcodeproj (optional)." },
+                device: { type: "string", description: "Device name or UDID. If omitted, uses the first available paired device." },
+                team: { type: "string", description: "Apple Development Team ID for code signing (optional if set in Xcode project)." },
+            },
+            required: ["scheme"],
+        },
+    },
+    {
+        name: "nerve_list_devices",
+        description: "List connected physical iOS devices and their state (available/unavailable).",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
     {
         name: "nerve_trace",
         description: "Trace method calls at runtime via swizzling. Logs every invocation to the console (read with nerve_console). Zero overhead compared to LLDB breakpoints. Use this to understand code flow without rebuilding.",
@@ -809,6 +691,36 @@ const TOOLS = [
             required: [],
         },
     },
+    {
+        name: "nerve_sequence",
+        description: "Execute multiple Nerve commands in a single call. Much faster than calling tools one-by-one because it eliminates round-trip delays between steps. Each step waits for UI to settle before the next runs. Returns the result of each step. Use this when you already know the sequence of actions to perform (e.g., tap tab → tap row → type text → submit).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: { type: "string", description: "Target ID. Auto-selects if only one connected." },
+                steps: {
+                    type: "array",
+                    description: "Array of commands to execute in order.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            command: {
+                                type: "string",
+                                description: "Nerve command: tap, type, scroll, swipe, back, dismiss, view, double_tap, long_press, context_menu, drag_drop, pull_to_refresh, pinch, scroll_to_find, wait_idle, inspect, screenshot",
+                            },
+                            params: {
+                                type: "object",
+                                description: "Parameters for the command (e.g., {\"query\": \"#login-btn\"} for tap, {\"text\": \"hello\"} for type).",
+                                additionalProperties: true,
+                            },
+                        },
+                        required: ["command"],
+                    },
+                },
+            },
+            required: ["steps"],
+        },
+    },
 ];
 // --- LLDB Session (Mac-side) ---
 class LLDBSession {
@@ -930,35 +842,24 @@ async function handleLLDB(params) {
     }
     // Auto-attach if not already connected
     if (!lldbSession.isAttached()) {
-        // Find PID from Nerve port files
-        let pid;
-        const targets = connection.getConnectedTargets();
-        if (targets.length > 0 && targets[0].udid) {
-            const portFile = `/tmp/nerve-ports/${targets[0].udid}-${targets[0].bundleId}.json`;
-            if (fs.existsSync(portFile)) {
-                const info = JSON.parse(fs.readFileSync(portFile, "utf-8"));
-                pid = info.pid;
-            }
+        if (!activeTarget) {
+            return {
+                content: [{ type: "text", text: "Error: No running app found. Launch the app first with nerve_run." }],
+                isError: true,
+            };
         }
-        if (!pid) {
-            // Try any port file
-            const dir = "/tmp/nerve-ports";
-            if (fs.existsSync(dir)) {
-                const files = fs.readdirSync(dir).filter(f => f.endsWith(".json"));
-                for (const file of files) {
-                    try {
-                        const info = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
-                        process.kill(info.pid, 0); // Check alive
-                        pid = info.pid;
-                        break;
-                    }
-                    catch { }
-                }
-            }
+        // Find PID by bundle ID from simctl
+        let pid;
+        try {
+            const out = await runShell(`xcrun simctl spawn "${activeTarget.udid}" launchctl list 2>/dev/null | grep "${activeTarget.bundleId}" | awk '{print $1}'`);
+            const parsed = parseInt(out.trim());
+            if (!isNaN(parsed))
+                pid = parsed;
         }
+        catch { }
         if (!pid) {
             return {
-                content: [{ type: "text", text: "Error: No running app found. Launch the app first with nerve_run." }],
+                content: [{ type: "text", text: "Error: Could not find running app process. Launch the app first with nerve_run." }],
                 isError: true,
             };
         }
@@ -1064,6 +965,15 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
     if (command === "build" || command === "run") {
         return handleBuildRun(command, params);
     }
+    if (command === "run_device") {
+        return handleRunDevice(params);
+    }
+    if (command === "appearance") {
+        return handleAppearance(params, targetId);
+    }
+    if (command === "list_devices") {
+        return handleListDevices();
+    }
     // Grant permissions via simctl (Mac-side)
     if (command === "grant_permissions") {
         return handleGrantPermissions(params);
@@ -1080,37 +990,56 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         return handleBootSimulator(params);
     }
     // Deeplink via simctl (Mac-side, when method is "simctl")
-    if (command === "deeplink" && (params.method === "simctl" || !connection.getConnectedTargets().length)) {
+    if (command === "deeplink" && (params.method === "simctl" || !activeTarget)) {
         return handleDeeplinkSimctl(params);
     }
-    // Special case: status doesn't need a connection
+    // Sequence: batch multiple commands in one call
+    if (command === "sequence") {
+        const steps = params.steps;
+        if (!steps || steps.length === 0) {
+            return {
+                content: [{ type: "text", text: "Error: 'steps' array is required and must not be empty" }],
+                isError: true,
+            };
+        }
+        const results = [];
+        for (let i = 0; i < steps.length; i++) {
+            const step = steps[i];
+            const stepParams = step.params ?? {};
+            try {
+                const result = await send(step.command, stepParams, targetId);
+                results.push(`[${i + 1}] ${step.command}: ${result}`);
+            }
+            catch (e) {
+                results.push(`[${i + 1}] ${step.command}: Error — ${e.message}`);
+                // Stop on error — later steps likely depend on earlier ones
+                break;
+            }
+        }
+        return { content: [{ type: "text", text: results.join("\n\n") }] };
+    }
+    // Special case: status
     if (command === "status") {
-        await connection.discover();
-        const targets = connection.getConnectedTargets();
-        if (targets.length === 0) {
+        if (!activeTarget) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: "No Nerve instances found.\n\nMake sure your iOS app includes the Nerve SPM package:\n  #if DEBUG\n  import Nerve\n  Nerve.start()\n  #endif\n\nThen build and run with nerve_run.",
+                        text: "No active target.\n\nMake sure your iOS app includes the Nerve SPM package:\n  #if DEBUG\n  import Nerve\n  Nerve.start()\n  #endif\n\nThen build and run with nerve_run.",
                     },
                 ],
             };
         }
-        // Get status from each connected target
-        const results = [];
-        for (const target of targets) {
-            try {
-                const result = await connection.send("status", {}, target.id);
-                results.push(result);
-            }
-            catch (e) {
-                results.push(`${target.id}: error — ${e.message}`);
-            }
+        try {
+            const result = await send("status", {}, targetId);
+            return { content: [{ type: "text", text: result }] };
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: `Error: ${e.message}` }],
+                isError: true,
+            };
         }
-        return {
-            content: [{ type: "text", text: results.join("\n\n") }],
-        };
     }
     try {
         // Remove device 'target' from params before forwarding
@@ -1119,7 +1048,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         if (command === "navigate" && target_screen) {
             commandParams.target = target_screen;
         }
-        const result = await connection.send(command, commandParams, targetId);
+        const result = await send(command, commandParams, targetId);
         // For screenshots, check if the result is base64 image data
         if (command === "screenshot" && result.startsWith("data:image/")) {
             const base64 = result.replace("data:image/png;base64,", "");
@@ -1162,6 +1091,60 @@ function runShell(cmd, timeoutMs = 120000) {
         proc.on("error", reject);
     });
 }
+// --- Nerve Framework Injection ---
+// Resolve paths for finding the Nerve framework
+// mcp-server/dist/index.js -> mcp-server/ (npm package root)
+// mcp-server/src/index.ts  -> mcp-server/ (development)
+const mpcPackageRoot = path.resolve(__dirname, "..");
+const nerveRepoRoot = path.resolve(mpcPackageRoot, "..");
+function findNerveFramework() {
+    const candidates = [
+        // 1. Bundled with npm package (npm install nerve-mcp)
+        path.join(mpcPackageRoot, "framework", "Nerve.framework", "Nerve"),
+        // 2. Homebrew installation
+        "/opt/homebrew/lib/nerve/Nerve.framework/Nerve",
+        "/usr/local/lib/nerve/Nerve.framework/Nerve",
+        // 3. Repo .build/inject/ (development from source)
+        path.join(nerveRepoRoot, ".build", "inject", "Nerve.framework", "Nerve"),
+    ];
+    return candidates.find(p => fs.existsSync(p)) ?? null;
+}
+async function ensureNerveFramework() {
+    const existing = findNerveFramework();
+    if (existing)
+        return existing;
+    // Auto-build from source (development mode)
+    const buildScript = path.join(nerveRepoRoot, "scripts", "build-framework.sh");
+    if (fs.existsSync(buildScript)) {
+        await runShell(`bash "${buildScript}"`, 180000);
+        const built = findNerveFramework();
+        if (built)
+            return built;
+    }
+    throw new Error("Nerve.framework not found. If installed via npm, reinstall nerve-mcp. " +
+        "If developing from source, run: scripts/build-framework.sh");
+}
+async function appContainsNerve(appPath) {
+    // Check if the app binary contains Nerve symbols (works for both static and dynamic SPM linking)
+    try {
+        const appName = path.basename(appPath, ".app");
+        const binary = path.join(appPath, appName);
+        const symbols = await runShell(`nm -gU "${binary}" 2>/dev/null | grep nerve_auto_start || true`);
+        if (symbols.trim())
+            return true;
+        // Also check Frameworks/ for dynamic linking case
+        const frameworks = path.join(appPath, "Frameworks");
+        if (fs.existsSync(frameworks)) {
+            const entries = fs.readdirSync(frameworks);
+            if (entries.some(e => e.startsWith("Nerve")))
+                return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
 async function findSimulatorUDID(name) {
     const json = await runShell("xcrun simctl list devices available -j");
     const data = JSON.parse(json);
@@ -1192,10 +1175,24 @@ async function handleBuildRun(command, params) {
             buildSource = `-workspace "${workspace}"`;
         else if (project)
             buildSource = `-project "${project}"`;
-        const derivedData = "/tmp/nerve-derived-data";
-        const buildCmd = `xcodebuild build ${buildSource} -scheme "${scheme}" -sdk iphonesimulator -configuration Debug -derivedDataPath "${derivedData}" -quiet 2>&1 | tail -5`;
+        // Per-project derived data to avoid cross-project collisions
+        const projectDir = workspace ? path.dirname(path.resolve(workspace)) : project ? path.dirname(path.resolve(project)) : process.cwd();
+        const projectName = path.basename(projectDir);
+        const derivedData = `/tmp/nerve-derived-data-${projectName}`;
+        const buildCmd = `set -o pipefail && xcodebuild build ${buildSource} -scheme "${scheme}" -sdk iphonesimulator -derivedDataPath "${derivedData}" -quiet 2>&1 | tail -20`;
         log.push(`Building ${scheme} for simulator...`);
-        const buildOutput = await runShell(buildCmd, 300000);
+        let buildOutput;
+        try {
+            buildOutput = await runShell(buildCmd, 300000);
+        }
+        catch (e) {
+            const errMsg = e.message;
+            log.push(errMsg);
+            return {
+                content: [{ type: "text", text: log.join("\n") }],
+                isError: true,
+            };
+        }
         if (buildOutput.trim())
             log.push(buildOutput.trim());
         log.push("Build succeeded.");
@@ -1203,8 +1200,12 @@ async function handleBuildRun(command, params) {
             return { content: [{ type: "text", text: log.join("\n") }] };
         }
         // --- Run: install + launch with Nerve injection ---
-        // Find the .app bundle
-        const appPath = (await runShell(`find "${derivedData}/Build/Products/Debug-iphonesimulator" -name "*.app" -maxdepth 1 | head -1`)).trim();
+        // Get exact app path from build settings (no guessing with find)
+        const settingsCmd = `xcodebuild -showBuildSettings ${buildSource} -scheme "${scheme}" -sdk iphonesimulator -derivedDataPath "${derivedData}" 2>/dev/null`;
+        const settings = await runShell(settingsCmd);
+        const builtProductsDir = settings.match(/^\s*BUILT_PRODUCTS_DIR = (.+)/m)?.[1]?.trim();
+        const productName = settings.match(/^\s*FULL_PRODUCT_NAME = (.+)/m)?.[1]?.trim();
+        const appPath = builtProductsDir && productName ? `${builtProductsDir}/${productName}` : "";
         if (!appPath) {
             return {
                 content: [{ type: "text", text: log.join("\n") + "\nError: Could not find .app bundle" }],
@@ -1234,28 +1235,215 @@ async function handleBuildRun(command, params) {
         catch {
             // Not running
         }
-        // Clean up old port file
-        try {
-            await runShell(`rm -f "/tmp/nerve-ports/${udid}-${bundleId}.json"`);
+        // Launch — detect SPM vs inject mode
+        const hasNerve = await appContainsNerve(appPath);
+        let injected = false;
+        if (hasNerve) {
+            await runShell(`xcrun simctl launch "${udid}" "${bundleId}"`);
+            log.push("Launched (SPM mode).");
         }
-        catch { /* ignore */ }
-        // Launch
-        await runShell(`xcrun simctl launch "${udid}" "${bundleId}"`);
-        log.push("Launched.");
-        // Wait for Nerve to be ready (app must have Nerve via SPM)
-        const portFile = `/tmp/nerve-ports/${udid}-${bundleId}.json`;
-        for (let i = 0; i < 30; i++) {
-            if (fs.existsSync(portFile)) {
-                const info = JSON.parse(fs.readFileSync(portFile, "utf-8"));
-                log.push(`Nerve ready on port ${info.port}`);
-                await connection.discover();
+        else {
+            const frameworkBinary = await ensureNerveFramework();
+            await runShell(`SIMCTL_CHILD_DYLD_INSERT_LIBRARIES="${frameworkBinary}" xcrun simctl launch "${udid}" "${bundleId}"`);
+            log.push("Launched (inject mode).");
+            injected = true;
+        }
+        // Set active target
+        activeTarget = { udid, bundleId };
+        const port = nervePort(udid, bundleId);
+        // Wait for Nerve to be ready: TCP probe on calculated port
+        let nerveReady = false;
+        for (let i = 0; i < 40; i++) {
+            if (await tcpProbe("127.0.0.1", port, 500)) {
+                log.push(`Nerve ready on port ${port}`);
+                nerveReady = true;
                 break;
             }
-            await new Promise(r => setTimeout(r, 500));
+            await new Promise(r => setTimeout(r, 250));
+        }
+        if (!nerveReady) {
+            if (injected) {
+                log.push("Nerve did not start after injection. The framework may be incompatible — try rebuilding: delete .build/inject/ and re-run.");
+            }
+            else {
+                log.push("Nerve did not start. Ensure your app calls Nerve.start() in #if DEBUG.");
+            }
+        }
+        return { content: [{ type: "text", text: log.join("\n") }] };
+    }
+    catch (e) {
+        const error = e;
+        log.push(`Error: ${error.message}`);
+        return {
+            content: [{ type: "text", text: log.join("\n") }],
+            isError: true,
+        };
+    }
+}
+// --- Appearance (Mac-side + in-app fallback) ---
+async function handleAppearance(params, targetId) {
+    const mode = params.mode;
+    if (!mode || !["dark", "light", "toggle"].includes(mode)) {
+        return {
+            content: [{ type: "text", text: "Error: 'mode' must be 'dark', 'light', or 'toggle'" }],
+            isError: true,
+        };
+    }
+    // Try simctl first (simulator)
+    if (activeTarget) {
+        try {
+            if (mode === "toggle") {
+                // Read current, then flip
+                const current = (await runShell(`xcrun simctl ui "${activeTarget.udid}" appearance 2>/dev/null`)).trim();
+                const newMode = current === "dark" ? "light" : "dark";
+                await runShell(`xcrun simctl ui "${activeTarget.udid}" appearance ${newMode}`);
+                return { content: [{ type: "text", text: `Switched to ${newMode} mode (was ${current})` }] };
+            }
+            await runShell(`xcrun simctl ui "${activeTarget.udid}" appearance ${mode}`);
+            return { content: [{ type: "text", text: `Switched to ${mode} mode` }] };
+        }
+        catch {
+            // Not a simulator — fall through to in-app override
+        }
+    }
+    // Fallback: override via Nerve in-app (works on device too)
+    try {
+        let style;
+        if (mode === "toggle") {
+            // Ask the app for current style, then flip
+            const current = await send("modify", {
+                query: ".UIWindow:0",
+                property: "overrideUserInterfaceStyle",
+            }, targetId);
+            // 0 = unspecified, 1 = light, 2 = dark
+            style = current.includes("2") ? "1" : "2";
+        }
+        else {
+            style = mode === "dark" ? "2" : "1";
+        }
+        const result = await send("modify", {
+            query: ".UIWindow:0",
+            property: "overrideUserInterfaceStyle",
+            value: parseInt(style),
+        }, targetId);
+        const label = style === "2" ? "dark" : "light";
+        return { content: [{ type: "text", text: `Switched to ${label} mode (in-app override)\n${result}` }] };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `Error: ${e.message}` }],
+            isError: true,
+        };
+    }
+}
+// --- Physical Device (Mac-side) ---
+async function handleListDevices() {
+    try {
+        const output = await runShell("xcrun devicectl list devices 2>&1");
+        return { content: [{ type: "text", text: output.trim() }] };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `Error listing devices: ${e.message}` }],
+            isError: true,
+        };
+    }
+}
+async function findDeviceIdentifier(nameOrUDID) {
+    const output = await runShell("xcrun devicectl list devices -j 2>/dev/null");
+    const data = JSON.parse(output);
+    const devices = data?.result?.devices ?? [];
+    for (const d of devices) {
+        if (d.connectionProperties?.transportType !== "wired" && d.connectionProperties?.transportType !== "localNetwork")
+            continue;
+        const devName = d.deviceProperties?.name ?? "";
+        const devId = d.hardwareProperties?.udid ?? d.identifier ?? "";
+        const coreId = d.identifier ?? "";
+        if (nameOrUDID) {
+            if (devName === nameOrUDID || devId === nameOrUDID || coreId === nameOrUDID) {
+                return { identifier: coreId, name: devName };
+            }
+        }
+        else {
+            // Return first available paired device
+            if (d.connectionProperties?.pairingState === "paired") {
+                return { identifier: coreId, name: devName };
+            }
+        }
+    }
+    throw new Error(nameOrUDID
+        ? `Device '${nameOrUDID}' not found or not connected. Run nerve_list_devices to see available devices.`
+        : "No paired device found. Connect a device and run nerve_list_devices.");
+}
+async function handleRunDevice(params) {
+    const scheme = params.scheme;
+    const workspace = params.workspace;
+    const project = params.project;
+    const device = params.device;
+    const team = params.team;
+    if (!scheme) {
+        return {
+            content: [{ type: "text", text: "Error: 'scheme' parameter is required" }],
+            isError: true,
+        };
+    }
+    const log = [];
+    try {
+        // Find the device
+        const dev = await findDeviceIdentifier(device);
+        log.push(`Device: ${dev.name} (${dev.identifier})`);
+        // Build for device
+        let buildSource = "";
+        if (workspace)
+            buildSource = `-workspace "${workspace}"`;
+        else if (project)
+            buildSource = `-project "${project}"`;
+        const projectDir = workspace ? path.dirname(path.resolve(workspace)) : project ? path.dirname(path.resolve(project)) : process.cwd();
+        const projectName = path.basename(projectDir);
+        const derivedData = `/tmp/nerve-derived-data-${projectName}`;
+        let signingFlags = "";
+        if (team) {
+            signingFlags = `DEVELOPMENT_TEAM="${team}" CODE_SIGN_STYLE=Automatic`;
         }
-        if (!fs.existsSync(portFile)) {
-            log.push("Nerve did not start. Ensure your app includes the Nerve SPM package with Nerve.start() in #if DEBUG.");
+        const buildCmd = `set -o pipefail && xcodebuild build ${buildSource} -scheme "${scheme}" -sdk iphoneos -destination "generic/platform=iOS" -derivedDataPath "${derivedData}" -allowProvisioningUpdates ${signingFlags} -quiet 2>&1 | tail -30`;
+        log.push(`Building ${scheme} for device...`);
+        let buildOutput;
+        try {
+            buildOutput = await runShell(buildCmd, 300000);
+        }
+        catch (e) {
+            const errMsg = e.message;
+            log.push(errMsg);
+            return {
+                content: [{ type: "text", text: log.join("\n") }],
+                isError: true,
+            };
         }
+        if (buildOutput.trim())
+            log.push(buildOutput.trim());
+        log.push("Build succeeded.");
+        // Find the .app bundle
+        const settingsCmd = `xcodebuild -showBuildSettings ${buildSource} -scheme "${scheme}" -sdk iphoneos -derivedDataPath "${derivedData}" 2>/dev/null`;
+        const settings = await runShell(settingsCmd);
+        const builtProductsDir = settings.match(/^\s*BUILT_PRODUCTS_DIR = (.+)/m)?.[1]?.trim();
+        const productName = settings.match(/^\s*FULL_PRODUCT_NAME = (.+)/m)?.[1]?.trim();
+        const appPath = builtProductsDir && productName ? `${builtProductsDir}/${productName}` : "";
+        if (!appPath) {
+            return {
+                content: [{ type: "text", text: log.join("\n") + "\nError: Could not find .app bundle" }],
+                isError: true,
+            };
+        }
+        const bundleId = (await runShell(`/usr/libexec/PlistBuddy -c "Print :CFBundleIdentifier" "${appPath}/Info.plist"`)).trim();
+        log.push(`App: ${bundleId}`);
+        // Install on device
+        log.push("Installing on device...");
+        await runShell(`xcrun devicectl device install app --device "${dev.identifier}" "${appPath}" 2>&1`, 120000);
+        log.push("Installed.");
+        // Launch on device
+        log.push("Launching...");
+        await runShell(`xcrun devicectl device process launch --device "${dev.identifier}" "${bundleId}" 2>&1`, 30000);
+        log.push("Launched.");
         return { content: [{ type: "text", text: log.join("\n") }] };
     }
     catch (e) {
@@ -1276,32 +1464,13 @@ async function handleGrantPermissions(params) {
             isError: true,
         };
     }
-    // Find connected target to get UDID and bundle ID
-    const targets = connection.getConnectedTargets();
-    let udid;
-    let bundleId;
-    if (targets.length > 0) {
-        udid = targets[0].udid;
-        bundleId = targets[0].bundleId;
-    }
-    else {
-        // Try to find from port files
-        const dir = "/tmp/nerve-ports";
-        if (fs.existsSync(dir)) {
-            const files = fs.readdirSync(dir).filter(f => f.endsWith(".json"));
-            if (files.length > 0) {
-                const info = JSON.parse(fs.readFileSync(path.join(dir, files[0]), "utf-8"));
-                udid = info.udid;
-                bundleId = info.bundleId;
-            }
-        }
-    }
-    if (!udid || !bundleId) {
+    if (!activeTarget) {
         return {
-            content: [{ type: "text", text: "Error: No running Nerve instance found. Launch the app first." }],
+            content: [{ type: "text", text: "Error: No active target. Launch the app first with nerve_run." }],
             isError: true,
         };
     }
+    const { udid, bundleId } = activeTarget;
     const log = [];
     for (const service of services) {
         try {
@@ -1323,22 +1492,7 @@ async function handleDeeplinkSimctl(params) {
             isError: true,
         };
     }
-    // Find UDID
-    let udid;
-    const targets = connection.getConnectedTargets();
-    if (targets.length > 0) {
-        udid = targets[0].udid;
-    }
-    else {
-        const dir = "/tmp/nerve-ports";
-        if (fs.existsSync(dir)) {
-            const files = fs.readdirSync(dir).filter(f => f.endsWith(".json"));
-            if (files.length > 0) {
-                const info = JSON.parse(fs.readFileSync(path.join(dir, files[0]), "utf-8"));
-                udid = info.udid;
-            }
-        }
-    }
+    let udid = activeTarget?.udid;
     if (!udid) {
         // Try booted simulators
         try {
@@ -1375,14 +1529,9 @@ async function handleDeeplinkSimctl(params) {
 }
 // --- Main ---
 async function main() {
-    // Initial discovery
-    await connection.discover();
-    // Start MCP server on stdio
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
     console.error("[nerve] MCP server started");
-    // Periodic re-discovery
-    setInterval(() => connection.discover(), 3000);
 }
 main().catch((e) => {
     console.error("[nerve] Fatal:", e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nerve-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Nerve — gives AI agents runtime access to iOS apps",
   "main": "dist/index.js",
   "bin": {
@@ -10,14 +10,15 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm run bundle-framework",
+    "bundle-framework": "bash ../scripts/build-framework.sh && rm -rf framework && mkdir -p framework/Nerve.framework && cp ../.build/inject/Nerve.framework/Nerve framework/Nerve.framework/ && cp ../.build/inject/Nerve.framework/Info.plist framework/Nerve.framework/"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/luchi0208/nerve-ios.git",
     "directory": "mcp-server"
   },
-  "files": ["dist", "README.md"],
+  "files": ["dist", "framework", "README.md"],
   "keywords": ["mcp", "ios", "automation", "simulator", "nerve"],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",