@ceraph/react-native-mcp 0.2.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,196 @@
+# @ceraph/react-native-mcp
+
+MCP server for React Native and Expo development. Automatic build error capture, console monitoring, reliable screen interactions, and prebuild detection.
+
+Works with any MCP client: Claude Code, Cursor, Codex, Windsurf, and others.
+
+## Requirements
+
+- Node.js 18+
+- macOS (for iOS Simulator/device support)
+- [WebDriverAgent](https://github.com/appium/WebDriverAgent) running on `localhost:8100`
+- [`mobile-mcp`](https://github.com/mobile-next/mobile-mcp) for screenshots, swipe, and device management
+- Expo dev client or prebuilt app (Expo Go is not supported)
+
+## Quick Setup
+
+Run this from your project root:
+
+```bash
+npx @ceraph/react-native-mcp init
+```
+
+This automatically:
+- Configures MCP servers for all detected clients (Claude Code, Cursor, Codex, VS Code, Windsurf, Antigravity)
+- Installs a Claude Code hook that injects runtime errors into your conversation automatically
+- Adds `.rn-errors.json` to your `.gitignore`
+
+## Manual Setup
+
+If you prefer to configure manually, follow the instructions for your client below.
+
+### Claude Code
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "mobile-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+    },
+    "react-native-mcp": {
+      "command": "npx",
+      "args": ["-y", "@ceraph/react-native-mcp@latest"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "mobile-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+    },
+    "react-native-mcp": {
+      "command": "npx",
+      "args": ["-y", "@ceraph/react-native-mcp@latest"]
+    }
+  }
+}
+```
+
+### Codex
+
+Add to `.codex/config.toml` in your project root:
+
+```toml
+[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"]
+```
+
+### VS Code / Copilot
+
+Add to `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "mobile-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+    },
+    "react-native-mcp": {
+      "command": "npx",
+      "args": ["-y", "@ceraph/react-native-mcp@latest"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json` (or Settings → Advanced Settings → Cascade):
+
+```json
+{
+  "mcpServers": {
+    "mobile-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+    },
+    "react-native-mcp": {
+      "command": "npx",
+      "args": ["-y", "@ceraph/react-native-mcp@latest"]
+    }
+  }
+}
+```
+
+### Antigravity
+
+Add to `~/.gemini/antigravity/mcp_config.json` (or Manage MCP Servers → View raw config):
+
+```json
+{
+  "mcpServers": {
+    "mobile-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+    },
+    "react-native-mcp": {
+      "command": "npx",
+      "args": ["-y", "@ceraph/react-native-mcp@latest"]
+    }
+  }
+}
+```
+
+### Cline / Roo Code (VS Code extensions)
+
+Open VS Code Settings → Extensions → Cline (or Roo Code) → MCP Servers, then add:
+
+```json
+{
+  "mobile-mcp": {
+    "command": "npx",
+    "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+  },
+  "react-native-mcp": {
+    "command": "npx",
+    "args": ["-y", "@ceraph/react-native-mcp@latest"]
+  }
+}
+```
+
+### JetBrains IDEs
+
+Settings → Tools → MCP Servers → Add, then enter:
+
+- **Name:** `react-native-mcp`
+- **Command:** `npx`
+- **Args:** `-y @ceraph/react-native-mcp@latest`
+
+Repeat for `mobile-mcp` with args `-y @mobilenext/mobile-mcp@latest`.
+
+## Tools
+
+### Build & Runtime
+
+| Tool | Description |
+|---|---|
+| `rn_build_ios` | Build the app with `expo run:ios`. Captures Xcode output and returns structured errors (file, line, message, type). Optionally runs `prebuild --clean` first. |
+| `rn_start` | Start Metro dev server. Monitors console output for runtime errors, JS exceptions, and red screens. |
+| `rn_get_errors` | Return all captured build and runtime errors without re-running anything. |
+| `rn_get_console` | Return recent Metro console output, filtered by log level. |
+| `rn_check_prebuild` | Detect if `prebuild --clean` is needed by diffing `package.json`, `app.json`, and `Podfile.lock` against the last successful build. |
+| `rn_stop` | Kill all managed React Native processes. |
+
+### Screen Interaction
+
+| Tool | Description |
+|---|---|
+| `screen_tap` | Tap at coordinates with automatic pixel ratio correction. Screenshot coordinates are divided by the device pixel ratio (2x/3x) so taps land where you expect. |
+| `screen_find_and_tap` | Find an element by text, accessibility label, or type, then tap its center. Most reliable interaction method — no coordinate guessing. |
+
+## Why both MCPs?
+
+`mobile-mcp` handles low-level device interaction (screenshots, swipe, app lifecycle, recording) and is actively maintained for iOS/Android compatibility.
+
+`@ceraph/react-native-mcp` adds the development workflow layer on top: structured error capture, console monitoring, pixel-ratio-corrected taps, and prebuild detection. Both talk to WebDriverAgent independently — they don't depend on each other, they complement each other.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * @ceraph/react-native-mcp CLI entry point.
+ *
+ * Usage:
+ *   npx @ceraph/react-native-mcp init   — set up MCP config and error hook
+ *   npx @ceraph/react-native-mcp        — start the MCP server (stdio transport)
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * @ceraph/react-native-mcp CLI entry point.
+ *
+ * Usage:
+ *   npx @ceraph/react-native-mcp init   — set up MCP config and error hook
+ *   npx @ceraph/react-native-mcp        — start the MCP server (stdio transport)
+ */
+const command = process.argv[2];
+if (command === "init") {
+    await import("./init.js");
+}
+else {
+    await import("./index.js");
+}
+export {};

package/dist/error-parser.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Parses Xcode build errors, Metro bundler errors, and runtime errors
+ * from raw process output.
+ */
+export interface BuildError {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+    severity: "error" | "warning" | "note";
+    type: "build" | "link" | "pod";
+}
+export interface RuntimeError {
+    message: string;
+    stack: string;
+    timestamp: string;
+}
+export interface Warning {
+    message: string;
+    source: string;
+}
+export interface AllErrors {
+    buildErrors: BuildError[];
+    runtimeErrors: RuntimeError[];
+    warnings: Warning[];
+}
+/**
+ * Parse all build output lines and extract structured errors.
+ */
+export declare function parseBuildOutput(lines: string[]): {
+    errors: BuildError[];
+    warnings: Warning[];
+    buildFailed: boolean;
+};
+/**
+ * Stateful parser for Metro output. Multi-line errors (message + stack
+ * trace) arrive across multiple `onData` chunks, so the in-progress
+ * error must persist across calls. Use one instance per Metro session
+ * and call `parse(lines)` as chunks arrive; call `flush()` at the end
+ * (e.g. on process exit) to emit any error still being assembled.
+ */
+export declare class MetroErrorParser {
+    private currentStack;
+    private currentErrorMessage;
+    private inStackTrace;
+    parse(lines: string[]): {
+        runtimeErrors: RuntimeError[];
+        warnings: Warning[];
+    };
+    /**
+     * Force-emit any error currently being assembled. Call on stream end.
+     */
+    flush(): {
+        runtimeErrors: RuntimeError[];
+        warnings: Warning[];
+    };
+}
+/**
+ * Parse a complete Metro buffer in one shot. Suitable for batch use
+ * (e.g. `getErrors()` re-parsing the rolling buffer); for streaming use
+ * a `MetroErrorParser` instance instead so multi-line state survives
+ * across chunks.
+ */
+export declare function parseMetroOutput(lines: string[]): {
+    runtimeErrors: RuntimeError[];
+    warnings: Warning[];
+};
+/**
+ * Classify a log line by level.
+ */
+export declare function classifyLogLevel(line: string): "error" | "warn" | "log";

package/dist/error-parser.js

@@ -0,0 +1,345 @@
+/**
+ * Parses Xcode build errors, Metro bundler errors, and runtime errors
+ * from raw process output.
+ */
+// Xcode-style: /path/to/File.swift:12:5: error: something went wrong
+const XCODE_ERROR_RE = /^(.+?):(\d+):(\d+):\s*(error|warning|note):\s*(.+)$/;
+// Xcode build failure markers
+const BUILD_FAILED_MARKERS = [
+    "Build Failed",
+    "** BUILD FAILED **",
+    "xcodebuild: error:",
+    "❌",
+];
+// Linker errors
+const LINKER_ERROR_RE = /^(ld|clang):\s*(error|warning):\s*(.+)$/;
+const UNDEFINED_SYMBOL_RE = /^Undefined symbols? for architecture .+:\s*"(.+)"/;
+// CocoaPods errors
+const POD_ERROR_RE = /^\[!\]\s*(.+)$/;
+// Metro bundler errors
+const METRO_ERROR_RE = /^(Error|TypeError|ReferenceError|SyntaxError|RangeError):\s*(.+)$/;
+const METRO_MODULE_RE = /Unable to resolve module ['"](.+?)['"]/;
+const METRO_ENCOUNTERED_RE = /Metro has encountered an error/;
+// Runtime errors from console
+const CONSOLE_ERROR_RE = /^(ERROR|console\.error)\s*(.+)$/i;
+const INVARIANT_RE = /Invariant Violation:\s*(.+)/;
+const UNHANDLED_JS_RE = /Unhandled JS Exception:\s*(.+)/;
+const RED_SCREEN_RE = /ExceptionsManager\.js/;
+/**
+ * Parse a single line for Xcode build errors/warnings.
+ */
+function parseXcodeLine(line) {
+    const match = line.match(XCODE_ERROR_RE);
+    if (match) {
+        return {
+            file: match[1],
+            line: parseInt(match[2], 10),
+            column: parseInt(match[3], 10),
+            message: match[5],
+            severity: match[4],
+            type: "build",
+        };
+    }
+    return null;
+}
+/**
+ * Parse a single line for linker errors.
+ */
+function parseLinkerLine(line) {
+    const linkerMatch = line.match(LINKER_ERROR_RE);
+    if (linkerMatch) {
+        return {
+            file: "",
+            line: 0,
+            column: 0,
+            message: linkerMatch[3],
+            severity: linkerMatch[2],
+            type: "link",
+        };
+    }
+    const undefinedMatch = line.match(UNDEFINED_SYMBOL_RE);
+    if (undefinedMatch) {
+        return {
+            file: "",
+            line: 0,
+            column: 0,
+            message: `Undefined symbol: ${undefinedMatch[1]}`,
+            severity: "error",
+            type: "link",
+        };
+    }
+    return null;
+}
+/**
+ * Parse a single line for CocoaPods notices.
+ *
+ * CocoaPods uses the `[!]` prefix for both errors and warnings. Default
+ * to `error` and only downgrade when the message matches a known-safe
+ * pattern (target overrides, deprecation hints, CDN/repo update notices,
+ * advisory "should" / "recommends" copy). This is closed under unknown
+ * failure modes — a new pod error vocabulary stays classified as an error
+ * rather than silently becoming a warning that lets a broken build
+ * resolve as success.
+ */
+const POD_SAFE_WARNING_RE = /\b(cdn|trunk|repo update|overrides the|setting defined in|deprecated|recommends|should)\b/i;
+function parsePodLine(line) {
+    const match = line.match(POD_ERROR_RE);
+    if (!match)
+        return null;
+    const message = match[1];
+    const isSafeWarning = POD_SAFE_WARNING_RE.test(message);
+    return {
+        file: "Podfile",
+        line: 0,
+        column: 0,
+        message,
+        severity: isSafeWarning ? "warning" : "error",
+        type: "pod",
+    };
+}
+/**
+ * Parse all build output lines and extract structured errors.
+ */
+export function parseBuildOutput(lines) {
+    const errors = [];
+    const warnings = [];
+    let buildFailed = false;
+    // Track multi-line error context: sometimes Xcode emits the error
+    // on one line and the source context on the next few lines.
+    // We append context to the last error's message.
+    let lastError = null;
+    let contextLines = 0;
+    const MAX_CONTEXT = 3;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            lastError = null;
+            contextLines = 0;
+            continue;
+        }
+        // Check for build failure markers
+        if (BUILD_FAILED_MARKERS.some((m) => trimmed.includes(m))) {
+            buildFailed = true;
+        }
+        // Try Xcode error format
+        const xcodeError = parseXcodeLine(trimmed);
+        if (xcodeError) {
+            if (xcodeError.severity === "error") {
+                errors.push(xcodeError);
+                lastError = xcodeError;
+                contextLines = 0;
+            }
+            else {
+                warnings.push({
+                    message: xcodeError.message,
+                    source: `${xcodeError.file}:${xcodeError.line}:${xcodeError.column}`,
+                });
+                // Don't set lastError for warnings/notes
+            }
+            continue;
+        }
+        // Try linker error format
+        const linkerError = parseLinkerLine(trimmed);
+        if (linkerError) {
+            if (linkerError.severity === "warning") {
+                warnings.push({ message: linkerError.message, source: "linker" });
+            }
+            else {
+                errors.push(linkerError);
+            }
+            lastError = linkerError;
+            contextLines = 0;
+            continue;
+        }
+        // Try CocoaPods notice format (warning or error depending on message)
+        const podNotice = parsePodLine(trimmed);
+        if (podNotice) {
+            if (podNotice.severity === "warning") {
+                warnings.push({ message: podNotice.message, source: "CocoaPods" });
+            }
+            else {
+                errors.push(podNotice);
+                lastError = podNotice;
+                contextLines = 0;
+            }
+            continue;
+        }
+        // Append context lines to last error for multi-line messages
+        if (lastError && contextLines < MAX_CONTEXT) {
+            lastError.message += `\n${trimmed}`;
+            contextLines++;
+        }
+    }
+    return { errors, warnings, buildFailed };
+}
+/**
+ * Stateful parser for Metro output. Multi-line errors (message + stack
+ * trace) arrive across multiple `onData` chunks, so the in-progress
+ * error must persist across calls. Use one instance per Metro session
+ * and call `parse(lines)` as chunks arrive; call `flush()` at the end
+ * (e.g. on process exit) to emit any error still being assembled.
+ */
+export class MetroErrorParser {
+    currentStack = [];
+    currentErrorMessage = "";
+    inStackTrace = false;
+    parse(lines) {
+        const runtimeErrors = [];
+        const warnings = [];
+        const flushInto = (sink) => {
+            if (this.currentErrorMessage) {
+                sink.push({
+                    message: this.currentErrorMessage,
+                    stack: this.currentStack.join("\n"),
+                    timestamp: new Date().toISOString(),
+                });
+                this.currentErrorMessage = "";
+                this.currentStack = [];
+                this.inStackTrace = false;
+            }
+        };
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Metro module resolution errors — single-line, emit immediately.
+            const moduleMatch = trimmed.match(METRO_MODULE_RE);
+            if (moduleMatch) {
+                flushInto(runtimeErrors);
+                runtimeErrors.push({
+                    message: `Unable to resolve module '${moduleMatch[1]}'`,
+                    stack: trimmed,
+                    timestamp: new Date().toISOString(),
+                });
+                continue;
+            }
+            // Metro encountered an error
+            if (METRO_ENCOUNTERED_RE.test(trimmed)) {
+                flushInto(runtimeErrors);
+                this.currentErrorMessage = "Metro has encountered an error";
+                this.inStackTrace = true;
+                continue;
+            }
+            // Invariant Violation
+            const invariantMatch = trimmed.match(INVARIANT_RE);
+            if (invariantMatch) {
+                flushInto(runtimeErrors);
+                this.currentErrorMessage = `Invariant Violation: ${invariantMatch[1]}`;
+                this.inStackTrace = true;
+                continue;
+            }
+            // Unhandled JS Exception
+            const unhandledMatch = trimmed.match(UNHANDLED_JS_RE);
+            if (unhandledMatch) {
+                flushInto(runtimeErrors);
+                this.currentErrorMessage = `Unhandled JS Exception: ${unhandledMatch[1]}`;
+                this.inStackTrace = true;
+                continue;
+            }
+            // JS error types
+            const metroMatch = trimmed.match(METRO_ERROR_RE);
+            if (metroMatch) {
+                flushInto(runtimeErrors);
+                this.currentErrorMessage = `${metroMatch[1]}: ${metroMatch[2]}`;
+                this.inStackTrace = true;
+                continue;
+            }
+            // Console errors
+            const consoleMatch = trimmed.match(CONSOLE_ERROR_RE);
+            if (consoleMatch) {
+                flushInto(runtimeErrors);
+                this.currentErrorMessage = consoleMatch[2];
+                this.inStackTrace = true;
+                continue;
+            }
+            // Red screen detection
+            if (RED_SCREEN_RE.test(trimmed)) {
+                if (!this.currentErrorMessage) {
+                    this.currentErrorMessage = "Red screen error detected";
+                }
+                this.inStackTrace = true;
+            }
+            // Stack trace lines (indented, or starting with "at ")
+            if (this.inStackTrace) {
+                if (trimmed.startsWith("at ") ||
+                    trimmed.startsWith("in ") ||
+                    /^\s+at\s/.test(line) ||
+                    /^\d+\s*\|/.test(trimmed) // source code context lines
+                ) {
+                    this.currentStack.push(trimmed);
+                    continue;
+                }
+                else if (trimmed === "") {
+                    flushInto(runtimeErrors);
+                    continue;
+                }
+                else {
+                    // Continuation of the error message. Skip the warning check —
+                    // a `warn ...` line interleaved with a stack trace would
+                    // otherwise be double-counted as both stack and warning.
+                    this.currentStack.push(trimmed);
+                    continue;
+                }
+            }
+            // Warnings from Metro
+            if (/^warn\s/i.test(trimmed) || /\(WARN\)/.test(trimmed)) {
+                warnings.push({
+                    message: trimmed.replace(/^warn\s*/i, "").replace(/\(WARN\)\s*/, ""),
+                    source: "metro",
+                });
+            }
+        }
+        // Do NOT flush at end of chunk — the in-progress error may continue
+        // in the next chunk. Caller must invoke `flush()` when the stream ends.
+        return { runtimeErrors, warnings };
+    }
+    /**
+     * Force-emit any error currently being assembled. Call on stream end.
+     */
+    flush() {
+        const runtimeErrors = [];
+        if (this.currentErrorMessage) {
+            runtimeErrors.push({
+                message: this.currentErrorMessage,
+                stack: this.currentStack.join("\n"),
+                timestamp: new Date().toISOString(),
+            });
+            this.currentErrorMessage = "";
+            this.currentStack = [];
+            this.inStackTrace = false;
+        }
+        return { runtimeErrors, warnings: [] };
+    }
+}
+/**
+ * Parse a complete Metro buffer in one shot. Suitable for batch use
+ * (e.g. `getErrors()` re-parsing the rolling buffer); for streaming use
+ * a `MetroErrorParser` instance instead so multi-line state survives
+ * across chunks.
+ */
+export function parseMetroOutput(lines) {
+    const parser = new MetroErrorParser();
+    const streamed = parser.parse(lines);
+    const flushed = parser.flush();
+    return {
+        runtimeErrors: [...streamed.runtimeErrors, ...flushed.runtimeErrors],
+        warnings: [...streamed.warnings, ...flushed.warnings],
+    };
+}
+/**
+ * Classify a log line by level.
+ */
+export function classifyLogLevel(line) {
+    const trimmed = line.trim().toLowerCase();
+    if (trimmed.startsWith("error") ||
+        trimmed.includes("console.error") ||
+        trimmed.startsWith("❌") ||
+        /^\s*error\s*:/i.test(line)) {
+        return "error";
+    }
+    if (trimmed.startsWith("warn") ||
+        trimmed.includes("console.warn") ||
+        trimmed.includes("(warn)") ||
+        /^\s*warning\s*:/i.test(line)) {
+        return "warn";
+    }
+    return "log";
+}