@ohah/react-native-mcp-server 0.1.0-rc.1

package/README.md

@@ -0,0 +1,108 @@
+# @ohah/react-native-mcp-server
+
+> [한국어 문서](./README_KO.md)
+
+MCP (Model Context Protocol) server for React Native app automation and monitoring. Lets AI assistants (Cursor, Claude Desktop, GitHub Copilot CLI) inspect and control your React Native app over WebSocket.
+
+## Features
+
+- Monitor app state, network requests, and console logs
+- Tap, swipe, type text, take screenshots via idb (iOS) / adb (Android)
+- Query the component tree, run scripts in the app context
+- One-command setup with `init`
+
+## Install
+
+**Prerequisites:** Node.js 18+ or Bun. For tap/swipe/screenshots you need [idb](https://fbidb.io/) (iOS, macOS) and [adb](https://developer.android.com/tools/adb) (Android).
+
+No global install required — use with npx:
+
+```bash
+npx -y @ohah/react-native-mcp-server init
+```
+
+This detects your project (React Native / Expo, package manager), asks for your MCP client (Cursor, Claude, etc.), and configures Babel + MCP config + .gitignore.
+
+Or install globally:
+
+```bash
+npm install -g @ohah/react-native-mcp-server
+```
+
+## Quick Start
+
+1. **Setup** (once per project):
+
+   ```bash
+   npx -y @ohah/react-native-mcp-server init
+   ```
+
+2. **Start your app.** In development, the MCP runtime is included automatically (no extra env needed). Example:
+
+   ```bash
+   npx react-native start
+   # or for Expo: npx expo start
+   ```
+
+   To enable MCP in release builds, run Metro with `REACT_NATIVE_MCP_ENABLED=true` or set it in your build config.
+
+3. **Configure your MCP client** (e.g. Cursor → Settings → MCP). The init command creates the config; typical entry:
+
+   ```json
+   {
+     "mcpServers": {
+       "react-native-mcp": {
+         "command": "npx",
+         "args": ["-y", "@ohah/react-native-mcp-server"]
+       }
+     }
+   }
+   ```
+
+4. Open your app and Cursor (or Claude/Copilot); the server connects to the app automatically.
+
+## Init options
+
+```bash
+npx -y @ohah/react-native-mcp-server init -y                    # Non-interactive (Cursor default)
+npx -y @ohah/react-native-mcp-server init --client cursor       # Cursor
+npx -y @ohah/react-native-mcp-server init --client claude-code  # Claude Code (CLI)
+npx -y @ohah/react-native-mcp-server init --client claude-desktop
+npx -y @ohah/react-native-mcp-server init --help
+```
+
+## Manual Babel setup
+
+If you prefer not to use `init`, add the Babel preset yourself so the app can connect to the MCP server:
+
+```js
+// babel.config.js
+module.exports = {
+  presets: [
+    'module:@react-native/babel-preset', // or your existing preset
+    '@ohah/react-native-mcp-server/babel-preset',
+  ],
+};
+```
+
+Then add the MCP server entry to your client config (e.g. `.cursor/mcp.json` or Claude config) as in the Quick Start step 3.
+
+## Native tools (idb / adb)
+
+For tap, swipe, screenshots, and similar tools you need:
+
+| Platform      | Tool | Install                                                                                    |
+| ------------- | ---- | ------------------------------------------------------------------------------------------ |
+| iOS Simulator | idb  | `brew tap facebook/fb && brew install idb-companion` (macOS)                               |
+| Android       | adb  | Install Android Studio (adb is included), or `brew install android-platform-tools` (macOS) |
+
+Without these, other MCP tools (state, network, console, eval) still work.
+
+## Documentation
+
+- **Full docs:** [https://ohah.github.io/react-native-mcp/](https://ohah.github.io/react-native-mcp/)
+- **Repository:** [github.com/ohah/react-native-mcp](https://github.com/ohah/react-native-mcp)
+
+## License
+
+MIT

package/babel-plugin-app-registry.cjs

@@ -0,0 +1,36 @@
+
+//#region src/babel-plugin-app-registry.ts
+const MCP_RUNTIME_ID = "__REACT_NATIVE_MCP__";
+const RUNTIME_MODULE_ID = "@ohah/react-native-mcp-server/runtime";
+function babel_plugin_app_registry_default(babel) {
+	const t = babel.types;
+	return {
+		name: "react-native-mcp-app-registry",
+		visitor: {
+			Program: { enter(_path, state) {
+				state.runtimeInjected = false;
+			} },
+			CallExpression(path, state) {
+				const node = path.node;
+				if ((path.hub?.file?.opts?.filename ?? "").includes("node_modules")) return;
+				if (!t.isCallExpression(node)) return;
+				if (!t.isMemberExpression(node.callee)) return;
+				const { object, property } = node.callee;
+				if (!t.isIdentifier(object) || !t.isIdentifier(property)) return;
+				if (object.name !== "AppRegistry" || property.name !== "registerComponent") return;
+				if (!state.runtimeInjected) {
+					const programPath = path.findParent((p) => p.isProgram?.());
+					if (programPath?.node?.body) {
+						programPath.node.body.unshift(t.expressionStatement(t.callExpression(t.identifier("require"), [t.stringLiteral(RUNTIME_MODULE_ID)])));
+						programPath.node.body.unshift(t.expressionStatement(t.assignmentExpression("=", t.memberExpression(t.identifier("global"), t.identifier("__REACT_NATIVE_MCP_ENABLED__")), t.booleanLiteral(true))));
+						state.runtimeInjected = true;
+					}
+				}
+				path.replaceWith(t.callExpression(t.memberExpression(t.identifier(MCP_RUNTIME_ID), t.identifier("registerComponent")), node.arguments));
+			}
+		}
+	};
+}
+
+//#endregion
+module.exports = babel_plugin_app_registry_default;

package/babel-plugin-inject-testid.cjs

@@ -0,0 +1,115 @@
+
+//#region src/babel-plugin-inject-testid.ts
+function getTestIdStringLiteral(t, attr) {
+	if (!attr.value) return null;
+	if (t.isStringLiteral(attr.value)) return attr.value.value;
+	if (t.isJSXExpressionContainer(attr.value) && t.isStringLiteral(attr.value.expression)) return attr.value.expression.value;
+	return null;
+}
+function getTagName(t, name) {
+	if (t.isJSXIdentifier(name)) return name.name;
+	if (t.isJSXNamespacedName(name)) return `${name.namespace.name}.${name.name.name}`;
+	const parts = [];
+	let cur = name;
+	while (true) {
+		if (t.isJSXIdentifier(cur.object)) parts.push(cur.object.name);
+		else parts.push(getTagName(t, cur.object));
+		if (t.isJSXIdentifier(cur.property)) {
+			parts.push(cur.property.name);
+			break;
+		}
+		cur = cur.property;
+	}
+	return parts.join(".");
+}
+function babel_plugin_inject_testid_default(babel) {
+	const t = babel.types;
+	return {
+		name: "react-native-mcp-inject-testid",
+		visitor: {
+			Program: { enter(_path, state) {
+				state.stack = [];
+			} },
+			Function: {
+				enter(path, state) {
+					let name = t.isFunctionDeclaration(path.node) || t.isFunctionExpression(path.node) ? path.node.id?.name ?? null : null;
+					if (!name && path.parent && t.isVariableDeclarator(path.parent) && t.isIdentifier(path.parent.id)) name = path.parent.id.name;
+					if (!name && t.isIdentifier(path.node.params[0])) name = path.node.params[0].name;
+					state.stack.push({
+						componentName: name ?? "Anonymous",
+						jsxIndex: 0
+					});
+				},
+				exit(path, state) {
+					const scope = state.stack[state.stack.length - 1];
+					if (scope && scope.jsxIndex > 0 && scope.componentName !== "Anonymous" && /^[A-Z]/.test(scope.componentName)) {
+						const stmt = t.expressionStatement(t.assignmentExpression("=", t.memberExpression(t.identifier(scope.componentName), t.identifier("displayName")), t.stringLiteral(scope.componentName)));
+						let target = null;
+						if (t.isFunctionDeclaration(path.node)) target = path.parentPath && (t.isExportDefaultDeclaration(path.parent) || t.isExportNamedDeclaration(path.parent)) ? path.parentPath : path;
+						else if (path.parentPath && t.isVariableDeclarator(path.parent)) {
+							target = path.parentPath.parentPath;
+							if (target?.parentPath && (t.isExportDefaultDeclaration(target.parent) || t.isExportNamedDeclaration(target.parent))) target = target.parentPath;
+						}
+						target?.insertAfter(stmt);
+					}
+					state.stack.pop();
+				}
+			},
+			JSXOpeningElement(path, state) {
+				if ((path.hub?.file?.opts?.filename ?? "").includes("node_modules")) return;
+				const scope = state.stack[state.stack.length - 1];
+				if (scope === void 0) return;
+				const el = path.node;
+				const testIdAttr = el.attributes.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === "testID");
+				if (!!!testIdAttr) {
+					const tagName = getTagName(t, el.name);
+					const baseValue = `${scope.componentName}-${scope.jsxIndex}-${tagName}`;
+					const keyAttr = el.attributes.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === "key");
+					let keyExpr = null;
+					if (keyAttr?.value) {
+						if (t.isStringLiteral(keyAttr.value)) keyExpr = keyAttr.value;
+						else if (t.isJSXExpressionContainer(keyAttr.value) && !t.isJSXEmptyExpression(keyAttr.value.expression)) keyExpr = keyAttr.value.expression;
+					}
+					if (keyExpr) {
+						const tpl = t.templateLiteral([t.templateElement({
+							raw: baseValue + "-",
+							cooked: baseValue + "-"
+						}, false), t.templateElement({
+							raw: "",
+							cooked: ""
+						}, true)], [t.cloneNode(keyExpr)]);
+						el.attributes.push(t.jsxAttribute(t.jsxIdentifier("testID"), t.jsxExpressionContainer(tpl)));
+					} else el.attributes.push(t.jsxAttribute(t.jsxIdentifier("testID"), t.stringLiteral(baseValue)));
+					scope.jsxIndex += 1;
+				}
+				if (getTagName(t, el.name) === "WebView") {
+					const webViewTidAttr = testIdAttr ?? el.attributes.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === "testID");
+					const webViewTestIdValue = webViewTidAttr ? getTestIdStringLiteral(t, webViewTidAttr) : null;
+					if (webViewTestIdValue != null) {
+						const refAttr = el.attributes.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === "ref");
+						const mcpRegister = t.expressionStatement(t.logicalExpression("&&", t.optionalMemberExpression(t.identifier("__REACT_NATIVE_MCP__"), t.identifier("registerWebView"), false, true), t.callExpression(t.memberExpression(t.optionalMemberExpression(t.identifier("__REACT_NATIVE_MCP__"), t.identifier("registerWebView"), false, true), t.identifier("call"), false), [
+							t.identifier("__REACT_NATIVE_MCP__"),
+							t.identifier("r"),
+							t.stringLiteral(webViewTestIdValue)
+						])));
+						const mcpUnregister = t.expressionStatement(t.logicalExpression("&&", t.optionalMemberExpression(t.identifier("__REACT_NATIVE_MCP__"), t.identifier("unregisterWebView"), false, true), t.callExpression(t.memberExpression(t.optionalMemberExpression(t.identifier("__REACT_NATIVE_MCP__"), t.identifier("unregisterWebView"), false, true), t.identifier("call"), false), [t.identifier("__REACT_NATIVE_MCP__"), t.stringLiteral(webViewTestIdValue)])));
+						const bodyStatements = [t.ifStatement(t.identifier("r"), mcpRegister, mcpUnregister)];
+						const userRefExpr = refAttr?.value && t.isJSXExpressionContainer(refAttr.value) ? refAttr.value.expression : null;
+						if (userRefExpr != null && !t.isJSXEmptyExpression(userRefExpr)) bodyStatements.push(t.ifStatement(t.binaryExpression("!=", t.cloneNode(userRefExpr), t.nullLiteral()), t.blockStatement([t.ifStatement(t.binaryExpression("===", t.unaryExpression("typeof", t.cloneNode(userRefExpr)), t.stringLiteral("function")), t.expressionStatement(t.callExpression(t.cloneNode(userRefExpr), [t.identifier("r")])), t.expressionStatement(t.assignmentExpression("=", t.memberExpression(t.cloneNode(userRefExpr), t.identifier("current")), t.identifier("r"))))])));
+						const composedRef = t.arrowFunctionExpression([t.identifier("r")], t.blockStatement(bodyStatements));
+						if (refAttr) refAttr.value = t.jsxExpressionContainer(composedRef);
+						else el.attributes.push(t.jsxAttribute(t.jsxIdentifier("ref"), t.jsxExpressionContainer(composedRef)));
+						const onMessageAttr = el.attributes.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === "onMessage");
+						const userOnMessageExpr = onMessageAttr?.value && t.isJSXExpressionContainer(onMessageAttr.value) ? onMessageAttr.value.expression : null;
+						const mcpOnMessage = userOnMessageExpr != null && !t.isJSXEmptyExpression(userOnMessageExpr) ? t.callExpression(t.memberExpression(t.identifier("__REACT_NATIVE_MCP__"), t.identifier("createWebViewOnMessage"), false), [userOnMessageExpr]) : t.arrowFunctionExpression([t.identifier("e")], t.callExpression(t.memberExpression(t.identifier("__REACT_NATIVE_MCP__"), t.identifier("handleWebViewMessage"), false), [t.memberExpression(t.memberExpression(t.identifier("e"), t.identifier("nativeEvent")), t.identifier("data"))]));
+						if (onMessageAttr) onMessageAttr.value = t.jsxExpressionContainer(mcpOnMessage);
+						else el.attributes.push(t.jsxAttribute(t.jsxIdentifier("onMessage"), t.jsxExpressionContainer(mcpOnMessage)));
+					}
+				}
+			}
+		}
+	};
+}
+
+//#endregion
+module.exports = babel_plugin_inject_testid_default;

