mobile-debug-mcp 0.33.0 → 0.35.0

package/src/observe/android/logs.ts

@@ -0,0 +1,110 @@
+import type { LogFilters } from '../logs/model.js'
+import type { StructuredLogEntry } from '../../types.js'
+import { GetLogsResponse } from "../../types.js"
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo, parseLogLine } from "../../utils/android/utils.js"
+export async function collectGetLogs(filters: { appId?: string, deviceId?: string, pid?: number, tag?: string, level?: string, contains?: string, since_seconds?: number, limit?: number } = {}): Promise<GetLogsResponse> {
+  const { appId, deviceId, pid, tag, level, contains, since_seconds, limit } = filters
+  const metadata = await getAndroidDeviceMetadata(appId || "", deviceId)
+  const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+  try {
+    const effectiveLimit = typeof limit === 'number' && limit > 0 ? limit : 50
+
+    const { pidArg, args } = await logcatArguments(filters, effectiveLimit)
+    const stdout = await execAdb(args, deviceId)
+    const allLines = stdout ? stdout.split(/\r?\n/).filter(Boolean) : []
+
+    // Parse lines into structured entries
+    const parsed = allLines.map(line => parseAndroidLog(line, pidArg))
+
+    // Apply client-side filters: contains, since_seconds
+    let filtered = parsed
+    if (contains) filtered = filtered.filter(e => e.message && e.message.includes(contains))
+
+    if (since_seconds) {
+      const sinceMs = Date.now() - (since_seconds * 1000)
+      filtered = filtered.filter(e => {
+        if (!e.timestamp) return false
+        const t = new Date(e.timestamp).getTime()
+        return t >= sinceMs
+      })
+    }
+
+    // If appId provided and no pidArg, try to filter by appId substring in message/tag
+    if (appId && !pidArg) {
+      const matched = filtered.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)))
+      if (matched.length > 0) filtered = matched
+    }
+
+    // Ensure ordering oldest -> newest (by timestamp when available)
+    filtered.sort((a, b) => {
+      const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0
+      const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0
+      return ta - tb
+    })
+
+    const limited = filtered.slice(-Math.max(0, effectiveLimit))
+
+    const source = pidArg ? 'pid' : (appId ? 'package' : 'broad')
+    const meta = { pidArg, appIdProvided: !!appId, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid }
+    return { device: deviceInfo, logs: limited, logCount: limited.length, source, meta }
+  } catch (e) {
+    console.error("Error fetching logs:", e)
+    return { device: deviceInfo, logs: [], logCount: 0, source: 'broad', meta: { error: e instanceof Error ? e.message : String(e) } }
+  }
+}
+
+function parseAndroidLog(l: string, pidArg: string | null): StructuredLogEntry {
+  const entry = parseLogLine(l)
+  // normalize level
+  const levelChar = (entry.level || '').toUpperCase()
+  const levelMapChar: Record<string, string> = { 'V': 'VERBOSE', 'D': 'DEBUG', 'I': 'INFO', 'W': 'WARN', 'E': 'ERROR' }
+  const normLevel = levelMapChar[levelChar] || (entry.level && String(entry.level).toUpperCase()) || 'INFO'
+  const iso = entry._iso || (() => {
+    const d = new Date(entry.timestamp || '')
+    if (!isNaN(d.getTime())) return d.toISOString()
+    return null
+  })()
+  let pidNum: number | null = null
+  if (entry.pid) pidNum = Number(entry.pid)
+  else if (pidArg) pidNum = Number(pidArg)
+  const pidVal = (pidNum !== null && !isNaN(pidNum)) ? pidNum : null
+  return { timestamp: iso, level: normLevel, tag: entry.tag || '', pid: pidVal, message: entry.message || '' }
+}
+
+async function logcatArguments(filters: LogFilters, effectiveLimit: number) {
+  const { appId, deviceId, pid, tag, level } = filters
+  // If appId provided, try to get pid to filter at source
+  let pidArg: string | null = null
+  if (appId) {
+    try {
+      const pidOut = await execAdb(['shell', 'pidof', appId], deviceId).catch(() => '')
+      const pidTrim = (pidOut || '').trim()
+      if (pidTrim) pidArg = pidTrim.split('\n')[0]
+    } catch (err) {
+      // Log a warning so failures to detect PID are visible during debugging
+      try { console.warn(`getLogs: pid detection failed for appId=${appId}:`, err instanceof Error ? err.message : String(err)) } catch { }
+    }
+  }
+
+  const args = ['logcat', '-d', '-v', 'threadtime']
+  // Apply pid filter via --pid if available
+  if (pidArg) args.push(`--pid=${pidArg}`)
+  else if (pid) args.push(`--pid=${pid}`)
+
+  // Apply tag/level filter if provided
+  if (tag && level) {
+    // Map verbose/debug/info/warn/error to single-letter levels
+    const levelMap: Record<string, string> = { 'VERBOSE': 'V', 'DEBUG': 'D', 'INFO': 'I', 'WARN': 'W', 'ERROR': 'E' }
+    const L = (levelMap[(level || '').toUpperCase()] || 'V')
+    args.push(`${tag}:${L}`)
+  } else {
+    // Default: show all levels
+    args.push('*:V')
+  }
+
+  // Use -t to limit lines (apply early)
+  args.push('-t', effectiveLimit.toString())
+
+  return { pidArg, args }
+}

