@mobilenext/mobile-mcp 0.0.29 → 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/mobilecli.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMobilecliPath = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const getMobilecliPath = () => {
+    if (process.env.MOBILECLI_PATH) {
+        return process.env.MOBILECLI_PATH;
+    }
+    const platform = process.platform;
+    let binaryName = "mobilecli";
+    switch (platform) {
+        case "darwin":
+            binaryName += "-darwin";
+            break;
+        case "linux":
+            const arch = process.arch;
+            if (arch === "arm64") {
+                binaryName += "-linux-arm64";
+            }
+            else {
+                binaryName += "-linux-amd64";
+            }
+            break;
+        case "win32":
+            binaryName += "-windows-amd64.exe";
+            break;
+        default:
+            throw new Error(`Unsupported platform: ${platform}`);
+    }
+    // Check if mobile-mcp is installed as a package
+    const currentPath = __filename;
+    const pathParts = currentPath.split(node_path_1.sep);
+    const lastNodeModulesIndex = pathParts.lastIndexOf("node_modules");
+    if (lastNodeModulesIndex !== -1) {
+        // We're inside node_modules, go to the last node_modules in the path
+        const nodeModulesParts = pathParts.slice(0, lastNodeModulesIndex + 1);
+        const lastNodeModulesPath = nodeModulesParts.join(node_path_1.sep);
+        const mobilecliPath = (0, node_path_1.join)(lastNodeModulesPath, "@mobilenext", "mobilecli", "bin", binaryName);
+        if ((0, node_fs_1.existsSync)(mobilecliPath)) {
+            return mobilecliPath;
+        }
+    }
+    // Not in node_modules, look one directory up from current script
+    const scriptDir = (0, node_path_1.dirname)(__filename);
+    const parentDir = (0, node_path_1.dirname)(scriptDir);
+    const mobilecliPath = (0, node_path_1.join)(parentDir, "node_modules", "@mobilenext", "mobilecli", "bin", binaryName);
+    if ((0, node_fs_1.existsSync)(mobilecliPath)) {
+        return mobilecliPath;
+    }
+    throw new Error(`Could not find mobilecli binary for platform: ${platform}`);
+};
+exports.getMobilecliPath = getMobilecliPath;

package/lib/server.js

@@ -9,6 +9,7 @@ const zod_1 = require("zod");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_child_process_1 = require("node:child_process");
 const logger_1 = require("./logger");
 const android_1 = require("./android");
 const robot_1 = require("./robot");
@@ -16,28 +17,12 @@ const iphone_simulator_1 = require("./iphone-simulator");
 const ios_1 = require("./ios");
 const png_1 = require("./png");
 const image_utils_1 = require("./image-utils");
+const mobilecli_1 = require("./mobilecli");
 const getAgentVersion = () => {
     const json = require("../package.json");
     return json.version;
 };
 exports.getAgentVersion = getAgentVersion;
-const getLatestAgentVersion = async () => {
-    const response = await fetch("https://api.github.com/repos/mobile-next/mobile-mcp/tags?per_page=1");
-    const json = await response.json();
-    return json[0].name;
-};
-const checkForLatestAgentVersion = async () => {
-    try {
-        const latestVersion = await getLatestAgentVersion();
-        const currentVersion = (0, exports.getAgentVersion)();
-        if (latestVersion !== currentVersion) {
-            (0, logger_1.trace)(`You are running an older version of the agent. Please update to the latest version: ${latestVersion}.`);
-        }
-    }
-    catch (error) {
-        // ignore
-    }
-};
 const createMcpServer = () => {
     const server = new mcp_js_1.McpServer({
         name: "mobile-mcp",
@@ -110,7 +95,21 @@ const createMcpServer = () => {
             // ignore
         }
     };
-    posthog("launch", {}).then();
+    const getMobilecliVersion = () => {
+        try {
+            const path = (0, mobilecli_1.getMobilecliPath)();
+            const output = (0, node_child_process_1.execFileSync)(path, ["--version"], { encoding: "utf8" }).toString().trim();
+            if (output.startsWith("mobilecli version ")) {
+                return output.substring("mobilecli version ".length);
+            }
+            return "failed";
+        }
+        catch (error) {
+            return "failed " + error.message;
+        }
+    };
+    const mobilecliVersion = getMobilecliVersion();
+    posthog("launch", { "MobilecliVersion": mobilecliVersion }).then();
     const simulatorManager = new iphone_simulator_1.SimctlManager();
     const getRobotFromDevice = (device) => {
         const iosManager = new ios_1.IosManager();
@@ -185,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 }) => {
@@ -348,8 +363,6 @@ const createMcpServer = () => {
         const orientation = await robot.getOrientation();
         return `Current device orientation is ${orientation}`;
     });
-    // async check for latest agent version
-    checkForLatestAgentVersion().then();
     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.29",
+  "version": "0.0.30",
   "description": "Mobile MCP",
   "repository": {
     "type": "git",
@@ -30,6 +30,9 @@
     "fast-xml-parser": "5.2.5",
     "zod-to-json-schema": "3.24.6"
   },
+  "optionalDependencies": {
+    "@mobilenext/mobilecli": "0.0.27"
+  },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",