@rvaim/deveco-mobile-mcp 0.1.0-rvaim.1

package/lib/iphone-simulator.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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");
+const utils_1 = require("./utils");
+const TIMEOUT = 30000;
+const WDA_PORT = 8100;
+const MAX_BUFFER_SIZE = 1024 * 1024 * 8;
+class Simctl {
+    simulatorUuid;
+    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())) {
+            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, node_child_process_1.execFileSync)("xcrun", ["simctl", ...args], {
+            timeout: TIMEOUT,
+            maxBuffer: MAX_BUFFER_SIZE,
+        });
+    }
+    async getScreenshot() {
+        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();
+        await wda.openUrl(url);
+        // alternative: this.simctl("openurl", this.simulatorUuid, url);
+    }
+    async launchApp(packageName, locale) {
+        (0, utils_1.validatePackageName)(packageName);
+        const args = ["launch", this.simulatorUuid, packageName];
+        if (locale) {
+            (0, utils_1.validateLocale)(locale);
+            const locales = locale.split(",").map(l => l.trim());
+            args.push("-AppleLanguages", `(${locales.join(", ")})`);
+            args.push("-AppleLocale", locales[0]);
+        }
+        this.simctl(...args);
+    }
+    async terminateApp(packageName) {
+        (0, utils_1.validatePackageName)(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", "-"], {
+            input: text,
+        });
+        const output = JSON.parse(result.toString());
+        return Object.values(output).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 swipeFromCoordinate(x, y, direction, distance) {
+        const wda = await this.wda();
+        return wda.swipeFromCoordinate(x, y, direction, distance);
+    }
+    async tap(x, y) {
+        const wda = await this.wda();
+        return wda.tap(x, y);
+    }
+    async doubleTap(x, y) {
+        const wda = await this.wda();
+        await wda.doubleTap(x, y);
+    }
+    async longPress(x, y, duration) {
+        const wda = await this.wda();
+        return wda.longPress(x, y, duration);
+    }
+    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();
+    }
+    /**
+     * 获取模拟器日志 (log stream)
+     * @param options - 可选的过滤选项
+     */
+    async getDeviceLogs(options) {
+        // iOS 模拟器使用 simctl spawn log 命令获取日志
+        try {
+            const args = ["spawn", this.simulatorUuid, "log", "show", "--last", "1m"];
+            // 添加行数限制
+            const lines = options?.lines || 100;
+            args.push("--info"); // 包含 info 级别及以上
+            const output = (0, node_child_process_1.execFileSync)("xcrun", ["simctl", ...args], {
+                maxBuffer: 1024 * 1024 * 8,
+                timeout: 15000,
+            }).toString();
+            // 按行分割并过滤
+            let lines_array = output.split("\n");
+            // 按标签过滤
+            if (options?.bundleName) {
+                lines_array = lines_array.filter(line => line.includes(options.bundleName));
+            }
+            // 按 PID 过滤
+            if (options?.pid) {
+                lines_array = lines_array.filter(line => line.includes(`[${options.pid}]`));
+            }
+            // 按级别过滤
+            if (options?.level) {
+                const levelPattern = options.level.toLowerCase();
+                lines_array = lines_array.filter(line => {
+                    const lowerLine = line.toLowerCase();
+                    return lowerLine.includes(levelPattern);
+                });
+            }
+            // 限制行数
+            return lines_array.slice(-lines).join("\n");
+        }
+        catch (error) {
+            throw new robot_1.ActionableError(`Failed to get simulator logs: ${error.message}`);
+        }
+    }
+}
+exports.Simctl = Simctl;

package/lib/jpeg.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JPEG = void 0;
+class JPEG {
+    buffer;
+    constructor(buffer) {
+        this.buffer = buffer;
+    }
+    getDimensions() {
+        // JPEG signature: FF D8
+        if (this.buffer[0] !== 0xff || this.buffer[1] !== 0xd8) {
+            throw new Error("Not a valid JPEG file");
+        }
+        let offset = 2;
+        while (offset < this.buffer.length - 1) {
+            // Find marker
+            if (this.buffer[offset] !== 0xff) {
+                offset++;
+                continue;
+            }
+            const marker = this.buffer[offset + 1];
+            // SOF0 (Baseline DCT), SOF1, SOF2 (Progressive DCT), etc.
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                // SOF marker found
+                // Structure: FF marker length(2) precision(1) height(2) width(2) ...
+                const height = this.buffer.readUInt16BE(offset + 5);
+                const width = this.buffer.readUInt16BE(offset + 7);
+                return { width, height };
+            }
+            // Skip to next marker
+            if (marker === 0xd8 || marker === 0xd9) {
+                // SOI or EOI, no length field
+                offset += 2;
+            }
+            else if (marker === 0xff) {
+                // Padding byte
+                offset++;
+            }
+            else {
+                // Read length and skip
+                const length = this.buffer.readUInt16BE(offset + 2);
+                offset += 2 + length;
+            }
+        }
+        throw new Error("Could not find JPEG dimensions");
+    }
+}
+exports.JPEG = JPEG;

