@ceraph/react-native-mcp 0.2.0

package/dist/screen.js

@@ -0,0 +1,357 @@
+/**
+ * WebDriverAgent client with pixel ratio correction.
+ *
+ * Talks to the WDA HTTP server running on localhost:8100 to perform
+ * taps and element lookups on a connected iOS device.
+ */
+const WDA_BASE_URL = "http://localhost:8100";
+const WDA_TIMEOUT_MS = 5000;
+/**
+ * Fetch wrapper with timeout for WDA requests.
+ */
+async function wdaFetch(path, options = {}) {
+    const url = `${WDA_BASE_URL}${path}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), WDA_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            signal: controller.signal,
+            headers: {
+                "Content-Type": "application/json",
+                ...options.headers,
+            },
+        });
+        return response;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export class ScreenManager {
+    sessionId = null;
+    pixelRatio = null;
+    /**
+     * Check whether WebDriverAgent is reachable.
+     */
+    async isAvailable() {
+        try {
+            const res = await wdaFetch("/status");
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get or create a WDA session. Sessions are cached and revalidated.
+     */
+    async ensureSession() {
+        // Try to reuse cached session
+        if (this.sessionId) {
+            try {
+                const res = await wdaFetch(`/session/${this.sessionId}`);
+                if (res.ok)
+                    return this.sessionId;
+            }
+            catch {
+                // Session is stale, create a new one
+            }
+            this.sessionId = null;
+        }
+        // Try to find an existing session from /status
+        try {
+            const statusRes = await wdaFetch("/status");
+            if (statusRes.ok) {
+                const statusData = (await statusRes.json());
+                const existingId = statusData.sessionId || statusData.value?.sessionId;
+                if (existingId) {
+                    this.sessionId = existingId;
+                    return existingId;
+                }
+            }
+        }
+        catch {
+            // Fall through to session creation
+        }
+        // Create a new session
+        const res = await wdaFetch("/session", {
+            method: "POST",
+            body: JSON.stringify({
+                capabilities: {
+                    alwaysMatch: {},
+                },
+            }),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "unknown error");
+            throw new Error(`Failed to create WDA session: ${res.status} ${text}`);
+        }
+        const data = (await res.json());
+        const sessionId = data.sessionId || data.value?.sessionId;
+        if (!sessionId) {
+            throw new Error("WDA session creation succeeded but no sessionId returned");
+        }
+        this.sessionId = sessionId;
+        return sessionId;
+    }
+    /**
+     * Determine the pixel ratio between screenshot coordinates and
+     * device logical coordinates.
+     *
+     * Screenshot images are in physical pixels; WDA taps use logical points.
+     * The ratio is typically 2 (for @2x Retina) or 3 (for @3x).
+     */
+    async getPixelRatio() {
+        if (this.pixelRatio)
+            return this.pixelRatio;
+        const sessionId = await this.ensureSession();
+        // Get the logical window size from WDA
+        const windowRes = await wdaFetch(`/session/${sessionId}/window/size`);
+        if (!windowRes.ok) {
+            throw new Error(`Failed to get window size: ${windowRes.status}`);
+        }
+        const windowData = (await windowRes.json());
+        const logicalWidth = windowData.value.width;
+        // Get a screenshot to measure actual pixel dimensions
+        const screenshotRes = await wdaFetch(`/session/${sessionId}/screenshot`);
+        if (!screenshotRes.ok) {
+            // Fallback: assume 3x for modern iPhones
+            this.pixelRatio = 3;
+            return this.pixelRatio;
+        }
+        const screenshotData = (await screenshotRes.json());
+        const base64 = screenshotData.value;
+        // Decode the PNG header to get image width.
+        // PNG stores width as a big-endian 32-bit int at byte offset 16.
+        const pngBuffer = Buffer.from(base64, "base64");
+        if (pngBuffer.length < 24) {
+            // Not enough data to read PNG header; fallback
+            this.pixelRatio = 3;
+            return this.pixelRatio;
+        }
+        const imageWidth = pngBuffer.readUInt32BE(16);
+        this.pixelRatio = Math.round(imageWidth / logicalWidth);
+        // Sanity check
+        if (this.pixelRatio < 1 || this.pixelRatio > 4) {
+            this.pixelRatio = 3; // safe default for modern iPhones
+        }
+        return this.pixelRatio;
+    }
+    /**
+     * Tap at the given coordinates.
+     *
+     * When `fromScreenshot` is true (the default), the coordinates are
+     * assumed to come from a screenshot image and are divided by the
+     * pixel ratio to convert to logical device points.
+     */
+    async tap(x, y, fromScreenshot = true) {
+        try {
+            const sessionId = await this.ensureSession();
+            const ratio = await this.getPixelRatio();
+            const correctedX = fromScreenshot ? x / ratio : x;
+            const correctedY = fromScreenshot ? y / ratio : y;
+            const res = await wdaFetch(`/session/${sessionId}/wda/tap/0`, {
+                method: "POST",
+                body: JSON.stringify({ x: correctedX, y: correctedY }),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    tappedAt: { x: correctedX, y: correctedY },
+                    pixelRatio: ratio,
+                    correction: fromScreenshot
+                        ? `Divided by ${ratio}x: (${x},${y}) -> (${correctedX.toFixed(1)},${correctedY.toFixed(1)})`
+                        : "No correction (device coordinates)",
+                    error: `WDA tap failed: ${res.status} ${text}`,
+                };
+            }
+            return {
+                success: true,
+                tappedAt: { x: correctedX, y: correctedY },
+                pixelRatio: ratio,
+                correction: fromScreenshot
+                    ? `Divided by ${ratio}x: (${x},${y}) -> (${correctedX.toFixed(1)},${correctedY.toFixed(1)})`
+                    : "No correction (device coordinates)",
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                tappedAt: { x, y },
+                pixelRatio: this.pixelRatio ?? 0,
+                correction: "Failed before correction could be applied",
+                error: err instanceof Error ? err.message : "Unknown error during tap",
+            };
+        }
+    }
+    /**
+     * Find an element in the UI tree and tap its center.
+     */
+    async findAndTap(query) {
+        try {
+            const sessionId = await this.ensureSession();
+            // Fetch the full element source tree
+            const sourceRes = await wdaFetch(`/session/${sessionId}/source?format=json`);
+            if (!sourceRes.ok) {
+                return {
+                    success: false,
+                    error: `Failed to get element tree: ${sourceRes.status}`,
+                };
+            }
+            const sourceData = (await sourceRes.json());
+            const root = sourceData.value;
+            // Find matching elements
+            const matches = this.searchElements(root, query);
+            if (matches.length === 0) {
+                // Collect a summary of visible elements for debugging
+                const visible = this.collectVisibleElements(root, 50);
+                return {
+                    success: false,
+                    availableElements: visible,
+                    error: `No element found matching query: ${JSON.stringify(query)}`,
+                };
+            }
+            // Select the element (by index or first match)
+            const index = query.index ?? 0;
+            if (index >= matches.length) {
+                return {
+                    success: false,
+                    error: `Index ${index} out of range. Found ${matches.length} matching element(s).`,
+                    availableElements: matches.map((m) => ({
+                        type: m.type ?? "unknown",
+                        label: m.label ?? "",
+                        text: String(m.value ?? m.label ?? ""),
+                    })),
+                };
+            }
+            const element = matches[index];
+            const rect = element.rect;
+            if (!rect) {
+                return {
+                    success: false,
+                    error: "Matched element has no bounds/rect information.",
+                };
+            }
+            // Calculate center point (already in device/logical coordinates)
+            const centerX = rect.x + rect.width / 2;
+            const centerY = rect.y + rect.height / 2;
+            // Tap at center -- these are already logical coordinates, no correction
+            const tapRes = await wdaFetch(`/session/${sessionId}/wda/tap/0`, {
+                method: "POST",
+                body: JSON.stringify({ x: centerX, y: centerY }),
+            });
+            if (!tapRes.ok) {
+                const text = await tapRes.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA tap failed: ${tapRes.status} ${text}`,
+                    element: {
+                        type: element.type ?? "unknown",
+                        label: element.label ?? element.name ?? "",
+                        bounds: rect,
+                    },
+                    tappedAt: { x: centerX, y: centerY },
+                };
+            }
+            return {
+                success: true,
+                element: {
+                    type: element.type ?? "unknown",
+                    label: element.label ?? element.name ?? "",
+                    bounds: rect,
+                },
+                tappedAt: { x: centerX, y: centerY },
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error
+                    ? err.message
+                    : "Unknown error during findAndTap",
+            };
+        }
+    }
+    /**
+     * Recursively search the WDA element tree for elements matching the query.
+     */
+    searchElements(element, query) {
+        const results = [];
+        if (this.elementMatches(element, query)) {
+            results.push(element);
+        }
+        const children = element.children;
+        if (Array.isArray(children)) {
+            for (const child of children) {
+                results.push(...this.searchElements(child, query));
+            }
+        }
+        return results;
+    }
+    /**
+     * Check whether a single element matches the given query.
+     */
+    elementMatches(element, query) {
+        if (query.text !== undefined) {
+            const searchText = query.text.toLowerCase();
+            const fields = [element.value, element.label, element.name]
+                .filter(Boolean)
+                .map(v => String(v).toLowerCase());
+            if (!fields.some(f => f.includes(searchText))) {
+                return false;
+            }
+        }
+        if (query.accessibilityLabel !== undefined) {
+            const label = String(element.label ?? element.name ?? "");
+            if (!label
+                .toLowerCase()
+                .includes(query.accessibilityLabel.toLowerCase())) {
+                return false;
+            }
+        }
+        if (query.type !== undefined) {
+            const elemType = String(element.type ?? "");
+            if (!elemType.toLowerCase().includes(query.type.toLowerCase())) {
+                return false;
+            }
+        }
+        // At least one query field must be specified
+        return (query.text !== undefined ||
+            query.accessibilityLabel !== undefined ||
+            query.type !== undefined);
+    }
+    /**
+     * Collect a summary of visible elements for debugging (when no match found).
+     */
+    collectVisibleElements(element, limit) {
+        const results = [];
+        if (limit <= 0)
+            return results;
+        const label = String(element.label ?? element.name ?? "");
+        const text = String(element.value ?? "");
+        const type = String(element.type ?? "");
+        // Only include elements that have some identifying info
+        if (label || text) {
+            results.push({ type, label, text });
+        }
+        const children = element.children;
+        if (Array.isArray(children)) {
+            for (const child of children) {
+                const remaining = limit - results.length;
+                if (remaining <= 0)
+                    break;
+                results.push(...this.collectVisibleElements(child, remaining));
+            }
+        }
+        return results;
+    }
+    /**
+     * Invalidate cached session and pixel ratio (e.g., after app restart).
+     */
+    reset() {
+        this.sessionId = null;
+        this.pixelRatio = null;
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ceraph/react-native-mcp",
+  "version": "0.2.0",
+  "description": "MCP server for React Native and Expo development workflow",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "react-native-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.7",
+    "vitest": "^3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}