@ceraph/react-native-mcp 0.2.2 → 0.3.1

package/LICENSE

@@ -1,21 +1,122 @@
-MIT License
+# Functional Source License, Version 1.1, MIT Future License
 
-Copyright (c) 2026 Ike Studios LLC
+## Abbreviation
 
-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:
+FSL-1.1-MIT
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+## Notice
+
+Copyright 2026 Ike Studios LLC
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publish, and redistribute the
+Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing
+Use means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe
+our patents, the license grant above includes a license under our patents.
+If you make a claim against any party that the Software infringes or
+contributes to the infringement of any patent, then your patent license to
+the Software ends immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives
+of the Software.
+
+If you redistribute any copies or modifications of the Software, you must
+include a copy of the License and retain all copyright and disclaimer
+notices in the Software.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin
+of the Software, you have no right under these Terms and Conditions to use
+our trademarks, trade names, service marks or product names.
+
+### Termination
+
+If you use the Software in violation of these Terms and Conditions, such
+use will be non-exempted and your rights to use the Software under these
+Terms and Conditions will terminate immediately and automatically. If we
+make available an updated version of the Software or any code or
+documentation related to the Software, these Terms and Conditions will
+apply to your use of that version as well.
+
+### No Liability
+
+***AS FAR AS THE LAW ALLOWS, THE SOFTWARE COMES AS IS, WITHOUT ANY WARRANTY
+OR CONDITION, AND WE WILL NOT BE LIABLE TO YOU FOR ANY DAMAGES ARISING OUT
+OF THESE TERMS AND CONDITIONS OR THE USE OR NATURE OF THE SOFTWARE, UNDER
+ANY KIND OF LEGAL CLAIM.***
+
+### Future License
+
+On the second anniversary of the date we make an initial release of the
+Software available, the terms above will no longer apply to that release,
+and the rights granted to you under that release will expand to the rights
+granted under the MIT License, copied below for your convenience.
+
+---
+
+## MIT License
+
+Copyright 2026 Ike Studios LLC
+
+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.
+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

@@ -1,6 +1,6 @@
 # @ceraph/react-native-mcp
 
-MCP server for React Native and Expo development. Automatic build error capture, console monitoring, reliable screen interactions, and prebuild detection.
+MCP server for React Native and Expo development. Automatic build error capture, console monitoring, reliable screen interactions, prebuild detection, and iOS Simulator support.
 
 Works with any MCP client: Claude Code, Cursor, Codex, Windsurf, and others.
 
@@ -12,12 +12,14 @@ Works with any MCP client: Claude Code, Cursor, Codex, Windsurf, and others.
 
 ## Requirements
 
+- macOS with Xcode 14+ (Command Line Tools installed)
+- iOS 16+ device on USB **OR** a booted iOS Simulator
 - 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)
 
+iOS-only. Android, Linux, and Windows hosts are not supported.
+
 ## Quick Setup
 
 Run this from your project root:
