mobile-debug-mcp 0.3.0 → 0.5.0

package/dist/ios.js

@@ -1,21 +1,210 @@
-import { exec } from "child_process";
-export function startIOSApp(bundleId) {
+import { execFile, spawn } from "child_process";
+import { promises as fs } from "fs";
+const XCRUN = process.env.XCRUN_PATH || "xcrun";
+// Validate bundle ID to prevent any potential injection or invalid characters
+function validateBundleId(bundleId) {
+    if (!bundleId)
+        return;
+    // Allow alphanumeric, dots, hyphens, and underscores.
+    if (!/^[a-zA-Z0-9.\-_]+$/.test(bundleId)) {
+        throw new Error(`Invalid Bundle ID: ${bundleId}. Must contain only alphanumeric characters, dots, hyphens, or underscores.`);
+    }
+}
+function execCommand(args, deviceId = "booted") {
     return new Promise((resolve, reject) => {
-        exec(`xcrun simctl launch booted ${bundleId}`, (err, stdout, stderr) => {
-            if (err)
-                reject(stderr);
-            else
-                resolve(stdout);
+        // Use spawn for better stream control and consistency with Android implementation
+        const child = spawn(XCRUN, args);
+        let stdout = '';
+        let stderr = '';
+        if (child.stdout) {
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        const timeoutMs = args.includes('log') ? 10000 : 5000; // 10s for logs, 5s for others
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Command timed out after ${timeoutMs}ms: ${XCRUN} ${args.join(' ')}`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                reject(new Error(stderr.trim() || `Command failed with code ${code}`));
+            }
+            else {
+                resolve({ output: stdout.trim(), device: { platform: "ios", id: deviceId } });
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
         });
     });
 }
-export function getIOSLogs() {
-    return new Promise((resolve, reject) => {
-        exec(`xcrun simctl spawn booted log show --style syslog --last 1m`, (err, stdout, stderr) => {
-            if (err)
-                reject(stderr);
-            else
-                resolve(stdout);
+function parseRuntimeName(runtime) {
+    // Example: com.apple.CoreSimulator.SimRuntime.iOS-17-0 -> iOS 17.0
+    try {
+        const parts = runtime.split('.');
+        const lastPart = parts[parts.length - 1];
+        return lastPart.replace(/-/g, ' ').replace('iOS ', 'iOS '); // Keep iOS prefix
+    }
+    catch {
+        return runtime;
+    }
+}
+export async function getIOSDeviceMetadata(deviceId = "booted") {
+    return new Promise((resolve) => {
+        // If deviceId is provided (and not "booted"), we could try to list just that device.
+        // But listing all booted devices is usually fine to find the one we want or just one.
+        // Let's stick to listing all and filtering if needed, or just return basic info if we can't find it.
+        execFile(XCRUN, ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+            // Default fallback
+            const fallback = {
+                platform: "ios",
+                id: deviceId,
+                osVersion: "Unknown",
+                model: "Simulator",
+                simulator: true,
+            };
+            if (err || !stdout) {
+                resolve(fallback);
+                return;
+            }
+            try {
+                const data = JSON.parse(stdout);
+                const devicesMap = data.devices || {};
+                // Find the device
+                for (const runtime in devicesMap) {
+                    const devices = devicesMap[runtime];
+                    if (Array.isArray(devices)) {
+                        for (const device of devices) {
+                            if (deviceId === "booted" || device.udid === deviceId) {
+                                resolve({
+                                    platform: "ios",
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                });
+                                return;
+                            }
+                        }
+                    }
+                }
+                resolve(fallback);
+            }
+            catch (error) {
+                resolve(fallback);
+            }
         });
     });
 }
+export async function startIOSApp(bundleId, deviceId = "booted") {
+    validateBundleId(bundleId);
+    const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
+    const device = await getIOSDeviceMetadata(deviceId);
+    // Simulate launch time and appStarted for demonstration
+    return {
+        device,
+        appStarted: !!result.output,
+        launchTimeMs: 1000,
+    };
+}
+export async function terminateIOSApp(bundleId, deviceId = "booted") {
+    validateBundleId(bundleId);
+    await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId);
+    const device = await getIOSDeviceMetadata(deviceId);
+    return {
+        device,
+        appTerminated: true
+    };
+}
+export async function restartIOSApp(bundleId, deviceId = "booted") {
+    // terminateIOSApp already validates bundleId
+    await terminateIOSApp(bundleId, deviceId);
+    const startResult = await startIOSApp(bundleId, deviceId);
+    return {
+        device: startResult.device,
+        appRestarted: startResult.appStarted,
+        launchTimeMs: startResult.launchTimeMs
+    };
+}
+export async function resetIOSAppData(bundleId, deviceId = "booted") {
+    validateBundleId(bundleId);
+    await terminateIOSApp(bundleId, deviceId);
+    const device = await getIOSDeviceMetadata(deviceId);
+    // Get data container path
+    const containerResult = await execCommand(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId);
+    const dataPath = containerResult.output.trim();
+    if (!dataPath) {
+        throw new Error(`Could not find data container for ${bundleId}`);
+    }
+    // Clear contents of Library and Documents
+    try {
+        const libraryPath = `${dataPath}/Library`;
+        const documentsPath = `${dataPath}/Documents`;
+        const tmpPath = `${dataPath}/tmp`;
+        await fs.rm(libraryPath, { recursive: true, force: true }).catch(() => { });
+        await fs.rm(documentsPath, { recursive: true, force: true }).catch(() => { });
+        await fs.rm(tmpPath, { recursive: true, force: true }).catch(() => { });
+        // Re-create empty directories as they are expected by apps
+        await fs.mkdir(libraryPath, { recursive: true }).catch(() => { });
+        await fs.mkdir(documentsPath, { recursive: true }).catch(() => { });
+        await fs.mkdir(tmpPath, { recursive: true }).catch(() => { });
+        return {
+            device,
+            dataCleared: true
+        };
+    }
+    catch (err) {
+        throw new Error(`Failed to clear data for ${bundleId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export async function getIOSLogs(appId, deviceId = "booted") {
+    // If appId is provided, use predicate filtering
+    // Note: execFile passes args directly, so we don't need shell escaping for the predicate string itself,
+    // but we do need to construct the predicate correctly for log show.
+    const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--last', '1m'];
+    if (appId) {
+        validateBundleId(appId);
+        args.push('--predicate', `subsystem contains "${appId}" or process == "${appId}"`);
+    }
+    const result = await execCommand(args, deviceId);
+    const device = await getIOSDeviceMetadata(deviceId);
+    const logs = result.output ? result.output.split('\n') : [];
+    return {
+        device,
+        logs,
+        logCount: logs.length,
+    };
+}
+export async function captureIOSScreenshot(deviceId = "booted") {
+    const device = await getIOSDeviceMetadata(deviceId);
+    const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`;
+    try {
+        // 1. Capture screenshot to temp file
+        await execCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId);
+        // 2. Read file as base64
+        const buffer = await fs.readFile(tmpFile);
+        const base64 = buffer.toString('base64');
+        // 3. Clean up
+        await fs.rm(tmpFile).catch(() => { });
+        return {
+            device,
+            screenshot: base64,
+            // Default resolution since we can't easily parse it without extra libs
+            // Clients will read the real dimensions from the PNG header anyway
+            resolution: { width: 0, height: 0 },
+        };
+    }
+    catch (err) {
+        // Ensure cleanup happens even on error
+        await fs.rm(tmpFile).catch(() => { });
+        throw new Error(`Failed to capture screenshot: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/server.js

@@ -2,16 +2,24 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { startAndroidApp, getAndroidLogs } from "./android.js";
-import { startIOSApp, getIOSLogs } from "./ios.js";
+import { startAndroidApp, getAndroidLogs, captureAndroidScreen, getAndroidDeviceMetadata, terminateAndroidApp, restartAndroidApp, resetAndroidAppData } from "./android.js";
+import { startIOSApp, getIOSLogs, captureIOSScreenshot, getIOSDeviceMetadata, terminateIOSApp, restartIOSApp, resetIOSAppData } from "./ios.js";
 const server = new Server({
     name: "mobile-debug-mcp",
-    version: "0.1.0"
+    version: "0.4.0"
 }, {
     capabilities: {
         tools: {}
     }
 });
+function wrapResponse(data) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            }]
+    };
+}
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
@@ -24,17 +32,43 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: "string",
                         enum: ["android", "ios"]
                     },
-                    id: {
+                    appId: {
                         type: "string",
                         description: "Android package name or iOS bundle id"
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected."
                     }
                 },
-                required: ["platform", "id"]
+                required: ["platform", "appId"]
             }
         },
         {
-            name: "get_logs",
-            description: "Get recent logs from Android or iOS simulator",
+            name: "terminate_app",
+            description: "Terminate a mobile app on Android or iOS simulator",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android", "ios"]
+                    },
+                    appId: {
+                        type: "string",
+                        description: "Android package name or iOS bundle id"
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected."
+                    }
+                },
+                required: ["platform", "appId"]
+            }
+        },
+        {
+            name: "restart_app",
+            description: "Restart a mobile app on Android or iOS simulator",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -42,16 +76,82 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: "string",
                         enum: ["android", "ios"]
                     },
