react-native-ai-debugger 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Ihor Zheludkov
+
+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,303 @@
+# React Native AI Debugger
+
+An MCP (Model Context Protocol) server for AI-powered React Native debugging. Enables AI assistants like Claude to capture logs, execute code, inspect state, and control navigation in your React Native app.
+
+## Features
+
+- Captures `console.log`, `console.warn`, `console.error` from React Native apps
+- **Network request tracking** - capture HTTP requests/responses with headers, timing, and status
+- Supports both **Expo SDK 54+** (React Native Bridgeless) and **RN 0.70+** (Hermes)
+- Auto-discovers running Metro servers on common ports
+- Filters logs by level (log, warn, error, info, debug)
+- Circular buffer stores last 1000 log entries and 500 network requests
+- **Execute JavaScript** directly in the running app (REPL-style)
+- **Inspect global objects** like Apollo Client, Redux store, Expo Router
+- **Discover debug globals** available in the app
+
+## Requirements
+
+- Node.js 18+
+- React Native app running with Metro bundler
+
+## Installation
+
+```bash
+npm install -g react-native-ai-debugger
+```
+
+Or install locally in your project:
+
+```bash
+npm install --save-dev react-native-ai-debugger
+```
+
+## Claude Code Setup
+
+### Global (all projects)
+
+```bash
+claude mcp add rn-debugger -- npx react-native-ai-debugger --scope user
+```
+
+### Project-specific
+
+```bash
+claude mcp add rn-debugger -- npx react-native-ai-debugger --scope project
+```
+
+### Manual Configuration
+
+Add to `~/.claude.json` (user scope) or `.mcp.json` (project scope):
+
+```json
+{
+  "mcpServers": {
+    "rn-debugger": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["react-native-ai-debugger"]
+    }
+  }
+}
+```
+
+Restart Claude Code after adding the configuration.
+
+## Available Tools
+
+### Connection & Logs
+
+| Tool | Description |
+|------|-------------|
+| `scan_metro` | Scan for running Metro servers and auto-connect |
+| `connect_metro` | Connect to a specific Metro port |
+| `get_apps` | List connected React Native apps |
+| `get_logs` | Retrieve console logs (with optional filtering and start position) |
+| `search_logs` | Search logs for specific text (case-insensitive) |
+| `clear_logs` | Clear the log buffer |
+
+### Network Tracking
+
+| Tool | Description |
+|------|-------------|
+| `get_network_requests` | Retrieve captured network requests with optional filtering |
+| `search_network` | Search requests by URL pattern (case-insensitive) |
+| `get_request_details` | Get full details of a request (headers, body, timing) |
+| `get_network_stats` | Get statistics: counts by method, status code, domain |
+| `clear_network` | Clear the network request buffer |
+
+### App Inspection & Execution
+
+| Tool | Description |
+|------|-------------|
+| `execute_in_app` | Execute JavaScript code in the connected app and return the result |
+| `list_debug_globals` | Discover available debug objects (Apollo, Redux, Expo Router, etc.) |
+| `inspect_global` | Inspect a global object to see its properties and callable methods |
+| `reload_app` | Reload the app (like pressing 'r' in Metro or shaking the device) |
+
+## Usage
+
+1. Start your React Native app:
+   ```bash
+   npm start
+   # or
+   expo start
+   ```
+
+2. In Claude Code, scan for Metro:
+   ```
+   Use scan_metro to find and connect to Metro
+   ```
+
+3. Get logs:
+   ```
+   Use get_logs to see recent console output
+   ```
+
+### Filtering Logs
+
+```
+get_logs with maxLogs=20 and level="error"
+```
+
+Available levels: `all`, `log`, `warn`, `error`, `info`, `debug`
+
+### Start from Specific Line
+
+```
+get_logs with startFromText="iOS Bundled" and maxLogs=100
+```
+
+This finds the **last** (most recent) line containing the text and returns logs from that point forward. Useful for getting logs since the last app reload.
+
+### Search Logs
+
+```
+search_logs with text="error" and maxResults=20
+```
+
+Case-insensitive search across all log messages.
+
+## Network Tracking
+
+### View Recent Requests
+
+```
+get_network_requests with maxRequests=20
+```
+
+### Filter by Method
+
+```
+get_network_requests with method="POST"
+```
+
+### Filter by Status Code
+
+Useful for debugging auth issues:
+
+```
+get_network_requests with status=401
+```
+
+### Search by URL
+
+```
+search_network with urlPattern="api/auth"
+```
+
+### Get Full Request Details
+
+After finding a request ID from `get_network_requests`:
+
+```
+get_request_details with requestId="123.45"
+```
+
+Shows full headers, request body, response headers, and timing.
+
+### View Statistics
+
+```
+get_network_stats
+```
+
+Example output:
+```
+Total requests: 47
+Completed: 45
+Errors: 2
+Avg duration: 234ms
+
+By Method:
+  GET: 32
+  POST: 15
+
+By Status:
+  2xx: 43
+  4xx: 2
+
+By Domain:
+  api.example.com: 40
+  cdn.example.com: 7
+```
+
+## App Inspection
+
+### Discover Debug Globals
+
+Find what debugging objects are available in your app:
+
+```
+list_debug_globals
+```
+
+Example output:
+```json
+{
+  "Apollo Client": ["__APOLLO_CLIENT__"],
+  "Redux": ["__REDUX_STORE__"],
+  "Expo": ["__EXPO_ROUTER__"],
+  "Reanimated": ["__reanimatedModuleProxy"]
+}
+```
+
+### Inspect an Object
+
+Before calling methods on an unfamiliar object, inspect it to see what's callable:
+
+```
+inspect_global with objectName="__EXPO_ROUTER__"
+```
+
+Example output:
+```json
+{
+  "navigate": { "type": "function", "callable": true },
+  "push": { "type": "function", "callable": true },
+  "currentPath": { "type": "string", "callable": false, "value": "/" },
+  "routes": { "type": "array", "callable": false }
+}
+```
+
+### Execute Code in App
+
+Run JavaScript directly in the connected app:
+
+```
+execute_in_app with expression="__DEV__"
+// Returns: true
+
+execute_in_app with expression="__APOLLO_CLIENT__.cache.extract()"
+// Returns: Full Apollo cache contents
+
+execute_in_app with expression="__EXPO_ROUTER__.navigate('/settings')"
+// Navigates the app to /settings
+```
+
+### Async Code
+
+For async operations, promises are awaited by default:
+
+```
+execute_in_app with expression="AsyncStorage.getItem('userToken')"
+```
+
+Set `awaitPromise=false` for synchronous execution only.
+
+## Supported React Native Versions
+
+| Version | Runtime | Status |
+|---------|---------|--------|
+| Expo SDK 54+ | React Native Bridgeless | ✓ |
+| RN 0.70 - 0.76 | Hermes React Native | ✓ |
+| RN < 0.70 | JSC | Not tested |
+
+## How It Works
+
+1. Fetches device list from Metro's `/json` endpoint
+2. Connects to the main JS runtime via CDP (Chrome DevTools Protocol) WebSocket
+3. Enables `Runtime.enable` to receive `Runtime.consoleAPICalled` events
+4. Enables `Network.enable` to receive network request/response events
+5. Stores logs and network requests in circular buffers for retrieval
+
+## Troubleshooting
+
+### No devices found
+- Make sure the app is running on a simulator/device
+- Check that Metro bundler is running (`npm start`)
+
+### Wrong device connected
+The server prioritizes devices in this order:
+1. React Native Bridgeless (SDK 54+)
+2. Hermes React Native
+3. Any React Native (excluding Reanimated/Experimental)
+
+### Logs not appearing
+- Ensure the app is actively running (not just Metro)
+- Try `clear_logs` then trigger some actions in the app
+- Check `get_apps` to verify connection status
+
+## License
+
+MIT

