@mobilenext/mobile-mcp 0.0.30-beta → 0.0.30

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

@@ -273,6 +273,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);
     }

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);

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", "-"], {

package/lib/server.js

@@ -34,8 +34,6 @@ 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 tool = (name, description, paramsSchema, cb) => {
         const wrappedCb = async (args) => {
             try {
@@ -76,7 +74,6 @@ const createMcpServer = () => {
                 Product: "mobile-mcp",
                 Version: (0, exports.getAgentVersion)(),
                 NodeVersion: process.version,
-                AgentName: clientName,
             };
             await fetch(url, {
                 method: "POST",
@@ -98,20 +95,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();
@@ -186,6 +184,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 }) => {
@@ -349,21 +363,6 @@ const createMcpServer = () => {
         const orientation = await robot.getOrientation();
         return `Current device orientation is ${orientation}`;
     });
-    // 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mobilenext/mobile-mcp",
   "mcpName": "io.github.mobile-next/mobile-mcp",
-  "version": "0.0.30-beta",
+  "version": "0.0.30",
   "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.27"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",