package/src/observe/android/screenshot.ts

@@ -0,0 +1,79 @@
+import { encodeScreenshot } from '../screenshot-encoding.js'
+import { spawn } from "child_process"
+import { CaptureAndroidScreenResponse, DeviceInfo } from "../../types.js"
+import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../../utils/android/utils.js"
+import { parsePngSize } from "../../utils/image.js"
+export async function collectCaptureScreen(deviceId?: string): Promise<CaptureAndroidScreenResponse> {
+  const metadata = await getAndroidDeviceMetadata("", deviceId)
+  const deviceInfo: DeviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+  return new Promise((resolve, reject) => {
+    const args = deviceId ? ['-s', deviceId, 'exec-out', 'screencap', '-p'] : ['exec-out', 'screencap', '-p'];
+    const child = spawn(getAdbCmd(), args)
+
+    const chunks: Buffer[] = []
+    let stderr = ''
+
+    child.stdout.on('data', (chunk) => {
+      chunks.push(Buffer.from(chunk))
+    })
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString()
+    })
+
+    const timeout = setTimeout(() => {
+      child.kill()
+      reject(new Error(`ADB screencap timed out after 10s`))
+    }, 10000)
+
+    child.on('close', async (code) => {
+      clearTimeout(timeout)
+      if (code !== 0) {
+        reject(new Error(stderr.trim() || `Screencap failed with code ${code}`))
+        return
+      }
+
+      const screenshotBuffer = Buffer.concat(chunks)
+      const screenshotBase64 = screenshotBuffer.toString('base64')
+
+      const parsed = parsePngSize(screenshotBuffer)
+      if (parsed.width > 0 && parsed.height > 0) {
+        const encoded = await encodeScreenshot(screenshotBuffer, 'android')
+        resolve({ device: deviceInfo, ...encoded, resolution: { width: parsed.width, height: parsed.height } })
+        return
+      } else {
+        // Fallback to querying wm size if parsing failed
+        execAdb(['shell', 'wm', 'size'], deviceId)
+          .then(sizeStdout => {
+            let width = 0
+            let height = 0
+            const match = sizeStdout.match(/Physical size: (\d+)x(\d+)/)
+            if (match) {
+              width = parseInt(match[1], 10)
+              height = parseInt(match[2], 10)
+            }
+            resolve({
+              device: deviceInfo,
+              screenshot: screenshotBase64,
+              screenshot_mime: 'image/png',
+              resolution: { width, height }
+            })
+          })
+          .catch(() => {
+            resolve({
+              device: deviceInfo,
+              screenshot: screenshotBase64,
+              screenshot_mime: 'image/png',
+              resolution: { width: 0, height: 0 }
+            })
+          })
+      }
+    })
+
+    child.on('error', (err) => {
+      clearTimeout(timeout)
+      reject(err)
+    })
+  })
+}

