@nbakka/mcp-appium 1.0.27 → 2.0.0

package/lib/ios.js

@@ -0,0 +1,175 @@
+"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");
+const robot_1 = require("./robot");
+const WDA_PORT = 8100;
+const IOS_TUNNEL_PORT = 60105;
+const getGoIosPath = () => {
+    if (process.env.GO_IOS_PATH) {
+        return process.env.GO_IOS_PATH;
+    }
+    // fallback to go-ios in PATH via `npm install -g go-ios`
+    return "ios";
+};
+class IosRobot {
+    deviceId;
+    constructor(deviceId) {
+        this.deviceId = deviceId;
+    }
+    isListeningOnPort(port) {
+        return new Promise((resolve, reject) => {
+            const client = new net_1.Socket();
+            client.connect(port, "localhost", () => {
+                client.destroy();
+                resolve(true);
+            });
+            client.on("error", (err) => {
+                resolve(false);
+            });
+        });
+    }
+    async isTunnelRunning() {
+        return await this.isListeningOnPort(IOS_TUNNEL_PORT);
+    }
+    async isWdaForwardRunning() {
+        return await this.isListeningOnPort(WDA_PORT);
+    }
+    async assertTunnelRunning() {
+        if (await this.isTunnelRequired()) {
+            if (!(await this.isTunnelRunning())) {
+                throw new robot_1.ActionableError("iOS tunnel is not running, please see https://github.com/mobile-next/mobile-mcp/wiki/");
+            }
+        }
+    }
+    async wda() {
+        await this.assertTunnelRunning();
+        if (!(await this.isWdaForwardRunning())) {
+            throw new robot_1.ActionableError("Port forwarding to WebDriverAgent is not running (tunnel okay), please see https://github.com/mobile-next/mobile-mcp/wiki/");
+        }
+        const wda = new webdriver_agent_1.WebDriverAgent("localhost", WDA_PORT);
+        if (!(await wda.isRunning())) {
+            throw new robot_1.ActionableError("WebDriverAgent is not running on device (tunnel okay, port forwarding okay), please see https://github.com/mobile-next/mobile-mcp/wiki/");
+        }
+        return wda;
+    }
+    async ios(...args) {
+        return (0, child_process_1.execFileSync)(getGoIosPath(), ["--udid", this.deviceId, ...args], {}).toString();
+    }
+    async getIosVersion() {
+        const output = await this.ios("info");
+        const json = JSON.parse(output);
+        return json.ProductVersion;
+    }
+    async isTunnelRequired() {
+        const version = await this.getIosVersion();
+        const args = version.split(".");
+        return parseInt(args[0], 10) >= 17;
+    }
+    async getScreenSize() {
+        const wda = await this.wda();
+        return await wda.getScreenSize();
+    }
+    async swipe(direction) {
+        const wda = await this.wda();
+        await wda.swipe(direction);
+    }
+    async listApps() {
+        await this.assertTunnelRunning();
+        const output = await this.ios("apps", "--all", "--list");
+        return output
+            .split("\n")
+            .map(line => {
+            const [packageName, appName] = line.split(" ");
+            return {
+                packageName,
+                appName,
+            };
+        });
+    }
+    async launchApp(packageName) {
+        await this.assertTunnelRunning();
+        await this.ios("launch", packageName);
+    }
+    async terminateApp(packageName) {
+        await this.assertTunnelRunning();
+        await this.ios("kill", packageName);
+    }
+    async openUrl(url) {
+        const wda = await this.wda();
+        await wda.openUrl(url);
+    }
+    async sendKeys(text) {
+        const wda = await this.wda();
+        await wda.sendKeys(text);
+    }
+    async pressButton(button) {
+        const wda = await this.wda();
+        await wda.pressButton(button);
+    }
+    async tap(x, y) {
+        const wda = await this.wda();
+        await wda.tap(x, y);
+    }
+    async getElementsOnScreen() {
+        const wda = await this.wda();
+        return await wda.getElementsOnScreen();
+    }
+    async getScreenshot() {
+        await this.assertTunnelRunning();
+        const tmpFilename = path_1.default.join((0, os_1.tmpdir)(), `screenshot-${(0, crypto_1.randomBytes)(8).toString("hex")}.png`);
+        await this.ios("screenshot", "--output", tmpFilename);
+        const buffer = (0, fs_1.readFileSync)(tmpFilename);
+        (0, fs_1.unlinkSync)(tmpFilename);
+        return buffer;
+    }
+    async setOrientation(orientation) {
+        const wda = await this.wda();
+        await wda.setOrientation(orientation);
+    }
+    async getOrientation() {
+        const wda = await this.wda();
+        return await wda.getOrientation();
+    }
+}
+exports.IosRobot = IosRobot;
+class IosManager {
+    async isGoIosInstalled() {
+        try {
+            const output = (0, 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");
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    async 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())) {
+            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) => ({
+            deviceId: device,
+            deviceName: await this.getDeviceName(device),
+        }));
+        return Promise.all(devices);
+    }
+}
+exports.IosManager = IosManager;