@@ -26,14 +28,19 @@ Run this from your project root:
 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`
+For testing on a simulator, also run `npm i -D appium-webdriveragent` and call `rn_wda_start` once from your MCP client (first WDA build takes 60–120s and may need an Xcode signing prompt; subsequent starts are ~5–10s via cache).
+
+## Uninstalling
+
+```bash
+npx @ceraph/react-native-mcp uninstall
+```
+
+Flags: `--yes` (skip prompts), `--purge-images` (also delete `.ceraph/`), `--global` (also delete `~/.ceraph/auth.json`), `--dry-run` (preview only).
 
 ## Manual Setup
 
-If you prefer to configure manually, follow the instructions for your client below.
+If you prefer to configure manually:
 
 ### Claude Code
 
@@ -42,40 +49,28 @@ 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"]
-    }
+    "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:
+Add to `.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "mobile-mcp": {
-      "command": "npx",
-      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
-    },
-    "react-native-mcp": {
-      "command": "npx",
-      "args": ["-y", "@ceraph/react-native-mcp@latest"]
-    }
+    "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:
+Add to `.codex/config.toml`:
 
 ```toml
 [mcp_servers.mobile-mcp]
@@ -89,19 +84,13 @@ args = ["-y", "@ceraph/react-native-mcp@latest"]
 
 ### VS Code / Copilot
 
-Add to `.vscode/mcp.json` in your project root:
+Add to `.vscode/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "mobile-mcp": {
-      "command": "npx",
-      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
-    },
-    "react-native-mcp": {
-      "command": "npx",
-      "args": ["-y", "@ceraph/react-native-mcp@latest"]
-    }
+    "mobile-mcp": { "command": "npx", "args": ["-y", "@mobilenext/mobile-mcp@latest"] },
+    "react-native-mcp": { "command": "npx", "args": ["-y", "@ceraph/react-native-mcp@latest"] }
   }
 }
 ```
@@ -113,63 +102,42 @@ Add to `~/.codeium/windsurf/mcp_config.json` (or Settings → Advanced Settings
 ```json
 {
   "mcpServers": {
-    "mobile-mcp": {
-      "command": "npx",
-      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
-    },
-    "react-native-mcp": {
-      "command": "npx",
-      "args": ["-y", "@ceraph/react-native-mcp@latest"]
-    }
+    "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):
+Add to `~/.gemini/antigravity/mcp_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "mobile-mcp": {
-      "command": "npx",
-      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
-    },
-    "react-native-mcp": {
-      "command": "npx",
-      "args": ["-y", "@ceraph/react-native-mcp@latest"]
-    }
+    "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:
+VS Code Settings → Extensions → Cline (or Roo Code) → MCP Servers:
 
 ```json
 {
-  "mobile-mcp": {
-    "command": "npx",
-    "args": ["-y", "@mobilenext/mobile-mcp@latest"]
-  },
-  "react-native-mcp": {
-    "command": "npx",
-    "args": ["-y", "@ceraph/react-native-mcp@latest"]
-  }
+  "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`
+Settings → Tools → MCP Servers → Add:
 
-Repeat for `mobile-mcp` with args `-y @mobilenext/mobile-mcp@latest`.
+- **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
 
@@ -177,26 +145,60 @@ Repeat for `mobile-mcp` with args `-y @mobilenext/mobile-mcp@latest`.
 
 | 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_build_ios` | Build with `expo run:ios`. Returns structured Xcode errors (file, line, message). Optionally runs `prebuild --clean` first. |
+| `rn_start` | Start Metro. Monitors stdout for runtime errors, JS exceptions, and red screens. |
+| `rn_get_errors` | Return all captured build and runtime errors. |
+| `rn_get_console` | Return recent Metro console output. |
+| `rn_check_prebuild` | Detect if `prebuild --clean` is needed (diffs `package.json`, `app.json`, `Podfile.lock`). |
 | `rn_stop` | Kill all managed React Native processes. |
+| `rn_reload` | Trigger a JS bundle reload via `DevSettings.reload()` on the running app. |
+
+### Target & Simulator
+
+| Tool | Description |
+|---|---|
+| `rn_target_status` | Report current target (device vs simulator), WDA base URL, simulator session status. |
+| `rn_wda_start` | Build + launch WebDriverAgent on a booted iOS Simulator. Idempotent. Real-device users don't need this. |
+| `rn_wda_stop` | Stop the simulator WDA session. Idempotent. |
+| `rn_boot_simulator` | Boot a simulator (defaults to newest available iPhone runtime). |
+| `rn_wait_for_device` | Wait for a real iOS device to appear over USB (event-driven via usbmuxd, no timeout). |
 
 ### 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. |
+| `screen_tap` | Tap at coordinates with automatic pixel-ratio correction. |
+| `screen_find_and_tap` | Find by text, accessibility label, or type, then tap. |
+| `screen_swipe` | Swipe up / down / left / right. |
+| `screen_scroll_to` | Repeatedly swipe until an element appears. |
+| `screen_long_press` | Long-press a matched element. |
+| `screen_type` | Send text to the focused element. |
+| `screen_clear_text` | Focus a field and clear it. |
+| `screen_press_key` | Press `home`, `volumeUp`, `volumeDown`, or `lock`. |
+| `screen_screenshot` | Base64 PNG screenshot. |
+| `screen_get_source` | WDA accessibility tree as JSON. |
+| `screen_wait_for` | Poll the source tree until an element appears or disappears. |
+| `screen_assert_visible` | One-shot visibility check (`invert: true` for assert-not-visible). |
+
+### App Lifecycle & Device
+
+| Tool | Description |
+|---|---|
+| `app_launch` | Launch by bundle ID (`xcrun devicectl`, falls back to `idb` / `simctl`). |
+| `app_terminate` | Terminate by bundle ID. |
+| `app_activate` | Foreground an app via WDA without a cold restart. |
+| `app_list_installed` | List installed apps (cached 30s). |
+| `app_active` | Foreground app's bundleId, pid, and name. |
+| `device_ensure_awake` | Wake + unlock prompt. |
+| `device_lock_state` | `unlocked` / `locked` / `screen-off` / `unknown`. |
+| `device_set_orientation` | Portrait or landscape. |
 
 ## Why both MCPs?
 
-`mobile-mcp` handles low-level device interaction (screenshots, swipe, app lifecycle, recording) and is actively maintained for iOS/Android compatibility.
+`mobile-mcp` handles low-level device interaction (screenshots, swipe, app lifecycle).
 
-`@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.
+`@ceraph/react-native-mcp` adds the development workflow layer: structured error capture, console monitoring, pixel-ratio-corrected taps, prebuild detection, and simulator lifecycle. Both talk to WebDriverAgent independently — they don't depend on each other, they complement each other.
 
 ## License
 
-MIT
+[FSL-1.1-MIT](LICENSE) — free for use; competing commercial products restricted. Auto-converts to MIT 2 years after each release.

package/dist/app-lifecycle.d.ts

@@ -0,0 +1,50 @@
+import type { ScreenManager } from "./screen.js";
+import type { TargetResolver } from "./target.js";
+export interface InstalledApp {
+    bundleId: string;
+    name: string;
+    version?: string;
+}
+export interface LifecycleResult {
+    success: boolean;
+    transport: "devicectl" | "idb" | "simctl" | "wda" | "none";
+    error?: string;
+    details?: Record<string, unknown>;
+}
+export declare function parseSimctlListapps(stdout: string): InstalledApp[];
+export declare class AppLifecycle {
+    private screen?;
+    private targetResolver?;
+    private udid;
+    private udidResolved;
+    private udidResolvedAt;
+    private static readonly UDID_TTL_MS;
+    private udidInflight;
+    private devicectlAvailable;
+    private idbAvailable;
+    private installedAppsCache;
+    private readonly INSTALLED_CACHE_MS;
+    constructor(screen?: ScreenManager | undefined, targetResolver?: TargetResolver | undefined);
+    setTargetResolver(resolver: TargetResolver): void;
+    private pickTransport;
+    getUdid(): Promise<string | null>;
+    private checkDevicectl;
+    private checkIdb;
+    launchApp(bundleId: string): Promise<LifecycleResult>;
+    terminateApp(bundleId: string): Promise<LifecycleResult>;
+    activateApp(bundleId: string): Promise<LifecycleResult>;
+    listInstalledApps(): Promise<{
+        success: boolean;
+        apps: InstalledApp[];
+        error?: string;
+    }>;
+    private listInstalledAppsSimulator;
+    getActiveApp(): Promise<{
+        success: boolean;
+        bundleId?: string;
+        pid?: number;
+        name?: string;
+        error?: string;
+    }>;
+    reset(): void;
+}