@mobilenext/mobile-mcp 0.0.19 → 0.0.20

package/README.md

@@ -175,7 +175,7 @@ What you will need to connect MCP with your agent and mobile devices:
 
 - [Xcode command line tools](https://developer.apple.com/xcode/resources/)
 - [Android Platform Tools](https://developer.android.com/tools/releases/platform-tools)
-- [node.js](https://nodejs.org/en/download/)
+- [node.js](https://nodejs.org/en/download/) v22+
 - [MCP](https://modelcontextprotocol.io/introduction) supported foundational models or agents, like [Claude MCP](https://modelcontextprotocol.io/quickstart/server), [OpenAI Agent SDK](https://openai.github.io/openai-agents-python/mcp/), [Copilot Studio](https://www.microsoft.com/en-us/microsoft-copilot/blog/copilot-studio/introducing-model-context-protocol-mcp-in-copilot-studio-simplified-integration-with-ai-apps-and-agents/)
 
 ### Simulators, Emulators, and Physical Devices

package/lib/android.js

@@ -94,6 +94,7 @@ class AndroidRobot {
         return { width, height, scale };
     }
     async listApps() {
+        // only apps that have a launcher activity are returned
         return this.adb("shell", "cmd", "package", "query-activities", "-a", "android.intent.action.MAIN", "-c", "android.intent.category.LAUNCHER")
             .toString()
             .split("\n")
@@ -106,6 +107,13 @@ class AndroidRobot {
             appName: packageName,
         }));
     }
+    async listPackages() {
+        return this.adb("shell", "pm", "list", "packages")
+            .toString()
+            .split("\n")
+            .filter(line => line.startsWith("package:"))
+            .map(line => line.substring("package:".length));
+    }
     async launchApp(packageName) {
         this.adb("shell", "monkey", "-p", packageName, "-c", "android.intent.category.LAUNCHER", "1");
     }
@@ -229,10 +237,37 @@ class AndroidRobot {
     async openUrl(url) {
         this.adb("shell", "am", "start", "-a", "android.intent.action.VIEW", "-d", url);
     }
+    isAscii(text) {
+        return /^[\x00-\x7F]*$/.test(text);
+    }
+    async isDeviceKitInstalled() {
+        const packages = await this.listPackages();
+        return packages.includes("com.mobilenext.devicekit");
+    }
     async sendKeys(text) {
-        // adb shell requires some escaping
-        const _text = text.replace(/ /g, "\\ ");
-        this.adb("shell", "input", "text", _text);
+        if (text === "") {
+            // bailing early, so we don't run adb shell with empty string.
+            // this happens when you prompt with a simple "submit".
+            return;
+        }
+        if (this.isAscii(text)) {
+            // adb shell input only supports ascii characters. and
+            // some of the keys have to be escaped.
+            const _text = text.replace(/ /g, "\\ ");
+            this.adb("shell", "input", "text", _text);
+        }
+        else if (await this.isDeviceKitInstalled()) {
+            // try sending over clipboard
+            const base64 = Buffer.from(text).toString("base64");
+            // send clipboard over and immediately paste it
+            this.adb("shell", "am", "broadcast", "-a", "devicekit.clipboard.set", "-e", "encoding", "base64", "-e", "text", base64, "-n", "com.mobilenext.devicekit/.ClipboardBroadcastReceiver");
+            this.adb("shell", "input", "keyevent", "KEYCODE_PASTE");
+            // clear clipboard when we're done
+            this.adb("shell", "am", "broadcast", "-a", "devicekit.clipboard.clear", "-n", "com.mobilenext.devicekit/.ClipboardBroadcastReceiver");
+        }
+        else {
+            throw new robot_1.ActionableError("Non-ASCII text is not supported on Android, please install mobilenext devicekit, see https://github.com/mobile-next/devicekit-android");
+        }
     }
     async pressButton(button) {
         if (!BUTTON_MAP[button]) {
@@ -245,8 +280,9 @@ class AndroidRobot {
     }
     async setOrientation(orientation) {
         const orientationValue = orientation === "portrait" ? 0 : 1;
-        this.adb("shell", "content", "insert", "--uri", "content://settings/system", "--bind", "name:s:user_rotation", "--bind", `value:i:${orientationValue}`);
+        // disable auto-rotation prior to setting the orientation
         this.adb("shell", "settings", "put", "system", "accelerometer_rotation", "0");
+        this.adb("shell", "content", "insert", "--uri", "content://settings/system", "--bind", "name:s:user_rotation", "--bind", `value:i:${orientationValue}`);
     }
     async getOrientation() {
         const rotation = this.adb("shell", "settings", "get", "system", "user_rotation").toString().trim();

package/lib/ios.js

@@ -1,13 +1,6 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IosManager = exports.IosRobot = void 0;
-const path_1 = __importDefault(require("path"));
-const os_1 = require("os");
-const crypto_1 = require("crypto");
-const fs_1 = require("fs");
 const child_process_1 = require("child_process");
 const net_1 = require("net");
 const webdriver_agent_1 = require("./webdriver-agent");
@@ -129,12 +122,16 @@ class IosRobot {
         return await wda.getElementsOnScreen();
     }
     async getScreenshot() {
+        const wda = await this.wda();
+        return await wda.getScreenshot();
+        /* alternative:
         await this.assertTunnelRunning();
-        const tmpFilename = path_1.default.join((0, os_1.tmpdir)(), `screenshot-${(0, crypto_1.randomBytes)(8).toString("hex")}.png`);
+        const tmpFilename = path.join(tmpdir(), `screenshot-${randomBytes(8).toString("hex")}.png`);
         await this.ios("screenshot", "--output", tmpFilename);
-        const buffer = (0, fs_1.readFileSync)(tmpFilename);
-        (0, fs_1.unlinkSync)(tmpFilename);
+        const buffer = readFileSync(tmpFilename);
+        unlinkSync(tmpFilename);
         return buffer;
+        */
     }
     async setOrientation(orientation) {
         const wda = await this.wda();
@@ -157,23 +154,23 @@ class IosManager {
             return false;
         }
     }
-    async getDeviceName(deviceId) {
+    getDeviceName(deviceId) {
         const output = (0, child_process_1.execFileSync)(getGoIosPath(), ["info", "--udid", deviceId]).toString();
         const json = JSON.parse(output);
         return json.DeviceName;
     }
-    async listDevices() {
-        if (!(await this.isGoIosInstalled())) {
+    listDevices() {
+        if (!this.isGoIosInstalled()) {
             console.error("go-ios is not installed, no physical iOS devices can be detected");
             return [];
         }
         const output = (0, child_process_1.execFileSync)(getGoIosPath(), ["list"]).toString();
         const json = JSON.parse(output);
-        const devices = json.deviceList.map(async (device) => ({
+        const devices = json.deviceList.map(device => ({
             deviceId: device,
-            deviceName: await this.getDeviceName(device),
+            deviceName: this.getDeviceName(device),
         }));
-        return Promise.all(devices);
+        return devices;
     }
 }
 exports.IosManager = IosManager;

package/lib/iphone-simulator.js

@@ -26,7 +26,9 @@ class Simctl {
         });
     }
     async getScreenshot() {
-        return this.simctl("io", this.simulatorUuid, "screenshot", "-");
+        const wda = await this.wda();
+        return await wda.getScreenshot();
+        // alternative: return this.simctl("io", this.simulatorUuid, "screenshot", "-");
     }
     async openUrl(url) {
         const wda = await this.wda();

package/lib/server.js

@@ -1,8 +1,13 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMcpServer = exports.getAgentVersion = void 0;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const zod_1 = require("zod");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
 const logger_1 = require("./logger");
 const android_1 = require("./android");
 const robot_1 = require("./robot");
@@ -41,6 +46,7 @@ const createMcpServer = () => {
             tools: {},
         },
     });
+    // an empty object to satisfy windsurf
     const noParams = zod_1.z.object({});
     const tool = (name, description, paramsSchema, cb) => {
         const wrappedCb = async (args) => {
@@ -70,6 +76,27 @@ const createMcpServer = () => {
         };
         server.tool(name, description, paramsSchema, args => wrappedCb(args));
     };
+    const posthog = (event, properties) => {
+        const url = "https://us.i.posthog.com/i/v0/e/";
+        const api_key = "phc_KHRTZmkDsU7A8EbydEK8s4lJpPoTDyyBhSlwer694cS";
+        const distinct_id = node_crypto_1.default.createHash("sha256").update(process.execPath).digest("hex");
+        fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                api_key,
+                event,
+                properties,
+                distinct_id,
+            })
+        }).then().catch();
+    };
+    posthog("launch", {
+        Product: "mobile-mcp",
+        Version: (0, exports.getAgentVersion)(),
+    });
     let robot;
     const simulatorManager = new iphone_simulator_1.SimctlManager();
     const requireRobot = () => {
@@ -77,13 +104,44 @@ const createMcpServer = () => {
             throw new robot_1.ActionableError("No device selected. Use the mobile_use_device tool to select a device.");
         }
     };
+    tool("mobile_use_default_device", "Use the default device. This is a shortcut for mobile_use_device with deviceType=simulator and device=simulator_name", {
+        noParams
+    }, async () => {
+        const iosManager = new ios_1.IosManager();
+        const androidManager = new android_1.AndroidDeviceManager();
+        const simulators = simulatorManager.listBootedSimulators();
+        const androidDevices = androidManager.getConnectedDevices();
+        const iosDevices = iosManager.listDevices();
+        const sum = simulators.length + androidDevices.length + iosDevices.length;
+        if (sum === 0) {
+            throw new robot_1.ActionableError("No devices found. Please connect a device and try again.");
+        }
+        else if (sum >= 2) {
+            throw new robot_1.ActionableError("Multiple devices found. Please use the mobile_list_available_devices tool to list available devices and select one.");
+        }
+        // only one device connected, let's find it now
+        if (simulators.length === 1) {
+            robot = simulatorManager.getSimulator(simulators[0].name);
+            return `Selected default device: ${simulators[0].name}`;
+        }
+        else if (androidDevices.length === 1) {
+            robot = new android_1.AndroidRobot(androidDevices[0].deviceId);
+            return `Selected default device: ${androidDevices[0].deviceId}`;
+        }
+        else if (iosDevices.length === 1) {
+            robot = new ios_1.IosRobot(iosDevices[0].deviceId);
+            return `Selected default device: ${iosDevices[0].deviceId}`;
+        }
+        // how did this happen?
+        throw new robot_1.ActionableError("No device selected. Please use the mobile_list_available_devices tool to list available devices and select one.");
+    });
     tool("mobile_list_available_devices", "List all available devices. This includes both physical devices and simulators. If there is more than one device returned, you need to let the user select one of them.", {
         noParams
     }, async ({}) => {
         const iosManager = new ios_1.IosManager();
         const androidManager = new android_1.AndroidDeviceManager();
-        const devices = simulatorManager.listBootedSimulators();
-        const simulatorNames = devices.map(d => d.name);
+        const simulators = simulatorManager.listBootedSimulators();
+        const simulatorNames = simulators.map(d => d.name);
         const androidDevices = androidManager.getConnectedDevices();
         const iosDevices = await iosManager.listDevices();
         const iosDeviceNames = iosDevices.map(d => d.deviceId);
@@ -149,7 +207,7 @@ const createMcpServer = () => {
         const screenSize = await robot.getScreenSize();
         return `Screen size is ${screenSize.width}x${screenSize.height} pixels`;
     });
-    tool("mobile_click_on_screen_at_coordinates", "Click on the screen at given x,y coordinates", {
+    tool("mobile_click_on_screen_at_coordinates", "Click on the screen at given x,y coordinates. If clicking on an element, use the list_elements_on_screen tool to find the coordinates.", {
         x: zod_1.z.number().describe("The x coordinate to click on the screen, in pixels"),
         y: zod_1.z.number().describe("The y coordinate to click on the screen, in pixels"),
     }, async ({ x, y }) => {
@@ -228,6 +286,14 @@ const createMcpServer = () => {
         }
         return `Typed text: ${text}`;
     });
+    tool("mobile_save_screenshot", "Save a screenshot of the mobile device to a file", {
+        saveTo: zod_1.z.string().describe("The path to save the screenshot to"),
+    }, async ({ saveTo }) => {
+        requireRobot();
+        const screenshot = await robot.getScreenshot();
+        node_fs_1.default.writeFileSync(saveTo, screenshot);
+        return `Screenshot saved to: ${saveTo}`;
+    });
     server.tool("mobile_take_screenshot", "Take a screenshot of the mobile device. Use this to understand what's on screen, if you need to press an element that is available through view hierarchy then you must list elements on screen instead. Do not cache this result.", {
         noParams
     }, async ({}) => {

package/lib/webdriver-agent.js

@@ -191,6 +191,12 @@ class WebDriverAgent {
             });
         });
     }
+    async getScreenshot() {
+        const url = `http://${this.host}:${this.port}/screenshot`;
+        const response = await fetch(url);
+        const json = await response.json();
+        return Buffer.from(json.value, "base64");
+    }
     async swipe(direction) {
         await this.withinSession(async (sessionUrl) => {
             const screenSize = await this.getScreenSize(sessionUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobilenext/mobile-mcp",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Mobile MCP",
   "repository": {
     "type": "git",