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

package/dist/index.js

@@ -0,0 +1,3829 @@
+#!/usr/bin/env node
+import { a as isAndroidEmulator, c as runAdbCommand, i as getAndroidTopInset, l as runCommand, n as checkAdbAvailable, o as listAdbDevices, r as getAndroidScale, s as resolveSerial, t as adbNotInstalledError } from "./adb-utils-DreOsWp-.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebSocket, WebSocketServer } from "ws";
+import { execFile } from "node:child_process";
+import { z } from "zod";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import * as path$1 from "node:path";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { XMLParser } from "fast-xml-parser";
+
+//#region src/tools/metro-cdp.ts
+/** deviceId → metroBaseUrl */
+const deviceMetroUrls = /* @__PURE__ */ new Map();
+let metroBaseUrlFromApp = null;
+function setMetroBaseUrlFromApp(url, deviceId) {
+	if (deviceId) if (url) deviceMetroUrls.set(deviceId, url);
+	else deviceMetroUrls.delete(deviceId);
+	else metroBaseUrlFromApp = url;
+}
+
+//#endregion
+//#region src/websocket-server.ts
+/**
+* MCP 서버 ↔ React Native 앱 간 WebSocket 서버 (Phase 1)
+* 포트 12300에서 앱 연결 수락, eval 요청 전송 및 응답 수신.
+* 다중 연결 지원: 디바이스별 deviceId(예: ios-1, android-1) 할당.
+*/
+const DEFAULT_PORT = 12300;
+/**
+* 앱 연결 세션: 다중 WebSocket, 디바이스별 요청/응답 매칭
+*/
+var AppSession = class {
+	devices = /* @__PURE__ */ new Map();
+	deviceByWs = /* @__PURE__ */ new Map();
+	awaitingInit = /* @__PURE__ */ new Set();
+	extensionClients = /* @__PURE__ */ new Set();
+	server = null;
+	staleCheckTimer = null;
+	/** 연결된 디바이스 중 열린 것 하나로 해석 (deviceId/platform 미지정 시) */
+	resolveDevice(deviceId, platform) {
+		const open = () => [...this.devices.values()].filter((c) => c.ws.readyState === WebSocket.OPEN);
+		if (deviceId != null && deviceId !== "") {
+			const conn = this.devices.get(deviceId);
+			if (!conn || conn.ws.readyState !== WebSocket.OPEN) throw new Error("Device not connected: " + deviceId);
+			return conn;
+		}
+		if (platform != null && platform !== "") {
+			const list = open().filter((c) => c.platform === platform);
+			if (list.length === 0) throw new Error("No " + platform + " device connected");
+			if (list.length > 1) throw new Error("Multiple " + platform + " devices connected");
+			const byPlatform = list[0];
+			if (!byPlatform) throw new Error("No " + platform + " device connected");
+			return byPlatform;
+		}
+		const list = open();
+		if (list.length === 0) throw new Error("No React Native app connected. Start the app with Metro and ensure the runtime is loaded.");
+		if (list.length > 1) throw new Error("Multiple devices connected. Specify deviceId or platform.");
+		const single = list[0];
+		if (!single) throw new Error("No React Native app connected.");
+		return single;
+	}
+	/** 현재 앱이 연결되어 있는지 (인자 없음: 1대 이상 연결 시 true) */
+	isConnected(deviceId, platform) {
+		try {
+			if (deviceId == null && platform == null) return [...this.devices.values()].some((c) => c.ws.readyState === WebSocket.OPEN);
+			this.resolveDevice(deviceId, platform);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* 연결된 디바이스 목록 (get_debugger_status 등에서 사용).
+	* 열린 연결만 반환, 각 항목에 connected: true 포함.
+	*/
+	getConnectedDevices() {
+		return [...this.devices.values()].filter((c) => c.ws.readyState === WebSocket.OPEN).map((c) => {
+			const ratio = c.pixelRatio ?? 1;
+			return {
+				deviceId: c.deviceId,
+				platform: c.platform,
+				deviceName: c.deviceName,
+				connected: true,
+				topInsetDp: c.platform === "android" && c.topInsetPx > 0 ? c.topInsetPx / ratio : 0
+			};
+		});
+	}
+	/** 연결된 디바이스의 pixelRatio 반환 (없으면 null) */
+	getPixelRatio(deviceId, platform) {
+		try {
+			return this.resolveDevice(deviceId, platform).pixelRatio;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Android top inset을 dp 단위로 반환.
+	* topInsetPx / pixelRatio. iOS는 항상 0.
+	*/
+	getTopInsetDp(deviceId, platform) {
+		try {
+			const conn = this.resolveDevice(deviceId, platform);
+			if (conn.platform !== "android" || conn.topInsetPx === 0) return 0;
+			const ratio = conn.pixelRatio ?? 1;
+			return conn.topInsetPx / ratio;
+		} catch {
+			return 0;
+		}
+	}
+	/**
+	* 수동으로 Android top inset(dp) 설정.
+	* ADB 자동 감지 결과를 덮어쓴다.
+	*/
+	setTopInsetDp(dp, deviceId, platform) {
+		const conn = this.resolveDevice(deviceId, platform);
+		const ratio = conn.pixelRatio ?? 1;
+		conn.topInsetPx = Math.round(dp * ratio);
+	}
+	/** 디버깅: WebSocket 서버/클라이언트 상태 */
+	getConnectionStatus() {
+		const open = [...this.devices.values()].filter((c) => c.ws.readyState === WebSocket.OPEN);
+		return {
+			connected: open.length > 0,
+			hasServer: this.server != null,
+			deviceCount: open.length
+		};
+	}
+	/** 테스트용: 디바이스를 직접 주입 (테스트에서만 사용) */
+	_testInjectDevice(conn) {
+		this.devices.set(conn.deviceId, conn);
+		this.deviceByWs.set(conn.ws, conn.deviceId);
+	}
+	nextDeviceId(platform) {
+		const indices = [...this.devices.values()].filter((c) => c.platform === platform).map((c) => {
+			const m = c.deviceId.match(/^(.+)-(\d+)$/);
+			return m && m[2] !== void 0 ? parseInt(m[2], 10) : 0;
+		});
+		return `${platform}-${(indices.length > 0 ? Math.max(...indices) : 0) + 1}`;
+	}
+	/** Broadcast a message to all connected extension clients. */
+	broadcastToExtensions(msg) {
+		const data = JSON.stringify(msg);
+		for (const ext of this.extensionClients) if (ext.readyState === WebSocket.OPEN) ext.send(data);
+	}
+	removeConnection(ws) {
+		if (this.extensionClients.delete(ws)) return;
+		const deviceId = this.deviceByWs.get(ws);
+		if (deviceId) {
+			setMetroBaseUrlFromApp(null, deviceId);
+			const conn = this.devices.get(deviceId);
+			if (conn) {
+				for (const { reject } of conn.pending.values()) reject(/* @__PURE__ */ new Error("Device disconnected"));
+				conn.pending.clear();
+			}
+			this.devices.delete(deviceId);
+			this.deviceByWs.delete(ws);
+			this.broadcastToExtensions({
+				type: "devices-changed",
+				devices: this.getConnectedDevices()
+			});
+		}
+		this.awaitingInit.delete(ws);
+	}
+	/**
+	* WebSocket 서버 시작 (지정 포트, 기본 12300)
+	*/
+	start(port = DEFAULT_PORT) {
+		if (this.server) return;
+		this.server = new WebSocketServer({ port });
+		this.server.on("connection", (ws) => {
+			console.error("[react-native-mcp-server] WebSocket client connected");
+			this.awaitingInit.add(ws);
+			ws.on("message", (data) => {
+				try {
+					const msg = JSON.parse(data.toString());
+					const existingDeviceId = this.deviceByWs.get(ws);
+					if (existingDeviceId) {
+						const existingConn = this.devices.get(existingDeviceId);
+						if (existingConn) existingConn.lastMessageTime = Date.now();
+					}
+					if (msg?.type === "ping") {
+						if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "pong" }));
+						return;
+					}
+					if (this.awaitingInit.has(ws) && msg?.type === "extension-init") {
+						this.awaitingInit.delete(ws);
+						this.extensionClients.add(ws);
+						ws.send(JSON.stringify({
+							type: "extension-init-ack",
+							devices: this.getConnectedDevices()
+						}));
+						return;
+					}
+					if (this.extensionClients.has(ws) && msg?.method === "eval") {
+						const reqId = typeof msg.id === "string" ? msg.id : crypto.randomUUID();
+						const params = msg.params ?? {};
+						const deviceId = typeof params.deviceId === "string" ? params.deviceId : void 0;
+						const platform = typeof params.platform === "string" ? params.platform : void 0;
+						const code = typeof params.code === "string" ? params.code : "";
+						this.sendRequest({
+							method: "eval",
+							params: { code }
+						}, 1e4, deviceId, platform).then((res) => {
+							if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({
+								id: reqId,
+								result: res.result,
+								error: res.error
+							}));
+						}).catch((err) => {
+							if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({
+								id: reqId,
+								error: err instanceof Error ? err.message : String(err)
+							}));
+						});
+						return;
+					}
+					if (this.extensionClients.has(ws) && msg?.method === "getDevices") {
+						const reqId = typeof msg.id === "string" ? msg.id : crypto.randomUUID();
+						ws.send(JSON.stringify({
+							id: reqId,
+							result: this.getConnectedDevices()
+						}));
+						return;
+					}
+					if (this.awaitingInit.has(ws) && msg?.type === "init") {
+						this.awaitingInit.delete(ws);
+						const platform = typeof msg.platform === "string" ? msg.platform : "unknown";
+						const deviceId = this.nextDeviceId(platform);
+						const deviceName = typeof msg.deviceName === "string" ? msg.deviceName : null;
+						const metroBaseUrl = typeof msg.metroBaseUrl === "string" ? msg.metroBaseUrl : null;
+						const pixelRatio = typeof msg.pixelRatio === "number" ? msg.pixelRatio : null;
+						const conn = {
+							deviceId,
+							platform,
+							deviceName,
+							ws,
+							pending: /* @__PURE__ */ new Map(),
+							metroBaseUrl,
+							pixelRatio,
+							topInsetPx: 0,
+							lastMessageTime: Date.now()
+						};
+						this.devices.set(deviceId, conn);
+						this.deviceByWs.set(ws, deviceId);
+						if (metroBaseUrl) setMetroBaseUrlFromApp(metroBaseUrl, deviceId);
+						this.broadcastToExtensions({
+							type: "devices-changed",
+							devices: this.getConnectedDevices()
+						});
+						if (platform === "android") {
+							const userTopInset = typeof msg.topInsetDp === "number" ? msg.topInsetDp : null;
+							if (userTopInset != null) {
+								const ratio = pixelRatio ?? 1;
+								conn.topInsetPx = Math.round(userTopInset * ratio);
+							} else getAndroidTopInset().then((px) => {
+								conn.topInsetPx = px;
+							}).catch(() => {});
+						}
+						return;
+					}
+					const respDeviceId = this.deviceByWs.get(ws);
+					if (respDeviceId != null) {
+						const conn = this.devices.get(respDeviceId);
+						const res = msg;
+						if (res?.id && conn?.pending.has(res.id)) {
+							const { resolve } = conn.pending.get(res.id);
+							conn.pending.delete(res.id);
+							resolve(res);
+						}
+					}
+				} catch {}
+			});
+			ws.on("close", () => {
+				console.error("[react-native-mcp-server] WebSocket client disconnected");
+				this.removeConnection(ws);
+			});
+			ws.on("error", () => {
+				this.removeConnection(ws);
+			});
+		});
+		this.server.on("listening", () => {
+			console.error(`[react-native-mcp-server] WebSocket server listening on ws://localhost:${port}`);
+		});
+		this.staleCheckTimer = setInterval(() => {
+			const now = Date.now();
+			for (const conn of this.devices.values()) if (now - conn.lastMessageTime > 6e4) {
+				console.error(`[react-native-mcp-server] Closing stale connection: ${conn.deviceId} (no message for 60s)`);
+				conn.ws.close();
+			}
+		}, 15e3);
+		this.server.on("error", (err) => {
+			if (err.message?.includes("EADDRINUSE")) {
+				console.error("[react-native-mcp-server] Port %s already in use. Only one MCP server should run. Kill the other process: kill $(lsof -t -i :%s)", port, port);
+				process.exit(1);
+			}
+			console.error("[react-native-mcp-server] WebSocket server error:", err.message);
+		});
+	}
+	/**
+	* 앱에 요청 전송 후 응답 대기 (타임아웃 ms).
+	* deviceId/platform 지정 시 해당 디바이스로, 미지정 시 연결 1대일 때만 가능.
+	*/
+	async sendRequest(request, timeoutMs = 1e4, deviceId, platform) {
+		const conn = this.resolveDevice(deviceId, platform);
+		const id = crypto.randomUUID();
+		const msg = {
+			...request,
+			id
+		};
+		if (conn.ws.readyState !== WebSocket.OPEN) throw new Error("No React Native app connected. Start the app with Metro and ensure the runtime is loaded.");
+		return new Promise((resolve, reject) => {
+			const t = setTimeout(() => {
+				if (conn.pending.delete(id)) reject(/* @__PURE__ */ new Error("Request timeout: no response from app"));
+			}, timeoutMs);
+			conn.pending.set(id, {
+				resolve: (res) => {
+					clearTimeout(t);
+					resolve(res);
+				},
+				reject: (err) => {
+					clearTimeout(t);
+					reject(err);
+				}
+			});
+			conn.ws.send(JSON.stringify(msg));
+		});
+	}
+	/** 서버 종료 */
+	stop() {
+		if (this.staleCheckTimer) {
+			clearInterval(this.staleCheckTimer);
+			this.staleCheckTimer = null;
+		}
+		if (this.server) {
+			this.server.close();
+			this.server = null;
+		}
+		for (const ext of this.extensionClients) ext.close();
+		this.extensionClients.clear();
+		for (const [ws] of this.deviceByWs) this.removeConnection(ws);
+	}
+};
+/** 싱글톤 앱 세션 (index에서 생성 후 tools에 전달) */
+const appSession = new AppSession();
+
+//#endregion
+//#region src/tools/device-param.ts
+/**
+* 다중 디바이스 라우팅용 공통 파라미터 (deviceId, platform)
+*/
+const deviceParam = z.string().optional().describe("Target device ID. Auto if single device. Use get_debugger_status to list.");
+const platformParam = z.enum(["ios", "android"]).optional().describe("Target platform. Auto when single device of that platform.");
+
+//#endregion
+//#region src/tools/query-selector.ts
+/**
+* MCP 도구: query_selector, query_selector_all
+* Fiber 트리에서 셀렉터로 요소 검색. CSS querySelector와 유사하지만 React Native Fiber 트리 전용.
+*
+* 셀렉터 문법:
+*   Type#testID[attr="val"]:text("..."):nth-of-type(N):has-press:has-scroll
+*   A > B (직접 자식), A B (후손), A, B (OR)
+*/
+const schema$23 = z.object({
+	selector: z.string().describe("Selector for RN Fiber tree. Read resource docs://guides/query-selector-syntax for full syntax (type, #testID, :text, hierarchy, etc.)."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function buildQuerySelectorEvalCode(selector) {
+	return `(function(){ var M = typeof __REACT_NATIVE_MCP__ !== 'undefined' ? __REACT_NATIVE_MCP__ : null; return M && M.querySelectorWithMeasure ? M.querySelectorWithMeasure(${JSON.stringify(selector)}) : null; })();`;
+}
+function buildQuerySelectorAllEvalCode(selector) {
+	return `(function(){ var M = typeof __REACT_NATIVE_MCP__ !== 'undefined' ? __REACT_NATIVE_MCP__ : null; return M && M.querySelectorAllWithMeasure ? M.querySelectorAllWithMeasure(${JSON.stringify(selector)}) : []; })();`;
+}
+/** WebView 감지 시 등록된 webViewId 목록을 조회해 힌트로 반환 */
+async function getWebViewHint(appSession, deviceId, platform) {
+	try {
+		const res = await appSession.sendRequest({
+			method: "eval",
+			params: { code: `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.getRegisteredWebViewIds ? __REACT_NATIVE_MCP__.getRegisteredWebViewIds() : []; })();` }
+		}, 5e3, deviceId, platform);
+		const ids = Array.isArray(res.result) ? res.result : [];
+		if (ids.length === 0) return "\n\n⚠️ This is a WebView but no WebView IDs are registered. Coordinate-based tap may be needed, or ensure the Babel plugin is configured.";
+		return `\n\n💡 WebView detected. Use webview_evaluate_script to interact with its DOM content (click, read text, etc.) — do NOT use coordinate-based tap.\nRegistered WebView IDs: [${ids.map((id) => `"${id}"`).join(", ")}]\nExample: webview_evaluate_script(webViewId: ${ids.length === 1 ? `"${ids[0]}"` : `<pick one>`}, script: "document.querySelector('button').click()")`;
+	} catch {
+		return "\n\n💡 This is a WebView. Use webview_evaluate_script instead of tap for DOM interactions.";
+	}
+}
+function isWebViewType(typeName) {
+	return typeName === "RNCWebView" || typeName.includes("WebView");
+}
+function registerQuerySelector(server, appSession) {
+	const register = (name, description, handler) => {
+		server.registerTool(name, {
+			description,
+			inputSchema: schema$23
+		}, handler);
+	};
+	register("query_selector", "Find first element matching selector in Fiber tree. Returns uid, type, measure (pageX, pageY, width, height). Workflow: query_selector → tap(center); uids unknown until called.", async (args) => {
+		const { selector, deviceId, platform } = schema$23.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected."
+		}] };
+		const code = buildQuerySelectorEvalCode(selector);
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			if (res.result == null) return { content: [{
+				type: "text",
+				text: "No element matches selector: " + selector
+			}] };
+			const result = res.result;
+			let text = JSON.stringify(result, null, 2);
+			if (isWebViewType(String(result.type ?? ""))) text += await getWebViewHint(appSession, deviceId, platform);
+			return { content: [{
+				type: "text",
+				text
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `query_selector failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	register("query_selector_all", "Find all elements matching selector. Returns array with measure. Prefer query_selector for one element; use only when enumerating multiple.", async (args) => {
+		const { selector, deviceId, platform } = schema$23.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected."
+		}] };
+		const code = buildQuerySelectorAllEvalCode(selector);
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const list = Array.isArray(res.result) ? res.result : [];
+			if (list.length === 0) return { content: [{
+				type: "text",
+				text: "No elements match selector: " + selector
+			}] };
+			let text = JSON.stringify(list, null, 2);
+			if (list.some((el) => isWebViewType(String(el.type ?? "")))) text += await getWebViewHint(appSession, deviceId, platform);
+			return { content: [{
+				type: "text",
+				text
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `query_selector_all failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/assert.ts
+/**
+* MCP 도구: assert_text, assert_visible, assert_not_visible, assert_element_count
+* 테스트 러너용 assertion. 내부적으로 querySelector 사용.
+* timeoutMs/intervalMs 파라미터로 polling 지원 (CI 안정성 향상).
+*/
+const timeoutParam = z.number().optional().default(0).describe("Max wait ms. 0 = single check; >0 = poll until pass or timeout.");
+const intervalParam = z.number().optional().default(300).describe("Poll interval ms. Used only when timeoutMs > 0.");
+const assertTextSchema = z.object({
+	text: z.string().describe("Text substring to assert exists on screen"),
+	selector: z.string().optional().describe("Optional selector to narrow scope."),
+	timeoutMs: timeoutParam,
+	intervalMs: intervalParam,
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const assertVisibleSchema = z.object({
+	selector: z.string().describe("Selector to check visibility."),
+	timeoutMs: timeoutParam,
+	intervalMs: intervalParam,
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const assertNotVisibleSchema = z.object({
+	selector: z.string().describe("Selector of element that must not be visible."),
+	timeoutMs: timeoutParam,
+	intervalMs: intervalParam,
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const assertElementCountSchema = z.object({
+	selector: z.string().describe("Selector to count matching elements."),
+	expectedCount: z.number().optional().describe("Exact count. Mutually exclusive with min/maxCount."),
+	minCount: z.number().optional().describe("Min count (inclusive)."),
+	maxCount: z.number().optional().describe("Max count (inclusive)."),
+	timeoutMs: timeoutParam,
+	intervalMs: intervalParam,
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerTool(server, name, description, inputSchema, handler) {
+	server.registerTool(name, {
+		description,
+		inputSchema
+	}, handler);
+}
+function sleep$1(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** 서버 측 polling 루프. checkFn이 pass:true 반환하거나 timeout 초과까지 반복. */
+async function pollUntil(checkFn, timeoutMs, intervalMs) {
+	const result = await checkFn();
+	if (result.pass || timeoutMs <= 0) return result;
+	const start = Date.now();
+	let lastResult = result;
+	while (Date.now() - start < timeoutMs) {
+		await sleep$1(intervalMs);
+		lastResult = await checkFn();
+		if (lastResult.pass) return lastResult;
+	}
+	return lastResult;
+}
+function textContent(data) {
+	return { content: [{
+		type: "text",
+		text: data.text
+	}] };
+}
+function jsonContent(obj) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(obj)
+	}] };
+}
+function registerAssert(server, appSession) {
+	registerTool(server, "assert_text", "Assert text exists on screen. Returns { pass, message }. Optional selector; supports timeoutMs/intervalMs polling.", assertTextSchema, async (args) => {
+		const { text, selector, timeoutMs, intervalMs, deviceId, platform } = assertTextSchema.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return textContent({
+			type: "text",
+			text: "No React Native app connected."
+		});
+		const code = buildQuerySelectorEvalCode(selector ? `${selector}:text(${JSON.stringify(text)})` : `:text(${JSON.stringify(text)})`);
+		const requestTimeout = Math.max(1e4, timeoutMs + 5e3);
+		try {
+			const result = await pollUntil(async () => {
+				const res = await appSession.sendRequest({
+					method: "eval",
+					params: { code }
+				}, requestTimeout, deviceId, platform);
+				if (res.error != null) return {
+					pass: false,
+					error: res.error
+				};
+				return { pass: res.result != null };
+			}, timeoutMs, intervalMs);
+			if (result.error) return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Error: ${result.error}`
+				}]
+			};
+			const pass = result.pass;
+			return jsonContent({
+				pass,
+				message: pass ? `PASS: text "${text}" found` : `FAIL: text "${text}" not found`
+			});
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `assert_text failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	registerTool(server, "assert_visible", "Assert element matching selector is visible. Returns { pass, message }. Supports polling.", assertVisibleSchema, async (args) => {
+		const { selector, timeoutMs, intervalMs, deviceId, platform } = assertVisibleSchema.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return textContent({
+			type: "text",
+			text: "No React Native app connected."
+		});
+		const code = buildQuerySelectorEvalCode(selector);
+		const requestTimeout = Math.max(1e4, timeoutMs + 5e3);
+		try {
+			const result = await pollUntil(async () => {
+				const res = await appSession.sendRequest({
+					method: "eval",
+					params: { code }
+				}, requestTimeout, deviceId, platform);
+				if (res.error != null) return {
+					pass: false,
+					error: res.error
+				};
+				return { pass: res.result != null };
+			}, timeoutMs, intervalMs);
+			if (result.error) return textContent({
+				type: "text",
+				text: `Error: ${result.error}`
+			});
+			const pass = result.pass;
+			return jsonContent({
+				pass,
+				message: pass ? `PASS: element matching "${selector}" found` : `FAIL: element matching "${selector}" not found`
+			});
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `assert_visible failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	registerTool(server, "assert_not_visible", "Assert element matching selector is NOT visible. Returns { pass, message }. Polling until gone.", assertNotVisibleSchema, async (args) => {
+		const { selector, timeoutMs, intervalMs, deviceId, platform } = assertNotVisibleSchema.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return textContent({
+			type: "text",
+			text: "No React Native app connected."
+		});
+		const code = buildQuerySelectorEvalCode(selector);
+		const requestTimeout = Math.max(1e4, timeoutMs + 5e3);
+		try {
+			const result = await pollUntil(async () => {
+				const res = await appSession.sendRequest({
+					method: "eval",
+					params: { code }
+				}, requestTimeout, deviceId, platform);
+				if (res.error != null) return {
+					pass: false,
+					error: res.error
+				};
+				return { pass: res.result == null };
+			}, timeoutMs, intervalMs);
+			if (result.error) return textContent({
+				type: "text",
+				text: `Error: ${result.error}`
+			});
+			const pass = result.pass;
+			return jsonContent({
+				pass,
+				message: pass ? `PASS: element matching "${selector}" not found (as expected)` : `FAIL: element matching "${selector}" still visible`
+			});
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `assert_not_visible failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	registerTool(server, "assert_element_count", "Assert count of elements matching selector. expectedCount or minCount/maxCount. Returns { pass, actualCount, message }.", assertElementCountSchema, async (args) => {
+		const { selector, expectedCount, minCount, maxCount, timeoutMs, intervalMs, deviceId, platform } = assertElementCountSchema.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return textContent({
+			type: "text",
+			text: "No React Native app connected."
+		});
+		const code = buildQuerySelectorAllEvalCode(selector);
+		const requestTimeout = Math.max(1e4, timeoutMs + 5e3);
+		function checkCount(count) {
+			if (expectedCount != null) return count === expectedCount;
+			let ok = true;
+			if (minCount != null) ok = ok && count >= minCount;
+			if (maxCount != null) ok = ok && count <= maxCount;
+			return ok;
+		}
+		try {
+			const result = await pollUntil(async () => {
+				const res = await appSession.sendRequest({
+					method: "eval",
+					params: { code }
+				}, requestTimeout, deviceId, platform);
+				if (res.error != null) return {
+					pass: false,
+					actualCount: 0,
+					error: res.error
+				};
+				const actualCount = (Array.isArray(res.result) ? res.result : []).length;
+				return {
+					pass: checkCount(actualCount),
+					actualCount
+				};
+			}, timeoutMs, intervalMs);
+			if (result.error) return textContent({
+				type: "text",
+				text: `Error: ${result.error}`
+			});
+			const { pass, actualCount } = result;
+			const expected = expectedCount != null ? `exactly ${expectedCount}` : `${minCount != null ? `>=${minCount}` : ""}${minCount != null && maxCount != null ? " and " : ""}${maxCount != null ? `<=${maxCount}` : ""}`;
+			return jsonContent({
+				pass,
+				actualCount,
+				message: pass ? `PASS: found ${actualCount} elements (expected ${expected})` : `FAIL: found ${actualCount} elements (expected ${expected})`
+			});
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `assert_element_count failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/webview-evaluate-script.ts
+/**
+* MCP 도구: webview_evaluate_script
+* 앱에 등록된 WebView 내부에서 임의의 JavaScript를 실행 (injectJavaScript)
+* Babel 플러그인(babel-plugin-inject-testid)이 <WebView> 태그를 자동 감지하여
+* registerWebView/unregisterWebView/onMessage를 주입하므로, 별도 수동 등록 없이
+* evaluate_script로 getRegisteredWebViewIds()를 호출하면 사용 가능한 ID를 확인할 수 있다.
+*/
+const schema$22 = z.object({
+	webViewId: z.string().describe("WebView id. Use evaluate_script getRegisteredWebViewIds() to discover."),
+	script: z.string().describe("JS to run in WebView (DOM query, click, etc). Must evaluate to value for result."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerWebviewEvaluateScript(server, appSession) {
+	server.registerTool("webview_evaluate_script", {
+		description: "Run JS in in-app WebView. Get webViewId via getRegisteredWebViewIds(). Prefer over tap for DOM (faster, reliable). onMessage needed for return value.",
+		inputSchema: schema$22
+	}, async (args) => {
+		const { webViewId, script, deviceId, platform } = schema$22.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ return __REACT_NATIVE_MCP__.evaluateInWebViewAsync(${JSON.stringify(webViewId)}, ${JSON.stringify(script)}); })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 15e3, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const result = res.result;
+			if (result && result.ok === true && result.value !== void 0) return { content: [{
+				type: "text",
+				text: result.value
+			}] };
+			if (result && result.ok === false && result.error != null) return { content: [{
+				type: "text",
+				text: `WebView error: ${result.error}`
+			}] };
+			if (result && result.ok === true) return { content: [{
+				type: "text",
+				text: `OK: script executed in WebView "${webViewId}". (No result: app may not forward onMessage to handleWebViewMessage.)`
+			}] };
+			return { content: [{
+				type: "text",
+				text: result?.error ?? JSON.stringify(result ?? res.result)
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Request failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/eval-code.ts
+/**
+* MCP 도구: evaluate_script
+* Chrome DevTools MCP 스펙. function + args를 앱에서 실행 (WebSocket eval)
+* @see docs/chrome-devtools-mcp-spec-alignment.md
+*/
+const schema$21 = z.object({
+	function: z.string().describe("JS function string. E.g. \"() => measureView(uid)\". require() not available."),
+	args: z.array(z.unknown()).optional().describe("Arguments array for the function."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function formatResult(value) {
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value, null, 2);
+	} catch {
+		return String(value);
+	}
+}
+/**
+* evaluate_script: Chrome DevTools MCP와 동일 (function, args). 앱에 코드 전송 후 결과 반환.
+*/
+function registerEvaluateScript(server, appSession) {
+	server.registerTool("evaluate_script", {
+		description: "Run JS in app context. function (string), args (array). Returns JSON result. Use measureView(uid) for tap/swipe coords.",
+		inputSchema: schema$21
+	}, async (args) => {
+		const { function: fnStr, args: fnArgs, deviceId, platform } = schema$21.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){try{var __f=(${fnStr});return __f.apply(null,${JSON.stringify(fnArgs ?? [])});}catch(e){return e.message||String(e);}})()`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			return { content: [{
+				type: "text",
+				text: formatResult(res.result)
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `evaluate_script failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/get-debugger-status.ts
+/**
+* MCP 도구: get_debugger_status
+* 앱↔MCP 연결 상태 확인. 다중 디바이스: 연결된 전체 디바이스 목록 포함.
+*/
+const schema$20 = z.object({
+	topInsetDp: z.number().optional().describe("Set Android top inset override (dp). Overrides ADB auto-detect. Persists for the connection."),
+	deviceId: z.string().optional().describe("Target device for topInsetDp override.")
+});
+function registerGetDebuggerStatus(server, appSession) {
+	server.registerTool("get_debugger_status", {
+		description: "MCP connection status. appConnected, devices list (deviceId, platform). Call first to see connected devices.",
+		inputSchema: schema$20
+	}, async (args) => {
+		const { topInsetDp, deviceId } = schema$20.parse(args ?? {});
+		if (topInsetDp != null) try {
+			appSession.setTopInsetDp(topInsetDp, deviceId, "android");
+		} catch {}
+		const appConnected = appSession.isConnected();
+		const devices = appSession.getConnectedDevices();
+		const status = {
+			appConnected,
+			devices
+		};
+		if (appConnected && devices.length > 0) try {
+			const info = (await appSession.sendRequest({
+				method: "eval",
+				params: { code: "(function(){ var M = typeof __REACT_NATIVE_MCP__ !== \"undefined\" ? __REACT_NATIVE_MCP__ : null; return M && M.getScreenInfo ? M.getScreenInfo() : null; })();" }
+			}, 5e3)).result;
+			if (info && typeof info === "object" && info.orientation) {
+				status.orientation = info.orientation;
+				if (info.window) status.window = info.window;
+			}
+		} catch {}
+		const text = [
+			`appConnected: ${appConnected}`,
+			`devices: ${devices.length > 0 ? devices.map((d) => `${d.deviceId}(${d.platform}${d.deviceName ? ", " + d.deviceName : ""}${d.platform === "android" ? `, topInset=${d.topInsetDp}dp` : ""})`).join(", ") : "none"}`,
+			status.orientation != null ? `orientation: ${status.orientation}` : ""
+		].filter(Boolean).join("\n");
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(status, null, 2)
+		}, {
+			type: "text",
+			text
+		}] };
+	});
+}
+
+//#endregion
+//#region src/tools/list-console-messages.ts
+/**
+* MCP 도구: list_console_messages, clear_console_messages
+* nativeLoggingHook을 통해 캡처된 콘솔 로그를 조회/초기화.
+* runtime.js의 getConsoleLogs / clearConsoleLogs를 eval로 호출.
+*/
+const LEVEL_NAMES = {
+	0: "log",
+	1: "info",
+	2: "warn",
+	3: "error"
+};
+const listSchema$3 = z.object({
+	level: z.enum([
+		"log",
+		"info",
+		"warn",
+		"error"
+	]).optional().describe("Filter by level. Omit for all."),
+	since: z.number().optional().describe("Only logs after timestamp (ms)."),
+	limit: z.number().optional().describe("Max logs. Default 100."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const clearSchema$4 = z.object({
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerListConsoleMessages(server, appSession) {
+	const s = server;
+	s.registerTool("list_console_messages", {
+		description: "List captured console logs. Filter by level, since, limit. Levels: log, info, warn, error.",
+		inputSchema: listSchema$3
+	}, async (args) => {
+		const parsed = listSchema$3.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const options = {};
+		if (parsed.success) {
+			if (parsed.data.level != null) options.level = parsed.data.level;
+			if (parsed.data.since != null) options.since = parsed.data.since;
+			if (parsed.data.limit != null) options.limit = parsed.data.limit;
+		}
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.getConsoleLogs ? __REACT_NATIVE_MCP__.getConsoleLogs(${JSON.stringify(options)}) : []; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const list = Array.isArray(res.result) ? res.result : [];
+			if (list.length === 0) return { content: [{
+				type: "text",
+				text: "No console messages."
+			}] };
+			const lines = list.map((entry) => {
+				const levelName = LEVEL_NAMES[entry.level ?? 0] ?? String(entry.level);
+				return `[${entry.id}] ${levelName}: ${entry.message ?? ""}  (${entry.timestamp ?? ""})`;
+			});
+			return { content: [{
+				type: "text",
+				text: `${list.length} message(s):\n${lines.join("\n")}`
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `list_console_messages failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	s.registerTool("clear_console_messages", {
+		description: "Clear all captured console messages from the buffer.",
+		inputSchema: clearSchema$4
+	}, async (args) => {
+		const parsed = clearSchema$4.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ if (typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.clearConsoleLogs) { __REACT_NATIVE_MCP__.clearConsoleLogs(); return true; } return false; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			return { content: [{
+				type: "text",
+				text: "Console messages cleared."
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `clear_console_messages failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/list-network-requests.ts
+/**
+* MCP 도구: list_network_requests, clear_network_requests
+* XHR/fetch monkey-patch를 통해 캡처된 네트워크 요청을 조회/초기화.
+* runtime.js의 getNetworkRequests / clearNetworkRequests를 eval로 호출.
+*/
+const listSchema$2 = z.object({
+	url: z.string().optional().describe("URL substring filter."),
+	method: z.string().optional().describe("HTTP method filter."),
+	status: z.number().optional().describe("Status code filter."),
+	since: z.number().optional().describe("Only requests after timestamp (ms)."),
+	limit: z.number().optional().describe("Max requests. Default 50."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const clearSchema$3 = z.object({
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerListNetworkRequests(server, appSession) {
+	const s = server;
+	s.registerTool("list_network_requests", {
+		description: "List captured XHR/fetch requests. Filter by url, method, status, since, limit. Returns request/response details.",
+		inputSchema: listSchema$2
+	}, async (args) => {
+		const parsed = listSchema$2.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const options = {};
+		if (parsed.success) {
+			if (parsed.data.url != null) options.url = parsed.data.url;
+			if (parsed.data.method != null) options.method = parsed.data.method;
+			if (parsed.data.status != null) options.status = parsed.data.status;
+			if (parsed.data.since != null) options.since = parsed.data.since;
+			if (parsed.data.limit != null) options.limit = parsed.data.limit;
+		}
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.getNetworkRequests ? __REACT_NATIVE_MCP__.getNetworkRequests(${JSON.stringify(options)}) : []; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const list = Array.isArray(res.result) ? res.result : [];
+			if (list.length === 0) return { content: [{
+				type: "text",
+				text: "No network requests."
+			}] };
+			const lines = list.map((entry) => {
+				const status = entry.status != null ? String(entry.status) : "-";
+				const duration = entry.duration != null ? `${entry.duration}ms` : "pending";
+				const error = entry.error ? ` [${entry.error}]` : "";
+				return `[${entry.id}] ${entry.method} ${entry.url} → ${status} (${duration})${error}`;
+			});
+			return { content: [{
+				type: "text",
+				text: `${list.length} request(s):\n${lines.join("\n")}`
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `list_network_requests failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	s.registerTool("clear_network_requests", {
+		description: "Clear all captured network requests from the buffer.",
+		inputSchema: clearSchema$3
+	}, async (args) => {
+		const parsed = clearSchema$3.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ if (typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.clearNetworkRequests) { __REACT_NATIVE_MCP__.clearNetworkRequests(); return true; } return false; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			return { content: [{
+				type: "text",
+				text: "Network requests cleared."
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `clear_network_requests failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/take-screenshot.ts
+/**
+* MCP 도구: take_screenshot
+* 네이티브 모듈 없이 호스트 CLI(ADB / simctl)로 스크린샷 캡처.
+* 항상 JPEG 80% + 720p. 좌표 보정용 원본 포인트 해상도 포함.
+*/
+const MAX_HEIGHT = 720;
+const JPEG_QUALITY = 80;
+const schema$19 = z.object({
+	platform: z.enum(["android", "ios"]).describe("android: adb. ios: simctl (simulator only)."),
+	filePath: z.string().optional().describe("Path to save screenshot.")
+});
+const PNG_SIGNATURE = Buffer.from([
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+]);
+function isValidPng(buf) {
+	return buf.length >= PNG_SIGNATURE.length && buf.subarray(0, 8).equals(PNG_SIGNATURE);
+}
+/** Android: adb exec-out screencap -p 로 raw PNG 수신. */
+async function captureAndroid() {
+	const png = await runCommand("adb", [
+		"exec-out",
+		"screencap",
+		"-p"
+	], { timeoutMs: 1e4 });
+	if (!isValidPng(png)) throw new Error("adb screencap produced invalid PNG. Try again or check device.");
+	return png;
+}
+/** iOS 시뮬레이터: simctl io booted screenshot → 파일 읽기. */
+async function captureIos() {
+	const path = join(tmpdir(), `rn-mcp-screenshot-${Date.now()}.png`);
+	await runCommand("xcrun", [
+		"simctl",
+		"io",
+		"booted",
+		"screenshot",
+		path
+	], { timeoutMs: 1e4 });
+	try {
+		return await readFile(path);
+	} finally {
+		await unlink(path).catch(() => {});
+	}
+}
+/** 720p JPEG 80%로 변환. 원본 포인트 해상도와 출력 크기를 함께 반환. */
+async function processImage(png, platform, runtimePixelRatio) {
+	const sharp = (await import("sharp")).default;
+	const metadata = await sharp(png).metadata();
+	const rawWidth = metadata.width || 0;
+	const rawHeight = metadata.height || 0;
+	let scale;
+	if (runtimePixelRatio != null) scale = runtimePixelRatio;
+	else if (platform === "android") scale = await getAndroidScale();
+	else {
+		const density = metadata.density || 72;
+		scale = Math.round(density / 72) || 1;
+	}
+	const pointSize = {
+		width: Math.round(rawWidth / scale),
+		height: Math.round(rawHeight / scale)
+	};
+	const buffer = await sharp(png).resize({
+		height: MAX_HEIGHT,
+		fit: "inside"
+	}).jpeg({ quality: JPEG_QUALITY }).toBuffer();
+	const outMeta = await sharp(buffer).metadata();
+	return {
+		buffer,
+		pointSize,
+		outputSize: {
+			width: outMeta.width || 0,
+			height: outMeta.height || 0
+		}
+	};
+}
+function registerTakeScreenshot(server, appSession) {
+	server.registerTool("take_screenshot", {
+		description: "Capture device/simulator screen. JPEG 720p. Returns point size for coords. Prefer assert_text/assert_visible (screenshots use vision tokens).",
+		inputSchema: schema$19
+	}, async (args) => {
+		const { platform, filePath } = schema$19.parse(args);
+		try {
+			const png = platform === "android" ? await captureAndroid() : await captureIos();
+			if (!isValidPng(png)) throw new Error("Capture produced invalid PNG.");
+			const { buffer, pointSize, outputSize } = await processImage(png, platform, appSession.getPixelRatio(void 0, platform));
+			if (filePath) await writeFile(filePath, buffer);
+			const base64 = buffer.toString("base64");
+			const scaleX = (pointSize.width / outputSize.width).toFixed(4);
+			const scaleY = (pointSize.height / outputSize.height).toFixed(4);
+			return { content: [{
+				type: "text",
+				text: `Screenshot captured (${platform}).${filePath ? ` Saved to ${filePath}.` : ""} Device point size: ${pointSize.width}x${pointSize.height}. Screenshot size: ${outputSize.width}x${outputSize.height}. Coordinate scale: point_x = screenshot_x × ${scaleX}, point_y = screenshot_y × ${scaleY}.`
+			}, {
+				type: "image",
+				data: base64,
+				mimeType: "image/jpeg"
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Screenshot failed: ${err instanceof Error ? err.message : String(err)}. Ensure ${platform === "android" ? "adb devices has a device" : "iOS Simulator is booted (xcrun simctl list devices)"}.`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/take-snapshot.ts
+/**
+* MCP 도구: take_snapshot
+* Chrome DevTools MCP 스펙 정렬. a11y 대신 Fiber 컴포넌트 트리(타입/testID/자식) 기반 스냅샷.
+* querySelector 대체: 트리에서 ScrollView, FlatList, Text 등 타입·uid로 요소 탐색.
+*/
+const schema$18 = z.object({
+	maxDepth: z.number().int().min(1).max(100).optional().describe("Max tree depth. Default 30."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerTakeSnapshot(server, appSession) {
+	server.registerTool("take_snapshot", {
+		description: "Capture component tree for uids. Returns uid, type, testID, text. uid = testID or path. Then measureView(uid) → tap/swipe.",
+		inputSchema: schema$18
+	}, async (args) => {
+		const parsed = schema$18.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.getComponentTree ? __REACT_NATIVE_MCP__.getComponentTree({ maxDepth: ${parsed.success && parsed.data.maxDepth != null ? parsed.data.maxDepth : 30} }) : null; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const tree = res.result;
+			return { content: [{
+				type: "text",
+				text: tree == null ? "Snapshot unavailable (DevTools hook or fiber root missing)." : JSON.stringify(tree, null, 2)
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `take_snapshot failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/accessibility-audit.ts
+/**
+* MCP 도구: accessibility_audit
+* Fiber 트리 순회로 접근성(a11y) 규칙 위반 자동 검출.
+* 규칙: pressable-needs-label, image-needs-alt, touch-target-size, missing-role.
+* text-contrast는 미구현(어려움: RN processColor 숫자화·스타일 병합으로 대비비 계산 불가).
+*/
+const schema$17 = z.object({
+	maxDepth: z.number().int().min(1).max(100).optional().describe("Max tree depth. Default 999."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerAccessibilityAudit(server, appSession) {
+	server.registerTool("accessibility_audit", {
+		description: "Run a11y audit on RN tree. Returns violations: rule, selector, severity, message. Rules: pressable-needs-label, image-needs-alt, touch-target-size, missing-role.",
+		inputSchema: schema$17
+	}, async (args) => {
+		const parsed = schema$17.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.getAccessibilityAudit ? __REACT_NATIVE_MCP__.getAccessibilityAudit({ maxDepth: ${parsed.success && parsed.data.maxDepth != null ? parsed.data.maxDepth : 999} }) : []; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 15e3, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const violations = Array.isArray(res.result) ? res.result : [];
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(violations, null, 2)
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `accessibility_audit failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/type-text.ts
+/**
+* MCP 도구: type_text
+* TextInput에 텍스트 입력. onChangeText 호출 + setNativeProps로 네이티브 값 동기화.
+*/
+const schema$16 = z.object({
+	uid: z.string().describe("testID or path of TextInput. Get from query_selector first."),
+	text: z.string().describe("Text to type."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerTypeText(server, appSession) {
+	server.registerTool("type_text", {
+		description: "Type text into TextInput by uid (from query_selector). Supports Unicode. Use instead of input_text for non-ASCII.",
+		inputSchema: schema$16
+	}, async (args) => {
+		const { uid, text: inputText, deviceId, platform } = schema$16.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.typeText ? __REACT_NATIVE_MCP__.typeText(${JSON.stringify(uid)}, ${JSON.stringify(inputText)}) : { ok: false, error: 'typeText not available' }; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const out = res.result;
+			return { content: [{
+				type: "text",
+				text: (out && typeof out.ok === "boolean" ? out.ok : false) ? `typed "${inputText}" into ${uid}` : out && out.error ? out.error : "typeText failed"
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `type_text failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/switch-keyboard.ts
+/**
+* MCP 도구: switch_keyboard
+* iOS 시뮬레이터 / Android 에뮬레이터 키보드 전환.
+* input_text는 HID 키코드 기반이라 현재 키보드 언어에 의존 — 이 도구로 영문 전환 후 사용.
+*/
+const schema$15 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	action: z.enum([
+		"list",
+		"get",
+		"switch"
+	]).describe("list: available keyboards. get: current. switch: toggle (iOS) or set IME (Android)."),
+	keyboard_id: z.string().optional().describe("Android switch only. IME ID. Use action=list to see IDs.")
+});
+async function iosListKeyboards() {
+	return (await runCommand("xcrun", [
+		"simctl",
+		"spawn",
+		"booted",
+		"defaults",
+		"read",
+		"-g",
+		"AppleKeyboards"
+	], { timeoutMs: 1e4 })).toString("utf8").trim();
+}
+async function iosSwitchKeyboard() {
+	await runCommand("osascript", ["-e", [
+		"tell application \"Simulator\" to activate",
+		"delay 0.3",
+		"tell application \"System Events\"",
+		"    key code 49 using control down",
+		"end tell"
+	].join("\n")], { timeoutMs: 1e4 });
+	return "Keyboard toggled via Ctrl+Space on iOS Simulator. If it did not work, ensure Simulator has multiple keyboards configured (Settings → General → Keyboard → Keyboards).";
+}
+async function androidListKeyboards() {
+	return (await runCommand("adb", [
+		"shell",
+		"ime",
+		"list",
+		"-s"
+	], { timeoutMs: 1e4 })).toString("utf8").trim();
+}
+async function androidGetKeyboard() {
+	return (await runCommand("adb", [
+		"shell",
+		"settings",
+		"get",
+		"secure",
+		"default_input_method"
+	], { timeoutMs: 1e4 })).toString("utf8").trim();
+}
+async function androidSwitchKeyboard(keyboardId) {
+	return (await runCommand("adb", [
+		"shell",
+		"ime",
+		"set",
+		keyboardId
+	], { timeoutMs: 1e4 })).toString("utf8").trim();
+}
+function registerSwitchKeyboard(server) {
+	server.registerTool("switch_keyboard", {
+		description: "Switch keyboard on simulator/emulator. Use before input_text for correct layout. iOS: Ctrl+Space. Android: IME by ID.",
+		inputSchema: schema$15
+	}, async (args) => {
+		const { platform, action, keyboard_id } = schema$15.parse(args);
+		try {
+			if (platform === "ios") switch (action) {
+				case "list": return { content: [{
+					type: "text",
+					text: `Registered keyboards on booted iOS Simulator:\n${await iosListKeyboards()}`
+				}] };
+				case "get": return { content: [{
+					type: "text",
+					text: `iOS Simulator does not expose the currently active keyboard directly. Registered keyboards:\n${await iosListKeyboards()}\n\nUse action=switch to toggle between them (Ctrl+Space).`
+				}] };
+				case "switch": return { content: [{
+					type: "text",
+					text: await iosSwitchKeyboard()
+				}] };
+			}
+			else switch (action) {
+				case "list": return { content: [{
+					type: "text",
+					text: `Available Android IMEs:\n${await androidListKeyboards()}`
+				}] };
+				case "get": return { content: [{
+					type: "text",
+					text: `Current Android IME: ${await androidGetKeyboard()}`
+				}] };
+				case "switch":
+					if (!keyboard_id) return { content: [{
+						type: "text",
+						text: "keyboard_id is required for Android switch. Use action=list to see available keyboards."
+					}] };
+					return { content: [{
+						type: "text",
+						text: `Android IME switched: ${await androidSwitchKeyboard(keyboard_id)}`
+					}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `switch_keyboard failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/idb-utils.ts
+/**
+* idb (iOS Development Bridge) 공유 유틸리티
+* UDID 자동 해석, idb 설치 확인, 명령 실행 래퍼.
+*/
+let _idbAvailable = null;
+async function checkIdbAvailable() {
+	if (_idbAvailable != null) return _idbAvailable;
+	try {
+		await runCommand("which", ["idb"], { timeoutMs: 3e3 });
+		_idbAvailable = true;
+	} catch {
+		_idbAvailable = false;
+	}
+	return _idbAvailable;
+}
+async function listIdbTargets() {
+	const lines = (await runCommand("idb", ["list-targets", "--json"], { timeoutMs: 1e4 })).toString("utf8").split("\n").filter((l) => l.trim().length > 0);
+	const targets = [];
+	for (const line of lines) try {
+		targets.push(JSON.parse(line));
+	} catch {}
+	return targets;
+}
+async function resolveUdid(udid) {
+	if (udid != null && udid !== "") return udid;
+	const booted = (await listIdbTargets()).filter((t) => t.state === "Booted" && t.type === "simulator");
+	if (booted.length === 0) throw new Error("No booted iOS simulator found. Boot one with: xcrun simctl boot \"<device name>\"");
+	if (booted.length > 1) {
+		const list = booted.map((t) => `  ${t.name} (${t.udid})`).join("\n");
+		throw new Error(`Multiple booted simulators found. Specify udid parameter.\n${list}\nUse list_devices(platform="ios") to see all devices.`);
+	}
+	return booted[0].udid;
+}
+async function runIdbCommand(subcommand, udid, options) {
+	return (await runCommand("idb", [
+		...subcommand,
+		"--udid",
+		udid
+	], { timeoutMs: options?.timeoutMs ?? 1e4 })).toString("utf8").trim();
+}
+function idbNotInstalledError() {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: [
+				"idb (iOS Development Bridge) is not installed.",
+				"",
+				"Install:",
+				"  brew tap facebook/fb",
+				"  brew install idb-companion",
+				"  pip3 install fb-idb",
+				"",
+				"Verify: idb list-targets",
+				"Docs: https://fbidb.io/docs/installation/"
+			].join("\n")
+		}]
+	};
+}
+
+//#endregion
+//#region src/tools/ios-landscape.ts
+/**
+* iOS 시뮬레이터 좌표 변환 유틸리티.
+*
+* idb ui tap/swipe는 GraphicsOrientation=1 (portrait 0°) 기준 좌표를 기대하므로,
+* 다른 orientation에서는 RN 좌표 → portrait 좌표로 변환해야 한다.
+*
+* GraphicsOrientation (com.apple.backboardd):
+*   1 = Portrait 0°        → 변환 없음 (x, y)
+*   2 = Portrait 180°      → 변환: (W - x, H - y)
+*   3 = Landscape A (270°) → 변환: (y, W - x)
+*   4 = Landscape B (90°)  → 변환: (H - y, x)
+*
+* W = window width, H = window height (현재 orientation 기준)
+*/
+const execFileAsync = promisify(execFile);
+const SCREEN_INFO_CODE = "(function(){ var M = typeof __REACT_NATIVE_MCP__ !== \"undefined\" ? __REACT_NATIVE_MCP__ : null; return M && M.getScreenInfo ? M.getScreenInfo() : null; })();";
+/**
+* 앱 런타임 + 시뮬레이터에서 orientation 정보를 수집한다.
+* orientation이 0° (portrait)가 아닐 때만 GraphicsOrientation을 조회.
+* @param orientationOverride e2e.yaml config.orientation 등에서 사용자가 강제 지정한 GraphicsOrientation 값 (1~4). 지정 시 xcrun 자동감지를 건너뛰고 이 값을 사용한다.
+*/
+async function getIOSOrientationInfo(appSession, deviceId, platform, udid, orientationOverride) {
+	const defaultInfo = {
+		graphicsOrientation: 1,
+		width: 0,
+		height: 0
+	};
+	if (platform !== "ios") return defaultInfo;
+	let width = 0;
+	let height = 0;
+	try {
+		const info = (await appSession.sendRequest({
+			method: "eval",
+			params: { code: SCREEN_INFO_CODE }
+		}, 3e3, deviceId, platform)).result;
+		if (info && typeof info === "object") {
+			width = info.window?.width ?? 0;
+			height = info.window?.height ?? 0;
+		}
+	} catch {
+		return defaultInfo;
+	}
+	let graphicsOrientation = 1;
+	if (orientationOverride != null && orientationOverride >= 1 && orientationOverride <= 4) graphicsOrientation = orientationOverride;
+	else try {
+		const { stdout } = await execFileAsync("xcrun", [
+			"simctl",
+			"spawn",
+			udid,
+			"defaults",
+			"read",
+			"com.apple.backboardd"
+		], { timeout: 3e3 });
+		const match = stdout.match(/GraphicsOrientation\s*=\s*(\d+)/);
+		if (match?.[1]) graphicsOrientation = parseInt(match[1], 10);
+	} catch {}
+	return {
+		graphicsOrientation,
+		width,
+		height
+	};
+}
+/**
+* RN 좌표 → idb portrait 좌표 변환.
+* GraphicsOrientation=1 이면 그대로 반환.
+* width/height=0 이면 변환 공식이 음수를 만들 수 있으므로 변환 없이 반환.
+*/
+function transformForIdb(x, y, info) {
+	if (info.width <= 0 || info.height <= 0) return {
+		x,
+		y
+	};
+	switch (info.graphicsOrientation) {
+		case 2: return {
+			x: info.width - x,
+			y: info.height - y
+		};
+		case 3: return {
+			x: y,
+			y: info.width - x
+		};
+		case 4: return {
+			x: info.height - y,
+			y: x
+		};
+		default: return {
+			x,
+			y
+		};
+	}
+}
+
+//#endregion
+//#region src/tools/tap.ts
+/**
+* MCP 도구: tap
+* iOS(idb) / Android(adb) 좌표 탭 통합.
+*/
+const schema$14 = z.object({
+	platform: z.enum(["ios", "android"]).describe("ios or android."),
+	x: z.number().describe("X in points (dp). Pixels auto on Android."),
+	y: z.number().describe("Y in points (dp). Pixels auto on Android."),
+	duration: z.number().optional().describe("Hold ms for long press. Omit for tap."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find."),
+	iosOrientation: z.number().optional().describe("iOS orientation 1-4. Portrait=1,2; Landscape=3,4. Skips auto-detect.")
+});
+function registerTap(server, appSession) {
+	server.registerTool("tap", {
+		description: "Tap at (x,y) in points. Long press via duration (ms). Use after query_selector; verify with assert_text.",
+		inputSchema: schema$14
+	}, async (args) => {
+		const { platform, x, y, duration, deviceId, iosOrientation } = schema$14.parse(args);
+		const isLongPress = duration != null && duration > 0;
+		const action = isLongPress ? "Long-pressed" : "Tapped";
+		try {
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				const t = transformForIdb(x, y, await getIOSOrientationInfo(appSession, deviceId, platform, udid, iosOrientation));
+				const ix = Math.round(t.x);
+				const iy = Math.round(t.y);
+				const cmd = [
+					"ui",
+					"tap",
+					String(ix),
+					String(iy)
+				];
+				if (isLongPress) cmd.push("--duration", String(duration / 1e3));
+				await runIdbCommand(cmd, udid);
+				await new Promise((r) => setTimeout(r, 300));
+				return { content: [{
+					type: "text",
+					text: `${action} at (${ix}, ${iy})${isLongPress ? ` for ${duration}ms` : ""} on iOS simulator ${udid}.`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				const scale = appSession.getPixelRatio(void 0, "android") ?? await getAndroidScale(serial);
+				const topInsetDp = appSession.getTopInsetDp(deviceId, "android");
+				const px = Math.round(x * scale);
+				const py = Math.round((y + topInsetDp) * scale);
+				if (isLongPress) await runAdbCommand([
+					"shell",
+					"input",
+					"swipe",
+					String(px),
+					String(py),
+					String(px),
+					String(py),
+					String(duration)
+				], serial);
+				else await runAdbCommand([
+					"shell",
+					"input",
+					"tap",
+					String(px),
+					String(py)
+				], serial);
+				await new Promise((r) => setTimeout(r, 300));
+				return { content: [{
+					type: "text",
+					text: `${action} at dp(${x}, ${y}) → px(${px}, ${py}) [scale=${scale}]${isLongPress ? ` for ${duration}ms` : ""} on Android device ${serial}.`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `tap failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/swipe.ts
+/**
+* MCP 도구: swipe
+* iOS(idb) / Android(adb) 스와이프 제스처 통합.
+* duration은 밀리초 단위로 통일 (iOS 내부에서 초로 변환).
+*/
+const schema$13 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	x1: z.number().describe("Start X in points (dp). Auto-converted to pixels on Android."),
+	y1: z.number().describe("Start Y in points (dp). Auto-converted to pixels on Android."),
+	x2: z.number().describe("End X in points (dp). Auto-converted to pixels on Android."),
+	y2: z.number().describe("End Y in points (dp). Auto-converted to pixels on Android."),
+	duration: z.number().optional().default(300).describe("Swipe duration ms. Default 300."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find."),
+	iosOrientation: z.number().optional().describe("iOS orientation 1-4. Skips auto-detect.")
+});
+function registerSwipe(server, appSession) {
+	server.registerTool("swipe", {
+		description: "Swipe (x1,y1)→(x2,y2) in points. Duration ms (default 300). For scroll/drawer. Use measureView(uid) then swipe; verify with assert_text.",
+		inputSchema: schema$13
+	}, async (args) => {
+		const { platform, x1, y1, x2, y2, duration, deviceId, iosOrientation } = schema$13.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				const durationSec = duration / 1e3;
+				const info = await getIOSOrientationInfo(appSession, deviceId, platform, udid, iosOrientation);
+				const s1 = transformForIdb(x1, y1, info);
+				const s2 = transformForIdb(x2, y2, info);
+				const ix1 = Math.round(s1.x);
+				const iy1 = Math.round(s1.y);
+				const ix2 = Math.round(s2.x);
+				const iy2 = Math.round(s2.y);
+				const cmd = [
+					"ui",
+					"swipe",
+					String(ix1),
+					String(iy1),
+					String(ix2),
+					String(iy2)
+				];
+				cmd.push("--duration", String(durationSec));
+				cmd.push("--delta", "10");
+				await runIdbCommand(cmd, udid);
+				return { content: [{
+					type: "text",
+					text: `Swiped from (${x1}, ${y1}) to (${x2}, ${y2}) in ${duration}ms on iOS simulator ${udid}.`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				const scale = appSession.getPixelRatio(void 0, "android") ?? await getAndroidScale(serial);
+				const topInsetDp = appSession.getTopInsetDp(deviceId, "android");
+				const px1 = Math.round(x1 * scale);
+				const py1 = Math.round((y1 + topInsetDp) * scale);
+				const px2 = Math.round(x2 * scale);
+				const py2 = Math.round((y2 + topInsetDp) * scale);
+				await runAdbCommand([
+					"shell",
+					"input",
+					"swipe",
+					String(px1),
+					String(py1),
+					String(px2),
+					String(py2),
+					String(duration)
+				], serial);
+				return { content: [{
+					type: "text",
+					text: `Swiped from dp(${x1}, ${y1}) → px(${px1}, ${py1}) to dp(${x2}, ${y2}) → px(${px2}, ${py2}) [scale=${scale}] in ${duration}ms on Android device ${serial}.`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `swipe failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/input-text.ts
+/**
+* MCP 도구: input_text
+* iOS(idb) / Android(adb) 현재 포커스된 입력에 텍스트 입력 통합.
+* ASCII만 지원. 한글/유니코드는 type_text(RN 레벨) 사용 권장.
+*/
+/** adb shell input text에서 특수문자 이스케이프 */
+function escapeAdbText(text) {
+	return text.replace(/([\\"'`\s&|;()<>$!#*?{}[\]~^])/g, "\\$1");
+}
+const schema$12 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	text: z.string().describe("Text to type. ASCII only. Use type_text for Unicode."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find.")
+});
+function registerInputText(server) {
+	server.registerTool("input_text", {
+		description: "Type into focused input. ASCII only. Use type_text for Korean/Unicode.",
+		inputSchema: schema$12
+	}, async (args) => {
+		const { platform, text, deviceId } = schema$12.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				await runIdbCommand([
+					"ui",
+					"text",
+					text
+				], udid);
+				return { content: [{
+					type: "text",
+					text: `Typed "${text}" on iOS simulator ${udid}.`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				await runAdbCommand([
+					"shell",
+					"input",
+					"text",
+					escapeAdbText(text)
+				], serial);
+				return { content: [{
+					type: "text",
+					text: `Typed "${text}" on Android device ${serial}.`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `input_text failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/input-key.ts
+/**
+* MCP 도구: input_key
+* iOS(idb HID) / Android(adb keyevent) 키코드 전송 통합.
+*/
+const schema$11 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	keycode: z.number().describe("Keycode. iOS: 40=Return, 42=Backspace, 44=Space, 41=Escape. Android: 4=BACK, 66=ENTER, 67=DEL."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find.")
+});
+function registerInputKey(server) {
+	server.registerTool("input_key", {
+		description: "Send keycode to simulator/device. iOS: HID. Android: adb. Common: Return, Backspace, ENTER, BACK.",
+		inputSchema: schema$11
+	}, async (args) => {
+		const { platform, keycode, deviceId } = schema$11.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				await runIdbCommand([
+					"ui",
+					"key",
+					String(keycode)
+				], udid);
+				return { content: [{
+					type: "text",
+					text: `Sent keycode ${keycode} on iOS simulator ${udid}.`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				await runAdbCommand([
+					"shell",
+					"input",
+					"keyevent",
+					String(keycode)
+				], serial);
+				return { content: [{
+					type: "text",
+					text: `Sent keycode ${keycode} on Android device ${serial}.`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `input_key failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/press-button.ts
+/**
+* MCP 도구: press_button
+* iOS(idb) / Android(adb) 물리 버튼 통합.
+* Android: HOME, BACK, MENU, APP_SWITCH, POWER, VOLUME_UP, VOLUME_DOWN, ENTER, DEL
+* iOS: HOME, LOCK, SIDE_BUTTON, SIRI, APPLE_PAY
+*/
+const ADB_BUTTON_MAP = {
+	HOME: 3,
+	BACK: 4,
+	MENU: 82,
+	APP_SWITCH: 187,
+	POWER: 26,
+	VOLUME_UP: 24,
+	VOLUME_DOWN: 25,
+	ENTER: 66,
+	DEL: 67
+};
+const IDB_BUTTONS = new Set([
+	"HOME",
+	"LOCK",
+	"SIDE_BUTTON",
+	"SIRI",
+	"APPLE_PAY"
+]);
+const schema$10 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	button: z.string().describe("Android: HOME, BACK, MENU, APP_SWITCH, POWER, VOLUME_UP/DOWN, ENTER, DEL. iOS: HOME, LOCK, SIDE_BUTTON."),
+	duration: z.number().optional().describe("Hold seconds. iOS only."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find.")
+});
+function registerPressButton(server) {
+	server.registerTool("press_button", {
+		description: "Press physical button. Android: HOME, BACK, MENU, etc. iOS: HOME, LOCK, SIDE_BUTTON. Duration = hold (iOS only).",
+		inputSchema: schema$10
+	}, async (args) => {
+		const { platform, button, duration, deviceId } = schema$10.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!IDB_BUTTONS.has(button)) return { content: [{
+					type: "text",
+					text: `Unknown iOS button "${button}". Available: ${[...IDB_BUTTONS].join(", ")}`
+				}] };
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				const cmd = [
+					"ui",
+					"button",
+					button
+				];
+				if (duration != null) cmd.push("--duration", String(duration));
+				await runIdbCommand(cmd, udid);
+				return { content: [{
+					type: "text",
+					text: `Pressed ${button}${duration != null ? ` for ${duration}s` : ""} on iOS simulator ${udid}.`
+				}] };
+			} else {
+				const keycode = ADB_BUTTON_MAP[button];
+				if (keycode == null) return { content: [{
+					type: "text",
+					text: `Unknown Android button "${button}". Available: ${Object.keys(ADB_BUTTON_MAP).join(", ")}`
+				}] };
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				await runAdbCommand([
+					"shell",
+					"input",
+					"keyevent",
+					String(keycode)
+				], serial);
+				return { content: [{
+					type: "text",
+					text: `Pressed ${button} (keycode ${keycode}) on Android device ${serial}.`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `press_button failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/describe-ui.ts
+/**
+* MCP 도구: describe_ui
+* iOS(idb describe-all/describe-point) / Android(uiautomator dump) UI 트리 통합.
+*/
+const xmlParser = new XMLParser({
+	ignoreAttributes: false,
+	attributeNamePrefix: "",
+	isArray: (name) => name === "node"
+});
+function stripEmpty(node) {
+	const out = {};
+	for (const [k, v] of Object.entries(node)) {
+		if (k === "node") continue;
+		if (v === "" || v === "false") continue;
+		out[k] = v;
+	}
+	if (node.node && Array.isArray(node.node)) out.children = node.node.map(stripEmpty);
+	return out;
+}
+function xmlToJson(xml) {
+	const parsed = xmlParser.parse(xml);
+	const hierarchy = parsed.hierarchy;
+	if (!hierarchy) return JSON.stringify(parsed, null, 2);
+	const result = {};
+	for (const [k, v] of Object.entries(hierarchy)) {
+		if (k === "node") continue;
+		if (v !== "" && v !== "false") result[k] = v;
+	}
+	if (hierarchy.node) result.children = hierarchy.node.map(stripEmpty);
+	return JSON.stringify(result, null, 2);
+}
+const schema$9 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	mode: z.enum(["all", "point"]).optional().default("all").describe("iOS: \"all\" or \"point\" at (x,y). Android: ignored."),
+	x: z.number().optional().describe("X in points. iOS, required for mode=point."),
+	y: z.number().optional().describe("Y in points. iOS, required for mode=point."),
+	nested: z.boolean().optional().default(false).describe("iOS: hierarchical tree. Android: ignored."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find.")
+});
+function registerDescribeUi(server) {
+	server.registerTool("describe_ui", {
+		description: "Query native UI/accessibility tree. Large payload. Prefer query_selector for RN elements.",
+		inputSchema: schema$9
+	}, async (args) => {
+		const { platform, mode, x, y, nested, deviceId } = schema$9.parse(args);
+		try {
+			if (platform === "ios") {
+				if (mode === "point" && (x == null || y == null)) return { content: [{
+					type: "text",
+					text: "x and y coordinates are required when mode is \"point\"."
+				}] };
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				const cmd = [];
+				if (mode === "point") {
+					const ix = Math.round(x);
+					const iy = Math.round(y);
+					cmd.push("ui", "describe-point", String(ix), String(iy));
+				} else cmd.push("ui", "describe-all");
+				if (nested) cmd.push("--nested");
+				cmd.push("--json");
+				return { content: [{
+					type: "text",
+					text: await runIdbCommand(cmd, udid, { timeoutMs: 15e3 })
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				const remotePath = "/sdcard/ui_dump.xml";
+				await runAdbCommand([
+					"shell",
+					"uiautomator",
+					"dump",
+					remotePath
+				], serial, { timeoutMs: 15e3 });
+				const xml = await runAdbCommand([
+					"exec-out",
+					"cat",
+					remotePath
+				], serial, { timeoutMs: 1e4 });
+				runAdbCommand([
+					"shell",
+					"rm",
+					"-f",
+					remotePath
+				], serial).catch(() => {});
+				let output;
+				try {
+					output = xmlToJson(xml);
+				} catch {
+					output = xml;
+				}
+				return { content: [{
+					type: "text",
+					text: output
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `describe_ui failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/file-push.ts
+/**
+* MCP 도구: file_push
+* iOS(idb file push) / Android(adb push) 파일 전송 통합.
+* iOS는 bundleId 필수 (앱 컨테이너 모델).
+*/
+const schema$8 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	localPath: z.string().describe("Absolute path to the local file to push."),
+	remotePath: z.string().describe("Destination. iOS: in app container. Android: e.g. /sdcard/Download/file.txt."),
+	bundleId: z.string().optional().describe("Bundle ID. iOS only, required."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find.")
+});
+function registerFilePush(server) {
+	server.registerTool("file_push", {
+		description: "Push local file to simulator/device. iOS: idb + bundleId. Android: adb path.",
+		inputSchema: schema$8
+	}, async (args) => {
+		const { platform, localPath, remotePath, bundleId, deviceId } = schema$8.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!bundleId) return { content: [{
+					type: "text",
+					text: "bundleId is required for iOS file_push. Specify the target app bundle ID (e.g. com.example.myapp)."
+				}] };
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				await runIdbCommand([
+					"file",
+					"push",
+					localPath,
+					remotePath,
+					bundleId
+				], udid, { timeoutMs: 3e4 });
+				return { content: [{
+					type: "text",
+					text: `Pushed ${localPath} → ${remotePath} (bundle: ${bundleId}) on iOS simulator ${udid}.`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				return { content: [{
+					type: "text",
+					text: `Pushed ${localPath} → ${remotePath} on Android device ${serial}.\n${await runAdbCommand([
+						"push",
+						localPath,
+						remotePath
+					], serial, { timeoutMs: 3e4 })}`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `file_push failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/add-media.ts
+/**
+* MCP 도구: add_media
+* iOS(idb add-media) / Android(adb push + media scanner) 미디어 추가 통합.
+*/
+const schema$7 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	filePaths: z.array(z.string()).min(1).describe("Absolute paths to images/videos for gallery."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find.")
+});
+function registerAddMedia(server) {
+	server.registerTool("add_media", {
+		description: "Add images/videos to simulator photo library or device gallery.",
+		inputSchema: schema$7
+	}, async (args) => {
+		const { platform, filePaths, deviceId } = schema$7.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				await runIdbCommand(["add-media", ...filePaths], udid, { timeoutMs: 3e4 });
+				return { content: [{
+					type: "text",
+					text: `Added ${filePaths.length} media file(s) to iOS simulator ${udid} photo library.`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				for (const filePath of filePaths) {
+					const remotePath = `/sdcard/Download/${path$1.basename(filePath)}`;
+					await runAdbCommand([
+						"push",
+						filePath,
+						remotePath
+					], serial, { timeoutMs: 3e4 });
+					await runAdbCommand([
+						"shell",
+						"am",
+						"broadcast",
+						"-a",
+						"android.intent.action.MEDIA_SCANNER_SCAN_FILE",
+						"-d",
+						`file://${remotePath}`
+					], serial);
+				}
+				return { content: [{
+					type: "text",
+					text: `Added ${filePaths.length} media file(s) to Android device ${serial} gallery.`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `add_media failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/list-devices.ts
+/**
+* MCP 도구: list_devices
+* iOS(idb list-targets) / Android(adb devices) 디바이스 목록 조회 통합.
+*/
+const schema$6 = z.object({ platform: z.enum(["ios", "android"]).describe("ios: idb simulators. android: adb devices.") });
+function registerListDevices(server) {
+	server.registerTool("list_devices", {
+		description: "List connected simulators/devices. Returns deviceId, state, model. Use for other tools.",
+		inputSchema: schema$6
+	}, async (args) => {
+		const { platform } = schema$6.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const targets = await listIdbTargets();
+				const booted = targets.filter((t) => t.state === "Booted");
+				return { content: [{
+					type: "text",
+					text: [
+						`Found ${targets.length} target(s), ${booted.length} booted.`,
+						"",
+						...targets.map((t) => `${t.state === "Booted" ? "● " : "○ "}${t.name} | ${t.udid} | ${t.state} | ${t.type} | ${t.os_version}`)
+					].join("\n")
+				}, {
+					type: "text",
+					text: JSON.stringify(targets, null, 2)
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const devices = await listAdbDevices();
+				const online = devices.filter((d) => d.state === "device");
+				const withEmulatorFlag = await Promise.all(devices.map(async (d) => ({
+					...d,
+					isEmulator: d.state === "device" ? await isAndroidEmulator(d.serial) : void 0
+				})));
+				return { content: [{
+					type: "text",
+					text: [
+						`Found ${devices.length} device(s), ${online.length} online.`,
+						"(emulator = AVD, physical = real device. set_location works only on emulator.)",
+						"",
+						...withEmulatorFlag.map((d) => `${d.state === "device" ? "● " : "○ "}${d.serial} | ${d.state}${d.isEmulator != null ? ` | ${d.isEmulator ? "emulator" : "physical"}` : ""}${d.model ? ` | ${d.model}` : ""}${d.product ? ` | ${d.product}` : ""}`)
+					].join("\n")
+				}, {
+					type: "text",
+					text: JSON.stringify(withEmulatorFlag, null, 2)
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `list_devices failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/open-deeplink.ts
+/**
+* MCP tool: open_deeplink
+* Open a deep link / URL on iOS simulator (xcrun simctl) or Android device (adb).
+*/
+const schema$5 = z.object({
+	url: z.string().describe("Deep link URL (e.g. myapp://product/123)."),
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single. list_devices to find.")
+});
+function registerOpenDeeplink(server) {
+	server.registerTool("open_deeplink", {
+		description: "Open deep link on simulator/device. Navigate to screens via URL scheme.",
+		inputSchema: schema$5
+	}, async (args) => {
+		const { url, platform, deviceId } = schema$5.parse(args);
+		try {
+			if (platform === "ios") {
+				const target = deviceId ?? "booted";
+				await runCommand("xcrun", [
+					"simctl",
+					"openurl",
+					target,
+					url
+				]);
+				return { content: [{
+					type: "text",
+					text: `Opened deep link "${url}" on iOS simulator ${target}.`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				await runAdbCommand([
+					"shell",
+					"am",
+					"start",
+					"-a",
+					"android.intent.action.VIEW",
+					"-d",
+					url
+				], serial);
+				return { content: [{
+					type: "text",
+					text: `Opened deep link "${url}" on Android device ${serial}.`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `open_deeplink failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/clear-state.ts
+/**
+* MCP 도구: clear_state
+* 앱 데이터/권한 초기화. Android: pm clear. iOS: simctl privacy reset (권한만).
+*
+* 플랫폼별 차이:
+* - Android: adb shell pm clear <package> — 앱 데이터 전부 삭제(AsyncStorage, SharedPreferences 등).
+* - iOS: xcrun simctl privacy <udid> reset all <bundleId> — 권한/프라이버시 리셋만.
+*   앱 샌드박스(문서/캐시)는 삭제되지 않음. 완전 초기화는 앱 삭제 후 재설치 필요.
+*/
+const schema$4 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	appId: z.string().describe("Bundle ID (iOS) or package name (Android)."),
+	deviceId: z.string().optional().describe("Optional. iOS: UDID. Android: serial. Auto if single device.")
+});
+function registerClearState(server) {
+	server.registerTool("clear_state", {
+		description: "Clear app data (Android: pm clear) or reset permissions (iOS: privacy only). Use before tests. iOS full reset needs uninstall+reinstall.",
+		inputSchema: schema$4
+	}, async (args) => {
+		const { platform, appId, deviceId } = schema$4.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				await runCommand("xcrun", [
+					"simctl",
+					"privacy",
+					udid,
+					"reset",
+					"all",
+					appId
+				], { timeoutMs: 15e3 });
+				return { content: [{
+					type: "text",
+					text: `Reset permissions for ${appId} on iOS simulator ${udid}. (Note: iOS only resets privacy permissions; app sandbox/data is not cleared. For full reset, uninstall and reinstall the app.)`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				await runAdbCommand([
+					"shell",
+					"pm",
+					"clear",
+					appId
+				], serial, { timeoutMs: 15e3 });
+				return { content: [{
+					type: "text",
+					text: `Cleared all app data for ${appId} on Android device ${serial}.`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `clear_state failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/set-location.ts
+/**
+* MCP 도구: set_location
+* 시뮬레이터/에뮬레이터에 위도·경도 설정. Android 실기기 미지원.
+*
+* 플랫폼별 차이:
+* - iOS: idb set-location <lat> <lon> — 시뮬레이터 모두 지원.
+* - Android: adb emu geo fix <lon> <lat> — 에뮬레이터 전용. 실기기에서는 동작하지 않음.
+*/
+const schema$3 = z.object({
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	latitude: z.number().min(-90).max(90).describe("Latitude (-90–90)."),
+	longitude: z.number().min(-180).max(180).describe("Longitude (-180–180)."),
+	deviceId: z.string().optional().describe("Optional. iOS: UDID. Android: serial. Auto if single device.")
+});
+function registerSetLocation(server) {
+	server.registerTool("set_location", {
+		description: "Set GPS on iOS simulator or Android emulator. Android: emulator only.",
+		inputSchema: schema$3
+	}, async (args) => {
+		const { platform, latitude, longitude, deviceId } = schema$3.parse(args);
+		try {
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) return idbNotInstalledError();
+				const udid = await resolveUdid(deviceId);
+				await runIdbCommand([
+					"set-location",
+					String(latitude),
+					String(longitude)
+				], udid, { timeoutMs: 5e3 });
+				return { content: [{
+					type: "text",
+					text: `Set location to ${latitude}, ${longitude} on iOS simulator ${udid}.`
+				}] };
+			} else {
+				if (!await checkAdbAvailable()) return adbNotInstalledError();
+				const serial = await resolveSerial(deviceId);
+				if (!await isAndroidEmulator(serial)) return {
+					isError: true,
+					content: [{
+						type: "text",
+						text: `set_location on Android is supported only on emulator. Device ${serial} appears to be a physical device (ro.kernel.qemu is not 1). Use an AVD (emulator) for location simulation.`
+					}]
+				};
+				await runAdbCommand([
+					"emu",
+					"geo",
+					"fix",
+					String(longitude),
+					String(latitude)
+				], serial, { timeoutMs: 5e3 });
+				return { content: [{
+					type: "text",
+					text: `Set location to ${latitude}, ${longitude} on Android emulator ${serial}. (Note: set_location on Android works only on emulator, not on physical devices.)`
+				}] };
+			}
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `set_location failed: ${err instanceof Error ? err.message : String(err)}.${platform === "android" ? " set_location on Android is supported only on emulator; use an AVD, not a physical device." : ""}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/scroll-until-visible.ts
+/**
+* MCP 도구: scroll_until_visible
+* 요소가 보일 때까지 자동 스크롤. querySelector + swipe 반복.
+* FlatList 가상화로 미렌더링된 아이템도 스크롤하면 나타남.
+*/
+const schema$2 = z.object({
+	selector: z.string().describe("Selector of element to find."),
+	direction: z.enum([
+		"up",
+		"down",
+		"left",
+		"right"
+	]).optional().default("down").describe("Scroll direction. Default \"down\"."),
+	maxScrolls: z.number().optional().default(10).describe("Max scroll attempts. Default 10."),
+	scrollableSelector: z.string().optional().describe("Selector for scroll container. Omit to use center."),
+	platform: z.enum(["ios", "android"]).describe("Target platform."),
+	deviceId: z.string().optional().describe("Device ID. Auto if single."),
+	iosOrientation: z.number().optional().describe("iOS orientation 1-4. Skips auto-detect.")
+});
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function registerScrollUntilVisible(server, appSession) {
+	server.registerTool("scroll_until_visible", {
+		description: "Scroll until selector is visible. querySelector + swipe loop. Returns pass, scrollCount, element. For long lists.",
+		inputSchema: schema$2
+	}, async (args) => {
+		const { selector, direction, maxScrolls, scrollableSelector, platform, deviceId, iosOrientation } = schema$2.parse(args);
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected."
+		}] };
+		const queryCode = buildQuerySelectorEvalCode(selector);
+		/** 요소의 중심이 뷰포트(화면) 안에 있는지. measure가 없으면 true(기존 동작 유지). */
+		function isInViewport(measure, screenWidth, screenHeight) {
+			if (!measure) return true;
+			const { pageX, pageY, width, height } = measure;
+			const centerX = pageX + width / 2;
+			const centerY = pageY + height / 2;
+			return centerX >= 0 && centerX <= screenWidth && centerY >= 0 && centerY <= screenHeight;
+		}
+		async function getScreenBounds() {
+			const screenRes = await appSession.sendRequest({
+				method: "eval",
+				params: { code: `(function(){ var M = typeof __REACT_NATIVE_MCP__ !== 'undefined' ? __REACT_NATIVE_MCP__ : null; return M && M.getScreenInfo ? M.getScreenInfo() : null; })();` }
+			}, 1e4, deviceId, platform);
+			if (screenRes.result?.window) {
+				const w = screenRes.result.window;
+				return {
+					width: w.width,
+					height: w.height
+				};
+			}
+			return {
+				width: 360,
+				height: 800
+			};
+		}
+		async function getScrollArea() {
+			if (scrollableSelector) {
+				const scrollCode = buildQuerySelectorEvalCode(scrollableSelector);
+				const res = await appSession.sendRequest({
+					method: "eval",
+					params: { code: scrollCode }
+				}, 1e4, deviceId, platform);
+				if (res.result?.measure) {
+					const m = res.result.measure;
+					return {
+						centerX: m.pageX + m.width / 2,
+						centerY: m.pageY + m.height / 2,
+						width: m.width,
+						height: m.height
+					};
+				}
+			}
+			const screenRes = await appSession.sendRequest({
+				method: "eval",
+				params: { code: `(function(){ var M = typeof __REACT_NATIVE_MCP__ !== 'undefined' ? __REACT_NATIVE_MCP__ : null; return M && M.getScreenInfo ? M.getScreenInfo() : null; })();` }
+			}, 1e4, deviceId, platform);
+			if (screenRes.result?.window) {
+				const w = screenRes.result.window;
+				return {
+					centerX: w.width / 2,
+					centerY: w.height / 2,
+					width: w.width,
+					height: w.height
+				};
+			}
+			return {
+				centerX: 180,
+				centerY: 400,
+				width: 360,
+				height: 800
+			};
+		}
+		function calcSwipeCoords(area, dir) {
+			const swipeDistance = dir === "left" || dir === "right" ? area.width * .6 : area.height * .4;
+			switch (dir) {
+				case "down": return {
+					x1: area.centerX,
+					y1: area.centerY + swipeDistance / 2,
+					x2: area.centerX,
+					y2: area.centerY - swipeDistance / 2
+				};
+				case "up": return {
+					x1: area.centerX,
+					y1: area.centerY - swipeDistance / 2,
+					x2: area.centerX,
+					y2: area.centerY + swipeDistance / 2
+				};
+				case "right": return {
+					x1: area.centerX + swipeDistance / 2,
+					y1: area.centerY,
+					x2: area.centerX - swipeDistance / 2,
+					y2: area.centerY
+				};
+				case "left": return {
+					x1: area.centerX - swipeDistance / 2,
+					y1: area.centerY,
+					x2: area.centerX + swipeDistance / 2,
+					y2: area.centerY
+				};
+				default: return {
+					x1: area.centerX,
+					y1: area.centerY + swipeDistance / 2,
+					x2: area.centerX,
+					y2: area.centerY - swipeDistance / 2
+				};
+			}
+		}
+		async function performSwipe(coords, orientationInfo) {
+			const duration = 500;
+			if (platform === "ios") {
+				if (!await checkIdbAvailable()) throw new Error("idb not available");
+				const udid = await resolveUdid(deviceId);
+				const s1 = transformForIdb(coords.x1, coords.y1, orientationInfo);
+				const s2 = transformForIdb(coords.x2, coords.y2, orientationInfo);
+				await runIdbCommand([
+					"ui",
+					"swipe",
+					String(Math.round(s1.x)),
+					String(Math.round(s1.y)),
+					String(Math.round(s2.x)),
+					String(Math.round(s2.y)),
+					"--duration",
+					String(duration / 1e3),
+					"--delta",
+					"10"
+				], udid);
+			} else {
+				if (!await checkAdbAvailable()) throw new Error("adb not available");
+				const serial = await resolveSerial(deviceId);
+				const scale = appSession.getPixelRatio(void 0, "android") ?? await getAndroidScale(serial);
+				const topInsetDp = appSession.getTopInsetDp(deviceId, "android");
+				const px1 = Math.round(coords.x1 * scale);
+				const py1 = Math.round((coords.y1 + topInsetDp) * scale);
+				const px2 = Math.round(coords.x2 * scale);
+				const py2 = Math.round((coords.y2 + topInsetDp) * scale);
+				await runAdbCommand([
+					"shell",
+					"input",
+					"swipe",
+					String(px1),
+					String(py1),
+					String(px2),
+					String(py2),
+					String(duration)
+				], serial);
+			}
+		}
+		try {
+			const bounds = await getScreenBounds();
+			const initialRes = await appSession.sendRequest({
+				method: "eval",
+				params: { code: queryCode }
+			}, 1e4, deviceId, platform);
+			if (initialRes.result != null) {
+				const el = initialRes.result;
+				if (isInViewport(el.measure, bounds.width, bounds.height)) return { content: [{
+					type: "text",
+					text: JSON.stringify({
+						pass: true,
+						scrollCount: 0,
+						element: initialRes.result,
+						message: `Element found without scrolling.`
+					})
+				}] };
+			}
+			const swipeCoords = calcSwipeCoords(await getScrollArea(), direction);
+			const orientationInfo = await getIOSOrientationInfo(appSession, deviceId, platform, platform === "ios" ? await resolveUdid(deviceId) : "", iosOrientation);
+			for (let i = 0; i < maxScrolls; i++) {
+				await performSwipe(swipeCoords, orientationInfo);
+				await sleep(500);
+				const res = await appSession.sendRequest({
+					method: "eval",
+					params: { code: queryCode }
+				}, 1e4, deviceId, platform);
+				if (res.result != null) {
+					const el = res.result;
+					if (isInViewport(el.measure, bounds.width, bounds.height)) return { content: [{
+						type: "text",
+						text: JSON.stringify({
+							pass: true,
+							scrollCount: i + 1,
+							element: res.result,
+							message: `Element found after ${i + 1} scroll(s).`
+						})
+					}] };
+				}
+			}
+			return { content: [{
+				type: "text",
+				text: JSON.stringify({
+					pass: false,
+					scrollCount: maxScrolls,
+					message: `Element matching "${selector}" not found after ${maxScrolls} scrolls.`
+				})
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `scroll_until_visible failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/inspect-state.ts
+/**
+* MCP 도구: inspect_state
+* 셀렉터로 찾은 컴포넌트의 React state Hook 목록을 반환.
+* runtime.js의 inspectState(selector)를 eval로 호출.
+*/
+const schema$1 = z.object({
+	selector: z.string().describe("Selector for component (e.g. CartScreen, #cart-view)."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerInspectState(server, appSession) {
+	server.registerTool("inspect_state", {
+		description: "Inspect React state hooks of component by selector. Returns hooks with index and value. Works with useState, Zustand, etc.",
+		inputSchema: schema$1
+	}, async (args) => {
+		const parsed = schema$1.safeParse(args ?? {});
+		if (!parsed.success) return {
+			isError: true,
+			content: [{
+				type: "text",
+				text: `Invalid arguments: ${parsed.error.message}`
+			}]
+		};
+		const { selector, deviceId, platform } = parsed.data;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.inspectState ? __REACT_NATIVE_MCP__.inspectState(${JSON.stringify(selector)}) : null; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			if (!res.result) return { content: [{
+				type: "text",
+				text: `No component found for selector: ${selector}`
+			}] };
+			const result = res.result;
+			const lines = [`Component: ${result.component}`, `State hooks: ${result.hooks.length}`];
+			for (const hook of result.hooks) lines.push(`  [${hook.index}] ${hook.type}: ${JSON.stringify(hook.value, null, 2)}`);
+			return { content: [{
+				type: "text",
+				text: lines.join("\n")
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `inspect_state failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/get-state-changes.ts
+/**
+* MCP 도구: get_state_changes, clear_state_changes
+* onCommitFiberRoot에서 수집된 상태 변경 이력을 조회/초기화.
+* runtime.js의 getStateChanges / clearStateChanges를 eval로 호출.
+*/
+const listSchema$1 = z.object({
+	component: z.string().optional().describe("Filter by component name. Omit for all."),
+	since: z.number().optional().describe("Only changes after timestamp (ms)."),
+	limit: z.number().optional().describe("Max changes to return. Default 100."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const clearSchema$2 = z.object({
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerGetStateChanges(server, appSession) {
+	const s = server;
+	s.registerTool("get_state_changes", {
+		description: "List captured state changes (timestamp, component, hook, prev/next). Filter by component, since, limit. Buffer up to 300.",
+		inputSchema: listSchema$1
+	}, async (args) => {
+		const parsed = listSchema$1.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const options = {};
+		if (parsed.success) {
+			if (parsed.data.component != null) options.component = parsed.data.component;
+			if (parsed.data.since != null) options.since = parsed.data.since;
+			if (parsed.data.limit != null) options.limit = parsed.data.limit;
+		}
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.getStateChanges ? __REACT_NATIVE_MCP__.getStateChanges(${JSON.stringify(options)}) : []; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const list = Array.isArray(res.result) ? res.result : [];
+			if (list.length === 0) return { content: [{
+				type: "text",
+				text: "No state changes recorded."
+			}] };
+			const lines = list.map((entry) => {
+				const ts = entry.timestamp ? new Date(entry.timestamp).toISOString() : "?";
+				return `[${entry.id}] ${ts} ${entry.component}[hook ${entry.hookIndex}]: ${JSON.stringify(entry.prev)} → ${JSON.stringify(entry.next)}`;
+			});
+			return { content: [{
+				type: "text",
+				text: `${list.length} state change(s):\n${lines.join("\n")}`
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `get_state_changes failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	s.registerTool("clear_state_changes", {
+		description: "Clear all captured state change entries from the buffer.",
+		inputSchema: clearSchema$2
+	}, async (args) => {
+		const parsed = clearSchema$2.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ if (typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.clearStateChanges) { __REACT_NATIVE_MCP__.clearStateChanges(); return true; } return false; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			return { content: [{
+				type: "text",
+				text: "State changes cleared."
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `clear_state_changes failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/network-mock.ts
+/**
+* MCP 도구: set_network_mock, list_network_mocks, clear_network_mocks, remove_network_mock
+* runtime.js의 addNetworkMock / listNetworkMocks / clearNetworkMocks / removeNetworkMock를 eval로 호출.
+*/
+const setSchema = z.object({
+	urlPattern: z.string().describe("URL pattern (substring or regex)."),
+	isRegex: z.boolean().optional().describe("urlPattern is regex."),
+	method: z.string().optional().describe("HTTP method. Omit to match all."),
+	status: z.number().optional().describe("Mock status. Default 200."),
+	statusText: z.string().optional().describe("Mock status text."),
+	headers: z.record(z.string()).optional().describe("Mock headers."),
+	body: z.string().optional().describe("Mock body."),
+	delay: z.number().optional().describe("Delay ms before mock."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const listSchema = z.object({
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const clearSchema$1 = z.object({
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const removeSchema = z.object({
+	id: z.number().describe("Mock rule ID to remove."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function notConnectedResponse() {
+	return { content: [{
+		type: "text",
+		text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+	}] };
+}
+function registerNetworkMock(server, appSession) {
+	const s = server;
+	s.registerTool("set_network_mock", {
+		description: "Add network mock. Matching XHR/fetch return mock without hitting network.",
+		inputSchema: setSchema
+	}, async (args) => {
+		const parsed = setSchema.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return notConnectedResponse();
+		const opts = {};
+		if (parsed.success) {
+			opts.urlPattern = parsed.data.urlPattern;
+			if (parsed.data.isRegex != null) opts.isRegex = parsed.data.isRegex;
+			if (parsed.data.method != null) opts.method = parsed.data.method;
+			if (parsed.data.status != null) opts.status = parsed.data.status;
+			if (parsed.data.statusText != null) opts.statusText = parsed.data.statusText;
+			if (parsed.data.headers != null) opts.headers = parsed.data.headers;
+			if (parsed.data.body != null) opts.body = parsed.data.body;
+			if (parsed.data.delay != null) opts.delay = parsed.data.delay;
+		}
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.addNetworkMock ? __REACT_NATIVE_MCP__.addNetworkMock(${JSON.stringify(opts)}) : null; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(res.result, null, 2)
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `set_network_mock failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	s.registerTool("list_network_mocks", {
+		description: "List all active network mock rules.",
+		inputSchema: listSchema
+	}, async (args) => {
+		const parsed = listSchema.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return notConnectedResponse();
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.listNetworkMocks ? __REACT_NATIVE_MCP__.listNetworkMocks() : []; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			const list = Array.isArray(res.result) ? res.result : [];
+			if (list.length === 0) return { content: [{
+				type: "text",
+				text: "No network mock rules."
+			}] };
+			const lines = list.map((r) => `[${r.id}] ${r.method || "*"} ${r.isRegex ? "/" + r.urlPattern + "/" : r.urlPattern} → ${r.status} (hits: ${r.hitCount})`);
+			return { content: [{
+				type: "text",
+				text: `${list.length} mock rule(s):\n${lines.join("\n")}`
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `list_network_mocks failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	s.registerTool("clear_network_mocks", {
+		description: "Clear all network mock rules.",
+		inputSchema: clearSchema$1
+	}, async (args) => {
+		const parsed = clearSchema$1.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return notConnectedResponse();
+		const code = `(function(){ if (typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.clearNetworkMocks) { __REACT_NATIVE_MCP__.clearNetworkMocks(); return true; } return false; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			return { content: [{
+				type: "text",
+				text: "Network mock rules cleared."
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `clear_network_mocks failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	s.registerTool("remove_network_mock", {
+		description: "Remove a specific network mock rule by ID.",
+		inputSchema: removeSchema
+	}, async (args) => {
+		const parsed = removeSchema.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return notConnectedResponse();
+		const id = parsed.success ? parsed.data.id : 0;
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.removeNetworkMock ? __REACT_NATIVE_MCP__.removeNetworkMock(${JSON.stringify(id)}) : false; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			return { content: [{
+				type: "text",
+				text: res.result === true ? `Mock rule ${id} removed.` : `Mock rule ${id} not found.`
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `remove_network_mock failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/image-compare.ts
+/**
+* 두 PNG 이미지를 픽셀 단위로 비교한다.
+* @param baselinePng 기준 이미지 PNG Buffer
+* @param currentPng 현재 이미지 PNG Buffer
+* @param threshold pixelmatch threshold (0~1). 기본 0.1 (pixelmatch 기본값)
+* @returns CompareResult
+*/
+async function compareImages(baselinePng, currentPng, threshold = .1) {
+	const sharp = (await import("sharp")).default;
+	const pixelmatch = (await import("pixelmatch")).default;
+	const [baseMeta, curMeta] = await Promise.all([sharp(baselinePng).metadata(), sharp(currentPng).metadata()]);
+	const bw = baseMeta.width;
+	const bh = baseMeta.height;
+	const cw = curMeta.width;
+	const ch = curMeta.height;
+	if (bw !== cw || bh !== ch) return {
+		pass: false,
+		diffRatio: 1,
+		diffPixels: bw * bh,
+		totalPixels: bw * bh,
+		dimensions: {
+			width: bw,
+			height: bh
+		},
+		message: `Size mismatch: baseline ${bw}x${bh} vs current ${cw}x${ch}`
+	};
+	const [baseRaw, curRaw] = await Promise.all([sharp(baselinePng).ensureAlpha().raw().toBuffer(), sharp(currentPng).ensureAlpha().raw().toBuffer()]);
+	const totalPixels = bw * bh;
+	const diffRaw = Buffer.alloc(bw * bh * 4);
+	const diffPixels = pixelmatch(baseRaw, curRaw, diffRaw, bw, bh, { threshold });
+	const diffRatio = diffPixels / totalPixels;
+	const diffBuffer = await sharp(diffRaw, { raw: {
+		width: bw,
+		height: bh,
+		channels: 4
+	} }).png().toBuffer();
+	const pass = diffPixels === 0;
+	return {
+		pass,
+		diffRatio,
+		diffPixels,
+		totalPixels,
+		dimensions: {
+			width: bw,
+			height: bh
+		},
+		diffBuffer,
+		message: pass ? `Images match (${bw}x${bh})` : `${diffPixels} pixels differ (${(diffRatio * 100).toFixed(2)}%) in ${bw}x${bh} image`
+	};
+}
+/**
+* PNG 이미지에서 지정 영역을 크롭한다.
+* @param png 원본 PNG Buffer
+* @param rect 크롭 영역 (pixel 단위)
+* @returns 크롭된 PNG Buffer
+*/
+async function cropElement(png, rect) {
+	const sharp = (await import("sharp")).default;
+	return sharp(png).extract(rect).png().toBuffer();
+}
+/**
+* PNG 이미지에서 스크린 스케일을 계산한다.
+* 런타임 pixelRatio를 우선 사용하고, 없으면 플랫폼별 fallback.
+*/
+async function getScreenScale(png, platform, runtimePixelRatio) {
+	if (runtimePixelRatio != null) return runtimePixelRatio;
+	if (platform === "android") {
+		const { getAndroidScale } = await import("./adb-utils-R7jCnMjU.js");
+		return getAndroidScale();
+	}
+	const sharp = (await import("sharp")).default;
+	const density = (await sharp(png).metadata()).density || 72;
+	return Math.round(density / 72) || 1;
+}
+
+//#endregion
+//#region src/tools/visual-compare.ts
+/**
+* MCP 도구: visual_compare
+* 스크린샷을 캡처하여 베이스라인 PNG 파일과 픽셀 단위 비교.
+* selector 지정 시 해당 요소만 크롭하여 비교 (컴포넌트 단위 비주얼 리그레션).
+*/
+const schema = z.object({
+	platform: z.enum(["android", "ios"]).describe("Target platform."),
+	baseline: z.string().describe("Absolute path to baseline PNG file."),
+	selector: z.string().optional().describe("CSS-like selector to crop a specific element. If omitted, compares full screen."),
+	threshold: z.number().min(0).max(1).optional().describe("pixelmatch threshold (0~1). Default 0.1."),
+	updateBaseline: z.boolean().optional().describe("If true, save current screenshot as new baseline and skip comparison."),
+	saveDiff: z.string().optional().describe("Path to save diff image PNG."),
+	saveCurrent: z.string().optional().describe("Path to save current screenshot PNG."),
+	deviceId: z.string().optional()
+});
+function registerVisualCompare(server, appSession) {
+	server.registerTool("visual_compare", {
+		description: "Compare current screenshot against a baseline PNG. Supports element-level cropping via selector. Use updateBaseline=true to save new baselines.",
+		inputSchema: schema
+	}, async (args) => {
+		const { platform, baseline, selector, threshold = .1, updateBaseline, saveDiff, saveCurrent, deviceId } = schema.parse(args);
+		try {
+			const rawPng = platform === "android" ? await captureAndroid() : await captureIos();
+			if (!isValidPng(rawPng)) throw new Error("Capture produced invalid PNG.");
+			let currentPng;
+			if (selector) {
+				const measure = await queryMeasure(appSession, selector, deviceId, platform);
+				if (!measure) throw new Error(`Element not found for selector: ${selector}`);
+				const scale = await getScreenScale(rawPng, platform, appSession.getPixelRatio(deviceId, platform));
+				const topInsetDp = appSession.getTopInsetDp(deviceId, platform);
+				currentPng = await cropElement(rawPng, {
+					left: Math.round(measure.pageX * scale),
+					top: Math.round((measure.pageY + topInsetDp) * scale),
+					width: Math.round(measure.width * scale),
+					height: Math.round(measure.height * scale)
+				});
+			} else currentPng = rawPng;
+			if (saveCurrent) {
+				await mkdir(dirname(saveCurrent), { recursive: true });
+				await writeFile(saveCurrent, currentPng);
+			}
+			if (updateBaseline) {
+				await mkdir(dirname(baseline), { recursive: true });
+				await writeFile(baseline, currentPng);
+				return { content: [{
+					type: "text",
+					text: JSON.stringify({
+						updated: true,
+						baseline,
+						message: `Baseline updated: ${baseline}`
+					})
+				}] };
+			}
+			let baselinePng;
+			try {
+				baselinePng = await readFile(baseline);
+			} catch {
+				throw new Error(`Baseline not found: ${baseline}. Run with updateBaseline=true to create it.`);
+			}
+			const result = await compareImages(baselinePng, currentPng, threshold);
+			if (saveDiff && result.diffBuffer) {
+				await mkdir(dirname(saveDiff), { recursive: true });
+				await writeFile(saveDiff, result.diffBuffer);
+			}
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						pass: result.pass,
+						diffRatio: result.diffRatio,
+						diffPixels: result.diffPixels,
+						totalPixels: result.totalPixels,
+						dimensions: result.dimensions,
+						threshold,
+						baseline,
+						selector: selector ?? null,
+						saveDiff: saveDiff ?? null,
+						message: result.message
+					})
+				}],
+				isError: !result.pass ? true : void 0
+			};
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `visual_compare failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+/** querySelector로 요소의 measure 좌표를 가져온다. */
+async function queryMeasure(appSession, selector, deviceId, platform) {
+	const code = buildQuerySelectorEvalCode(selector);
+	const res = await appSession.sendRequest({
+		method: "eval",
+		params: { code }
+	}, 1e4, deviceId, platform);
+	if (res.error != null || res.result == null) return null;
+	return res.result.measure ?? null;
+}
+
+//#endregion
+//#region src/tools/render-tracking.ts
+/**
+* MCP 도구: start_render_profile, get_render_report, clear_render_profile
+* React 컴포넌트 리렌더 프로파일링 — 불필요 리렌더 탐지, 핫 컴포넌트 리포트.
+*/
+const startSchema = z.object({
+	components: z.array(z.string()).optional().describe("Whitelist: track only these components. Overrides ignore."),
+	ignore: z.array(z.string()).optional().describe("Blacklist: skip these components (added to default ignore list). Ignored when components is set."),
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const reportSchema = z.object({
+	deviceId: deviceParam,
+	platform: platformParam
+});
+const clearSchema = z.object({
+	deviceId: deviceParam,
+	platform: platformParam
+});
+function registerRenderTracking(server, appSession) {
+	const s = server;
+	s.registerTool("start_render_profile", {
+		description: "Start render profiling. Tracks component mounts, re-renders, and unnecessary renders caused by parent re-renders. Optional `components` filter.",
+		inputSchema: startSchema
+	}, async (args) => {
+		const parsed = startSchema.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const options = {};
+		if (parsed.success && parsed.data.components) options.components = parsed.data.components;
+		if (parsed.success && parsed.data.ignore) options.ignore = parsed.data.ignore;
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.startRenderProfile ? __REACT_NATIVE_MCP__.startRenderProfile(${JSON.stringify(options)}) : null; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			let filterMsg = "";
+			if (parsed.success && parsed.data.components) filterMsg = ` Whitelist: ${parsed.data.components.join(", ")}`;
+			else if (parsed.success && parsed.data.ignore) filterMsg = ` Ignoring: ${parsed.data.ignore.join(", ")} (+ defaults)`;
+			else filterMsg = " Tracking all components (default ignore applied).";
+			return { content: [{
+				type: "text",
+				text: `Render profiling started.${filterMsg}`
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `start_render_profile failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	s.registerTool("get_render_report", {
+		description: "Get render profiling report. Shows hot components sorted by render count, unnecessary renders (preventable with React.memo), and recent render details with trigger analysis.",
+		inputSchema: reportSchema
+	}, async (args) => {
+		const parsed = reportSchema.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ return typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.getRenderReport ? __REACT_NATIVE_MCP__.getRenderReport() : null; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			if (!res.result) return { content: [{
+				type: "text",
+				text: "No render profiling data. Call start_render_profile first."
+			}] };
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(res.result, null, 2)
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `get_render_report failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+	s.registerTool("clear_render_profile", {
+		description: "Stop render profiling and clear all collected data.",
+		inputSchema: clearSchema
+	}, async (args) => {
+		const parsed = clearSchema.safeParse(args ?? {});
+		const deviceId = parsed.success ? parsed.data.deviceId : void 0;
+		const platform = parsed.success ? parsed.data.platform : void 0;
+		if (!appSession.isConnected(deviceId, platform)) return { content: [{
+			type: "text",
+			text: "No React Native app connected. Start the app with Metro and ensure the MCP runtime is loaded."
+		}] };
+		const code = `(function(){ if (typeof __REACT_NATIVE_MCP__ !== 'undefined' && __REACT_NATIVE_MCP__.clearRenderProfile) { __REACT_NATIVE_MCP__.clearRenderProfile(); return true; } return false; })();`;
+		try {
+			const res = await appSession.sendRequest({
+				method: "eval",
+				params: { code }
+			}, 1e4, deviceId, platform);
+			if (res.error != null) return { content: [{
+				type: "text",
+				text: `Error: ${res.error}`
+			}] };
+			return { content: [{
+				type: "text",
+				text: "Render profiling stopped and data cleared."
+			}] };
+		} catch (err) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `clear_render_profile failed: ${err instanceof Error ? err.message : String(err)}`
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+//#region src/tools/index.ts
+function registerAllTools(server, appSession) {
+	registerEvaluateScript(server, appSession);
+	registerTakeSnapshot(server, appSession);
+	registerTakeScreenshot(server, appSession);
+	registerAccessibilityAudit(server, appSession);
+	registerWebviewEvaluateScript(server, appSession);
+	registerTypeText(server, appSession);
+	registerQuerySelector(server, appSession);
+	registerAssert(server, appSession);
+	registerGetDebuggerStatus(server, appSession);
+	registerListConsoleMessages(server, appSession);
+	registerListNetworkRequests(server, appSession);
+	registerTap(server, appSession);
+	registerSwipe(server, appSession);
+	registerInputText(server);
+	registerInputKey(server);
+	registerPressButton(server);
+	registerDescribeUi(server);
+	registerFilePush(server);
+	registerAddMedia(server);
+	registerListDevices(server);
+	registerSwitchKeyboard(server);
+	registerOpenDeeplink(server);
+	registerClearState(server);
+	registerSetLocation(server);
+	registerScrollUntilVisible(server, appSession);
+	registerInspectState(server, appSession);
+	registerGetStateChanges(server, appSession);
+	registerNetworkMock(server, appSession);
+	registerVisualCompare(server, appSession);
+	registerRenderTracking(server, appSession);
+}
+
+//#endregion
+//#region src/guides/query-selector.ts
+const querySelectorGuide = {
+	name: "query-selector-syntax",
+	description: "query_selector / query_selector_all selector syntax reference. Type, testID, text, attribute, hierarchy, capability selectors and workflow examples.",
+	content: `# query_selector / query_selector_all
+
+Selector syntax for finding elements in the React Native Fiber tree. Similar to CSS \`querySelector\` but for the **React Fiber tree**, not DOM.
+
+## Basic syntax
+
+### Type selector
+
+Match by component type name:
+
+\`\`\`
+View
+Text
+ScrollView
+Pressable
+FlatList
+TextInput
+\`\`\`
+
+### testID selector
+
+\`#\` for testID:
+
+\`\`\`
+#login-btn
+#email-input
+#product-list
+\`\`\`
+
+Combine with type:
+
+\`\`\`
+Pressable#login-btn
+TextInput#email-input
+\`\`\`
+
+### Text selector
+
+\`:text("...")\` — **substring match** on subtree text:
+
+\`\`\`
+:text("Login")
+:text("Submit")
+Text:text("Welcome")
+Pressable:text("OK")
+\`\`\`
+
+> Text is concatenated from all children. E.g. \`<View><Text>Hello</Text><Text>World</Text></View>\` matches \`:text("Hello World")\`.
+
+### Attribute selector
+
+\`[attr="value"]\` — match by props:
+
+\`\`\`
+[accessibilityLabel="Close"]
+[placeholder="Email"]
+View[accessibilityRole="button"]
+\`\`\`
+
+### displayName selector
+
+\`:display-name("...")\` — match by \`fiber.type.displayName\` (independent of type name):
+
+\`\`\`
+:display-name("Animated.View")   # Reanimated: type is AnimatedComponent, displayName matches Animated.View
+View:display-name("CustomBox")
+\`\`\`
+
+### Index selectors
+
+\`:first-of-type\` — first match (same as \`:nth-of-type(1)\`). \`:last-of-type\` — last match:
+
+\`\`\`
+Pressable:first-of-type      # first Pressable
+Pressable:last-of-type       # last Pressable
+View:text("Bottom sheet"):last-of-type   # last View containing "Bottom sheet"
+\`\`\`
+
+\`:nth-of-type(N)\` — Nth match (1-based):
+
+\`\`\`
+Text:nth-of-type(1)          # first Text (= :first-of-type)
+Pressable:nth-of-type(3)     # third Pressable
+:text("Item"):nth-of-type(2) # second element containing "Item"
+\`\`\`
+
+### Capability selectors
+
+\`:has-press\` — element has \`onPress\` handler:
+
+\`\`\`
+:has-press                    # all pressable elements
+View:has-press                # View with onPress
+:has-press:text("Delete")     # pressable with "Delete" text
+\`\`\`
+
+\`:has-scroll\` — element has \`scrollTo\` or \`scrollToOffset\`:
+
+\`\`\`
+:has-scroll                   # all scrollable elements
+ScrollView:has-scroll         # scrollable ScrollView
+\`\`\`
+
+## Hierarchy selectors
+
+### Direct child (\`>\`)
+
+\`\`\`
+View > Text              # Text that is direct child of View
+ScrollView > View > Text # 3-level hierarchy
+\`\`\`
+
+### Descendant (space)
+
+\`\`\`
+View Text                # Text anywhere under View
+ScrollView Pressable     # any Pressable under ScrollView
+\`\`\`
+
+### Combined example
+
+\`\`\`
+View > ScrollView:has-scroll > Pressable:text("Add")
+\`\`\`
+
+## OR (comma)
+
+Combine multiple selectors with comma:
+
+\`\`\`
+ScrollView, FlatList           # ScrollView or FlatList
+Pressable, TouchableOpacity    # either type
+#btn-a, #btn-b                 # either testID
+\`\`\`
+
+## Compound examples
+
+\`\`\`
+# Find login button
+Pressable:text("Login")
+
+# TextInput by testID
+TextInput#email-input
+
+# Close button by accessibility label
+[accessibilityLabel="Close"]:has-press
+
+# Third pressable inside ScrollView
+ScrollView :has-press:nth-of-type(3)
+
+# FlatList or ScrollView
+FlatList, ScrollView
+
+# All Text inside a specific View
+View#header > Text
+\`\`\`
+
+## Return value
+
+### query_selector (single)
+
+\`\`\`json
+{
+  "uid": "login-btn",
+  "type": "Pressable",
+  "testID": "login-btn",
+  "text": "Login",
+  "accessibilityLabel": null,
+  "hasOnPress": true,
+  "hasOnLongPress": false,
+  "hasScrollTo": false,
+  "measure": {
+    "x": 100, "y": 200,
+    "width": 150, "height": 44,
+    "pageX": 100, "pageY": 200
+  }
+}
+\`\`\`
+
+- \`uid\` — testID when present, otherwise path string (e.g. \`"0.1.2"\`)
+- \`measure\` — element coordinates and size (points). pageX/pageY are absolute from top-left of screen.
+- If \`measure\` is null, use \`evaluate_script(measureView(uid))\` to get it (rare).
+
+### query_selector_all (multiple)
+
+\`\`\`json
+[
+  { "uid": "item-0", "type": "Pressable", "text": "Item 1", "hasOnPress": true, "measure": { ... } },
+  { "uid": "item-1", "type": "Pressable", "text": "Item 2", "hasOnPress": true, "measure": { ... } }
+]
+\`\`\`
+
+## Workflow
+
+### Find element → native tap (2 steps)
+
+\`\`\`
+1. query_selector('Pressable:text("Login")') → get uid + measure
+2. tap(platform, measure.pageX + measure.width/2, measure.pageY + measure.height/2) → tap center
+\`\`\`
+
+> measure is included in the result, so a separate measureView call is not needed.
+
+### Assert text
+
+\`\`\`
+assert_text("Welcome") → { pass: true }
+\`\`\`
+
+### List all pressable elements
+
+\`\`\`
+query_selector_all(':has-press')
+\`\`\`
+
+### All text nodes
+
+\`\`\`
+query_selector_all('Text')
+\`\`\`
+
+## Syntax summary
+
+| Syntax | Description | Example |
+|---|---|---|
+| \`Type\` | Component type | \`View\`, \`Text\`, \`Pressable\` |
+| \`#id\` | testID | \`#login-btn\` |
+| \`[attr="val"]\` | Props attribute | \`[accessibilityLabel="Close"]\` |
+| \`:text("...")\` | Text substring match | \`:text("Login")\` |
+| \`:display-name("...")\` | fiber.type.displayName match | \`:display-name("Animated.View")\` |
+| \`:first-of-type\` | First match | \`Pressable:first-of-type\` |
+| \`:last-of-type\` | Last match | \`View:text("Bottom sheet"):last-of-type\` |
+| \`:nth-of-type(N)\` | Nth match (1-based) | \`:nth-of-type(1)\` |
+| \`:has-press\` | Has onPress | \`:has-press\` |
+| \`:has-scroll\` | Has scrollTo | \`:has-scroll\` |
+| \`A > B\` | Direct child | \`View > Text\` |
+| \`A B\` | Descendant | \`View Text\` |
+| \`A, B\` | OR | \`ScrollView, FlatList\` |
+`
+};
+
+//#endregion
+//#region src/resources/query-selector.ts
+function registerQuerySelectorResource(server) {
+	server.registerResource(querySelectorGuide.name, `docs://guides/${querySelectorGuide.name}`, {
+		description: querySelectorGuide.description,
+		mimeType: "text/markdown"
+	}, () => ({ contents: [{
+		uri: `docs://guides/${querySelectorGuide.name}`,
+		text: querySelectorGuide.content,
+		mimeType: "text/markdown"
+	}] }));
+}
+
+//#endregion
+//#region src/resources/index.ts
+function registerAllResources(server) {
+	registerQuerySelectorResource(server);
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* React Native MCP 서버 진입점
+* Stdio transport (Cursor 연동) + WebSocket 서버 (앱 연동)
+*
+* `init` 서브커맨드: 프로젝트 셋업 CLI
+*/
+const VERSION = "0.1.0";
+const WS_PORT = 12300;
+/**
+* MCP 서버 시작
+*/
+async function main() {
+	appSession.start(WS_PORT);
+	const server = new McpServer({
+		name: "react-native-mcp-server",
+		version: VERSION
+	});
+	registerAllTools(server, appSession);
+	registerAllResources(server);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	console.error("[react-native-mcp-server] Running on stdio");
+}
+if (process.argv[2] === "init") {
+	const { parseArgs } = await import("node:util");
+	const { runInit } = await import("./init-202kCwU5.js");
+	const VALID_CLIENTS = [
+		"cursor",
+		"claude-code",
+		"claude-desktop",
+		"windsurf",
+		"antigravity"
+	];
+	const { values } = parseArgs({
+		args: process.argv.slice(3),
+		options: {
+			client: { type: "string" },
+			yes: {
+				type: "boolean",
+				short: "y",
+				default: false
+			},
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	if (values.help) console.log(`
+Usage: react-native-mcp-server init [options]
+
+Options:
+  --client <name>    MCP client: cursor, claude-code, claude-desktop, windsurf, antigravity
+  -y, --yes          Skip prompts (non-interactive mode)
+  --help, -h         Show this help message
+`);
+	else {
+		let client;
+		if (values.client) if (!VALID_CLIENTS.includes(values.client)) {
+			console.error(`Invalid client: ${values.client}`);
+			console.error(`Valid clients: ${VALID_CLIENTS.join(", ")}`);
+			process.exitCode = 1;
+		} else client = values.client;
+		if (process.exitCode !== 1) await runInit({
+			client,
+			interactive: !values.yes
+		});
+	}
+} else main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});
+
+//#endregion
+export { VERSION };