@ceraph/react-native-mcp 0.2.0

package/dist/index.js

@@ -0,0 +1,442 @@
+#!/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";
+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).
+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 prebuildDetector = new PrebuildDetector(PROJECT_DIR, CACHE_DIR);
+// ---------------------------------------------------------------------------
+// Create MCP server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "react-native-mcp",
+    version: "0.1.0",
+}, {
+    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
+// ---------------------------------------------------------------------------
+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. " +
+    "If clean is true, runs `npx expo prebuild --clean` first (Expo only).", {
+    clean: z
+        .boolean()
+        .optional()
+        .describe("Run prebuild --clean before building (Expo only)"),
+    device: z
+        .string()
+        .optional()
+        .describe("Device UDID to target (e.g., 00008140-001958943A78801C)"),
+}, 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 {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_build_ios failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// 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
+        .number()
+        .optional()
+        .describe("Port for Metro bundler (default: 8081)"),
+    clear: z
+        .boolean()
+        .optional()
+        .describe("Clear Metro bundler cache on start"),
+}, async ({ port, clear }) => {
+    try {
+        const result = await rnManager.startMetro({ port, clear });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_start failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// 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 () => {
+    try {
+        const errors = rnManager.getErrors();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(errors, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_get_errors failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool: rn_get_console
+// ---------------------------------------------------------------------------
+server.tool("rn_get_console", "Return recent console output from Metro dev server, " +
+    "optionally filtered by log level.", {
+    lines: z
+        .number()
+        .optional()
+        .describe("Number of recent lines to return (default: 50)"),
+    level: z
+        .enum(["all", "error", "warn", "log"])
+        .optional()
+        .describe("Filter by log level (default: all)"),
+}, async ({ lines, level }) => {
+    try {
+        const output = rnManager.getConsole({ lines, level });
+        if (output.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No console output captured. Is Metro running? Use rn_start to launch it.",
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: output.join("\n"),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_get_console failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// 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 () => {
+    try {
+        const isExpo = await rnManager.detectProjectType();
+        if (!isExpo) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            needsClean: false,
+                            reasons: ["Not an Expo project. Prebuild detection is Expo-only."],
+                        }),
+                    },
+                ],
+            };
+        }
+        const result = await prebuildDetector.check();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_check_prebuild failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// 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). " +
+    "Requires WebDriverAgent running on localhost:8100.", {
+    x: z.number().describe("X coordinate to tap"),
+    y: z.number().describe("Y coordinate to tap"),
+    coordinateSource: z
+        .enum(["screenshot", "device"])
+        .optional()
+        .describe("Source of coordinates: 'screenshot' (default) auto-corrects " +
+        "for pixel ratio; 'device' uses coordinates as-is"),
+}, async ({ x, y, coordinateSource }) => {
+    try {
+        const available = await screenManager.isAvailable();
+        if (!available) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "WebDriverAgent is not reachable at localhost:8100. " +
+                                "Ensure it is running on the device.",
+                            tappedAt: { x, y },
+                            pixelRatio: 0,
+                            correction: "N/A",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const fromScreenshot = (coordinateSource ?? "screenshot") === "screenshot";
+        const result = await screenManager.tap(x, y, fromScreenshot);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_tap failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// 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. " +
+    "Requires WebDriverAgent running on localhost:8100.", {
+    text: z
+        .string()
+        .optional()
+        .describe("Text content to search for (case-insensitive substring match)"),
+    accessibilityLabel: z
+        .string()
+        .optional()
+        .describe("Accessibility label to search for (case-insensitive substring match)"),
+    type: z
+        .string()
+        .optional()
+        .describe("Element type to filter by (e.g., XCUIElementTypeButton, XCUIElementTypeStaticText)"),
+    index: z
+        .number()
+        .optional()
+        .describe("If multiple matches, tap the nth match (0-indexed, default: 0)"),
+}, async ({ text, accessibilityLabel, type, index }) => {
+    try {
+        const available = await screenManager.isAvailable();
+        if (!available) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "WebDriverAgent is not reachable at localhost:8100. " +
+                                "Ensure it is running on the device.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (!text && !accessibilityLabel && !type) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "At least one of text, accessibilityLabel, or type must be provided.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const result = await screenManager.findAndTap({
+            text,
+            accessibilityLabel,
+            type,
+            index,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `screen_find_and_tap failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool: rn_stop
+// ---------------------------------------------------------------------------
+server.tool("rn_stop", "Stop all managed React Native processes (Metro dev server and/or build process).", {}, async () => {
+    try {
+        const stopped = await rnManager.stopAll();
+        if (stopped.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            stopped: [],
+                            message: "No managed processes were running.",
+                        }),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ stopped }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `rn_stop failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Start the server
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[react-native-mcp] Server started on stdio transport");
+}
+main().catch((err) => {
+    console.error("[react-native-mcp] Fatal error:", err);
+    process.exit(1);
+});

package/dist/init.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * @ceraph/react-native-mcp init
+ *
+ * Sets up MCP configuration and the runtime error hook for the current project.
+ * Detects which MCP clients are in use and writes config for each one.
+ */
+export {};

package/dist/init.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * @ceraph/react-native-mcp init
+ *
+ * Sets up MCP configuration and the runtime error hook for the current project.
+ * Detects which MCP clients are in use and writes config for each one.
+ */
+import { readFile, writeFile, mkdir, access, chmod } from "node:fs/promises";
+import { join } from "node:path";
+const PROJECT_DIR = process.cwd();
+// ---------------------------------------------------------------------------
+// Hook script content
+// ---------------------------------------------------------------------------
+const HOOK_SCRIPT = `#!/bin/bash
+# rn-error-notify.sh — Injected by @ceraph/react-native-mcp init
+# Reads .rn-errors.json and injects runtime errors into Claude's context.
+
+ERROR_FILE="\$CLAUDE_PROJECT_DIR/mobile/.rn-errors.json"
+
+# Also check project root if mobile/ doesn't exist
+if [ ! -f "\$ERROR_FILE" ]; then
+  ERROR_FILE="\$CLAUDE_PROJECT_DIR/.rn-errors.json"
+fi
+
+if [ ! -f "\$ERROR_FILE" ]; then
+  exit 0
+fi
+
+ERROR_COUNT=\$(jq -r '.errors | length' "\$ERROR_FILE" 2>/dev/null)
+
+if [ "\$ERROR_COUNT" = "0" ] || [ -z "\$ERROR_COUNT" ]; then
+  exit 0
+fi
+
+echo "REACT NATIVE RUNTIME ERROR DETECTED:"
+echo ""
+jq -r '.errors[] | "Error: \\(.message)\\nStack: \\(.stack)\\nTime: \\(.timestamp)\\n---"' "\$ERROR_FILE" 2>/dev/null
+echo ""
+echo "Use rn_get_errors for full details. Fix the error and rebuild."
+`;
+// ---------------------------------------------------------------------------
+// MCP server entry (same for all JSON-based clients)
+// ---------------------------------------------------------------------------
+const MCP_ENTRY = {
+    "mobile-mcp": {
+        command: "npx",
+        args: ["-y", "@mobilenext/mobile-mcp@latest"],
+    },
+    "react-native-mcp": {
+        command: "npx",
+        args: ["-y", "@ceraph/react-native-mcp@latest"],
+    },
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJson(path) {
+    try {
+        const content = await readFile(path, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeJson(path, data) {
+    await mkdir(join(path, ".."), { recursive: true });
+    await writeFile(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function log(msg) {
+    console.log(`  ${msg}`);
+}
+// ---------------------------------------------------------------------------
+// MCP config writers
+// ---------------------------------------------------------------------------
+async function setupJsonMcp(configPath, label) {
+    const existing = (await readJson(configPath)) ?? {};
+    const servers = (existing.mcpServers ?? {});
+    if (servers["react-native-mcp"]) {
+        log(`${label}: already configured`);
+        return false;
+    }
+    servers["mobile-mcp"] = MCP_ENTRY["mobile-mcp"];
+    servers["react-native-mcp"] = MCP_ENTRY["react-native-mcp"];
+    existing.mcpServers = servers;
+    await writeJson(configPath, existing);
+    log(`${label}: configured ✓`);
+    return true;
+}
+async function setupCodexToml(configPath) {
+    let content = "";
+    try {
+        content = await readFile(configPath, "utf-8");
+    }
+    catch {
+        // File doesn't exist, we'll create it
+    }
+    if (content.includes("react-native-mcp")) {
+        log("Codex: already configured");
+        return false;
+    }
+    const tomlBlock = `
+[mcp_servers.mobile-mcp]
+command = "npx"
+args = ["-y", "@mobilenext/mobile-mcp@latest"]
+
+[mcp_servers.react-native-mcp]
+command = "npx"
+args = ["-y", "@ceraph/react-native-mcp@latest"]
+`;
+    await mkdir(join(configPath, ".."), { recursive: true });
+    await writeFile(configPath, content + tomlBlock, "utf-8");
+    log("Codex: configured ✓");
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Hook setup
+// ---------------------------------------------------------------------------
+async function setupClaudeHook() {
+    // Write the hook script
+    const hooksDir = join(PROJECT_DIR, ".claude", "hooks");
+    const hookPath = join(hooksDir, "rn-error-notify.sh");
+    await mkdir(hooksDir, { recursive: true });
+    await writeFile(hookPath, HOOK_SCRIPT, "utf-8");
+    await chmod(hookPath, 0o755);
+    log("Hook script: .claude/hooks/rn-error-notify.sh ✓");
+    // Add FileChanged hook to settings.
+    // Check both settings.json and settings.local.json — if either already has
+    // the hook, we treat it as configured. This prevents duplicate hooks (which
+    // would fire twice per .rn-errors.json write) for projects where the hook
+    // was originally written to settings.local.json.
+    const sharedSettingsPath = join(PROJECT_DIR, ".claude", "settings.json");
+    const localSettingsPath = join(PROJECT_DIR, ".claude", "settings.local.json");
+    const isMatcher = (h) => h.matcher === ".rn-errors.json";
+    const fileChangedFrom = (s) => {
+        const hooks = (s?.hooks ?? {});
+        return (hooks.FileChanged ?? []);
+    };
+    const sharedSettings = await readJson(sharedSettingsPath);
+    const localSettings = await readJson(localSettingsPath);
+    if (fileChangedFrom(sharedSettings).some(isMatcher) ||
+        fileChangedFrom(localSettings).some(isMatcher)) {
+        log("Claude Code hook: already configured");
+        return;
+    }
+    // Write to settings.json (the shared default). settings.local.json is
+    // reserved for per-machine overrides; we don't write there.
+    const settings = sharedSettings ?? {};
+    const hooks = (settings.hooks ?? {});
+    const fileChangedHooks = (hooks.FileChanged ?? []);
+    fileChangedHooks.push({
+        matcher: ".rn-errors.json",
+        hooks: [
+            {
+                type: "command",
+                command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/rn-error-notify.sh',
+            },
+        ],
+    });
+    hooks.FileChanged = fileChangedHooks;
+    settings.hooks = hooks;
+    await writeJson(sharedSettingsPath, settings);
+    log("Claude Code hook: FileChanged → .rn-errors.json ✓");
+}
+// ---------------------------------------------------------------------------
+// Gitignore
+// ---------------------------------------------------------------------------
+async function setupGitignore() {
+    const gitignorePath = join(PROJECT_DIR, ".gitignore");
+    let content = "";
+    try {
+        content = await readFile(gitignorePath, "utf-8");
+    }
+    catch {
+        // No .gitignore yet
+    }
+    const entries = [".rn-errors.json", ".rn-mcp-cache/"];
+    const missing = entries.filter((e) => !content.includes(e));
+    if (missing.length === 0) {
+        return;
+    }
+    const prefix = content === "" || content.endsWith("\n") ? "" : "\n";
+    const addition = prefix + missing.join("\n") + "\n";
+    await writeFile(gitignorePath, content + addition, "utf-8");
+    log(`.gitignore: added ${missing.join(", ")} ✓`);
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    console.log("\n@ceraph/react-native-mcp init\n");
+    // Detect and configure MCP clients
+    console.log("MCP configuration:");
+    // Claude Code
+    await setupJsonMcp(join(PROJECT_DIR, ".mcp.json"), "Claude Code");
+    // Cursor
+    await setupJsonMcp(join(PROJECT_DIR, ".cursor", "mcp.json"), "Cursor");
+    // Codex
+    await setupCodexToml(join(PROJECT_DIR, ".codex", "config.toml"));
+    // VS Code / Copilot
+    await setupJsonMcp(join(PROJECT_DIR, ".vscode", "mcp.json"), "VS Code");
+    // Windsurf (user-level config)
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (home) {
+        const windsurfPath = join(home, ".codeium", "windsurf", "mcp_config.json");
+        if (await fileExists(join(home, ".codeium", "windsurf"))) {
+            await setupJsonMcp(windsurfPath, "Windsurf");
+        }
+        // Antigravity (user-level config)
+        const antigravityPath = join(home, ".gemini", "antigravity", "mcp_config.json");
+        if (await fileExists(join(home, ".gemini", "antigravity"))) {
+            await setupJsonMcp(antigravityPath, "Antigravity");
+        }
+    }
+    // Claude Code error hook
+    console.log("\nRuntime error hook:");
+    await setupClaudeHook();
+    // Gitignore
+    console.log("\nGitignore:");
+    await setupGitignore();
+    console.log("\nDone. Runtime errors will be automatically injected into Claude's context.\n");
+}
+main().catch((err) => {
+    console.error("Init failed:", err);
+    process.exit(1);
+});