package/lib/iphone-simulator.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimctlManager = exports.Simctl = void 0;
+const child_process_1 = require("child_process");
+const webdriver_agent_1 = require("./webdriver-agent");
+const robot_1 = require("./robot");
+const TIMEOUT = 30000;
+const WDA_PORT = 8100;
+const MAX_BUFFER_SIZE = 1024 * 1024 * 4;
+class Simctl {
+    simulatorUuid;
+    constructor(simulatorUuid) {
+        this.simulatorUuid = simulatorUuid;
+    }
+    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/");
+        }
+        return wda;
+    }
+    simctl(...args) {
+        return (0, child_process_1.execFileSync)("xcrun", ["simctl", ...args], {
+            timeout: TIMEOUT,
+            maxBuffer: MAX_BUFFER_SIZE,
+        });
+    }
+    async getScreenshot() {
+        return this.simctl("io", this.simulatorUuid, "screenshot", "-");
+    }
+    async openUrl(url) {
+        const wda = await this.wda();
+        await wda.openUrl(url);
+        // alternative: this.simctl("openurl", this.simulatorUuid, url);
+    }
+    async launchApp(packageName) {
+        this.simctl("launch", this.simulatorUuid, packageName);
+    }
+    async terminateApp(packageName) {
+        this.simctl("terminate", this.simulatorUuid, packageName);
+    }
+    static parseIOSAppData(inputText) {
+        const result = [];
+        let ParseState;
+        (function (ParseState) {
+            ParseState[ParseState["LOOKING_FOR_APP"] = 0] = "LOOKING_FOR_APP";
+            ParseState[ParseState["IN_APP"] = 1] = "IN_APP";
+            ParseState[ParseState["IN_PROPERTY"] = 2] = "IN_PROPERTY";
+        })(ParseState || (ParseState = {}));
+        let state = ParseState.LOOKING_FOR_APP;
+        let currentApp = {};
+        let appIdentifier = "";
+        const lines = inputText.split("\n");
+        for (let line of lines) {
+            line = line.trim();
+            if (line === "") {
+                continue;
+            }
+            switch (state) {
+                case ParseState.LOOKING_FOR_APP:
+                    // look for app identifier pattern: "com.example.app" = {
+                    const appMatch = line.match(/^"?([^"=]+)"?\s*=\s*\{/);
+                    if (appMatch) {
+                        appIdentifier = appMatch[1].trim();
+                        currentApp = {
+                            CFBundleIdentifier: appIdentifier,
+                        };
+                        state = ParseState.IN_APP;
+                    }
+                    break;
+                case ParseState.IN_APP:
+                    if (line === "};") {
+                        result.push(currentApp);
+                        currentApp = {};
+                        state = ParseState.LOOKING_FOR_APP;
+                    }
+                    else {
+                        // look for property: PropertyName = Value;
+                        const propertyMatch = line.match(/^([^=]+)\s*=\s*(.+?);\s*$/);
+                        if (propertyMatch) {
+                            const propName = propertyMatch[1].trim();
+                            let propValue = propertyMatch[2].trim();
+                            // remove quotes if present (they're optional)
+                            if (propValue.startsWith('"') && propValue.endsWith('"')) {
+                                propValue = propValue.substring(1, propValue.length - 1);
+                            }
+                            // add property to current app
+                            currentApp[propName] = propValue;
+                        }
+                        else if (line.endsWith("{")) {
+                            // nested property like GroupContainers = {
+                            state = ParseState.IN_PROPERTY;
+                        }
+                    }
+                    break;
+                case ParseState.IN_PROPERTY:
+                    if (line === "};") {
+                        // end of nested property
+                        state = ParseState.IN_APP;
+                    }
+                    // skip content of nested properties, we don't care of those right now
+                    break;
+            }
+        }
+        return result;
+    }
+    async listApps() {
+        const text = this.simctl("listapps", this.simulatorUuid).toString();
+        const apps = Simctl.parseIOSAppData(text);
+        return apps.map(app => ({
+            packageName: app.CFBundleIdentifier,
+            appName: app.CFBundleDisplayName,
+        }));
+    }
+    async getScreenSize() {
+        const wda = await this.wda();
+        return wda.getScreenSize();
+    }
+    async sendKeys(keys) {
+        const wda = await this.wda();
+        return wda.sendKeys(keys);
+    }
+    async swipe(direction) {
+        const wda = await this.wda();
+        return wda.swipe(direction);
+    }
+    async tap(x, y) {
+        const wda = await this.wda();
+        return wda.tap(x, y);
+    }
+    async pressButton(button) {
+        const wda = await this.wda();
+        return wda.pressButton(button);
+    }
+    async getElementsOnScreen() {
+        const wda = await this.wda();
+        return wda.getElementsOnScreen();
+    }
+    async setOrientation(orientation) {
+        const wda = await this.wda();
+        return wda.setOrientation(orientation);
+    }
+    async getOrientation() {
+        const wda = await this.wda();
+        return wda.getOrientation();
+    }
+}
+exports.Simctl = Simctl;
+class SimctlManager {
+    listSimulators() {
+        // detect if this is a mac
+        if (process.platform !== "darwin") {
+            // don't even try to run xcrun
+            return [];
+        }
+        try {
+            const text = (0, 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 => {
+                    return {
+                        name: d.name,
+                        uuid: d.udid,
+                        state: d.state,
+                    };
+                });
+            });
+        }
+        catch (error) {
+            console.error("Error listing simulators", error);
+            return [];
+        }
+    }
+    listBootedSimulators() {
+        return this.listSimulators()
+            .filter(simulator => simulator.state === "Booted");
+    }
+    getSimulator(uuid) {
+        return new Simctl(uuid);
+    }
+}
+exports.SimctlManager = SimctlManager;

