@nbakka/mcp-appium 1.0.28 → 2.0.1

package/lib/server.js

@@ -0,0 +1,307 @@
+"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.clickByXPath(xpath);
+    if (!element) {
+        throw new Error(`Element with text "${text}" not found`);
+    }
+    // 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;
+};
+
+tool(
+  "mobile_create_session",
+  "create a mobile session once so that session id can be used in other tools where it is needed",
+  {},
+  async () => {
+    const capabilities = {
+      platformName: "Android",
+      "appium:udid": "emulator-5554",
+      "appium:automationName": "UiAutomator2",
+      "appium:noReset": true,
+      "appium:appPackage": "com.locon.housing",
+      "appium:appActivity": "com.locon.housing.presentation.MainActivity",
+    };
+
+    const payload = {
+      capabilities: {
+        firstMatch: [{}],
+        alwaysMatch: capabilities,
+      },
+    };
+
+    const response = await fetch("http://localhost:4723/session", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to create session: ${response.statusText}`);
+    }
+
+    const json = await response.json();
+    return `Session created with sessionId: ${json.sessionId}`;
+  }
+);
+
+
+tool(
+  "mobile_click_using_xpath",
+  "Click an element identified by text using path",
+  {
+    sessionId: zod_1.z.string().describe("Appium session ID"),
+    text: zod_1.z.string().describe("Visible text of the element to click"),
+  },
+  async ({ sessionId, text }) => {
+    const xpath = `//*[@text="${text}"]`;
+    const clickUrl = `http://localhost:4723/session/${sessionId}/element`;
+
+    // Find element
+    const findResponse = await fetch(clickUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ using: "xpath", value: xpath }),
+    });
+
+    if (!findResponse.ok) {
+      throw new Error(`Failed to find element: ${findResponse.statusText}`);
+    }
+
+    const findJson = await findResponse.json();
+    if (!findJson.value || !findJson.value.elementId) {
+      throw new Error(`Element with text "${text}" not found`);
+    }
+
+    const elementId = findJson.value.elementId;
+
+    // Click element
+    const clickElementUrl = `http://localhost:4723/session/${sessionId}/element/${elementId}/click`;
+    const clickResponse = await fetch(clickElementUrl, { method: "POST" });
+
+    if (!clickResponse.ok) {
+      throw new Error(`Failed to click element: ${clickResponse.statusText}`);
+    }
+
+    // Optional wait after click
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    return `Clicked on element with text: "${text}" in session: ${sessionId}`;
+  }
+);
+exports.createMcpServer = createMcpServer;