package/build/core/android.d.ts

@@ -0,0 +1,108 @@
+export interface AndroidDevice {
+    id: string;
+    status: "device" | "offline" | "unauthorized" | "no permissions" | string;
+    product?: string;
+    model?: string;
+    device?: string;
+    transportId?: string;
+}
+export interface AdbResult {
+    success: boolean;
+    result?: string;
+    error?: string;
+    data?: Buffer;
+    scaleFactor?: number;
+    originalWidth?: number;
+    originalHeight?: number;
+}
+/**
+ * Check if ADB is available in PATH
+ */
+export declare function isAdbAvailable(): Promise<boolean>;
+/**
+ * List connected Android devices
+ */
+export declare function listAndroidDevices(): Promise<AdbResult>;
+/**
+ * Get the first connected Android device ID
+ */
+export declare function getDefaultAndroidDevice(): Promise<string | null>;
+/**
+ * Take a screenshot from an Android device
+ */
+export declare function androidScreenshot(outputPath?: string, deviceId?: string): Promise<AdbResult>;
+/**
+ * Install an APK on an Android device
+ */
+export declare function androidInstallApp(apkPath: string, deviceId?: string, options?: {
+    replace?: boolean;
+    grantPermissions?: boolean;
+}): Promise<AdbResult>;
+/**
+ * Launch an app on an Android device
+ */
+export declare function androidLaunchApp(packageName: string, activityName?: string, deviceId?: string): Promise<AdbResult>;
+/**
+ * Get list of installed packages on the device
+ */
+export declare function androidListPackages(deviceId?: string, filter?: string): Promise<AdbResult>;
+/**
+ * Common key event codes for Android
+ */
+export declare const ANDROID_KEY_EVENTS: {
+    readonly HOME: 3;
+    readonly BACK: 4;
+    readonly CALL: 5;
+    readonly END_CALL: 6;
+    readonly VOLUME_UP: 24;
+    readonly VOLUME_DOWN: 25;
+    readonly POWER: 26;
+    readonly CAMERA: 27;
+    readonly CLEAR: 28;
+    readonly TAB: 61;
+    readonly ENTER: 66;
+    readonly DEL: 67;
+    readonly MENU: 82;
+    readonly SEARCH: 84;
+    readonly MEDIA_PLAY_PAUSE: 85;
+    readonly MEDIA_STOP: 86;
+    readonly MEDIA_NEXT: 87;
+    readonly MEDIA_PREVIOUS: 88;
+    readonly MOVE_HOME: 122;
+    readonly MOVE_END: 123;
+    readonly APP_SWITCH: 187;
+    readonly ESCAPE: 111;
+};
+/**
+ * Tap at coordinates on an Android device
+ */
+export declare function androidTap(x: number, y: number, deviceId?: string): Promise<AdbResult>;
+/**
+ * Long press at coordinates on an Android device
+ */
+export declare function androidLongPress(x: number, y: number, durationMs?: number, deviceId?: string): Promise<AdbResult>;
+/**
+ * Swipe on an Android device
+ */
+export declare function androidSwipe(startX: number, startY: number, endX: number, endY: number, durationMs?: number, deviceId?: string): Promise<AdbResult>;
+/**
+ * Input text on an Android device
+ *
+ * ADB input text has limitations with special characters.
+ * This function handles escaping properly for URLs, emails, and special strings.
+ */
+export declare function androidInputText(text: string, deviceId?: string): Promise<AdbResult>;
+/**
+ * Send a key event to an Android device
+ */
+export declare function androidKeyEvent(keyCode: number | keyof typeof ANDROID_KEY_EVENTS, deviceId?: string): Promise<AdbResult>;
+/**
+ * Get device screen size
+ */
+export declare function androidGetScreenSize(deviceId?: string): Promise<{
+    success: boolean;
+    width?: number;
+    height?: number;
+    error?: string;
+}>;
+//# sourceMappingURL=android.d.ts.map

package/build/core/android.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"android.d.ts","sourceRoot":"","sources":["../../src/core/android.ts"],"names":[],"mappings":"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"}