mobile-debug-mcp 0.4.0 → 0.5.0

package/src/ios.ts

@@ -1,25 +1,243 @@
-import { exec } from "child_process"
+import { execFile, spawn } from "child_process"
+import { promises as fs } from "fs"
+import { pathToFileURL } from "url"
+import { StartAppResponse, GetLogsResponse, GetCrashResponse, CaptureIOSScreenshotResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, DeviceInfo } from "./types.js"
 
-export function startIOSApp(bundleId: string): Promise<string> {
+const XCRUN = process.env.XCRUN_PATH || "xcrun"
+
+interface IOSResult {
+  output: string
+  device: DeviceInfo
+}
+
+// Validate bundle ID to prevent any potential injection or invalid characters
+function validateBundleId(bundleId: string) {
+  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: string[], deviceId: string = "booted"): Promise<IOSResult> {
   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 } as DeviceInfo })
       }
-    )
+    })
+
+    child.on('error', (err) => {
+      clearTimeout(timeout)
+      reject(err)
+    })
   })
 }
 
-export function getIOSLogs(): Promise<string> {
-  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: string): string {
+  // 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: string = "booted"): Promise<DeviceInfo> {
+  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: DeviceInfo = {
+        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: string, deviceId: string = "booted"): Promise<StartAppResponse> {
+  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: string, deviceId: string = "booted"): Promise<TerminateAppResponse> {
+  validateBundleId(bundleId)
+  await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
+  const device = await getIOSDeviceMetadata(deviceId)
+  return {
+    device,
+    appTerminated: true
+  }
+}
+
+export async function restartIOSApp(bundleId: string, deviceId: string = "booted"): Promise<RestartAppResponse> {
+  // 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: string, deviceId: string = "booted"): Promise<ResetAppDataResponse> {
+  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?: string, deviceId: string = "booted"): Promise<GetLogsResponse> {
+  // 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: string = "booted"): Promise<CaptureIOSScreenshotResponse> {
+  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/src/server.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { Server } from "@modelcontextprotocol/sdk/server/index.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
@@ -5,13 +6,21 @@ import {
   CallToolRequestSchema
 } from "@modelcontextprotocol/sdk/types.js"
 
-import { startAndroidApp, getAndroidLogs } from "./android.js"
-import { startIOSApp, getIOSLogs } from "./ios.js"
+import {
+  StartAppResponse,
+  DeviceInfo,
+  TerminateAppResponse,
+  RestartAppResponse,
+  ResetAppDataResponse
+} from "./types.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: {
@@ -20,6 +29,15 @@ const server = new Server(
   }
 )
 
+function wrapResponse<T>(data: T) {
+  return {
+    content: [{
+      type: "text" as const,
+      text: JSON.stringify(data, null, 2)
+    }]
+  }
+}
+
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
@@ -32,17 +50,65 @@ 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: {
+          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: "reset_app_data",
+      description: "Reset app data (clear storage) for a mobile app on Android or iOS simulator",
       inputSchema: {
         type: "object",
         properties: {
@@ -50,16 +116,60 @@ 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: "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"]
       }
     }
   ]
@@ -70,35 +180,206 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   try {
     if (name === "start_app") {
-      const { platform, id } = args as {
+      const { platform, appId, deviceId } = args as {
         platform: "android" | "ios"
-        id: string
+        appId: string
+        deviceId?: string
       }
 
-      const result =
-        platform === "android"
-          ? await startAndroidApp(id)
-          : await startIOSApp(id)
+      let appStarted: boolean
+      let launchTimeMs: number
+      let deviceInfo: DeviceInfo
 
-      return {
-        content: [{ type: "text", text: result }]
+      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: StartAppResponse = {
+        device: deviceInfo,
+        appStarted,
+        launchTimeMs
+      }
+
+      return wrapResponse(response)
+    }
+
+    if (name === "terminate_app") {
+      const { platform, appId, deviceId } = args as {
+        platform: "android" | "ios"
+        appId: string
+        deviceId?: string
+      }
+
+      let appTerminated: boolean
+      let deviceInfo: 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: TerminateAppResponse = {
+        device: deviceInfo,
+        appTerminated
+      }
+
+      return wrapResponse(response)
+    }
+
+    if (name === "restart_app") {
+      const { platform, appId, deviceId } = args as {
+        platform: "android" | "ios"
+        appId: string
+        deviceId?: string
+      }
+
+      let appRestarted: boolean
+      let launchTimeMs: number
+      let deviceInfo: 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: RestartAppResponse = {
+        device: deviceInfo,
+        appRestarted,
+        launchTimeMs
       }
+
+      return wrapResponse(response)
+    }
+
+    if (name === "reset_app_data") {
+      const { platform, appId, deviceId } = args as {
+        platform: "android" | "ios"
+        appId: string
+        deviceId?: string
+      }
+
+      let dataCleared: boolean
+      let deviceInfo: 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: ResetAppDataResponse = {
+        device: deviceInfo,
+        dataCleared
+      }
+
+      return wrapResponse(response)
     }
 
     if (name === "get_logs") {
-      const { platform, id, lines } = args as {
+      const { platform, appId, deviceId, lines } = args as {
         platform: "android" | "ios"
-        id: string
+        appId?: string
+        deviceId?: string
         lines?: number
       }
 
-      const logs =
-        platform === "android"
-          ? await getAndroidLogs(id, lines ?? 200)
-          : await getIOSLogs()
+      let logs: string[]
+      let deviceInfo: 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 as { platform: "android" | "ios"; deviceId?: string }
+
+      let screenshot: string
+      let resolution: { width: number; height: number }
+      let deviceInfo: 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"
+          }
+        ]
       }
     }
   } catch (error) {