mobile-debug-mcp 0.21.1 → 0.21.3

package/dist/utils/image.js

@@ -0,0 +1,18 @@
+export function parsePngSize(buf) {
+    try {
+        if (!buf || buf.length < 24)
+            return { width: 0, height: 0 };
+        // PNG signature + IHDR checks
+        if (buf.readUInt32BE(0) !== 0x89504e47 || buf.readUInt32BE(4) !== 0x0d0a1a0a)
+            return { width: 0, height: 0 };
+        const ihdr = buf.toString('ascii', 12, 16);
+        if (ihdr !== 'IHDR')
+            return { width: 0, height: 0 };
+        const width = buf.readUInt32BE(16);
+        const height = buf.readUInt32BE(20);
+        return { width, height };
+    }
+    catch {
+        return { width: 0, height: 0 };
+    }
+}

package/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.21.3]
+- Added structured logs
+
+## [0.21.2]
+- Fixed screenshots not working, imnproved tool
+
 ## [0.21.1]
 - Removed wait_for_element and renamed observe_until to wait_for_ui (obsolete references removed)
 

package/docs/tools/observe.md

@@ -3,27 +3,32 @@
 Tools that retrieve device state, logs, screenshots and UI hierarchies.
 
 ## get_logs
-Fetch recent logs from the app or device.
 
-Input:
+Fetch recent logs as structured entries optimized for AI agents.
+
+Input (example):
 
 ```json
-{ "platform": "android", "appId": "com.example.app", "deviceId": "emulator-5554", "lines": 200 }
+{ "platform": "android|ios", "appId": "com.example.app", "deviceId": "emulator-5554", "pid": 1234, "tag": "MyTag", "level": "ERROR", "contains": "timeout", "since_seconds": 60, "limit": 50 }
 ```
 
-Response (metadata):
+Defaults:
+
+- No filters → return the most recent 50 log entries (app-scoped if appId provided), across all levels.
+
+Response (structured):
 
 ```json
-{ "entries": 200, "crash_summary": { "crash_detected": false } }
+{ "device": { "platform": "android", "id": "emulator-5554" }, "logs": [ { "timestamp": "2026-03-30T16:00:00.000Z", "level": "ERROR", "tag": "MyTag", "pid": 1234, "message": "Something failed" } ], "count": 1, "filtered": true }
 ```
 
-Followed by a raw log plain text block.
-
 Notes:
-- Android log parsing includes basic crash detection (searching for "FATAL EXCEPTION" and exception names).
-- Use `lines` to control how many log lines are returned from `adb logcat`.
 
----
+- Each log entry: timestamp (ISO), level (VERBOSE|DEBUG|INFO|WARN|ERROR), tag (string), pid (number|null), message (string).
+- Logs ordered oldest → newest. count equals number of entries returned. filtered is true if any filter was applied.
+- Supported filters: pid, tag, level, contains, since_seconds, limit.
+- Platform behaviour: Android uses `adb logcat` with source-side filters where possible; iOS uses unified logging (`log show`/simctl) and maps subsystem/category → tag.
+- Errors are returned as structured objects with `error.code` and `error.message`. Possible codes: LOGS_UNAVAILABLE, INVALID_FILTER, PLATFORM_NOT_SUPPORTED, INTERNAL_ERROR.
 
 ## capture_screenshot
 Capture screen. Returns JSON metadata then an image/png block with base64 PNG data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.21.1",
+  "version": "0.21.3",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -27,7 +27,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "fast-xml-parser": "^5.5.1",
-    "zod": "^3.22.4"
+    "zod": "^3.22.4",
+    "sharp": "^0.32.1"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",

package/src/interact/index.ts

@@ -223,6 +223,16 @@ export class ToolsInteract {
     return await ToolsInteract.waitForUICore({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId })
   }
 