-                    id: {
+                    appId: {
                         type: "string",
                         description: "Android package name or iOS bundle id"
                     },
+                    deviceId: {
+                        type: "string",
+                        description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected."
+                    }
+                },
+                required: ["platform", "appId"]
+            }
+        },
+        {
+            name: "reset_app_data",
+            description: "Reset app data (clear storage) for a mobile app on Android or iOS simulator",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android", "ios"]
+                    },
+                    appId: {
+                        type: "string",
+                        description: "Android package name or iOS bundle id"
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected."
+                    }
+                },
+                required: ["platform", "appId"]
+            }
+        },
+        {
+            name: "get_logs",
+            description: "Get recent logs from Android or iOS simulator. Returns device metadata and the log output.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android", "ios"]
+                    },
+                    appId: {
+                        type: "string",
+                        description: "Filter by Android package name or iOS bundle id"
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected."
+                    },
                     lines: {
                         type: "number",
                         description: "Number of log lines (android only)"
                     }
                 },
-                required: ["platform", "id"]
+                required: ["platform"]
+            }
+        },
+        {
+            name: "capture_screenshot",
+            description: "Capture a screenshot from an Android device or iOS simulator. Returns device metadata and the screenshot image.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android", "ios"]
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected."
+                    }
+                },
+                required: ["platform"]
             }
         }
     ]