package/lib/logger.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.error = exports.trace = void 0;
+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, node_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/mobile-device.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobileDevice = void 0;
+const mobilecli_1 = require("./mobilecli");
+class MobileDevice {
+    deviceId;
+    mobilecli;
+    constructor(deviceId) {
+        this.deviceId = deviceId;
+        this.mobilecli = new mobilecli_1.Mobilecli();
+    }
+    runCommand(args) {
+        const fullArgs = [...args, "--device", this.deviceId];
+        return this.mobilecli.executeCommand(fullArgs);
+    }
+    async getScreenSize() {
+        const response = JSON.parse(this.runCommand(["device", "info"]));
+        if (response.data.device.screenSize) {
+            return response.data.device.screenSize;
+        }
+        return { width: 0, height: 0, scale: 1.0 };
+    }
+    async swipe(direction) {
+        const screenSize = await this.getScreenSize();
+        const centerX = Math.floor(screenSize.width / 2);
+        const centerY = Math.floor(screenSize.height / 2);
+        const distance = 400; // Default distance in pixels
+        let startX = centerX;
+        let startY = centerY;
+        let endX = centerX;
+        let endY = centerY;
+        switch (direction) {
+            case "up":
+                startY = centerY + distance / 2;
+                endY = centerY - distance / 2;
+                break;
+            case "down":
+                startY = centerY - distance / 2;
+                endY = centerY + distance / 2;
+                break;
+            case "left":
+                startX = centerX + distance / 2;
+                endX = centerX - distance / 2;
+                break;
+            case "right":
+                startX = centerX - distance / 2;
+                endX = centerX + distance / 2;
+                break;
+        }
+        this.runCommand(["io", "swipe", `${startX},${startY},${endX},${endY}`]);
+    }
+    async swipeFromCoordinate(x, y, direction, distance) {
+        const swipeDistance = distance || 400;
+        let endX = x;
+        let endY = y;
+        switch (direction) {
+            case "up":
+                endY = y - swipeDistance;
+                break;
+            case "down":
+                endY = y + swipeDistance;
+                break;
+            case "left":
+                endX = x - swipeDistance;
+                break;
+            case "right":
+                endX = x + swipeDistance;
+                break;
+        }
+        this.runCommand(["io", "swipe", `${x},${y},${endX},${endY}`]);
+    }
+    async getScreenshot() {
+        const fullArgs = ["screenshot", "--device", this.deviceId, "--format", "png", "--output", "-"];
+        return this.mobilecli.executeCommandBuffer(fullArgs);
+    }
+    async listApps() {
+        const response = JSON.parse(this.runCommand(["apps", "list"]));
+        return response.data.map(app => ({
+            appName: app.appName || app.packageName,
+            packageName: app.packageName,
+        }));
+    }
+    async launchApp(packageName, locale) {
+        const args = ["apps", "launch", packageName];
+        if (locale) {
+            args.push("--locale", locale);
+        }
+        this.runCommand(args);
+    }
+    async terminateApp(packageName) {
+        this.runCommand(["apps", "terminate", packageName]);
+    }
+    async installApp(path) {
+        this.runCommand(["apps", "install", path]);
+    }
+    async uninstallApp(bundleId) {
+        this.runCommand(["apps", "uninstall", bundleId]);
+    }
+    async openUrl(url) {
+        this.runCommand(["url", url]);
+    }
+    async sendKeys(text) {
+        this.runCommand(["io", "text", text]);
+    }
+    async pressButton(button) {
+        this.runCommand(["io", "button", button]);
+    }
+    async tap(x, y) {
+        this.runCommand(["io", "tap", `${x},${y}`]);
+    }
+    async doubleTap(x, y) {
+        // TODO: should move into mobilecli itself as "io doubletap"
+        await this.tap(x, y);
+        await this.tap(x, y);
+    }
+    async longPress(x, y, duration) {
+        this.runCommand(["io", "longpress", `${x},${y}`, "--duration", `${duration}`]);
+    }
+    async getElementsOnScreen() {
+        const response = JSON.parse(this.runCommand(["dump", "ui"]));
+        return response.data.elements.map(element => ({
+            type: element.type,
+            label: element.label,
+            text: element.text,
+            name: element.name,
+            value: element.value,
+            identifier: element.identifier,
+            rect: element.rect,
+            focused: element.focused,
+        }));
+    }
+    async setOrientation(orientation) {
+        this.runCommand(["device", "orientation", "set", orientation]);
+    }
+    async getOrientation() {
+        const response = JSON.parse(this.runCommand(["device", "orientation", "get"]));
+        return response.data.orientation;
+    }
+    async getDeviceLogs(options) {
+        const args = ["logs", "get"];
+        if (options?.bundleName) {
+            args.push("--tag", options.bundleName);
+        }
+        if (options?.pid) {
+            args.push("--pid", options.pid.toString());
+        }
+        if (options?.level) {
+            args.push("--level", options.level);
+        }
+        if (options?.lines) {
+            args.push("--lines", options.lines.toString());
+        }
+        if (options?.clear) {
+            args.push("--clear");
+        }
+        return this.runCommand(args);
+    }
+}
+exports.MobileDevice = MobileDevice;