package/lib/webdriver-agent.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebDriverAgent = void 0;
+const robot_1 = require("./robot");
+class WebDriverAgent {
+    host;
+    port;
+    constructor(host, port) {
+        this.host = host;
+        this.port = port;
+    }
+    async isRunning() {
+        const url = `http://${this.host}:${this.port}/status`;
+        try {
+            const response = await fetch(url);
+            return response.status === 200;
+        }
+        catch (error) {
+            console.error(`Failed to connect to WebDriverAgent: ${error}`);
+            return false;
+        }
+    }
+    async createSession() {
+        const url = `http://${this.host}:${this.port}/session`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ capabilities: { alwaysMatch: { platformName: "iOS" } } }),
+        });
+        const json = await response.json();
+        return json.value.sessionId;
+    }
+    async deleteSession(sessionId) {
+        const url = `http://${this.host}:${this.port}/session/${sessionId}`;
+        const response = await fetch(url, { method: "DELETE" });
+        return response.json();
+    }
+    async withinSession(fn) {
+        const sessionId = await this.createSession();
+        const url = `http://${this.host}:${this.port}/session/${sessionId}`;
+        const result = await fn(url);
+        await this.deleteSession(sessionId);
+        return result;
+    }
+    async getScreenSize() {
+        return this.withinSession(async (sessionUrl) => {
+            const url = `${sessionUrl}/wda/screen`;
+            const response = await fetch(url);
+            const json = await response.json();
+            return {
+                width: json.value.screenSize.width,
+                height: json.value.screenSize.height,
+                scale: json.value.scale || 1,
+            };
+        });
+    }
+    async sendKeys(keys) {
+        await this.withinSession(async (sessionUrl) => {
+            const url = `${sessionUrl}/wda/keys`;
+            await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ value: [keys] }),
+            });
+        });
+    }
+    async pressButton(button) {
+        const _map = {
+            "HOME": "home",
+            "VOLUME_UP": "volumeup",
+            "VOLUME_DOWN": "volumedown",
+        };
+        if (button === "ENTER") {
+            await this.sendKeys("\n");
+            return;
+        }
+        // Type assertion to check if button is a key of _map
+        if (!(button in _map)) {
+            throw new robot_1.ActionableError(`Button "${button}" is not supported`);
+        }
+        await this.withinSession(async (sessionUrl) => {
+            const url = `${sessionUrl}/wda/pressButton`;
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    name: button,
+                }),
+            });
+            return response.json();
+        });
+    }
+    async tap(x, y) {
+        await this.withinSession(async (sessionUrl) => {
+            const url = `${sessionUrl}/actions`;
+            await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    actions: [
+                        {
+                            type: "pointer",
+                            id: "finger1",
+                            parameters: { pointerType: "touch" },
+                            actions: [
+                                { type: "pointerMove", duration: 0, x, y },
+                                { type: "pointerDown", button: 0 },
+                                { type: "pause", duration: 100 },
+                                { type: "pointerUp", button: 0 }
+                            ]
+                        }
+                    ]
+                }),
+            });
+        });
+    }
+    isVisible(rect) {
+        return rect.x >= 0 && rect.y >= 0;
+    }
+    filterSourceElements(source) {
+        const output = [];
+        const acceptedTypes = ["TextField", "Button", "Switch", "Icon", "SearchField", "StaticText", "Image"];
+        if (acceptedTypes.includes(source.type)) {
+            if (source.isVisible === "1" && this.isVisible(source.rect)) {
+                if (source.label !== null || source.name !== null) {
+                    output.push({
+                        type: source.type,
+                        label: source.label,
+                        name: source.name,
+                        value: source.value,
+                        rect: {
+                            x: source.rect.x,
+                            y: source.rect.y,
+                            width: source.rect.width,
+                            height: source.rect.height,
+                        },
+                    });
+                }
+            }
+        }
+        if (source.children) {
+            for (const child of source.children) {
+                output.push(...this.filterSourceElements(child));
+            }
+        }
+        return output;
+    }
+    async getPageSource() {
+        const url = `http://${this.host}:${this.port}/source/?format=json`;
+        const response = await fetch(url);
+        const json = await response.json();
+        return json;
+    }
+    async getElementsOnScreen() {
+        const source = await this.getPageSource();
+        return this.filterSourceElements(source.value);
+    }
+    async openUrl(url) {
+        await this.withinSession(async (sessionUrl) => {
+            await fetch(`${sessionUrl}/url`, {
+                method: "POST",
+                body: JSON.stringify({ url }),
+            });
+        });
+    }
+    async swipe(direction) {
+        await this.withinSession(async (sessionUrl) => {
+            const x0 = 200;
+            let y0 = 600;
+            const x1 = 200;
+            let y1 = 200;
+            if (direction === "up") {
+                const tmp = y0;
+                y0 = y1;
+                y1 = tmp;
+            }
+            const url = `${sessionUrl}/actions`;
+            await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    actions: [
+                        {
+                            type: "pointer",
+                            id: "finger1",
+                            parameters: { pointerType: "touch" },
+                            actions: [
+                                { type: "pointerMove", duration: 0, x: x0, y: y0 },
+                                { type: "pointerDown", button: 0 },
+                                { type: "pointerMove", duration: 0, x: x1, y: y1 },
+                                { type: "pause", duration: 1000 },
+                                { type: "pointerUp", button: 0 }
+                            ]
+                        }
+                    ]
+                }),
+            });
+        });
+    }
+    async setOrientation(orientation) {
+        await this.withinSession(async (sessionUrl) => {
+            const url = `${sessionUrl}/orientation`;
+            await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    orientation: orientation.toUpperCase()
+                })
+            });
+        });
+    }
+    async getOrientation() {
+        return this.withinSession(async (sessionUrl) => {
+            const url = `${sessionUrl}/orientation`;
+            const response = await fetch(url);
+            const json = await response.json();
+            return json.value.toLowerCase();
+        });
+    }
+}
+exports.WebDriverAgent = WebDriverAgent;

