@ceraph/react-native-mcp 0.2.1 → 0.3.1

package/dist/index.js

@@ -1,11 +1,4 @@
 #!/usr/bin/env node
-/**
- * @ceraph/react-native-mcp — MCP server for React Native / Expo development workflow.
- *
- * Auto-detects Expo vs bare React Native projects and uses the appropriate
- * commands. Provides tools for building, running, error capture, screen
- * interaction, and prebuild detection.
- */
 import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -13,39 +6,87 @@ import { z } from "zod";
 import { RNManager } from "./expo-manager.js";
 import { ScreenManager } from "./screen.js";
 import { PrebuildDetector } from "./prebuild-detector.js";
-// ---------------------------------------------------------------------------
-// Resolve the project working directory.
-// ---------------------------------------------------------------------------
-// Cache lives next to the consumer's project (where the RN/Expo app actually
-// lives) so the prebuild snapshot persists across MCP restarts and across
-// different install paths (npx cache vs. local checkout).
+import { AppLifecycle } from "./app-lifecycle.js";
+import { DeviceAutonomy } from "./device-autonomy.js";
+import { IproxyManager } from "./iproxy-manager.js";
+import { runPreflight } from "./preflight.js";
+import { TargetResolver } from "./target.js";
+import { WdaManager } from "./wda-manager.js";
+import { bootSimulator } from "./simulator-boot.js";
+import { waitForDevice } from "./wait-for-device.js";
+import { syncCameraRegistry, relativeRegistryPath, } from "./camera-registry-sync.js";
+import { addCameraImage, AddCameraImageError, } from "./camera-image-writer.js";
+import { SignalListener } from "./signal-listener.js";
+import { PermissionInterceptor, modeFromEnv, } from "./permission-interceptor.js";
+import { detectMonorepoStatus, getInitStatus, injectBoot, installCeraphPackage, pollAuthFlow, preflightForMcp, registerScheme, replaceCameraView, scanCameraUsages, setupImagesDir, setupMcpClients, startAuthFlow, } from "./init/steps.js";
+import { detectMacLanIp } from "./init/lan-ip.js";
+import { registerUninstallTools } from "./uninstall/mcp-tools.js";
 const PROJECT_DIR = process.cwd();
 const CACHE_DIR = join(PROJECT_DIR, ".rn-mcp-cache");
-// ---------------------------------------------------------------------------
-// Initialize managers
-// ---------------------------------------------------------------------------
 const rnManager = new RNManager(PROJECT_DIR);
-const screenManager = new ScreenManager();
+const targetResolver = new TargetResolver();
+const screenManager = new ScreenManager({ targetResolver });
 const prebuildDetector = new PrebuildDetector(PROJECT_DIR, CACHE_DIR);