package/lib/mobilecli.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mobilecli = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const TIMEOUT = 30000;
+const MAX_BUFFER_SIZE = 1024 * 1024 * 8;
+class Mobilecli {
+    path = null;
+    constructor() { }
+    getPath() {
+        if (!this.path) {
+            this.path = Mobilecli.getMobilecliPath();
+        }
+        return this.path;
+    }
+    executeCommand(args) {
+        const path = this.getPath();
+        return (0, node_child_process_1.execFileSync)(path, args, { encoding: "utf8" }).toString().trim();
+    }
+    spawnCommand(args) {
+        const binaryPath = this.getPath();
+        return (0, node_child_process_1.spawn)(binaryPath, args, {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+    }
+    executeCommandBuffer(args) {
+        const path = this.getPath();
+        return (0, node_child_process_1.execFileSync)(path, args, {
+            encoding: "buffer",
+            maxBuffer: MAX_BUFFER_SIZE,
+            timeout: TIMEOUT,
+        });
+    }
+    static getMobilecliPath() {
+        if (process.env.MOBILECLI_PATH) {
+            return process.env.MOBILECLI_PATH;
+        }
+        const platform = process.platform;
+        const arch = process.arch;
+        const normalizedPlatform = platform === "win32" ? "windows" : platform;
+        const normalizedArch = arch === "arm64" ? "arm64" : "amd64";
+        const ext = platform === "win32" ? ".exe" : "";
+        const binaryName = `mobilecli-${normalizedPlatform}-${normalizedArch}${ext}`;
+        // 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}`);
+    }
+    getVersion() {
+        try {
+            const output = this.executeCommand(["--version"]);
+            if (output.startsWith("mobilecli version ")) {
+                return output.substring("mobilecli version ".length);
+            }
+            return "failed";
+        }
+        catch (error) {
+            return "failed " + error.message;
+        }
+    }
+    fleetListDevices() {
+        return this.executeCommand(["fleet", "list-devices"]);
+    }
+    fleetAllocate(platform) {
+        return this.executeCommand(["fleet", "allocate", "--platform", platform]);
+    }
+    fleetRelease(deviceId) {
+        return this.executeCommand(["fleet", "release", "--device", deviceId]);
+    }
+    getDevices(options) {
+        const args = ["devices"];
+        if (options) {
+            if (options.includeOffline) {
+                args.push("--include-offline");
+            }
+            if (options.platform) {
+                if (options.platform !== "ios" && options.platform !== "android") {
+                    throw new Error(`Invalid platform: ${options.platform}. Must be "ios" or "android"`);
+                }
+                args.push("--platform", options.platform);
+            }
+            if (options.type) {
+                if (options.type !== "real" && options.type !== "emulator" && options.type !== "simulator") {
+                    throw new Error(`Invalid type: ${options.type}. Must be "real", "emulator", or "simulator"`);
+                }
+                args.push("--type", options.type);
+            }
+        }
+        const mobilecliOutput = this.executeCommand(args);
+        return JSON.parse(mobilecliOutput);
+    }
+}
+exports.Mobilecli = Mobilecli;

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;