@@ -60,21 +160,163 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
         if (name === "start_app") {
-            const { platform, id } = args;
-            const result = platform === "android"
-                ? await startAndroidApp(id)
-                : await startIOSApp(id);
-            return {
-                content: [{ type: "text", text: result }]
+            const { platform, appId, deviceId } = args;
+            let appStarted;
+            let launchTimeMs;
+            let deviceInfo;
+            if (platform === "android") {
+                const result = await startAndroidApp(appId, deviceId);
+                appStarted = result.appStarted;
+                launchTimeMs = result.launchTimeMs;
+                deviceInfo = await getAndroidDeviceMetadata(appId, deviceId);
+            }
+            else {
+                const result = await startIOSApp(appId, deviceId);
+                appStarted = result.appStarted;
+                launchTimeMs = result.launchTimeMs;
+                deviceInfo = await getIOSDeviceMetadata(deviceId);
+            }
+            const response = {
+                device: deviceInfo,
+                appStarted,
+                launchTimeMs
             };
+            return wrapResponse(response);
+        }
+        if (name === "terminate_app") {
+            const { platform, appId, deviceId } = args;
+            let appTerminated;
+            let deviceInfo;
+            if (platform === "android") {
+                const result = await terminateAndroidApp(appId, deviceId);
+                appTerminated = result.appTerminated;
+                deviceInfo = await getAndroidDeviceMetadata(appId, deviceId);
+            }
+            else {
+                const result = await terminateIOSApp(appId, deviceId);
+                appTerminated = result.appTerminated;
+                deviceInfo = await getIOSDeviceMetadata(deviceId);
+            }
+            const response = {
+                device: deviceInfo,
+                appTerminated
+            };
+            return wrapResponse(response);
+        }
+        if (name === "restart_app") {
+            const { platform, appId, deviceId } = args;
+            let appRestarted;
+            let launchTimeMs;
+            let deviceInfo;
+            if (platform === "android") {
+                const result = await restartAndroidApp(appId, deviceId);
+                appRestarted = result.appRestarted;
+                launchTimeMs = result.launchTimeMs;
+                deviceInfo = await getAndroidDeviceMetadata(appId, deviceId);
+            }
+            else {
+                const result = await restartIOSApp(appId, deviceId);
+                appRestarted = result.appRestarted;
+                launchTimeMs = result.launchTimeMs;
+                deviceInfo = await getIOSDeviceMetadata(deviceId);
+            }
+            const response = {
+                device: deviceInfo,
+                appRestarted,
+                launchTimeMs
+            };
+            return wrapResponse(response);
+        }
+        if (name === "reset_app_data") {
+            const { platform, appId, deviceId } = args;
+            let dataCleared;
+            let deviceInfo;
+            if (platform === "android") {
+                const result = await resetAndroidAppData(appId, deviceId);
+                dataCleared = result.dataCleared;
+                deviceInfo = await getAndroidDeviceMetadata(appId, deviceId);
+            }
+            else {
+                const result = await resetIOSAppData(appId, deviceId);
+                dataCleared = result.dataCleared;
+                deviceInfo = await getIOSDeviceMetadata(deviceId);
+            }
+            const response = {
+                device: deviceInfo,
+                dataCleared
+            };
+            return wrapResponse(response);
         }
         if (name === "get_logs") {
-            const { platform, id, lines } = args;
-            const logs = platform === "android"
-                ? await getAndroidLogs(id, lines ?? 200)
-                : await getIOSLogs();
+            const { platform, appId, deviceId, lines } = args;
+            let logs;
+            let deviceInfo;
+            if (platform === "android") {
+                deviceInfo = await getAndroidDeviceMetadata(appId || "", deviceId);
+                const response = await getAndroidLogs(appId, lines ?? 200, deviceId);
+                logs = Array.isArray(response.logs) ? response.logs : [];
+            }
+            else {
+                deviceInfo = await getIOSDeviceMetadata(deviceId);
+                const response = await getIOSLogs(appId, deviceId);
+                logs = Array.isArray(response.logs) ? response.logs : [];
+            }
+            // Filter crash lines (e.g. lines containing 'FATAL EXCEPTION') for internal or AI use
+            const crashLines = logs.filter(line => line.includes('FATAL EXCEPTION'));
+            // Return device metadata plus logs
             return {
-                content: [{ type: "text", text: logs }]
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            device: deviceInfo,
+                            result: {
+                                lines: logs.length,
+                                crashLines: crashLines.length > 0 ? crashLines : undefined
+                            }
+                        }, null, 2)
+                    },
+                    {
+                        type: "text",
+                        text: logs.join("\n")
+                    }
+                ]
+            };
+        }
+        if (name === "capture_screenshot") {
+            const { platform, deviceId } = args;
+            let screenshot;
+            let resolution;
+            let deviceInfo;
+            if (platform === "android") {
+                deviceInfo = await getAndroidDeviceMetadata("", deviceId);
+                const result = await captureAndroidScreen(deviceId);
+                screenshot = result.screenshot;
+                resolution = result.resolution;
+            }
+            else {
+                deviceInfo = await getIOSDeviceMetadata(deviceId);
+                const result = await captureIOSScreenshot(deviceId);
+                screenshot = result.screenshot;
+                resolution = result.resolution;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            device: deviceInfo,
+                            result: {
+                                resolution
+                            }
+                        }, null, 2)
+                    },
+                    {
+                        type: "image",
+                        data: screenshot,
+                        mimeType: "image/png"
+                    }
+                ]
             };
         }
     }

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to the **Mobile Debug MCP** project will be documented in this file.
+
+## [0.4.0] - 2026-03-09
+
+### Added
+- **`terminate_app` tool**: Added ability to terminate apps on Android and iOS.
+- **`restart_app` tool**: Added ability to restart apps (terminate + launch) in a single command.
+- **`reset_app_data` tool**: Added ability to clear app data/storage for fresh install testing.
+- **Unified `capture_screenshot` tool**: Replaces `capture_android_screen` and `capture_ios_screenshot` with a single cross-platform tool. Returns both metadata and image data.
+- **Environment Configuration**: Added support for `XCRUN_PATH` to configure iOS tools path (alongside existing `ADB_PATH`).
+- **Smoke Test**: Added `smoke-test.ts` for end-to-end verification of toolchain.
+
+### Security
+- **Shell Injection Prevention**: Refactored Android and iOS tools to use `execFile` with argument arrays instead of string concatenation, preventing potential shell injection attacks via malicious app IDs or inputs.
+
+### Changed
+- **Response Format**: Updated all tools to return JSON metadata within `text` content blocks (instead of invalid `application/json` type) to comply with MCP spec.
+- **iOS Device Metadata**: `get_logs` and `capture_screenshot` now return real device metadata (OS version, model) from the booted simulator instead of hardcoded values.
+- **Android Logging**: Improved `get_logs` reliability by removing dependency on `pidof` (which caused hangs) and using robust string-based filtering. Added timeouts to prevent infinite hangs.
+- **Docs**: Updated `README.md` with new tools and workflow recommendations.
+- **Docs**: Created `.github/copilot-instructions.md` to assist AI agents.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
+  "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
     "mobile-debug-mcp": "./dist/server.js"
@@ -14,6 +15,11 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "typescript": "^5.9.3"
   }
 }