package/src/observe/android/ui-tree.ts

@@ -0,0 +1,113 @@
+import { XMLParser } from "fast-xml-parser"
+import { GetUITreeResponse, UIElement } from "../../types.js"
+import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode } from "../../utils/android/utils.js"
+import { deriveSnapshotMetadata } from "../snapshot-metadata.js"
+import { remainingBudget } from '../../utils/operation-budget.js'
+import { createObservationMeasurement } from '../performance-metrics.js'
+export async function collectGetUITree(deviceId?: string): Promise<GetUITreeResponse> {
+  const measurement = createObservationMeasurement('android')
+  let metadata
+  try {
+    metadata = await measurement.timed('metadata_ms', () => getAndroidDeviceMetadata("", deviceId))
+  } catch (error) {
+    measurement.setOutcome('unavailable')
+    measurement.finish()
+    throw error
+  }
+  const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+  try {
+    // Get screen resolution first
+    const resolution = await measurement.timed('resolution_ms', () => getScreenResolution(deviceId));
+    if (resolution.width === 0 && resolution.height === 0) {
+      throw new Error("Failed to get screen resolution. Is the device connected and authorized?");
+    }
+
+    const xmlContent = await readAndroidTree(deviceId, measurement)
+    const parser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: "@_"
+    });
+    const result = await measurement.timed('parse_ms', async () => parser.parse(xmlContent));
+
+    const elements: UIElement[] = [];
+
+    // The root is usually hierarchy -> node
+    if (result.hierarchy && result.hierarchy.node) {
+      // If the root is an array (unlikely for root, but good to be safe) or single object
+      if (Array.isArray(result.hierarchy.node)) {
+        result.hierarchy.node.forEach((n: Parameters<typeof traverseNode>[0]) => traverseNode(n, elements));
+      } else {
+        traverseNode(result.hierarchy.node, elements);
+      }
+    }
+
+    const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, {
+      screen: "",
+      resolution,
+      elements
+    }, 'ui_tree')
+
+    measurement.setOutcome('observed')
+    const response = measurement.bindObservation({
+      device: deviceInfo,
+      screen: "",
+      resolution,
+      elements,
+      ...snapshotMetadata
+    })
+    measurement.finish()
+    return response
+  } catch (e) {
+    const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
+    console.error(errorMessage);
+    const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, null, 'ui_tree')
+    measurement.setOutcome('unavailable')
+    measurement.finish()
+    return {
+      device: deviceInfo,
+      screen: "",
+      resolution: { width: 0, height: 0 },
+      elements: [],
+      ...snapshotMetadata,
+      error: errorMessage
+    };
+  }
+}
+
+async function readAndroidTree(deviceId: string | undefined, measurement: ReturnType<typeof createObservationMeasurement>) {
+  // Retry Logic
+  let xmlContent = '';
+  let attempts = 0;
+  const maxAttempts = 3;
+
+  while (attempts < maxAttempts) {
+    remainingBudget()
+    attempts++;
+    try {
+      // The first read starts immediately so it remains fresh for in-place UI changes.
+      // Delay only a retry after a failed or invalid acquisition.
+      if (attempts > 1) {
+        await measurement.timed('observation_wait_ms', () => delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))));
+      }
+      remainingBudget()
+
+      xmlContent = await measurement.physicalRead(async () => {
+        await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId)
+        const content = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId)
+        if (!content || !content.trim() || content.includes('ERROR:')) throw new Error('Empty or invalid UI dump')
+        return content
+      })
+      break
+    } catch (e) {
+      if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
+      console.error(`Attempt ${attempts} failed: ${e}`);
+    }
+
+    if (attempts === maxAttempts) {
+      throw new Error(`Failed to retrieve valid UI dump after ${maxAttempts} attempts.`);
+    }
+  }
+
+  return xmlContent
+}