@mobilenext/mobile-mcp 0.0.19 → 0.0.21

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

@@ -37,14 +37,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AndroidDeviceManager = exports.AndroidRobot = void 0;
-const path_1 = __importDefault(require("path"));
-const child_process_1 = require("child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
 const xml = __importStar(require("fast-xml-parser"));
 const robot_1 = require("./robot");
 const getAdbPath = () => {
     let executable = "adb";
     if (process.env.ANDROID_HOME) {
-        executable = path_1.default.join(process.env.ANDROID_HOME, "platform-tools", "adb");
+        executable = node_path_1.default.join(process.env.ANDROID_HOME, "platform-tools", "adb");
     }
     return executable;
 };
@@ -68,7 +68,7 @@ class AndroidRobot {
         this.deviceId = deviceId;
     }
     adb(...args) {
-        return (0, child_process_1.execFileSync)(getAdbPath(), ["-s", this.deviceId, ...args], {
+        return (0, node_child_process_1.execFileSync)(getAdbPath(), ["-s", this.deviceId, ...args], {
             maxBuffer: MAX_BUFFER_SIZE,
             timeout: TIMEOUT,
         });
@@ -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,14 @@ class AndroidRobot {
             appName: packageName,
         }));
     }
+    async listPackages() {
+        return this.adb("shell", "pm", "list", "packages")
+            .toString()
+            .split("\n")
+            .map(line => line.trim())
+            .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 +238,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 +281,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();
@@ -297,11 +334,12 @@ class AndroidDeviceManager {
     }
     getConnectedDevices() {
         try {
-            const names = (0, child_process_1.execFileSync)(getAdbPath(), ["devices"])
+            const names = (0, node_child_process_1.execFileSync)(getAdbPath(), ["devices"])
                 .toString()
                 .split("\n")
+                .map(line => line.trim())
+                .filter(line => line !== "")
                 .filter(line => !line.startsWith("List of devices attached"))
-                .filter(line => line.trim() !== "")
                 .map(line => line.split("\t")[0]);
             return names.map(name => ({
                 deviceId: name,

package/lib/ios.js

@@ -1,15 +1,8 @@
 "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 node_net_1 = require("node:net");
+const node_child_process_1 = require("node:child_process");
 const webdriver_agent_1 = require("./webdriver-agent");
 const robot_1 = require("./robot");
 const WDA_PORT = 8100;
@@ -28,7 +21,7 @@ class IosRobot {
     }
     isListeningOnPort(port) {
         return new Promise((resolve, reject) => {
-            const client = new net_1.Socket();
+            const client = new node_net_1.Socket();
             client.connect(port, "localhost", () => {
                 client.destroy();
                 resolve(true);
@@ -63,7 +56,7 @@ class IosRobot {
         return wda;
     }
     async ios(...args) {
-        return (0, child_process_1.execFileSync)(getGoIosPath(), ["--udid", this.deviceId, ...args], {}).toString();
+        return (0, node_child_process_1.execFileSync)(getGoIosPath(), ["--udid", this.deviceId, ...args], {}).toString();
     }
     async getIosVersion() {
         const output = await this.ios("info");
@@ -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();
@@ -149,7 +146,7 @@ exports.IosRobot = IosRobot;
 class IosManager {
     async isGoIosInstalled() {
         try {
-            const output = (0, child_process_1.execFileSync)(getGoIosPath(), ["version"], { stdio: ["pipe", "pipe", "ignore"] }).toString();
+            const output = (0, node_child_process_1.execFileSync)(getGoIosPath(), ["version"], { stdio: ["pipe", "pipe", "ignore"] }).toString();
             const json = JSON.parse(output);
             return json.version !== undefined && (json.version.startsWith("v") || json.version === "local-build");
         }
@@ -157,23 +154,23 @@ class IosManager {
             return false;
         }
     }
-    async getDeviceName(deviceId) {
-        const output = (0, child_process_1.execFileSync)(getGoIosPath(), ["info", "--udid", deviceId]).toString();
+    getDeviceName(deviceId) {
+        const output = (0, node_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 output = (0, node_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

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SimctlManager = exports.Simctl = void 0;
-const child_process_1 = require("child_process");
+const node_child_process_1 = require("node:child_process");
+const logger_1 = require("./logger");
 const webdriver_agent_1 = require("./webdriver-agent");
 const robot_1 = require("./robot");
 const TIMEOUT = 30000;
@@ -12,21 +13,54 @@ class Simctl {
     constructor(simulatorUuid) {
         this.simulatorUuid = simulatorUuid;
     }
+    async isWdaInstalled() {
+        const apps = await this.listApps();
+        return apps.map(app => app.packageName).includes("com.facebook.WebDriverAgentRunner.xctrunner");
+    }
+    async startWda() {
+        if (!(await this.isWdaInstalled())) {
+            // wda is not even installed, won't attempt to start it
+            return;
+        }
+        (0, logger_1.trace)("Starting WebDriverAgent");
+        const webdriverPackageName = "com.facebook.WebDriverAgentRunner.xctrunner";
+        this.simctl("launch", this.simulatorUuid, webdriverPackageName);
+        // now we wait for wda to have a successful status
+        const wda = new webdriver_agent_1.WebDriverAgent("localhost", WDA_PORT);
+        // wait up to 10 seconds for wda to start
+        const timeout = +new Date() + 10 * 1000;
+        while (+new Date() < timeout) {
+            // cross fingers and see if wda is already running
+            if (await wda.isRunning()) {
+                (0, logger_1.trace)("WebDriverAgent is now running");
+                return;
+            }
+            // wait 100ms before trying again
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        (0, logger_1.trace)("Could not start WebDriverAgent in time, giving up");
+    }
     async wda() {
         const wda = new webdriver_agent_1.WebDriverAgent("localhost", WDA_PORT);
         if (!(await wda.isRunning())) {
-            throw new robot_1.ActionableError("WebDriverAgent is not running on simulator, please see https://github.com/mobile-next/mobile-mcp/wiki/");
+            await this.startWda();
+            if (!(await wda.isRunning())) {
+                throw new robot_1.ActionableError("WebDriverAgent is not running on simulator, please see https://github.com/mobile-next/mobile-mcp/wiki/");
+            }
+            // was successfully started
         }
         return wda;
     }
     simctl(...args) {
-        return (0, child_process_1.execFileSync)("xcrun", ["simctl", ...args], {
+        return (0, node_child_process_1.execFileSync)("xcrun", ["simctl", ...args], {
             timeout: TIMEOUT,
             maxBuffer: MAX_BUFFER_SIZE,
         });
     }
     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();
@@ -41,7 +75,7 @@ class Simctl {
     }
     async listApps() {
         const text = this.simctl("listapps", this.simulatorUuid).toString();
-        const result = (0, child_process_1.execFileSync)("plutil", ["-convert", "json", "-o", "-", "-r", "-"], {
+        const result = (0, node_child_process_1.execFileSync)("plutil", ["-convert", "json", "-o", "-", "-r", "-"], {
             input: text,
         });
         const output = JSON.parse(result.toString());
@@ -96,7 +130,7 @@ class SimctlManager {
             return [];
         }
         try {
-            const text = (0, child_process_1.execFileSync)("xcrun", ["simctl", "list", "devices", "-j"]).toString();
+            const text = (0, node_child_process_1.execFileSync)("xcrun", ["simctl", "list", "devices", "-j"]).toString();
             const json = JSON.parse(text);
             return Object.values(json.devices).flatMap(device => {
                 return device.map(d => {

package/lib/logger.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.error = exports.trace = void 0;
-const fs_1 = require("fs");
+const node_fs_1 = require("node:fs");
 const writeLog = (message) => {
     if (process.env.LOG_FILE) {
         const logfile = process.env.LOG_FILE;
         const timestamp = new Date().toISOString();
         const levelStr = "INFO";
         const logMessage = `[${timestamp}] ${levelStr} ${message}`;
-        (0, fs_1.appendFileSync)(logfile, logMessage + "\n");
+        (0, node_fs_1.appendFileSync)(logfile, logMessage + "\n");
     }
     console.error(message);
 };

package/lib/server.js

@@ -1,8 +1,14 @@
 "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_os_1 = __importDefault(require("node:os"));
+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 +47,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) => {
@@ -48,6 +55,7 @@ const createMcpServer = () => {
                 (0, logger_1.trace)(`Invoking ${name} with args: ${JSON.stringify(args)}`);
                 const response = await cb(args);
                 (0, logger_1.trace)(`=> ${response}`);
+                posthog("tool_invoked", {}).then();
                 return {
                     content: [{ type: "text", text: response }],
                 };
@@ -70,6 +78,39 @@ const createMcpServer = () => {
         };
         server.tool(name, description, paramsSchema, args => wrappedCb(args));
     };
+    const posthog = async (event, properties) => {
+        try {
+            const url = "https://us.i.posthog.com/i/v0/e/";
+            const api_key = "phc_KHRTZmkDsU7A8EbydEK8s4lJpPoTDyyBhSlwer694cS";
+            const name = node_os_1.default.hostname() + process.execPath;
+            const distinct_id = node_crypto_1.default.createHash("sha256").update(name).digest("hex");
+            const systemProps = {
+                Platform: node_os_1.default.platform(),
+                Product: "mobile-mcp",
+                Version: (0, exports.getAgentVersion)(),
+                NodeVersion: process.version,
+            };
+            await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json"
+                },
+                body: JSON.stringify({
+                    api_key,
+                    event,
+                    properties: {
+                        ...systemProps,
+                        ...properties,
+                    },
+                    distinct_id,
+                })
+            });
+        }
+        catch (err) {
+            // ignore
+        }
+    };
+    posthog("launch", {}).then();
     let robot;
     const simulatorManager = new iphone_simulator_1.SimctlManager();
     const requireRobot = () => {
@@ -77,13 +118,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 +221,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 +300,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

@@ -13,10 +13,11 @@ class WebDriverAgent {
         const url = `http://${this.host}:${this.port}/status`;
         try {
             const response = await fetch(url);
-            return response.status === 200;
+            const json = await response.json();
+            return response.status === 200 && json.value?.ready === true;
         }
         catch (error) {
-            console.error(`Failed to connect to WebDriverAgent: ${error}`);
+            // console.error(`Failed to connect to WebDriverAgent: ${error}`);
             return false;
         }
     }
@@ -191,6 +192,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.21",
   "description": "Mobile MCP",
   "repository": {
     "type": "git",
@@ -23,8 +23,6 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.6.1",
-    "@types/commander": "^2.12.0",
-    "@types/express": "^5.0.3",
     "commander": "^14.0.0",
     "express": "^5.1.0",
     "fast-xml-parser": "^5.0.9",
@@ -34,6 +32,8 @@
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",
     "@stylistic/eslint-plugin": "^3.0.1",
+    "@types/commander": "^2.12.0",
+    "@types/express": "^5.0.3",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.13.10",
     "@typescript-eslint/eslint-plugin": "^8.28.0",