-// ---------------------------------------------------------------------------
-// Create MCP server
-// ---------------------------------------------------------------------------
+const appLifecycle = new AppLifecycle(screenManager, targetResolver);
+targetResolver.setAppLifecycle(appLifecycle);
+const deviceAutonomy = new DeviceAutonomy(screenManager);
+const wdaManager = new WdaManager(targetResolver, CACHE_DIR, PROJECT_DIR);
+const iproxyManager = new IproxyManager();
+const permissionInterceptor = new PermissionInterceptor({
+    screen: screenManager,
+    mode: modeFromEnv(process.env.CERAPH_AUTO_ACCEPT_PERMISSIONS),
+});
+const signalListenerPort = process.env.CERAPH_SIGNAL_PORT
+    ? Number(process.env.CERAPH_SIGNAL_PORT)
+    : undefined;
+const signalListener = new SignalListener(rnManager, {
+    port: Number.isFinite(signalListenerPort) ? signalListenerPort : undefined,
+});
 const server = new McpServer({
     name: "react-native-mcp",
-    version: "0.1.0",
+    version: "0.3.1",
 }, {
     capabilities: {
         tools: {},
     },
-    instructions: "React Native / Expo development workflow tools. Auto-detects project type. " +
-        "Use rn_build_ios to build, rn_start to launch Metro, rn_get_errors to " +
-        "check for problems, screen_tap and screen_find_and_tap for device " +
-        "interaction with automatic pixel ratio correction, and rn_check_prebuild " +
-        "to detect when a clean native rebuild is needed (Expo only).",
-});
-// ---------------------------------------------------------------------------
-// Tool: rn_build_ios
-// ---------------------------------------------------------------------------
+    instructions: "React Native / Expo development workflow tools. Auto-detects project type.\n\n" +
+        "HOW TO DRIVE THE APP:\n" +
+        "Compose screen_* and app_* primitives to exercise the app on a real iOS " +
+        "device or simulator. You plan the steps yourself; this MCP just drives " +
+        "WebDriverAgent. Use screen_screenshot and screen_get_source between " +
+        "actions to observe state and decide the next step. Typical scenarios: " +
+        "'tap the Premium plan and verify checkout opens', 'sign in as user X and " +
+        "confirm the dashboard loads', 'reproduce the bug where tapping save " +
+        "crashes the app'.\n\n" +
+        "STARTUP FLOW WHEN NO TARGET IS AVAILABLE:\n" +
+        "  - User wants a quick start with no device attached → rn_boot_simulator " +
+        "(auto-picks newest iPhone), then rn_wda_start, then retry the original tool.\n" +
+        "  - User wants to test on their phone (or CERAPH_TARGET=device is set) → " +
+        "tell the user to plug in their iPhone, then rn_wait_for_device (event-driven " +
+        "via usbmuxd, no timeout) — the original tool can be re-run as soon as that " +
+        "returns success.\n" +
+        "  - Ambiguous first-time setup: prefer the simulator path unless the user " +
+        "has signalled device intent (mentioned their phone, set CERAPH_TARGET=device, " +
+        "etc). Simulator avoids cable/trust friction for the first happy path.\n\n" +
+        "WDA-direct primitives (you orchestrate): app_launch/terminate/activate, " +
+        "screen_tap, screen_find_and_tap, screen_swipe, screen_scroll_to, " +
+        "screen_long_press, screen_type, screen_clear_text, screen_press_key, " +
+        "screen_screenshot, screen_get_source, screen_wait_for, screen_assert_visible.\n\n" +
+        "Build with rn_build_ios, run Metro with rn_start, inspect errors with " +
+        "rn_get_errors, check rn_check_prebuild when native deps change (Expo only). " +
+        "Camera testing: test images for the React Native camera live in " +
+        "`.ceraph/camera-images/` in the user's repo. When the user provides " +
+        "an image for camera testing, paste it into that folder with a " +
+        "descriptive lowercase filename (e.g. `profile.jpg`, `id-card.png`, " +
+        "`product.jpg`). The filename without extension is the imageKey. " +
+        "In source code, replace `<CameraView>` (from expo-camera) with " +
+        "`<CeraphCamera imageKey=\"profile\" />` from " +
+        "`@ceraph/react-native-mcp/shim`, choosing the imageKey based on " +
+        "what the camera screen captures conceptually. Then call " +
+        "`rn_sync_camera_registry` to regenerate the registry. The " +
+        "`rn_preflight` tool will warn about any unwrapped `<CameraView>`, " +
+        "missing imageKey props, or orphan imageKey references.",
+});
 server.tool("rn_build_ios", "Build and run the React Native app on an iOS device or simulator. " +
     "Auto-detects Expo vs bare React Native and uses the correct command. " +
     "Captures Xcode build output and returns structured error information. " +
@@ -61,10 +102,8 @@ server.tool("rn_build_ios", "Build and run the React Native app on an iOS device
 }, async ({ clean, device }) => {
     try {
         const result = await rnManager.runBuild({ clean, device });
-        // On success, save a snapshot for future prebuild checks
         if (result.success) {
             await prebuildDetector.saveSnapshot().catch(() => {
-                // Non-critical; don't fail the build result over this
             });
         }
         return {
@@ -89,9 +128,6 @@ server.tool("rn_build_ios", "Build and run the React Native app on an iOS device
         };
     }
 });
-// ---------------------------------------------------------------------------
-// Tool: rn_start
-// ---------------------------------------------------------------------------
 server.tool("rn_start", "Start the Metro dev server. Auto-detects Expo vs bare React Native. " +
     "Monitors console output for runtime errors and warnings.", {
     port: z
@@ -127,9 +163,6 @@ server.tool("rn_start", "Start the Metro dev server. Auto-detects Expo vs bare R
         };
     }
 });
-// ---------------------------------------------------------------------------
-// Tool: rn_get_errors
-// ---------------------------------------------------------------------------
 server.tool("rn_get_errors", "Return all captured errors from build and runtime. " +
     "Includes structured build errors (file, line, column, message), " +
     "runtime JS errors (message, stack trace), and warnings.", {}, async () => {
@@ -156,9 +189,6 @@ server.tool("rn_get_errors", "Return all captured errors from build and runtime.
         };
     }
 });
-// ---------------------------------------------------------------------------
-// Tool: rn_get_console
-// ---------------------------------------------------------------------------
 server.tool("rn_get_console", "Return recent console output from Metro dev server, " +
     "optionally filtered by log level.", {
     lines: z
@@ -203,9 +233,6 @@ server.tool("rn_get_console", "Return recent console output from Metro dev serve
         };
     }
 });
-// ---------------------------------------------------------------------------
-// Tool: rn_check_prebuild
-// ---------------------------------------------------------------------------
 server.tool("rn_check_prebuild", "Check if a clean Expo prebuild is needed (Expo projects only). " +
     "Compares current package.json dependencies, app.json config, and " +
     "ios/Podfile.lock against a cached snapshot from the last successful build.", {}, async () => {
@@ -246,9 +273,6 @@ server.tool("rn_check_prebuild", "Check if a clean Expo prebuild is needed (Expo
         };
     }
 });
-// ---------------------------------------------------------------------------
-// Tool: screen_tap
-// ---------------------------------------------------------------------------
 server.tool("screen_tap", "Tap at specific coordinates on the iOS device screen via WebDriverAgent. " +
     "Automatically corrects for pixel ratio mismatch when coordinates come " +
     "from a screenshot (divides by device pixel ratio). " +
@@ -305,9 +329,6 @@ server.tool("screen_tap", "Tap at specific coordinates on the iOS device screen
         };
     }
 });
-// ---------------------------------------------------------------------------
-// Tool: screen_find_and_tap
-// ---------------------------------------------------------------------------
 server.tool("screen_find_and_tap", "Find a UI element on the iOS device screen by text, accessibility label, " +
     "or element type, then tap its center. Uses the WebDriverAgent element tree. " +
     "If no match is found, returns a summary of visible elements for debugging. " +
@@ -388,9 +409,771 @@ server.tool("screen_find_and_tap", "Find a UI element on the iOS device screen b
         };
     }
 });