package/lib/logger.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.error = exports.trace = void 0;
+const fs_1 = require("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");
+    }
+    console.error(message);
+};
+const trace = (message) => {
+    writeLog(message);
+};
+exports.trace = trace;
+const error = (message) => {
+    writeLog(message);
+};
+exports.error = error;

package/lib/png.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PNG = void 0;
+class PNG {
+    buffer;
+    constructor(buffer) {
+        this.buffer = buffer;
+    }
+    getDimensions() {
+        const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+        if (!this.buffer.subarray(0, 8).equals(pngSignature)) {
+            throw new Error("Not a valid PNG file");
+        }
+        const width = this.buffer.readUInt32BE(16);
+        const height = this.buffer.readUInt32BE(20);
+        return { width, height };
+    }
+}
+exports.PNG = PNG;

package/lib/robot.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionableError = void 0;
+class ActionableError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+exports.ActionableError = ActionableError;

package/lib/server.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpServer = void 0;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const logger_1 = require("./logger");
+const android_1 = require("./android");
+const robot_1 = require("./robot");
+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 getAgentVersion = () => {
+    const json = require("../package.json");
+    return json.version;
+};
+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 = 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",
+        version: getAgentVersion(),
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+    });
+    const tool = (name, description, paramsSchema, cb) => {
+        const wrappedCb = async (args) => {
+            try {
+                (0, logger_1.trace)(`Invoking ${name} with args: ${JSON.stringify(args)}`);
+                const response = await cb(args);
+                (0, logger_1.trace)(`=> ${response}`);
+                return {
+                    content: [{ type: "text", text: response }],
+                };
+            }
+            catch (error) {
+                if (error instanceof robot_1.ActionableError) {
+                    return {
+                        content: [{ type: "text", text: `${error.message}. Please fix the issue and try again.` }],
+                    };
+                }
+                else {
+                    // a real exception
+                    (0, logger_1.trace)(`Tool '${description}' failed: ${error.message} stack: ${error.stack}`);
+                    return {
+                        content: [{ type: "text", text: `Error: ${error.message}` }],
+                        isError: true,
+                    };
+                }
+            }
+        };
+        server.tool(name, description, paramsSchema, args => wrappedCb(args));
+    };
+    let robot;
+    const simulatorManager = new iphone_simulator_1.SimctlManager();
+    const requireRobot = () => {
+        if (!robot) {
+            throw new robot_1.ActionableError("No device selected. Use the mobile_use_device tool to select a device.");
+        }
+    };
+    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.", {}, 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 androidDevices = androidManager.getConnectedDevices();
+        const iosDevices = await iosManager.listDevices();
+        const iosDeviceNames = iosDevices.map(d => d.deviceId);
+        const androidTvDevices = androidDevices.filter(d => d.deviceType === "tv").map(d => d.deviceId);
+        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(".")}]`);
+        }
+        if (iosDevices.length > 0) {
+            resp.push(`iOS devices: [${iosDeviceNames.join(",")}]`);
+        }
+        if (androidMobileDevices.length > 0) {
+            resp.push(`Android devices: [${androidMobileDevices.join(",")}]`);
+        }
+        if (androidTvDevices.length > 0) {
+            resp.push(`Android TV devices: [${androidTvDevices.join(",")}]`);
+        }
+        return resp.join("\n");
+    });
+    tool("mobile_use_device", "Select a device to use. This can be a simulator or an Android device. Use the list_available_devices tool to get a list of available devices.", {
+        device: zod_1.z.string().describe("The name of the device to select"),
+        deviceType: zod_1.z.enum(["simulator", "ios", "android"]).describe("The type of device to select"),
+    }, async ({ device, deviceType }) => {
+        switch (deviceType) {
+            case "simulator":
+                robot = simulatorManager.getSimulator(device);
+                break;
+            case "ios":
+                robot = new ios_1.IosRobot(device);
+                break;
+            case "android":
+                robot = new android_1.AndroidRobot(device);
+                break;
+        }
+        return `Selected device: ${device}`;
+    });
+    tool("mobile_list_apps", "List all the installed apps on the device", {}, async ({}) => {
+        requireRobot();
+        const result = await robot.listApps();
+        return `Found these apps on device: ${result.map(app => `${app.appName} (${app.packageName})`).join(", ")}`;
+    });
+    tool("mobile_launch_app", "Launch an app on mobile device. Use this to open a specific app. You can find the package name of the app by calling list_apps_on_device.", {
+        packageName: zod_1.z.string().describe("The package name of the app to launch"),
+    }, async ({ packageName }) => {
+        requireRobot();
+        await robot.launchApp(packageName);
+        return `Launched app ${packageName}`;
+    });
+    tool("mobile_terminate_app", "Stop and terminate an app on mobile device", {
+        packageName: zod_1.z.string().describe("The package name of the app to terminate"),
+    }, async ({ packageName }) => {
+        requireRobot();
+        await robot.terminateApp(packageName);
+        return `Terminated app ${packageName}`;
+    });
+    tool("mobile_get_screen_size", "Get the screen size of the mobile device in pixels", {}, async ({}) => {
+        requireRobot();
+        const screenSize = await robot.getScreenSize();
+        return `Screen size is ${screenSize.width}x${screenSize.height} pixels`;
+    });
+tool("mobile_click_on_element_by_text", "Click on the screen element identified by its text", {
+    text: zod_1.z.string().describe("The visible text of the element to click"),
+}, async ({ text }) => {
+    requireRobot();
+    const xpath = `//*[@text="${text}"]`;
+    const element = await robot.findElementByXPath(xpath);
+    if (!element) {
+        throw new Error(`Element with text "${text}" not found`);
+    }
+    await element.click();
+    // Wait for 2 seconds after click
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    return `Clicked on element with text: "${text}"`;
+});
+
+tool("mobile_list_elements_on_screen", "List elements on screen with display text or accessibility label. Do not cache this result.", {}, async ({}) => {
+    requireRobot();
+    const elements = await robot.getElementsOnScreen();
+    const result = elements.map(element => {
+        const out = {
+            type: element.type,
+            text: element.text,
+            label: element.label,
+            name: element.name,
+            value: element.value,
+        };
+        if (element.focused) {
+            out.focused = true;
+        }
+        return out;
+    });
+    return `Found these elements on screen: ${JSON.stringify(result)}`;
+});
+    tool("mobile_press_button", "Press a button on device", {
+        button: zod_1.z.string().describe("The button to press. Supported buttons: BACK (android only), HOME, VOLUME_UP, VOLUME_DOWN, ENTER, DPAD_CENTER (android tv only), DPAD_UP (android tv only), DPAD_DOWN (android tv only), DPAD_LEFT (android tv only), DPAD_RIGHT (android tv only)"),
+    }, async ({ button }) => {
+        requireRobot();
+        await robot.pressButton(button);
+        return `Pressed the button: ${button}`;
+    });
+    tool("mobile_open_url", "Open a URL in browser on device", {
+        url: zod_1.z.string().describe("The URL to open"),
+    }, async ({ url }) => {
+        requireRobot();
+        await robot.openUrl(url);
+await new Promise(resolve => setTimeout(resolve, 5000));
+        return `Opened URL: ${url}`;
+    });
+    tool("swipe_on_screen", "Swipe on the screen", {
+        direction: zod_1.z.enum(["up", "down"]).describe("The direction to swipe"),
+    }, async ({ direction }) => {
+        requireRobot();
+        await robot.swipe(direction);
+        return `Swiped ${direction} on screen`;
+    });
+    tool("mobile_type_keys", "Type text into the focused element", {
+        text: zod_1.z.string().describe("The text to type"),
+        submit: zod_1.z.boolean().describe("Whether to submit the text. If true, the text will be submitted as if the user pressed the enter key."),
+    }, async ({ text, submit }) => {
+        requireRobot();
+        await robot.sendKeys(text);
+        if (submit) {
+            await robot.pressButton("ENTER");
+        }
+        return `Typed text: ${text}`;
+    });
+    tool("mobile_set_orientation", "Change the screen orientation of the device", {
+        orientation: zod_1.z.enum(["portrait", "landscape"]).describe("The desired orientation"),
+    }, async ({ orientation }) => {
+        requireRobot();
+        await robot.setOrientation(orientation);
+        return `Changed device orientation to ${orientation}`;
+    });
+    tool("mobile_get_orientation", "Get the current screen orientation of the device", {}, async () => {
+        requireRobot();
+        const orientation = await robot.getOrientation();
+        return `Current device orientation is ${orientation}`;
+    });
+    // async check for latest agent version
+    checkForLatestAgentVersion().then();
+    return server;
+};
+exports.createMcpServer = createMcpServer;