package/babel-preset.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * Babel preset: AppRegistry 래핑 + testID 자동 주입
+ * babel.config.js에서 presets에 한 번만 넣으면 됨.
+ * - __DEV__ 빌드: 자동 활성화 (환경변수 불필요)
+ * - Release 빌드: REACT_NATIVE_MCP_ENABLED=true|1 일 때만 활성화
+ */
+function isMcpEnabled() {
+  // Metro는 DEV 빌드 시 NODE_ENV를 'development'로 설정한다
+  if (process.env.NODE_ENV !== 'production') return true;
+  const v = process.env.REACT_NATIVE_MCP_ENABLED;
+  return v === 'true' || v === '1';
+}
+
+module.exports = function () {
+  if (!isMcpEnabled()) {
+    return { plugins: [] };
+  }
+  return {
+    plugins: [
+      require('./babel-plugin-app-registry.cjs'),
+      require('./babel-plugin-inject-testid.cjs'),
+    ],
+  };
+};

package/dist/adb-utils-DreOsWp-.js

@@ -0,0 +1,206 @@
+import { spawn } from "node:child_process";
+
+//#region src/tools/run-command.ts
+/**
+* 공유 CLI 명령 실행 유틸리티
+* take-screenshot, idb 도구 등 호스트 CLI를 실행하는 모든 도구에서 사용.
+*/
+function runCommand(command, args, options) {
+	return new Promise((resolve, reject) => {
+		const proc = spawn(command, args, { stdio: options?.stdin ? [
+			"pipe",
+			"pipe",
+			"pipe"
+		] : [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		const outChunks = [];
+		const errChunks = [];
+		proc.stdout?.on("data", (chunk) => outChunks.push(chunk));
+		proc.stderr?.on("data", (chunk) => errChunks.push(chunk));
+		const timeout = options?.timeoutMs != null ? setTimeout(() => {
+			proc.kill("SIGKILL");
+			reject(/* @__PURE__ */ new Error("Command timed out"));
+		}, options.timeoutMs) : void 0;
+		proc.on("close", (code) => {
+			clearTimeout(timeout);
+			if (code !== 0) {
+				const stderr = Buffer.concat(errChunks).toString("utf8").slice(0, 300);
+				reject(/* @__PURE__ */ new Error(`Command failed with code ${code}. ${stderr}`));
+				return;
+			}
+			resolve(Buffer.concat(outChunks));
+		});
+		proc.on("error", (err) => {
+			clearTimeout(timeout);
+			reject(err);
+		});
+		if (options?.stdin && proc.stdin) {
+			proc.stdin.write(options.stdin);
+			proc.stdin.end();
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/adb-utils.ts
+/**
+* adb (Android Debug Bridge) 공유 유틸리티
+* 디바이스 시리얼 자동 해석, adb 설치 확인, 명령 실행 래퍼.
+*/
+let _adbAvailable = null;
+async function checkAdbAvailable() {
+	if (_adbAvailable != null) return _adbAvailable;
+	try {
+		await runCommand("which", ["adb"], { timeoutMs: 3e3 });
+		_adbAvailable = true;
+	} catch {
+		_adbAvailable = false;
+	}
+	return _adbAvailable;
+}
+async function listAdbDevices() {
+	const lines = (await runCommand("adb", ["devices", "-l"], { timeoutMs: 1e4 })).toString("utf8").split("\n").filter((l) => l.trim().length > 0);
+	const devices = [];
+	for (const line of lines) {
+		if (line.startsWith("List of")) continue;
+		const match = line.match(/^(\S+)\s+(device|offline|unauthorized|no permissions)\b(.*)$/);
+		if (!match) continue;
+		const serial = match[1];
+		const state = match[2];
+		const rest = match[3] ?? "";
+		const device = {
+			serial,
+			state
+		};
+		const productMatch = rest.match(/product:(\S+)/);
+		if (productMatch) device.product = productMatch[1];
+		const modelMatch = rest.match(/model:(\S+)/);
+		if (modelMatch) device.model = modelMatch[1];
+		const deviceMatch = rest.match(/device:(\S+)/);
+		if (deviceMatch) device.device = deviceMatch[1];
+		const transportMatch = rest.match(/transport_id:(\S+)/);
+		if (transportMatch) device.transport_id = transportMatch[1];
+		devices.push(device);
+	}
+	return devices;
+}
+async function resolveSerial(serial) {
+	if (serial != null && serial !== "") return serial;
+	const online = (await listAdbDevices()).filter((d) => d.state === "device");
+	if (online.length === 0) throw new Error("No connected Android device found. Connect a device or start an emulator with: emulator -avd <avd_name>");
+	if (online.length > 1) {
+		const list = online.map((d) => `  ${d.serial}${d.model ? ` (${d.model})` : ""}`).join("\n");
+		throw new Error(`Multiple Android devices connected. Specify serial parameter.\n${list}\nUse list_devices(platform="android") to see all devices.`);
+	}
+	return online[0].serial;
+}
+/**
+* 해당 Android 대상이 에뮬레이터(AVD)인지 여부.
+* - adb shell getprop ro.kernel.qemu → "1" 이면 에뮬.
+* - 시리얼이 "emulator-" 로 시작해도 에뮬로 간주 (getprop 실패 시 fallback).
+*/
+async function isAndroidEmulator(serial) {
+	try {
+		return (await runAdbCommand([
+			"shell",
+			"getprop",
+			"ro.kernel.qemu"
+		], serial, { timeoutMs: 3e3 })).trim() === "1";
+	} catch {
+		return serial.startsWith("emulator-");
+	}
+}
+async function runAdbCommand(subcommand, serial, options) {
+	const args = [];
+	if (serial) args.push("-s", serial);
+	args.push(...subcommand);
+	return (await runCommand("adb", args, { timeoutMs: options?.timeoutMs ?? 1e4 })).toString("utf8").trim();
+}
+const _scaleBySerial = /* @__PURE__ */ new Map();
+/**
+* Android screen density scale (디바이스별 캐싱).
+* density 160 = 1x, 320 = 2x, 480 = 3x 등.
+* dp × scale = pixel.
+*/
+async function getAndroidScale(serial) {
+	const key = serial ?? "_default";
+	const cached = _scaleBySerial.get(key);
+	if (cached != null) return cached;
+	try {
+		const match = (await runCommand("adb", serial ? [
+			"-s",
+			serial,
+			"shell",
+			"wm",
+			"density"
+		] : [
+			"shell",
+			"wm",
+			"density"
+		], { timeoutMs: 5e3 })).toString().match(/(\d+)/);
+		if (!match) throw new Error("density not found in wm output");
+		const scale = parseInt(match[1], 10) / 160;
+		_scaleBySerial.set(key, scale);
+		return scale;
+	} catch {
+		return 2.75;
+	}
+}
+const _topInsetBySerial = /* @__PURE__ */ new Map();
+/**
+* Android 디바이스의 실제 top inset(px)을 `dumpsys window displays`에서 파싱.
+* captionBar(태블릿 등)가 있으면 우선, 없으면 statusBars 사용.
+* 파싱 실패 시 0 반환 (호출자가 fallback 처리).
+*/
+async function getAndroidTopInset(serial) {
+	const key = serial ?? "_default";
+	const cached = _topInsetBySerial.get(key);
+	if (cached != null) return cached;
+	try {
+		const text = await runAdbCommand([
+			"shell",
+			"dumpsys",
+			"window",
+			"displays"
+		], serial, { timeoutMs: 5e3 });
+		const captionMatch = text.match(/InsetsSource[^\n]*type=captionBar[^\n]*frame=\[\d+,\d+\]\[\d+,(\d+)\]/);
+		if (captionMatch) {
+			const px = parseInt(captionMatch[1], 10);
+			_topInsetBySerial.set(key, px);
+			return px;
+		}
+		const statusMatch = text.match(/InsetsSource[^\n]*type=statusBars[^\n]*frame=\[\d+,\d+\]\[\d+,(\d+)\]/);
+		if (statusMatch) {
+			const px = parseInt(statusMatch[1], 10);
+			_topInsetBySerial.set(key, px);
+			return px;
+		}
+		_topInsetBySerial.set(key, 0);
+		return 0;
+	} catch {
+		return 0;
+	}
+}
+function adbNotInstalledError() {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: [
+				"adb (Android Debug Bridge) is not installed or not in PATH.",
+				"",
+				"Install Android SDK Platform-Tools:",
+				"  macOS: brew install android-platform-tools",
+				"  Or download from: https://developer.android.com/tools/releases/platform-tools",
+				"",
+				"Verify: adb devices"
+			].join("\n")
+		}]
+	};
+}
+
+//#endregion
+export { isAndroidEmulator as a, runAdbCommand as c, getAndroidTopInset as i, runCommand as l, checkAdbAvailable as n, listAdbDevices as o, getAndroidScale as r, resolveSerial as s, adbNotInstalledError as t };

package/dist/adb-utils-R7jCnMjU.js

@@ -0,0 +1,3 @@
+import { a as isAndroidEmulator, c as runAdbCommand, i as getAndroidTopInset, n as checkAdbAvailable, o as listAdbDevices, r as getAndroidScale, s as resolveSerial, t as adbNotInstalledError } from "./adb-utils-DreOsWp-.js";
+
+export { getAndroidScale };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+//#region src/index.d.ts
+/**
+ * React Native MCP 서버 진입점
+ * Stdio transport (Cursor 연동) + WebSocket 서버 (앱 연동)
+ *
+ * `init` 서브커맨드: 프로젝트 셋업 CLI
+ */
+declare const VERSION = "0.1.0";
+//#endregion
+export { VERSION };