@mobilenext/mobile-mcp 0.0.31-beta → 0.0.32

package/README.md

@@ -83,7 +83,7 @@ More details in our [wiki page](https://github.com/mobile-next/mobile-mcp/wiki)
 
 ## Installation and configuration
 
-Setup our MCP with Cline, Cursor, Claude, VS Code, Github Copilot:
+**Standard config** works in most of the tools:
 
 ```json
 {
@@ -94,23 +94,74 @@ Setup our MCP with Cline, Cursor, Claude, VS Code, Github Copilot:
     }
   }
 }
-
 ```
-[Cline:](https://docs.cline.bot/mcp/configuring-mcp-servers) To setup Cline, just add the json above to your MCP settings file.
+
+<details>
+<summary>Cline</summary>
+
+To setup Cline, just add the json above to your MCP settings file.
+
 [More in our wiki](https://github.com/mobile-next/mobile-mcp/wiki/Cline)
 
-[Claude Code:](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)
+</details>
 
-```
-claude mcp add mobile -- npx -y @mobilenext/mobile-mcp@latest
-```
+<details>
+<summary>Claude Code</summary>
 
-[Gemini CLI:](https://cloud.google.com/gemini/docs/codeassist/gemini-cli)
+Use the Claude Code CLI to add the Mobile MCP server:
 
+```bash
+claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
 ```
-gemini mcp add mobile npx -y @mobilenext/mobile-mcp@latest
+
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+#### Click the button to install:
+
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=Mobile%20MCP&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtb2JpbGVuZXh0L21vYmlsZS1tY3BAbGF0ZXN0Il19)
+
+#### Or install manually:
+
+Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx -y @mobilenext/mobile-mcp@latest`. You can also verify config or add command like arguments via clicking `Edit`.
+
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+Use the Gemini CLI to add the Mobile MCP server:
+
+```bash
+gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
 ```
 
+</details>
+
+<details>
+<summary>Goose</summary>
+
+#### Click the button to install:
+
+[![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40mobilenext%2Fmobile-mcp%40latest&id=mobile-mcp&name=Mobile%20MCP&description=Mobile%20automation%20and%20development%20for%20iOS%2C%20Android%2C%20simulators%2C%20emulators%2C%20and%20real%20devices)
+
+#### Or install manually:
+
+Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx -y @mobilenext/mobile-mcp@latest`. Click "Add Extension".
+
+</details>
+
+<details>
+<summary>Qodo Gen</summary>
+
+Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.
+
+Click <code>Save</code>.
+
+</details>
+
 [Read more in our wiki](https://github.com/mobile-next/mobile-mcp/wiki)! 🚀
 
 

package/lib/android.js

@@ -120,7 +120,7 @@ class AndroidRobot {
             .map(line => line.substring("package:".length));
     }
     async launchApp(packageName) {
-        this.adb("shell", "monkey", "-p", packageName, "-c", "android.intent.category.LAUNCHER", "1");
+        this.adb("shell", "monkey", "-p", packageName, "-c", "android.intent.category.LAUNCHER", "1", "1>/dev/null", "2>/dev/null");
     }
     async listRunningProcesses() {
         return this.adb("shell", "ps", "-e")
@@ -202,23 +202,51 @@ class AndroidRobot {
             .length;
     }
     getFirstDisplayId() {
-        const displays = this.adb("shell", "cmd", "display", "get-displays")
-            .toString()
-            .split("\n")
-            .filter(s => s.startsWith("Display id "))
-            // filter for state ON even though get-displays only returns turned on displays
-            .filter(s => s.indexOf(", state ON,") >= 0)
-            // another paranoia check
-            .filter(s => s.indexOf(", uniqueId ") >= 0);
-        if (displays.length > 0) {
-            const m = displays[0].match(/uniqueId \"([^\"]+)\"/);
-            if (m !== null) {
-                const displayId = m[1];
-                if (displayId.indexOf("local:") === 0) {
-                    return displayId.split(":")[1];
+        try {
+            // Try using cmd display get-displays (Android 11+)
+            const displays = this.adb("shell", "cmd", "display", "get-displays")
+                .toString()
+                .split("\n")
+                .filter(s => s.startsWith("Display id "))
+                // filter for state ON even though get-displays only returns turned on displays
+                .filter(s => s.indexOf(", state ON,") >= 0)
+                // another paranoia check
+                .filter(s => s.indexOf(", uniqueId ") >= 0);
+            if (displays.length > 0) {
+                const m = displays[0].match(/uniqueId \"([^\"]+)\"/);
+                if (m !== null) {
+                    let displayId = m[1];
+                    if (displayId.startsWith("local:")) {
+                        displayId = displayId.substring("local:".length);
+                    }
+                    return displayId;
+                }
+            }
+        }
+        catch (error) {
+            // cmd display get-displays not available on this device
+        }
+        // fallback: parse dumpsys display for display info (compatible with older Android versions)
+        try {
+            const dumpsys = this.adb("shell", "dumpsys", "display")
+                .toString();
+            // look for DisplayViewport entries with isActive=true and type=INTERNAL
+            const viewportMatch = dumpsys.match(/DisplayViewport\{type=INTERNAL[^}]*isActive=true[^}]*uniqueId='([^']+)'/);
+            if (viewportMatch) {
+                let uniqueId = viewportMatch[1];
+                if (uniqueId.startsWith("local:")) {
+                    uniqueId = uniqueId.substring("local:".length);
                 }
-                return displayId;
+                return uniqueId;
             }
+            // fallback: look for active display with state ON
+            const displayStateMatch = dumpsys.match(/Display Id=(\d+)[\s\S]*?Display State=ON/);
+            if (displayStateMatch) {
+                return displayStateMatch[1];
+            }
+        }
+        catch (error) {
+            // dumpsys display also failed
         }
         return null;
     }
@@ -229,6 +257,11 @@ class AndroidRobot {
         }
         // find the first display that is turned on, and capture that one
         const displayId = this.getFirstDisplayId();
+        if (displayId === null) {
+            // no idea why, but we have displayCount >= 2, yet we failed to parse
+            // let's go with screencap's defaults and hope for the best
+            return this.adb("exec-out", "screencap", "-p");
+        }
         return this.adb("exec-out", "screencap", "-p", "-d", `${displayId}`);
     }
     collectElements(node) {
@@ -273,6 +306,28 @@ class AndroidRobot {
     async terminateApp(packageName) {
         this.adb("shell", "am", "force-stop", packageName);
     }
+    async installApp(path) {
+        try {
+            this.adb("install", "-r", path);
+        }
+        catch (error) {
+            const stdout = error.stdout ? error.stdout.toString() : "";
+            const stderr = error.stderr ? error.stderr.toString() : "";
+            const output = (stdout + stderr).trim();
+            throw new robot_1.ActionableError(output || error.message);
+        }
+    }
+    async uninstallApp(bundleId) {
+        try {
+            this.adb("uninstall", bundleId);
+        }
+        catch (error) {
+            const stdout = error.stdout ? error.stdout.toString() : "";
+            const stderr = error.stderr ? error.stderr.toString() : "";
+            const output = (stdout + stderr).trim();
+            throw new robot_1.ActionableError(output || error.message);
+        }
+    }
     async openUrl(url) {
         this.adb("shell", "am", "start", "-a", "android.intent.action.VIEW", "-d", url);
     }
@@ -326,6 +381,11 @@ class AndroidRobot {
         // a long press is a swipe with no movement and a long duration
         this.adb("shell", "input", "swipe", `${x}`, `${y}`, `${x}`, `${y}`, "500");
     }
+    async doubleTap(x, y) {
+        await this.tap(x, y);
+        await new Promise(r => setTimeout(r, 100)); // short delay
+        await this.tap(x, y);
+    }
     async setOrientation(orientation) {
         const value = orientation === "portrait" ? 0 : 1;
         // disable auto-rotation prior to setting the orientation

package/lib/ios.js

@@ -101,6 +101,30 @@ class IosRobot {
         await this.assertTunnelRunning();
         await this.ios("kill", packageName);
     }
+    async installApp(path) {
+        await this.assertTunnelRunning();
+        try {
+            await this.ios("install", "--path", path);
+        }
+        catch (error) {
+            const stdout = error.stdout ? error.stdout.toString() : "";
+            const stderr = error.stderr ? error.stderr.toString() : "";
+            const output = (stdout + stderr).trim();
+            throw new robot_1.ActionableError(output || error.message);
+        }
+    }
+    async uninstallApp(bundleId) {
+        await this.assertTunnelRunning();
+        try {
+            await this.ios("uninstall", "--bundleid", bundleId);
+        }
+        catch (error) {
+            const stdout = error.stdout ? error.stdout.toString() : "";
+            const stderr = error.stderr ? error.stderr.toString() : "";
+            const output = (stdout + stderr).trim();
+            throw new robot_1.ActionableError(output || error.message);
+        }
+    }
     async openUrl(url) {
         const wda = await this.wda();
         await wda.openUrl(url);
@@ -117,6 +141,10 @@ class IosRobot {
         const wda = await this.wda();
         await wda.tap(x, y);
     }
+    async doubleTap(x, y) {
+        const wda = await this.wda();
+        await wda.doubleTap(x, y);
+    }
     async longPress(x, y) {
         const wda = await this.wda();
         await wda.longPress(x, y);

package/lib/iphone-simulator.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SimctlManager = exports.Simctl = void 0;
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
 const logger_1 = require("./logger");
 const webdriver_agent_1 = require("./webdriver-agent");
 const robot_1 = require("./robot");
@@ -73,6 +76,87 @@ class Simctl {
     async terminateApp(packageName) {
         this.simctl("terminate", this.simulatorUuid, packageName);
     }
+    findAppBundle(dir) {
+        const entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.endsWith(".app")) {
+                return (0, node_path_1.join)(dir, entry.name);
+            }
+        }
+        return null;
+    }
+    validateZipPaths(zipPath) {
+        const output = (0, node_child_process_1.execFileSync)("/usr/bin/zipinfo", ["-1", zipPath], {
+            timeout: TIMEOUT,
+            maxBuffer: MAX_BUFFER_SIZE,
+        }).toString();
+        const invalidPath = output
+            .split("\n")
+            .map(s => s.trim())
+            .filter(s => s)
+            .find(s => s.startsWith("/") || s.includes(".."));
+        if (invalidPath) {
+            throw new robot_1.ActionableError(`Security violation: File path '${invalidPath}' contains invalid characters`);
+        }
+    }
+    async installApp(path) {
+        let tempDir = null;
+        let installPath = path;
+        try {
+            // zip files need to be extracted prior to installation
+            if ((0, node_path_1.extname)(path).toLowerCase() === ".zip") {
+                (0, logger_1.trace)(`Detected .zip file, validating contents`);
+                // before extracting, let's make sure there's no zip-slip bombs here
+                this.validateZipPaths(path);
+                tempDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "ios-app-"));
+                try {
+                    (0, node_child_process_1.execFileSync)("unzip", ["-q", path, "-d", tempDir], {
+                        timeout: TIMEOUT,
+                    });
+                }
+                catch (error) {
+                    throw new robot_1.ActionableError(`Failed to unzip file: ${error.message}`);
+                }
+                const appBundle = this.findAppBundle(tempDir);
+                if (!appBundle) {
+                    throw new robot_1.ActionableError("No .app bundle found in the .zip file, please visit wiki at https://github.com/mobile-next/mobile-mcp/wiki for assistance.");
+                }
+                installPath = appBundle;
+                (0, logger_1.trace)(`Found .app bundle at: ${(0, node_path_1.basename)(appBundle)}`);
+            }
+            // continue with installation
+            this.simctl("install", this.simulatorUuid, installPath);
+        }
+        catch (error) {
+            const stdout = error.stdout ? error.stdout.toString() : "";
+            const stderr = error.stderr ? error.stderr.toString() : "";
+            const output = (stdout + stderr).trim();
+            throw new robot_1.ActionableError(output || error.message);
+        }
+        finally {
+            // Clean up temporary directory if it was created
+            if (tempDir) {
+                try {
+                    (0, logger_1.trace)(`Cleaning up temporary directory`);
+                    (0, node_fs_1.rmSync)(tempDir, { recursive: true, force: true });
+                }
+                catch (cleanupError) {
+                    (0, logger_1.trace)(`Warning: Failed to cleanup temporary directory: ${cleanupError}`);
+                }
+            }
+        }
+    }
+    async uninstallApp(bundleId) {
+        try {
+            this.simctl("uninstall", this.simulatorUuid, bundleId);
+        }
+        catch (error) {
+            const stdout = error.stdout ? error.stdout.toString() : "";
+            const stderr = error.stderr ? error.stderr.toString() : "";
+            const output = (stdout + stderr).trim();
+            throw new robot_1.ActionableError(output || error.message);
+        }
+    }
     async listApps() {
         const text = this.simctl("listapps", this.simulatorUuid).toString();
         const result = (0, node_child_process_1.execFileSync)("plutil", ["-convert", "json", "-o", "-", "-r", "-"], {
@@ -104,6 +188,10 @@ class Simctl {
         const wda = await this.wda();
         return wda.tap(x, y);
     }
+    async doubleTap(x, y) {
+        const wda = await this.wda();
+        await wda.doubleTap(x, y);
+    }
     async longPress(x, y) {
         const wda = await this.wda();
         return wda.longPress(x, y);

package/lib/server.js

@@ -34,8 +34,16 @@ const createMcpServer = () => {
     });
     // an empty object to satisfy windsurf
     const noParams = zod_1.z.object({});
-    // will be replaced later by 'initialize' jsonrpc request
-    let clientName = "unknown";
+    const getClientName = () => {
+        try {
+            const clientInfo = server.server.getClientVersion();
+            const clientName = clientInfo?.name || "unknown";
+            return clientName;
+        }
+        catch (error) {
+            return "unknown";
+        }
+    };
     const tool = (name, description, paramsSchema, cb) => {
         const wrappedCb = async (args) => {
             try {
@@ -76,8 +84,11 @@ const createMcpServer = () => {
                 Product: "mobile-mcp",
                 Version: (0, exports.getAgentVersion)(),
                 NodeVersion: process.version,
-                AgentName: clientName,
             };
+            const clientName = getClientName();
+            if (clientName !== "unknown") {
+                systemProps.AgentName = clientName;
+            }
             await fetch(url, {
                 method: "POST",
                 headers: {
@@ -98,20 +109,21 @@ const createMcpServer = () => {
             // ignore
         }
     };
-    const reportMobilecliVersion = async () => {
+    const getMobilecliVersion = () => {
         try {
             const path = (0, mobilecli_1.getMobilecliPath)();
             const output = (0, node_child_process_1.execFileSync)(path, ["--version"], { encoding: "utf8" }).toString().trim();
-            const version = output.startsWith("mobilecli version ")
-                ? output.split(" ").pop()
-                : output;
-            await posthog("mobilecli_check", { MobilecliVersion: version || output });
+            if (output.startsWith("mobilecli version ")) {
+                return output.substring("mobilecli version ".length);
+            }
+            return "failed";
         }
         catch (error) {
-            await posthog("mobilecli_check", { MobilecliVersion: "failed" });
+            return "failed " + error.message;
         }
     };
-    posthog("launch", {}).then();
+    const mobilecliVersion = getMobilecliVersion();
+    posthog("launch", { "MobilecliVersion": mobilecliVersion }).then();
     const simulatorManager = new iphone_simulator_1.SimctlManager();
     const getRobotFromDevice = (device) => {
         const iosManager = new ios_1.IosManager();
@@ -150,7 +162,7 @@ const createMcpServer = () => {
         const androidMobileDevices = androidDevices.filter(d => d.deviceType === "mobile").map(d => d.deviceId);
         const resp = ["Found these devices:"];
         if (simulatorNames.length > 0) {
-            resp.push(`iOS simulators: [${simulatorNames.join(".")}]`);
+            resp.push(`iOS simulators: [${simulatorNames.join(",")}]`);
         }
         if (iosDevices.length > 0) {
             resp.push(`iOS devices: [${iosDeviceNames.join(",")}]`);
@@ -186,6 +198,22 @@ const createMcpServer = () => {
         await robot.terminateApp(packageName);
         return `Terminated app ${packageName}`;
     });
+    tool("mobile_install_app", "Install an app on mobile device", {
+        device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
+        path: zod_1.z.string().describe("The path to the app file to install. For iOS simulators, provide a .zip file or a .app directory. For Android provide an .apk file. For iOS real devices provide an .ipa file"),
+    }, async ({ device, path }) => {
+        const robot = getRobotFromDevice(device);
+        await robot.installApp(path);
+        return `Installed app from ${path}`;
+    });
+    tool("mobile_uninstall_app", "Uninstall an app from mobile device", {
+        device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
+        bundle_id: zod_1.z.string().describe("Bundle identifier (iOS) or package name (Android) of the app to be uninstalled"),
+    }, async ({ device, bundle_id }) => {
+        const robot = getRobotFromDevice(device);
+        await robot.uninstallApp(bundle_id);
+        return `Uninstalled app ${bundle_id}`;
+    });
     tool("mobile_get_screen_size", "Get the screen size of the mobile device in pixels", {
         device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
     }, async ({ device }) => {
@@ -202,6 +230,15 @@ const createMcpServer = () => {
         await robot.tap(x, y);
         return `Clicked on screen at coordinates: ${x}, ${y}`;
     });
+    tool("mobile_double_tap_on_screen", "Double-tap on the screen at given x,y coordinates.", {
+        device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
+        x: zod_1.z.number().describe("The x coordinate to double-tap, in pixels"),
+        y: zod_1.z.number().describe("The y coordinate to double-tap, in pixels"),
+    }, async ({ device, x, y }) => {
+        const robot = getRobotFromDevice(device);
+        await robot.doubleTap(x, y);
+        return `Double-tapped on screen at coordinates: ${x}, ${y}`;
+    });
     tool("mobile_long_press_on_screen_at_coordinates", "Long press on the screen at given x,y coordinates. If long pressing on an element, use the list_elements_on_screen tool to find the coordinates.", {
         device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
         x: zod_1.z.number().describe("The x coordinate to long press on the screen, in pixels"),
@@ -349,28 +386,6 @@ const createMcpServer = () => {
         const orientation = await robot.getOrientation();
         return `Current device orientation is ${orientation}`;
     });
-    tool("mobile_test_mobilecli", "Test mobilecli integration and report status", {
-        noParams,
-    }, async () => {
-        const path = (0, mobilecli_1.getMobilecliPath)();
-        const output = (0, node_child_process_1.execFileSync)(path, ["devices"], { encoding: "utf8" }).toString().trim();
-        return `Here are the available devices: ${output}`;
-    });
-    // async report mobilecli version
-    reportMobilecliVersion().then();
-    const hook = server.connect;
-    server.connect = (transport) => {
-        transport.onmessage = (message) => {
-            if ("method" in message) {
-                const request = message;
-                if (request.method === "initialize") {
-                    const initialize = request;
-                    clientName = initialize.params.clientInfo.name || "unknown";
-                }
-            }
-        };
-        return hook.apply(server, [transport]);
-    };
     return server;
 };
 exports.createMcpServer = createMcpServer;

package/lib/webdriver-agent.js

@@ -142,6 +142,36 @@ class WebDriverAgent {
             });
         });
     }
+    async doubleTap(x, y) {
+        await this.withinSession(async (sessionUrl) => {
+            const url = `${sessionUrl}/actions`;
+            await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    actions: [
+                        {
+                            type: "pointer",
+                            id: "finger1",
+                            parameters: { pointerType: "touch" },
+                            actions: [
+                                { type: "pointerMove", duration: 0, x, y },
+                                { type: "pointerDown", button: 0 },
+                                { type: "pause", duration: 50 },
+                                { type: "pointerUp", button: 0 },
+                                { type: "pause", duration: 100 },
+                                { type: "pointerDown", button: 0 },
+                                { type: "pause", duration: 50 },
+                                { type: "pointerUp", button: 0 }
+                            ]
+                        }
+                    ]
+                }),
+            });
+        });
+    }
     async longPress(x, y) {
         await this.withinSession(async (sessionUrl) => {
             const url = `${sessionUrl}/actions`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mobilenext/mobile-mcp",
   "mcpName": "io.github.mobile-next/mobile-mcp",
-  "version": "0.0.31-beta",
+  "version": "0.0.32",
   "description": "Mobile MCP",
   "repository": {
     "type": "git",
@@ -28,8 +28,10 @@
     "commander": "14.0.0",
     "express": "5.1.0",
     "fast-xml-parser": "5.2.5",
-    "zod-to-json-schema": "3.24.6",
-    "@mobilenext/mobilecli": "0.0.25"
+    "zod-to-json-schema": "3.24.6"
+  },
+  "optionalDependencies": {
+    "@mobilenext/mobilecli": "0.0.28"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",