package/package.json

@@ -1,24 +1,52 @@
 {
   "name": "@nbakka/mcp-appium",
-  "version": "1.0.28",
-  "description": "Selenium WebDriver MCP Server",
-  "type": "module",
-  "main": "src/lib/server.js",
-  "bin": {
-    "mcp-appium": "./src/lib/server.js"
+  "version": "2.0.1",
+  "description": "Appium MCP",
+  "engines": {
+    "node": ">=18"
   },
+  "license": "Apache-2.0",
   "scripts": {
-"start": "node src/lib/server.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc && chmod +x lib/index.js",
+    "lint": "eslint .",
+    "test": "nyc mocha --require ts-node/register test/*.ts",
+    "watch": "tsc --watch",
+    "clean": "rm -rf lib",
+    "prepare": "husky"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "files": [
+    "lib"
+  ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.7.0",
-     "axios": "^1.4.0",
-    "zod": "^3.22.2",
-    "yargs": "^17.7.2",
-"xml2js": "0.6.2"
-  }
-}
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "fast-xml-parser": "^5.0.9",
+    "zod-to-json-schema": "^3.24.4"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.19.0",
+    "@stylistic/eslint-plugin": "^3.0.1",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.13.10",
+    "@typescript-eslint/eslint-plugin": "^8.28.0",
+    "@typescript-eslint/parser": "^8.26.1",
+    "@typescript-eslint/utils": "^8.26.1",
+    "eslint": "^9.19.0",
+    "eslint-plugin": "^1.0.1",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-notice": "^1.0.0",
+    "husky": "^9.1.7",
+    "nyc": "^17.1.0",
+    "mocha": "^11.1.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  },
+  "main": "index.js",
+  "bin": {
+    "mcp-appium": "lib/index.js"
+  },
+  "directories": {
+    "lib": "lib"
+  },
+  "author": "nbakka"
+}

package/bin/mcp-appium.js

@@ -1,57 +0,0 @@
-#!/usr/bin/env node
-
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-import { spawn } from 'child_process';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const serverPath = resolve(__dirname, '../src/lib/server.js');
-
-// Start the server
-const child = spawn('node', [serverPath], {
-    stdio: 'inherit'
-});
-
-child.on('error', (error) => {
-    console.error(`Error starting server: ${error.message}`);
-    process.exit(1);
-});
-
-// Handle process termination
-process.on('SIGTERM', () => {
-    child.kill('SIGTERM');
-});
-
-process.on('SIGINT', () => {
-    child.kill('SIGINT');
-});#!/usr/bin/env node
-
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-import { spawn } from 'child_process';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const serverPath = resolve(__dirname, '../src/lib/server.js');
-
-// Start the server
-const child = spawn('node', [serverPath], {
-    stdio: 'inherit'
-});
-
-child.on('error', (error) => {
-    console.error(`Error starting server: ${error.message}`);
-    process.exit(1);
-});
-
-// Handle process termination
-process.on('SIGTERM', () => {
-    child.kill('SIGTERM');
-});
-
-process.on('SIGINT', () => {
-    child.kill('SIGINT');
-});