-// ---------------------------------------------------------------------------
-// Tool: rn_stop
-// ---------------------------------------------------------------------------
+async function requireWDA() {
+    const available = await screenManager.isAvailable();
+    if (available)
+        return { ok: true };
+    return {
+        ok: false,
+        payload: {
+            success: false,
+            error: "WebDriverAgent is not reachable at localhost:8100. " +
+                "Ensure it is running on the device.",
+        },
+    };
+}
+function jsonText(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+function toolErrorContent(toolName, err) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${toolName} failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        ],
+        isError: true,
+    };
+}
+server.tool("screen_swipe", "Swipe on the iOS device screen. Direction is up/down/left/right; " +
+    "optional from-point and distance default to a center-screen swipe of " +
+    "~60% of the relevant axis. Coordinates are device-space by default; " +
+    "pass coordinateSource: 'screenshot' if `from` came from a screenshot.", {
+    direction: z.enum(["up", "down", "left", "right"]),
+    from: z
+        .object({ x: z.number(), y: z.number() })
+        .optional()
+        .describe("Optional swipe start point. Defaults to screen center."),
+    distancePx: z.number().optional().describe("Swipe distance in points."),
+    durationMs: z.number().optional().describe("Swipe duration in ms."),
+    coordinateSource: z.enum(["screenshot", "device"]).optional(),
+}, async (args) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        const res = await screenManager.swipe({
+            direction: args.direction,
+            from: args.from,
+            distancePx: args.distancePx,
+            durationMs: args.durationMs,
+            coordinateSource: args.coordinateSource,
+        });
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_swipe failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_scroll_to", "Repeatedly swipe until an element matching text/accessibilityLabel " +
+    "appears in the accessibility tree. Returns without tapping. Default " +
+    "direction is 'down' (swipe up), max 10 swipes.", {
+    text: z.string().optional(),
+    accessibilityLabel: z.string().optional(),
+    maxSwipes: z.number().optional(),
+    direction: z.enum(["up", "down"]).optional(),
+}, async (args) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        if (!args.text && !args.accessibilityLabel) {
+            return {
+                ...jsonText({
+                    success: false,
+                    error: "text or accessibilityLabel is required.",
+                }),
+                isError: true,
+            };
+        }
+        const res = await screenManager.scrollToElement({
+            text: args.text,
+            accessibilityLabel: args.accessibilityLabel,
+        }, { maxSwipes: args.maxSwipes, direction: args.direction });
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_scroll_to failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_long_press", "Long-press an element matched by text/accessibilityLabel. " +
+    "Default duration is 1000ms.", {
+    text: z.string().optional(),
+    accessibilityLabel: z.string().optional(),
+    durationMs: z.number().optional(),
+}, async (args) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        if (!args.text && !args.accessibilityLabel) {
+            return {
+                ...jsonText({
+                    success: false,
+                    error: "text or accessibilityLabel is required.",
+                }),
+                isError: true,
+            };
+        }
+        const res = await screenManager.longPressElement({
+            text: args.text,
+            accessibilityLabel: args.accessibilityLabel,
+        }, args.durationMs ?? 1000);
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_long_press failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_type", "Type text into the currently focused element. If hideKeyboardAfter is " +
+    "true, sends a newline after to dismiss the keyboard. Use screen_find_and_tap " +
+    "to focus an input field first if needed.", {
+    text: z.string(),
+    hideKeyboardAfter: z.boolean().optional(),
+}, async ({ text, hideKeyboardAfter }) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        const res = await screenManager.type(text, { hideKeyboardAfter });
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_type failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_clear_text", "Focus an input field and send backspaces equal to its current value length.", {
+    text: z.string().optional(),
+    accessibilityLabel: z.string().optional(),
+}, async (args) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        if (!args.text && !args.accessibilityLabel) {
+            return {
+                ...jsonText({
+                    success: false,
+                    error: "text or accessibilityLabel is required.",
+                }),
+                isError: true,
+            };
+        }
+        const res = await screenManager.clearText({
+            text: args.text,
+            accessibilityLabel: args.accessibilityLabel,
+        });
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_clear_text failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_press_key", "Press a hardware/system button: home, volumeUp, volumeDown, or lock.", {
+    key: z.enum(["home", "volumeUp", "volumeDown", "lock"]),
+}, async ({ key }) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        const res = await screenManager.pressKey(key);
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_press_key failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_screenshot", "Capture a base64 PNG screenshot of the current iOS screen via WebDriverAgent.", {}, async () => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        const res = await screenManager.screenshot();
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_screenshot failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_get_source", "Return the full WebDriverAgent accessibility tree as JSON. " +
+    "Useful for discovering element identifiers when no screenshot is available.", {}, async () => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        const res = await screenManager.getSource();
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_get_source failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_wait_for", "Poll the WDA source tree until an element matching the query is visible " +
+    "(or, if disappear is true, until it vanishes). Default timeout is 5s.", {
+    text: z.string().optional(),
+    accessibilityLabel: z.string().optional(),
+    type: z.string().optional(),
+    timeoutMs: z.number().optional(),
+    pollIntervalMs: z.number().optional(),
+    disappear: z.boolean().optional(),
+}, async (args) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        if (!args.text && !args.accessibilityLabel && !args.type) {
+            return {
+                ...jsonText({
+                    success: false,
+                    error: "text, accessibilityLabel, or type is required.",
+                }),
+                isError: true,
+            };
+        }
+        const res = await screenManager.waitFor({
+            text: args.text,
+            accessibilityLabel: args.accessibilityLabel,
+            type: args.type,
+        }, {
+            timeoutMs: args.timeoutMs,
+            pollIntervalMs: args.pollIntervalMs,
+            disappear: args.disappear,
+        });
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_wait_for failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("screen_assert_visible", "Single-shot check: is the element currently visible? Pass invert: true " +
+    "to assert it is NOT visible.", {
+    text: z.string().optional(),
+    accessibilityLabel: z.string().optional(),
+    type: z.string().optional(),
+    invert: z.boolean().optional(),
+}, async (args) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        if (!args.text && !args.accessibilityLabel && !args.type) {
+            return {
+                ...jsonText({
+                    success: false,
+                    error: "text, accessibilityLabel, or type is required.",
+                }),
+                isError: true,
+            };
+        }
+        const query = {
+            text: args.text,
+            accessibilityLabel: args.accessibilityLabel,
+            type: args.type,
+        };
+        if (args.invert) {
+            const res = await screenManager.assertNotVisible(query);
+            return { ...jsonText(res), isError: !res.success || res.visible };
+        }
+        const res = await screenManager.assertVisible(query);
+        return { ...jsonText(res), isError: !res.success || !res.visible };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_assert_visible failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("app_launch", "Launch an iOS app by bundle ID on a connected real device (preferred) or " +
+    "the booted simulator (fallback). Terminates any existing instance first " +
+    "via devicectl --terminate-existing.", {
+    bundleId: z.string().describe("e.g., com.acme.myapp"),
+}, async ({ bundleId }) => {
+    try {
+        const res = await appLifecycle.launchApp(bundleId);
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `app_launch failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("app_terminate", "Terminate an iOS app by bundle ID.", {
+    bundleId: z.string(),
+}, async ({ bundleId }) => {
+    try {
+        const res = await appLifecycle.terminateApp(bundleId);
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `app_terminate failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("app_activate", "Bring an app to the foreground without a cold restart. Uses WDA's " +
+    "/wda/apps/launch, falls back to a fresh launch if WDA is unreachable.", {
+    bundleId: z.string(),
+}, async ({ bundleId }) => {
+    try {
+        const res = await appLifecycle.activateApp(bundleId);
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `app_activate failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("app_list_installed", "List apps installed on the connected real device via " +
+    "`xcrun devicectl device info apps`. Cached for 30s.", {}, async () => {
+    try {
+        const res = await appLifecycle.listInstalledApps();
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `app_list_installed failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("app_active", "Return info about the foreground app via WDA's /wda/activeAppInfo " +
+    "(bundleId, pid, name).", {}, async () => {
+    try {
+        const res = await appLifecycle.getActiveApp();
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `app_active failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("device_ensure_awake", "Ensure the iOS device is awake and unlocked. Returns a structured " +
+    "result with remediation guidance when the device is locked.", {}, async () => {
+    try {
+        const res = await deviceAutonomy.ensureAwake();
+        return { ...jsonText(res), isError: !res.awake };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `device_ensure_awake failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("device_lock_state", "Report the current device lock state: unlocked, locked, screen-off, or unknown.", {}, async () => {
+    try {
+        const state = await deviceAutonomy.getLockState();
+        return jsonText({ lockState: state });
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `device_lock_state failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("device_set_orientation", "Set the device orientation to portrait or landscape via WDA.", {
+    orientation: z.enum(["portrait", "landscape"]),
+}, async ({ orientation }) => {
+    try {
+        const res = await deviceAutonomy.setOrientation(orientation);
+        return { ...jsonText(res), isError: !res.success };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `device_set_orientation failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("rn_preflight", "Run every setup check we can before flows execute: WDA reachable, " +
+    "device connected, device awake, app installed, required env vars " +
+    "present, laptop WiFi. Returns a structured PreflightResult — when " +
+    "ok: false, surface the failing checks' remediation verbatim and " +
+    "DO NOT attempt to fix environment issues by editing source code. " +
+    "Call this once before a batch of rn_test_* runs.", {
+    bundleId: z
+        .string()
+        .optional()
+        .describe("Bundle ID of the app under test (e.g., com.acme.myapp). " +
+        "Required for the app-installed check."),
+    requiredEnv: z
+        .array(z.string())
+        .optional()
+        .describe("Env var names the planned flows reference. " +
+        "Each must be set + non-empty."),
+    expectedNetwork: z
+        .string()
+        .optional()
+        .describe("Optional WiFi SSID the user expects the laptop (and phone) " +
+        "to be on. Mismatch is a warning, not an error."),
+}, async ({ bundleId, requiredEnv, expectedNetwork }) => {
+    try {
+        const result = await runPreflight({
+            screen: screenManager,
+            apps: appLifecycle,
+            autonomy: deviceAutonomy,
+            iproxyManager,
+            bundleId,
+            requiredEnv,
+            expectedNetwork,
+            projectDir: PROJECT_DIR,
+            target: targetResolver,
+        });
+        return { ...jsonText(result), isError: !result.ok };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_preflight failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("rn_sync_camera_registry", "Scan .ceraph/camera-images/ for test images and (re)generate the " +
+    "static `_registry.ts` the app imports at boot. The filename without " +
+    "extension becomes the imageKey passed to <CeraphCamera imageKey>. " +
+    "Call this after adding or removing image files manually (Finder, " +
+    "git pull). `ceraph_add_camera_image` already auto-syncs after each " +
+    "write — only call this tool for manual drops. Idempotent — does " +
+    "not rewrite the registry when it already matches the discovered set.", {}, async () => {
+    try {
+        const result = await syncCameraRegistry(PROJECT_DIR);
+        if (result.writtenOrUnchanged === "missing-dir") {
+            return {
+                ...jsonText({
+                    registered: [],
+                    registryPath: relativeRegistryPath(PROJECT_DIR, result.registryPath),
+                    state: result.writtenOrUnchanged,
+                    message: "Create `.ceraph/camera-images/` and add at least one image. " +
+                        "Run this tool again to generate the registry.",
+                }),
+                isError: true,
+            };
+        }
+        return jsonText({
+            registered: result.registered.map((r) => r.key),
+            registryPath: relativeRegistryPath(PROJECT_DIR, result.registryPath),
+            state: result.writtenOrUnchanged,
+        });
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_sync_camera_registry failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("ceraph_add_camera_image", "Drop a camera test image into `.ceraph/camera-images/` without the dev " +
+    "having to copy files by hand. Pass `imageBase64` (the bytes — no " +
+    "`data:` prefix needed) plus a lowercase hyphen-separated `imageKey` " +
+    "(e.g. `handwriting-sample-1`). `contentType` is a hint only — the " +
+    "extension is chosen from magic bytes (JPEG/PNG/WebP/HEIC). A " +
+    "collision with an existing imageKey is rejected unless `overwrite: " +
+    "true` is set. After writing, the static `_registry.ts` is " +
+    "regenerated automatically (same step as `rn_sync_camera_registry`).", {
+    imageKey: z
+        .string()
+        .describe("Lowercase + hyphen-separated stem (e.g. `profile`, `id-card`, " +
+        "`handwriting-sample-1`). Becomes both the filename stem AND " +
+        "the value devs pass to `<CeraphCamera imageKey>`."),
+    imageBase64: z
+        .string()
+        .describe("Base64-encoded image payload. A `data:image/...;base64,...` " +
+        "URI prefix is accepted and stripped automatically."),
+    contentType: z
+        .string()
+        .optional()
+        .describe("Optional MIME hint (e.g. `image/jpeg`). The actual extension is " +
+        "chosen from magic-byte detection; if the hint mismatches, the " +
+        "tool returns a warning but still writes using the detected type."),
+    overwrite: z
+        .boolean()
+        .optional()
+        .describe("Allow replacing an existing imageKey (across different " +
+        "extensions). Defaults to false."),
+    subDir: z
+        .string()
+        .optional()
+        .describe("Optional single-segment subdirectory under " +
+        "`.ceraph/camera-images/`. Most callers omit this. Must be " +
+        "lowercase + hyphen-separated; no slashes, no `..`."),
+}, async ({ imageKey, imageBase64, contentType, overwrite, subDir }) => {
+    try {
+        const result = await addCameraImage(PROJECT_DIR, {
+            imageKey,
+            imageBase64,
+            contentType,
+            overwrite,
+            subDir,
+        });
+        return jsonText({
+            written: result.written,
+            registry: result.registry,
+            registered: result.registered,
+            detectedContentType: result.detectedContentType,
+            detectedExt: result.detectedExt,
+            replaced: result.replaced,
+            removedSiblingPath: result.removedSiblingPath,
+            bytes: result.bytes,
+            registryState: result.registryState,
+            warnings: result.warnings,
+        });
+    }
+    catch (err) {
+        if (err instanceof AddCameraImageError) {
+            return {
+                ...jsonText({
+                    error: err.code,
+                    message: err.message,
+                    remediation: err.remediation,
+                }),
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `ceraph_add_camera_image failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("rn_permission_auto_accept", "Toggle the iOS system-permission dialog interceptor for the running " +
+    "MCP process. 'auto-accept' (default) taps the permissive button on " +
+    "any known system dialog before each flow step; 'ask' invokes the " +
+    "configured callback (defaults to accept); 'off' is a no-op. " +
+    "Mode persists for the lifetime of this MCP process. To set the " +
+    "default for new processes, export CERAPH_AUTO_ACCEPT_PERMISSIONS.", {
+    mode: z.enum(["auto-accept", "ask", "off"]),
+}, async ({ mode }) => {
+    try {
+        const next = mode;
+        permissionInterceptor.setMode(next);
+        return {
+            ...jsonText({
+                mode: next,
+                message: `Permission interceptor mode set to '${next}'.`,
+            }),
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_permission_auto_accept failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("rn_reload", "Request a JS bundle reload on the running RN app by dispatching the " +
+    "`ceraph://reload` deep link through WDA. Requires the app to have " +
+    "called `installSignalCapture()` (or otherwise registered the " +
+    "reload deep-link listener) at boot. Waits up to `timeoutMs` for " +
+    "WDA to become responsive again, then captures a screenshot. " +
+    "Dev-only; does nothing in a production build.", {
+    timeoutMs: z
+        .number()
+        .optional()
+        .describe("Max time in ms to wait for the app to come back after the " +
+        "reload (default 10000)."),
+}, async ({ timeoutMs }) => {
+    try {
+        const guard = await requireWDA();
+        if (!guard.ok)
+            return { ...jsonText(guard.payload), isError: true };
+        const dispatch = await screenManager.openUrl("ceraph://reload");
+        if (!dispatch.success) {
+            return {
+                ...jsonText({
+                    success: false,
+                    error: dispatch.error ?? "openUrl failed",
+                }),
+                isError: true,
+            };
+        }
+        const limit = timeoutMs ?? 10_000;
+        const start = Date.now();
+        let backUp = false;
+        while (Date.now() - start < limit) {
+            const ok = await screenManager.pingStatus().catch(() => false);
+            if (ok) {
+                backUp = true;
+                break;
+            }
+            await new Promise((r) => setTimeout(r, 200));
+        }
+        const shot = await screenManager.screenshot().catch(() => undefined);
+        return {
+            ...jsonText({
+                success: backUp,
+                elapsedMs: Date.now() - start,
+                screenshotBase64: shot?.base64,
+                error: backUp ? undefined : `WDA did not return within ${limit}ms`,
+            }),
+            isError: !backUp,
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_reload failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
 server.tool("rn_stop", "Stop all managed React Native processes (Metro dev server and/or build process).", {}, async () => {
     try {
         const stopped = await rnManager.stopAll();
@@ -428,13 +1211,440 @@ server.tool("rn_stop", "Stop all managed React Native processes (Metro dev serve
         };
     }
 });
-// ---------------------------------------------------------------------------
-// Start the server
-// ---------------------------------------------------------------------------
+server.tool("rn_target_status", "Report which iOS target is currently selected (device vs simulator), " +
+    "the resolved WDA base URL, whether a simulator WDA session is " +
+    "running, and the CERAPH_TARGET env preference. Call this when the " +
+    "developer asks `am I testing on device or simulator?` or before " +
+    "starting a flow if uncertain which transport is active.", {}, async () => {
+    try {
+        targetResolver.invalidate();
+        const info = await targetResolver.resolve();
+        const session = wdaManager.getSession();
+        return jsonText({
+            target: info.target,
+            udid: info.udid,
+            baseUrl: info.baseUrl,
+            reason: info.reason,
+            preferenceEnv: process.env.CERAPH_TARGET ?? null,
+            simulatorWdaSession: session
+                ? { port: session.port, udid: session.udid, projectPath: session.projectPath }
+                : null,
+        });
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_target_status failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("rn_wda_start", "Build and launch WebDriverAgent against a booted iOS simulator. " +
+    "Required ONCE per MCP session when testing on the simulator (real " +
+    "devices don't need this). Reads `appium-webdriveragent` from " +
+    "node_modules (optional dep — install with `npm i -D " +
+    "appium-webdriveragent` if missing). Captures the WDA port from " +
+    "xcodebuild's output and routes all screen_*/app_* tools to the " +
+    "simulator automatically. First-time build can take 60-120s and " +
+    "may require an Xcode signing prompt. Idempotent — re-calling " +
+    "returns the existing session.", {
+    udid: z
+        .string()
+        .optional()
+        .describe("Booted simulator UDID. When omitted, the first booted " +
+        "simulator is used. Run `xcrun simctl list devices booted` " +
+        "to see options."),
+    startupTimeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Max wait for the `ServerURLHere->...<-ServerURLHere` marker " +
+        "in xcodebuild's stdout. Default 120000ms (cold-build safe)."),
+}, async ({ udid, startupTimeoutMs }) => {
+    try {
+        const result = await wdaManager.start({ udid, startupTimeoutMs });
+        return { ...jsonText(result), isError: !result.ok };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_wda_start failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("rn_wda_stop", "Stop the simulator WebDriverAgent session started by rn_wda_start. " +
+    "Idempotent — returns `{ stopped: false }` when no session is " +
+    "active. Real-device WDA is unaffected (it's managed by Xcode, " +
+    "not this MCP).", {}, async () => {
+    try {
+        const result = await wdaManager.stop();
+        return jsonText(result);
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_wda_stop failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("rn_boot_simulator", "Boot an iOS simulator from cold via `xcrun simctl`. Use this when " +
+    "the developer doesn't have a real device plugged in and no " +
+    "simulator is already booted — preflight will surface that state. " +
+    "Auto-picks the newest available iPhone (preferring the plain " +
+    "model like `iPhone 15` over `iPhone 15 Pro Max`) unless `udid` " +
+    "or `deviceType` narrows the choice. Idempotent — returns " +
+    "`{ alreadyBooted: true }` when the chosen sim is already running. " +
+    "After this succeeds, call rn_wda_start to ready WebDriverAgent, " +
+    "then retry the original test tool.", {
+    udid: z
+        .string()
+        .optional()
+        .describe("Boot a specific simulator by UDID. When set, discovery is " +
+        "skipped (deviceType is ignored). Run `xcrun simctl list " +
+        "devices` to see options."),
+    deviceType: z
+        .string()
+        .optional()
+        .describe("Substring match against simulator names (case-insensitive, " +
+        "e.g. `iPhone 15`, `iPhone 14 Pro`). Picks the newest iOS " +
+        "runtime among matches. Ignored when `udid` is set."),
+    bootTimeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Max wait for `simctl bootstatus -b` to confirm the simulator " +
+        "has settled. Default 120000ms (first boots of a fresh " +
+        "runtime can take 60-90s)."),
+}, async ({ udid, deviceType, bootTimeoutMs }) => {
+    try {
+        const result = await bootSimulator({ udid, deviceType, bootTimeoutMs });
+        targetResolver.invalidate();
+        return jsonText(result);
+    }
+    catch (err) {
+        return toolErrorContent("rn_boot_simulator", err);
+    }
+});
+server.tool("rn_wait_for_device", "Wait for an iPhone to be connected via USB-C. Uses macOS's " +
+    "usbmuxd daemon for sub-second event-driven detection (no " +
+    "polling). Waits indefinitely until either a device connects or " +
+    "the agent aborts the call. Use this after telling the user " +
+    "'please plug in your iPhone' — the call resolves immediately " +
+    "when they do, with zero detection lag.", {
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional explicit deadline in milliseconds. Default: none — " +
+        "the call waits forever and relies on the MCP abort signal " +
+        "for cancellation. Set this only when you want a hard cap."),
+}, async ({ timeoutMs }, extra) => {
+    try {
+        const result = await waitForDevice({
+            timeoutMs,
+            signal: extra.signal,
+        });
+        targetResolver.invalidate();
+        return jsonText(result);
+    }
+    catch (err) {
+        return toolErrorContent("rn_wait_for_device", err);
+    }
+});
+function initToolResult(payload) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(payload, null, 2) },
+        ],
+    };
+}
+function initToolError(toolName, err) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${toolName} failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        ],
+        isError: true,
+    };
+}
+server.tool("ceraph_init_status", "Snapshot the current init state of the project: which steps are " +
+    "complete (package installed, GitHub auth cached, ceraph:// scheme " +
+    "registered, installCeraph() injected, CameraView usages found) and " +
+    "which MCP-client config files exist. Use this FIRST to decide which " +
+    "individual init tools still need to run.", {
+    projectDir: z
+        .string()
+        .optional()
+        .describe("Directory to inspect. Defaults to the MCP server's cwd " +
+        "(usually the user's project root)."),
+}, async ({ projectDir }) => {
+    try {
+        const result = await getInitStatus(projectDir ?? PROJECT_DIR);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_status", err);
+    }
+});
+server.tool("ceraph_init_install_package", "Detect the project's package manager (pnpm/yarn/bun/npm via lockfile) " +
+    "and install @ceraph/react-native-mcp into dependencies. Idempotent — " +
+    "returns `{ already: true }` if the package is already in package.json.", {
+    projectDir: z.string().optional(),
+}, async ({ projectDir }) => {
+    try {
+        const result = await installCeraphPackage(projectDir ?? PROJECT_DIR);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_install_package", err);
+    }
+});
+server.tool("ceraph_init_auth_start", "Begin the GitHub OAuth device flow. Returns { verificationUri, " +
+    "userCode, pollUrl } — surface verificationUri + userCode to the user " +
+    "VERBATIM (don't paraphrase), then call ceraph_init_auth_poll with " +
+    "pollUrl in a short loop (every ~5 seconds) until status is 'complete' " +
+    "or 'failed'.", {}, async () => {
+    try {
+        const result = await startAuthFlow();
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_auth_start", err);
+    }
+});
+server.tool("ceraph_init_auth_poll", "Poll the in-progress device flow once. Returns one of: " +
+    "{ status: 'pending' }, { status: 'slow_down', intervalSeconds }, " +
+    "{ status: 'complete', login }, or { status: 'failed', reason }. " +
+    "Wait `intervalSeconds` before the next call on slow_down. Stop when " +
+    "status === 'complete' or 'failed'. On 'failed', restart with " +
+    "ceraph_init_auth_start (NOT a retry of the same pollUrl).", {
+    pollUrl: z
+        .string()
+        .describe("Opaque handle returned by ceraph_init_auth_start."),
+}, async ({ pollUrl }) => {
+    try {
+        const result = await pollAuthFlow(pollUrl);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_auth_poll", err);
+    }
+});
+server.tool("ceraph_init_scan_camera", "AST-scan the project for <CameraView> usages (from expo-camera). " +
+    "Returns each usage with its file path, line, suggested imageKey " +
+    "(heuristic), and ~30 lines of surrounding code so the AI can " +
+    "reason about what to put in imageKey. The AI should override the " +
+    "suggestion based on context (e.g. a `project.type === 'uppercase'` " +
+    "branch nearby implies imageKey='letter-uppercase').", {
+    projectDir: z.string().optional(),
+}, async ({ projectDir }) => {
+    try {
+        const result = await scanCameraUsages(projectDir ?? PROJECT_DIR);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_scan_camera", err);
+    }
+});
+server.tool("ceraph_init_replace_camera", "Apply ONE <CameraView> → <CeraphCamera imageKey=\"...\"> AST " +
+    "replacement. The AI provides the imageKey based on the context it " +
+    "saw in scan_camera's surroundingCode. Also adds the shim import " +
+    "and trims `CameraView` from the expo-camera import when no JSX " +
+    "uses it anymore. Idempotent — returns `{ already: true }` when " +
+    "the line is already CeraphCamera.", {
+    filePath: z.string().describe("Absolute path of the source file."),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based line of the opening <CameraView> tag."),
+    imageKey: z
+        .string()
+        .min(1)
+        .describe("The imageKey to use. Should be lowercase-with-dashes."),
+    projectDir: z.string().optional(),
+}, async ({ filePath, line, imageKey, projectDir }) => {
+    try {
+        const result = await replaceCameraView(projectDir ?? PROJECT_DIR, {
+            filePath,
+            line,
+            imageKey,
+        });
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_replace_camera", err);
+    }
+});
+server.tool("ceraph_init_inject_boot", "AST-inject `useEffect(() => { installCeraph(); }, [])` plus the " +
+    "shim + react imports into the root layout (app/_layout.tsx for " +
+    "Expo Router, App.tsx for bare RN). Idempotent — returns " +
+    "`{ already: true }` when installCeraph() is already present.", {
+    projectDir: z.string().optional(),
+}, async ({ projectDir }) => {
+    try {
+        const result = await injectBoot(projectDir ?? PROJECT_DIR);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_inject_boot", err);
+    }
+});
+server.tool("ceraph_init_register_scheme", "Register `ceraph` as a custom URL scheme so deep links " +
+    "(ceraph://test-image, ceraph://reload, ceraph://reset) reach the " +
+    "running app. Auto-edits static expo.scheme in app.json; for " +
+    "dynamic app.config.{js,ts} or bare RN, returns the exact " +
+    "instructions to surface to the user.", {
+    projectDir: z.string().optional(),
+}, async ({ projectDir }) => {
+    try {
+        const result = await registerScheme(projectDir ?? PROJECT_DIR);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_register_scheme", err);
+    }
+});
+server.tool("ceraph_init_setup_images_dir", "Create the `.ceraph/camera-images/` directory with a README that " +
+    "documents the imageKey naming convention, and append " +
+    "`.rn-errors.json`, `.rn-flow-progress.json`, `.rn-mcp-cache/` to " +
+    ".gitignore. Idempotent — second invocation reports no changes.", {
+    projectDir: z.string().optional(),
+}, async ({ projectDir }) => {
+    try {
+        const result = await setupImagesDir(projectDir ?? PROJECT_DIR);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_setup_images_dir", err);
+    }
+});
+server.tool("ceraph_init_setup_mcp_clients", "Write MCP server config blocks to every supported editor's local " +
+    "config file: .mcp.json (Claude Code), .cursor/mcp.json (Cursor), " +
+    ".codex/config.toml (Codex), .vscode/mcp.json (VS Code). Returns " +
+    "{ written: string[], skipped: string[] }. Skip = already had the " +
+    "react-native-mcp entry.", {
+    projectDir: z.string().optional(),
+}, async ({ projectDir }) => {
+    try {
+        const result = await setupMcpClients(projectDir ?? PROJECT_DIR);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_setup_mcp_clients", err);
+    }
+});
+server.tool("ceraph_init_preflight", "Run the full preflight check suite (Xcode, WDA, device, app, " +
+    "camera-images sync, etc.) and return the structured result. Use " +
+    "this AFTER the other init tools to verify the project is ready " +
+    "to run flows.", {
+    projectDir: z.string().optional(),
+}, async ({ projectDir }) => {
+    try {
+        const result = await preflightForMcp(projectDir ?? PROJECT_DIR, {
+            screen: screenManager,
+            apps: appLifecycle,
+            autonomy: deviceAutonomy,
+            target: targetResolver,
+            iproxyManager,
+        });
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_preflight", err);
+    }
+});
+server.tool("ceraph_init_monorepo_status", "Inspect the project root for monorepo signals (package.json " +
+    "workspaces, pnpm-workspace.yaml, lerna.json) and return any RN/Expo " +
+    "subpackages found. If the cwd is itself an RN app, " +
+    "`rootIsRnApp: true` and `matches: []`. Use this before calling other " +
+    "init tools — when matches.length === 1, pass that absPath as " +
+    "projectDir to every subsequent ceraph_init_* call.", {
+    projectDir: z.string().optional(),
+}, async ({ projectDir }) => {
+    try {
+        const result = await detectMonorepoStatus(projectDir ?? PROJECT_DIR);
+        return initToolResult(result);
+    }
+    catch (err) {
+        return initToolError("ceraph_init_monorepo_status", err);
+    }
+});
+registerUninstallTools(server);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[react-native-mcp] Server started on stdio transport");
+    if (!process.env.CERAPH_SIGNAL_HOST) {
+        try {
+            const detected = detectMacLanIp();
+            if (detected) {
+                process.env.CERAPH_SIGNAL_HOST = detected.address;
+                console.error(`[react-native-mcp] CERAPH_SIGNAL_HOST auto-detected: ${detected.address} ` +
+                    `(${detected.interfaceName}, ${detected.kind}). To persist across shells, ` +
+                    `run \`npx @ceraph/react-native-mcp init\` — it adds the export to ~/.zshrc.`);
+            }
+            else {
+                console.error("[react-native-mcp] CERAPH_SIGNAL_HOST is unset and no LAN IP was " +
+                    "auto-detectable. Real-device shim signals will default to " +
+                    "localhost (which the device cannot reach back to the Mac). " +
+                    "Set it manually: export CERAPH_SIGNAL_HOST=<your-mac-ip>");
+            }
+        }
+        catch (err) {
+            console.error(`[react-native-mcp] CERAPH_SIGNAL_HOST auto-detection failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else {
+        console.error(`[react-native-mcp] CERAPH_SIGNAL_HOST=${process.env.CERAPH_SIGNAL_HOST}`);
+    }
+    const listenResult = await signalListener.start();
+    if (listenResult.ok) {
+        console.error(`[react-native-mcp] Signal listener bound on 127.0.0.1:${listenResult.port}`);
+    }
+    else if (listenResult.errorCode === "EADDRINUSE") {
+        console.error(`[react-native-mcp] ERROR: Port ${listenResult.port} is already in use.\n` +
+            "Another Ceraph MCP server is already running on this machine.\n" +
+            "Stop the existing process before starting a new one.\n" +
+            "(WDA port 8100 is owned by WDA itself and is a separate concern.)");
+        process.exit(1);
+    }
+    else {
+        console.error(`[react-native-mcp] Signal listener failed to bind on port ${listenResult.port}: ${listenResult.error}. ` +
+            "Shim-side signals (JS errors, unhandled rejections, network failures) will be dropped.");
+    }
+    const shutdown = async () => {
+        await Promise.all([
+            signalListener.stop().catch(() => undefined),
+            iproxyManager.stop().catch(() => undefined),
+        ]);
+        await wdaManager.stop().catch(() => undefined);
+    };
+    process.on("SIGINT", () => {
+        void shutdown().then(() => process.exit(0));
+    });
+    process.on("SIGTERM", () => {
+        void shutdown().then(() => process.exit(0));
+    });
 }
 main().catch((err) => {
     console.error("[react-native-mcp] Fatal error:", err);