+  // Helper: normalize various log objects into plain message strings for comparison
+  private static _logsToMessages(logsArr: any[]): string[] {
+    if (!Array.isArray(logsArr)) return []
+    return logsArr.map((l: any) => {
+      if (typeof l === 'string') return l
+      if (l && (l.message || l.msg)) return l.message || l.msg
+      try { return JSON.stringify(l) } catch { return String(l) }
+    })
+  }
+
   static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }: { platform?: 'android' | 'ios', previousFingerprint: string, timeoutMs?: number, pollIntervalMs?: number, deviceId?: string }) {
     const start = Date.now()
     let lastFingerprint: string | null = null
@@ -279,7 +289,9 @@ export class ToolsInteract {
       if (fpRes && typeof fpRes === 'object') initialFingerprint = (fpRes as ScreenFingerprintResponse).fingerprint ?? null
       if (gl) {
         const logsArr = Array.isArray((gl as any).logs) ? (gl as any).logs : []
-        baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null
+        // Normalize to last message string for baseline comparison
+        const msgs = ToolsInteract._logsToMessages(logsArr)
+        baselineLastLine = msgs.length ? msgs[msgs.length - 1] : null
       }
     } catch (err) {
       try { console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
@@ -348,13 +360,15 @@ export class ToolsInteract {
 
             const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 }) as any
             const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : []
+            // Normalize to messages for comparison
+            const msgs = ToolsInteract._logsToMessages(logsArr)
             let startIndex = 0
             if (baselineLastLine) {
-              const idx = logsArr.lastIndexOf(baselineLastLine)
+              const idx = msgs.lastIndexOf(baselineLastLine)
               startIndex = idx >= 0 ? idx + 1 : 0
             }
-            for (let i = startIndex; i < logsArr.length; i++) {
-              const line = logsArr[i]
+            for (let i = startIndex; i < msgs.length; i++) {
+              const line = msgs[i]
               if (q && String(line).includes(q)) {
                 const now2 = Date.now()
                 return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true }

package/src/observe/android.ts

@@ -6,6 +6,7 @@ import { createWriteStream } from "fs"
 import { promises as fsPromises } from "fs"
 import path from "path"
 import { computeScreenFingerprint } from "../utils/ui/index.js"
+import { parsePngSize } from "../utils/image.js"
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 
@@ -92,26 +93,97 @@ export class AndroidObserve {
     }
   }
 
-  async getLogs(appId?: string, lines = 200, deviceId?: string): Promise<GetLogsResponse> {
+  async getLogs(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 stdout = await execAdb(['logcat', '-d', '-t', lines.toString(), '-v', 'threadtime'], deviceId)
-      const allLogs = stdout.split('\n')
-      
-      let filteredLogs = allLogs
+      const effectiveLimit = typeof limit === 'number' && limit > 0 ? limit : 50
+
+      // If appId provided, try to get pid to filter at source
+      let pidArg: string | null = null
       if (appId) {
-         const matchingLogs = allLogs.filter(line => line.includes(appId))
-         
-         if (matchingLogs.length > 0) {
-           filteredLogs = matchingLogs
-         } else {
-           filteredLogs = allLogs
-         }
+        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 { }
+        }
       }
-      
-      return { device: deviceInfo, logs: filteredLogs, logCount: filteredLogs.length }
+
+      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())
+
+      const stdout = await execAdb(args, deviceId)
+      const allLines = stdout ? stdout.split(/\r?\n/).filter(Boolean) : []
+
+      // Parse lines into structured entries
+      const parsed = allLines.map(l => {
+        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 || '' }
+      })
+
+      // 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))
+
+      return { device: deviceInfo, logs: limited, logCount: limited.length }
     } catch (e) {
       console.error("Error fetching logs:", e)
       return { device: deviceInfo, logs: [], logCount: 0 }
@@ -142,7 +214,7 @@ export class AndroidObserve {
         reject(new Error(`ADB screencap timed out after 10s`))
       }, 10000)
 
-      child.on('close', (code) => {
+      child.on('close', async (code) => {
         clearTimeout(timeout)
         if (code !== 0) {
           reject(new Error(stderr.trim() || `Screencap failed with code ${code}`))
@@ -152,28 +224,91 @@ export class AndroidObserve {
         const screenshotBuffer = Buffer.concat(chunks)
         const screenshotBase64 = screenshotBuffer.toString('base64')
 
-        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)
+        const parsed = parsePngSize(screenshotBuffer)
+        if (parsed.width > 0 && parsed.height > 0) {
+          // Attempt to convert to WebP (preferred) and provide JPEG fallback (awaited to avoid race)
+          try {
+            const sharpModule = await import('sharp'); const sharp = sharpModule && (sharpModule as any).default ? (sharpModule as any).default : sharpModule;
+            const buf = screenshotBuffer;
+            const img = sharp(buf);
+            const meta = await img.metadata().catch((err: any) => { console.error('sharp.metadata failed (Android):', err); return {} as any });
+            const hasAlpha = !!meta.hasAlpha || (meta.channels && meta.channels > 3);
+
+            let webpBuf: Buffer | null = null;
+            let jpegBuf: Buffer | null = null;
+            try {
+              webpBuf = await img.webp({ quality: 80 }).toBuffer();
+            } catch (err) {
+              console.error('WebP conversion failed (Android):', err instanceof Error ? err.message : String(err));
+              webpBuf = null;
+            }
+            try {
+              jpegBuf = await img.jpeg({ quality: 80 }).toBuffer();
+            } catch (err) {
+              console.error('JPEG conversion failed (Android):', err instanceof Error ? err.message : String(err));
+              jpegBuf = null;
+            }
+
+            if (hasAlpha) {
+              if (webpBuf) {
+                const webpB64 = webpBuf.toString('base64')
+                const jpegB64 = jpegBuf ? jpegBuf.toString('base64') : null
+                resolve({ device: deviceInfo, screenshot: webpB64, screenshot_mime: 'image/webp', screenshot_fallback: jpegB64, screenshot_fallback_mime: jpegB64 ? 'image/jpeg' : undefined, resolution: { width: parsed.width, height: parsed.height } } as any)
+                return
+              }
+              const pngB64 = buf.toString('base64')
+              resolve({ device: deviceInfo, screenshot: pngB64, screenshot_mime: 'image/png', resolution: { width: parsed.width, height: parsed.height } })
+              return
             }
-            resolve({
-              device: deviceInfo,
-              screenshot: screenshotBase64,
-              resolution: { width, height }
+
+            if (webpBuf) {
+              const webpB64 = webpBuf.toString('base64')
+              const jpegB64 = jpegBuf ? jpegBuf.toString('base64') : null
+              resolve({ device: deviceInfo, screenshot: webpB64, screenshot_mime: 'image/webp', screenshot_fallback: jpegB64, screenshot_fallback_mime: jpegB64 ? 'image/jpeg' : undefined, resolution: { width: parsed.width, height: parsed.height } } as any)
+              return
+            }
+
+            if (jpegBuf) {
+              resolve({ device: deviceInfo, screenshot: jpegBuf.toString('base64'), screenshot_mime: 'image/jpeg', resolution: { width: parsed.width, height: parsed.height } })
+              return
+            }
+
+            // No conversions succeeded; return original PNG
+            resolve({ device: deviceInfo, screenshot: screenshotBase64, screenshot_mime: 'image/png', resolution: { width: parsed.width, height: parsed.height } })
+            return
+          } catch (err) {
+            console.error('Screenshot conversion pipeline failed (Android):', err instanceof Error ? err.message : String(err));
+            // Conversion failed - fall back to original PNG with parsed resolution
+            resolve({ device: deviceInfo, screenshot: screenshotBase64, screenshot_mime: 'image/png', 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,
-              resolution: { width: 0, height: 0 }
+            .catch(() => {
+               resolve({
+                device: deviceInfo,
+                screenshot: screenshotBase64,
+                screenshot_mime: 'image/png',
+                resolution: { width: 0, height: 0 }
+              })
             })
-          })
+        }
       })
 
       child.on('error', (err) => {

package/src/observe/index.ts

@@ -38,18 +38,29 @@ export class ToolsObserve {
     return await (observe as AndroidObserve).getCurrentScreen(resolved.id)
   }
 
-  static async getLogsHandler({ platform, appId, deviceId, lines }: { platform?: 'android' | 'ios', appId?: string, deviceId?: string, lines?: number }) {
+  static async getLogsHandler({ platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines }: { platform?: 'android' | 'ios', appId?: string, deviceId?: string, pid?: number, tag?: string, level?: string, contains?: string, since_seconds?: number, limit?: number, lines?: number }) {
     const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId, appId)
+    const filters = { appId, deviceId: resolved.id, pid, tag, level, contains, since_seconds, limit: limit ?? lines }
+
+    // Validate filters
+    if (level && !['VERBOSE','DEBUG','INFO','WARN','ERROR'].includes(level.toString().toUpperCase())) {
+      return { device: resolved, logs: [], crashLines: [], logCount: 0, error: { code: 'INVALID_FILTER', message: `Unsupported level filter: ${level}` } } as any
+    }
+
     if (observe instanceof AndroidObserve) {
-      const response = await observe.getLogs(appId, lines ?? 200, resolved.id)
+      const response = await observe.getLogs(filters)
       const logs = Array.isArray(response.logs) ? response.logs : []
-      const crashLines = logs.filter(line => line.includes('FATAL EXCEPTION'))
-      return { device: response.device, logs, crashLines }
+      const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message))
+      const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds)
+      if (anyFilterApplied && logs.length === 0) return { device: response.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
+      return { device: response.device, logs, crashLines, logCount: response.logCount }
     } else {
-      const resp = await (observe as iOSObserve).getLogs(appId, resolved.id)
+      const resp = await (observe as iOSObserve).getLogs(filters)
       const logs = Array.isArray(resp.logs) ? resp.logs : []
-      const crashLines = logs.filter(l => l.includes('FATAL EXCEPTION'))
-      return { device: resp.device, logs, crashLines }
+      const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message))
+      const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds)
+      if (anyFilterApplied && logs.length === 0) return { device: resp.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
+      return { device: resp.device, logs, crashLines, logCount: resp.logCount }
     }
   }
 
@@ -96,7 +107,7 @@ export class ToolsObserve {
 
     // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
     const sid = sessionId || 'default'
-    const tasks = {
+    const tasks: Record<string, Promise<any>> = {
       screenshot: ToolsObserve.captureScreenshotHandler({ platform, deviceId }),
       currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
       fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
@@ -145,10 +156,20 @@ export class ToolsObserve {
         let entries: any[] = Array.isArray(out._streamEntries) ? out._streamEntries : []
         if (!entries || entries.length === 0) {
           const gl = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines: logLines })
-          const raw: string[] = (gl && (gl as any).logs) ? (gl as any).logs : []
-          entries = raw.slice(-Math.max(0, logLines)).map(line => {
-            const level = /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(line) ? 'ERROR' : /\b(WARN| W )\b/i.test(line) ? 'WARN' : 'INFO'
-            return { timestamp: null, level, message: line }
+          const raw: any[] = (gl && (gl as any).logs) ? (gl as any).logs : []
+          // raw may be structured entries or strings
+          entries = raw.slice(-Math.max(0, logLines)).map(item => {
+            if (!item) return { timestamp: null, level: 'INFO', message: '' }
+            if (typeof item === 'string') {
+              const level = /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(item) ? 'ERROR' : /\b(WARN| W )\b/i.test(item) ? 'WARN' : 'INFO'
+              return { timestamp: null, level, message: item }
+            }
+            const msg = item.message || item.msg || JSON.stringify(item)
+            const levelRaw = item.level || item.levelName || item._level || ''
+            const level = (levelRaw && String(levelRaw)).toUpperCase() || (/\bERROR\b/i.test(msg) ? 'ERROR' : /\bWARN\b/i.test(msg) ? 'WARN' : 'INFO')
+            const ts = item.timestamp || item._iso || null
+            const tsNum = (ts && typeof ts === 'string') ? (isNaN(new Date(ts).getTime()) ? null : new Date(ts).getTime()) : (typeof ts === 'number' ? ts : null)
+            return { timestamp: tsNum, level, message: msg }
           })
         } else {
           entries = entries.map(ent => {