mobile-debug-mcp 0.30.2 → 0.32.0

package/test/unit/observe/capture_debug_snapshot.test.ts

@@ -83,6 +83,12 @@ async function run() {
     assert.ok(pass3, 'captureDebugSnapshot should return an empty logs array when includeLogs is false')
     console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
 
+    let screenshotCalls = 0
+    ;(ToolsObserve as any).captureScreenshotHandler = async function() { screenshotCalls++; return { screenshot: 'unexpected' } }
+    const res4: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false, includeScreenshot: false })
+    assert.strictEqual(screenshotCalls, 0, 'includeScreenshot=false must not invoke screenshot capture')
+    assert.strictEqual(res4.raw.screenshot, null)
+
   } finally {
     ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
     ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler

package/test/unit/observe/snapshot_metadata.test.ts

@@ -1,5 +1,5 @@
 import assert from 'assert'
-import { deriveSnapshotMetadata, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { deriveSnapshotMetadata, getStateDelta, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
 
 async function run() {
   console.log('Starting snapshot_metadata unit tests...')
@@ -57,6 +57,25 @@ async function run() {
     total_elements: 1
   })
 
+  const delta = getStateDelta(deviceKey, 1, 2)
+  assert.ok(delta)
+  assert.strictEqual(delta!.added.length, 0)
+  assert.strictEqual(delta!.removed.length, 0)
+  assert.strictEqual(delta!.changed.length, 1)
+  assert.strictEqual(delta!.changed[0].text, 'Beta')
+  assert.strictEqual(delta!.truncated, false)
+  assert.strictEqual(getStateDelta(deviceKey, 99, 2), null)
+
+  for (let index = 3; index <= 10; index++) {
+    deriveSnapshotMetadata(deviceKey, {
+      screen: 'Home',
+      resolution: { width: 100, height: 200 },
+      elements: [{ text: `Revision ${index}`, stable_id: 'stable-row', visible: true }]
+    }, 'ui_tree')
+  }
+  assert.ok(getStateDelta(deviceKey, 3, 10), 'recent revisions remain available after pruning')
+  assert.strictEqual(getStateDelta(deviceKey, 2, 10), null, 'only the oldest revision is pruned')
+
   resetSnapshotMetadataForTests()
   console.log('snapshot_metadata unit tests passed')
 }

package/test/unit/observe/state_delta.test.ts

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict'
+import { deriveSnapshotMetadata, getStateDelta, getLatestStateDelta, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+resetSnapshotMetadataForTests()
+const tree = (text: string) => ({ elements: [{ stable_id: 'one', text }, { stable_id: 'unchanged', text: 'fixed' }] }) as any
+const first = deriveSnapshotMetadata('android:test', tree('before'), 'test')
+const second = deriveSnapshotMetadata('android:test', tree('after'), 'test')
+const delta = getStateDelta('android:test', first.snapshot_revision, second.snapshot_revision)!
+assert.equal(delta.changed.length, 1)
+assert.equal(delta.changed[0].text, 'after')
+deriveSnapshotMetadata('android:test', tree('after'), 'test')
+assert.equal(getLatestStateDelta('android:test')!.changed.length, 0)
+const large = { elements: Array.from({ length: 501 }, (_, i) => ({ stable_id: String(i), text: String(i) })) } as any
+const third = deriveSnapshotMetadata('android:test', large, 'test')
+assert.equal(getStateDelta('android:test', second.snapshot_revision, third.snapshot_revision)!.truncated, true)
+assert.equal(getStateDelta('android:test', -1, third.snapshot_revision), null)

package/test/unit/server/benchmark_report.test.ts

@@ -0,0 +1,4 @@
+import assert from 'node:assert/strict'
+import { summarize } from '../../device/automated/latency/report.js'
+assert.equal(summarize([]), null)
+assert.deepEqual(summarize([10, 1, 8, 2, 9, 3, 7, 4, 6, 5]), { count: 10, p50: 5, p95: 10, min: 1, max: 10 })

package/test/unit/server/contract.test.ts

@@ -49,7 +49,7 @@ async function run() {
 
   const tapElement = toolDefinitions.find((tool) => tool.name === 'tap_element')
   assert(tapElement, 'tap_element should be registered')
-  assert.deepStrictEqual((tapElement as any).inputSchema.required, ['elementId'])
+  assert.deepStrictEqual((tapElement as any).inputSchema.oneOf, [{ required: ['elementId'], not: { required: ['selector'] } }, { required: ['selector'], not: { required: ['elementId'] } }])
   assert.match((tapElement as any).description, /RESOLVE → ACT → WAIT \(if needed\) → EXPECT/)
   assert.match((tapElement as any).description, /If needed, wait for transition using wait_for_\*/)
   assert.match((tapElement as any).description, /Verify outcome using expect_\*/)

package/test/unit/server/interaction_modes.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { AndroidManage } from '../../../src/manage/android.js'
+import { markDispatchStarted } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const treeOriginal = ToolsObserve.getUITreeHandler
+  const fingerprintOriginal = ToolsObserve.getScreenFingerprintHandler
+  const tapOriginal = ToolsInteract.tapHandler
+  const launchOriginal = AndroidManage.prototype.startApp
+  const device: any = { platform: 'android', id: 'fixture' }
+  let dispatched = false
+  let postReads = 0
+  let fingerprints = 0
+  ToolsObserve.getUITreeHandler = async () => {
+    if (dispatched) postReads++
+    return { device, elements: [{ text: 'Go', stable_id: 'go', bounds: [0, 0, 40, 40], visible: true, enabled: true, clickable: true }] } as any
+  }
+  ToolsObserve.getScreenFingerprintHandler = async () => { fingerprints++; return { fingerprint: 'fixture' } as any }
+  ToolsInteract.tapHandler = async () => { dispatched = true; return { success: true, device } as any }
+  AndroidManage.prototype.startApp = async () => { dispatched = true; return { appStarted: true, device } as any }
+  try {
+    for (const tool of ['tap_element', 'start_app']) {
+      for (const mode of ['none', 'light', 'full']) {
+        dispatched = false; postReads = 0; fingerprints = 0
+        const response = await handleToolCall(tool, { platform: 'android', deviceId: 'fixture', ...(tool === 'tap_element' ? { selector: { text: 'Go' } } : { appId: 'fixture' }), verificationMode: mode, responseMode: 'compact' })
+        const result = JSON.parse(response.content[0].text!)
+        assert.equal(result.success, true, JSON.stringify(result))
+        assert.equal(postReads, mode === 'light' ? 1 : 0)
+        assert.equal(fingerprints, mode === 'full' ? 2 : 0)
+        assert.equal(result.device, undefined)
+        assert.equal(result.trace, undefined)
+        assert.equal(result.dispatch_started, true)
+        assert.deepEqual(Object.keys(result.timing), ['total_ms'])
+        if (mode !== 'full') assert.equal(result.lifecycle_state, 'pending_verification')
+      }
+    }
+    ToolsObserve.getUITreeHandler = async () => { throw new Error('offline') }
+    const result = JSON.parse((await handleToolCall('start_app', { platform: 'android', appId: 'fixture', verificationMode: 'light', responseMode: 'compact' })).content[0].text!)
+    assert.equal(result.success, true)
+    assert.equal(result.verification.status, 'unavailable')
+    assert.equal(result.verification_diagnostic.retryable, true)
+    ToolsInteract.tapHandler = async () => { markDispatchStarted(); dispatched = true; return { success: false, error: 'ACTION_TIMEOUT', device } as any }
+    const timedOut = JSON.parse((await handleToolCall('tap', { platform: 'android', deviceId: 'fixture', x: 1, y: 1, verificationMode: 'none', responseMode: 'compact' })).content[0].text!)
+    assert.equal(timedOut.failure_code, 'ACTION_TIMEOUT')
+    assert.equal(timedOut.delivery_status, 'unknown')
+    assert.equal(timedOut.retryable, false)
+    AndroidManage.prototype.startApp = async () => ({ appStarted: false, device, error: 'launch failed', diagnostics: { runResult: { exitCode: 1, stdout: '', stderr: 'launch failed' } } } as any)
+    const failedLaunch = JSON.parse((await handleToolCall('start_app', { platform: 'android', appId: 'fixture' })).content[0].text!)
+    assert.equal(failedLaunch.details.diagnostics.runResult.exitCode, 1)
+  } finally {
+    ToolsObserve.getUITreeHandler = treeOriginal
+    ToolsObserve.getScreenFingerprintHandler = fingerprintOriginal
+    ToolsInteract.tapHandler = tapOriginal
+    AndroidManage.prototype.startApp = launchOriginal
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/operation_budget.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import { runWithBudget, remainingBudget, markDispatchStarted } from '../../../src/utils/operation-budget.js'
+import { execCmd } from '../../../src/utils/exec.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  await runWithBudget(100, async budget => {
+    assert.equal(budget.dispatchStarted, false)
+    markDispatchStarted()
+    assert.equal(budget.dispatchStarted, true)
+    const response = await execCmd(process.execPath, ['-e', 'setTimeout(() => {}, 10000)'])
+    assert.equal(response.stderr, 'ACTION_TIMEOUT')
+    assert.throws(() => remainingBudget(), /ACTION_TIMEOUT/)
+  })
+  await runWithBudget(1, async budget => {
+    await new Promise(resolve => setTimeout(resolve, 5))
+    assert.throws(() => markDispatchStarted(), /ACTION_TIMEOUT/)
+    assert.equal(budget.dispatchStarted, false)
+  })
+  const originalTree = ToolsObserve.getUITreeHandler
+  ToolsObserve.getUITreeHandler = async () => { throw new Error('transient observation error') }
+  try {
+    await assert.rejects(
+      () => runWithBudget(30, () => ToolsInteract.waitForUIHandler({ selector: { text: 'missing' }, timeout_ms: 1000, poll_interval_ms: 5, platform: 'android', deviceId: 'fixture' })),
+      /ACTION_TIMEOUT/
+    )
+  } finally {
+    ToolsObserve.getUITreeHandler = originalTree
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/response_shapes.test.ts

@@ -37,7 +37,7 @@ async function run() {
 
     const missingBuildResponse = await handleToolCall('build_app', { projectPath: '/tmp/project' })
     const missingBuildPayload = JSON.parse((missingBuildResponse as any).content[0].text)
-    assert.deepStrictEqual(missingBuildPayload, {
+    assert.deepStrictEqual({ error: missingBuildPayload.error }, {
       error: {
         tool: 'build_app',
         message: 'Missing or invalid string argument: platform'
@@ -236,7 +236,7 @@ async function run() {
     const failingTapResponse = await handleToolCall('tap', { platform: 'android', x: 1, y: 2 })
     assert.strictEqual((failingTapResponse as any).content.length, 1)
     const failingTapPayload = JSON.parse((failingTapResponse as any).content[0].text)
-    assert.deepStrictEqual(failingTapPayload, {
+    assert.deepStrictEqual({ error: failingTapPayload.error }, {
       error: {
         tool: 'tap',
         message: 'boom'
@@ -255,7 +255,7 @@ async function run() {
 
     const missingArgResponse = await handleToolCall('tap', { platform: 'android', x: 1 })
     const missingArgPayload = JSON.parse((missingArgResponse as any).content[0].text)
-    assert.deepStrictEqual(missingArgPayload, {
+    assert.deepStrictEqual({ error: missingArgPayload.error }, {
       error: {
         tool: 'tap',
         message: 'Missing or invalid number argument: y'

package/test/unit/server/run_journey.test.ts

@@ -0,0 +1,90 @@
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import assert from 'assert'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  const originalWait = (ToolsInteract as any).waitForUIHandler
+  const originalExpectVisible = (ToolsInteract as any).expectElementVisibleHandler
+  const originalTap = (ToolsInteract as any).tapElementHandler
+  const originalTree = (ToolsObserve as any).getUITreeHandler
+  let resolutions = 0
+  _setDeviceListersForTests({ listAndroidDevices: async () => { resolutions++; return [{ id: 'fixture', platform: 'android' } as any] } })
+  try {
+    const calls: string[] = []
+    ;(ToolsInteract as any).waitForUIHandler = async () => {
+      calls.push('wait')
+      return { status: 'success', element: { elementId: 'ready' } }
+    }
+    ;(ToolsInteract as any).expectElementVisibleHandler = async () => {
+      calls.push('assert')
+      return { success: false, failure_code: 'TIMEOUT' }
+    }
+
+    const response: any = await handleToolCall('run_journey', {
+      platform: 'android',
+      steps: [
+        { id: 'wait-ready', type: 'wait', selector: { text: 'Ready' } },
+        { id: 'assert-ready', type: 'assert', assertion: { kind: 'element_visible', selector: { text: 'Ready' } } },
+        { id: 'not-run', type: 'wait', selector: { text: 'Later' } }
+      ]
+    })
+    const result = JSON.parse(response.content[0].text)
+    assert.strictEqual(resolutions, 1)
+    assert.deepStrictEqual(calls, ['wait', 'assert'])
+    await handleToolCall('run_journey', { platform: 'android', steps: [{ id: 'valid', type: 'wait', selector: { text: 'Ready' } }, { id: 'bad', type: 'tap' }] })
+    assert.strictEqual(resolutions, 1, 'Invalid later steps must fail before device work')
+    assert.deepStrictEqual(calls, ['wait', 'assert'])
+    assert.strictEqual(result.success, false)
+    assert.strictEqual(result.stopped_at_step_id, 'assert-ready')
+    assert.strictEqual(result.steps[0].status, 'passed')
+    assert.strictEqual(result.steps[1].status, 'failed')
+    assert.deepStrictEqual(result.steps[2], {
+      id: 'not-run', type: 'wait', status: 'not_run', success: false,
+      reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 }
+    })
+
+    let postActionReads = 0
+    ;(ToolsObserve as any).getUITreeHandler = async () => { postActionReads++; throw new Error('Unexpected duplicate observation') }
+    ;(ToolsInteract as any).waitForUIHandler = async () => ({ status: 'success', element: { elementId: 'target' }, _tree: {} })
+    ;(ToolsInteract as any).tapElementHandler = async (args: any) => {
+      assert.strictEqual(args.verificationMode, 'none')
+      return { success: true, action_id: 'tap', action_type: 'tap_element' }
+    }
+    ;(ToolsInteract as any).expectElementVisibleHandler = async () => ({ success: true, observed: { matched_count: 1 } })
+    const lightResponse: any = await handleToolCall('run_journey', {
+      platform: 'android', responseMode: 'compact', defaults: { verificationMode: 'light' },
+      steps: [
+        { id: 'tap-target', type: 'tap', selector: { accessibility_id: 'target' } },
+        { id: 'assert-result', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'result' } } }
+      ]
+    })
+    const light = JSON.parse(lightResponse.content[0].text)
+    assert.strictEqual(light.success, true)
+    assert.deepStrictEqual(Object.keys(light.timing), ['total_ms'])
+    assert.deepStrictEqual(light.steps[0].result.verification, { mode: 'light', status: 'observed' })
+    assert.strictEqual(light.steps[0].result.verification_diagnostic, undefined)
+    assert.strictEqual(postActionReads, 0, 'The following assertion supplies the fresh observation')
+    ;(ToolsInteract as any).expectElementVisibleHandler = async () => ({ success: false, failure_code: 'TIMEOUT', observed: { matched_count: 0 } })
+    const failedAssertionResponse: any = await handleToolCall('run_journey', {
+      platform: 'android', responseMode: 'compact', defaults: { verificationMode: 'light' },
+      steps: [
+        { id: 'tap-target', type: 'tap', selector: { accessibility_id: 'target' } },
+        { id: 'assert-result', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'result' } } }
+      ]
+    })
+    const failedAssertion = JSON.parse(failedAssertionResponse.content[0].text)
+    assert.strictEqual(failedAssertion.success, false)
+    assert.deepStrictEqual(failedAssertion.steps[0].result.verification, { mode: 'light', status: 'observed' })
+    assert.strictEqual(postActionReads, 0)
+  } finally {
+    _resetDeviceListersForTests()
+    ;(ToolsInteract as any).waitForUIHandler = originalWait
+    ;(ToolsInteract as any).expectElementVisibleHandler = originalExpectVisible
+    ;(ToolsInteract as any).tapElementHandler = originalTap
+    ;(ToolsObserve as any).getUITreeHandler = originalTree
+  }
+}
+
+run().catch((error) => { console.error(error); process.exit(1) })

package/test/unit/server/tap_selector.test.ts

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+
+async function run() {
+  const originalWait = ToolsInteract.waitForUIHandler
+  const originalTap = ToolsInteract.tapElementHandler
+  let tapCount = 0
+  let lastWait: any
+  let resolution: any
+  ToolsInteract.waitForUIHandler = async (args: any) => { lastWait = args; return resolution }
+  ToolsInteract.tapElementHandler = async (args: any) => {
+    tapCount++
+    assert.equal(args.elementId, 'selected')
+    assert.deepEqual(args.freshTree, { elements: [] })
+    return { action_id: 'tap', action_type: 'tap_element', success: true, lifecycle_state: 'pending_verification' } as any
+  }
+  try {
+    const selector = { accessibility_id: 'save' }
+    resolution = { status: 'success', element: { elementId: 'selected' }, _tree: { elements: [] } }
+    const success = JSON.parse((await handleToolCall('tap_element', {
+      selector, platform: 'android', verificationMode: 'none', responseMode: 'compact'
+    })).content[0].text!)
+    assert.equal(success.success, true)
+    assert.equal(tapCount, 1)
+    assert.equal(lastWait.condition, 'clickable')
+    assert.equal(lastWait.singleObservation, true)
+    assert.equal(lastWait.singleAttempt, true)
+    assert.equal(lastWait.rejectAmbiguous, true)
+
+    await handleToolCall('tap_element', {
+      selector, waitFor: { condition: 'visible', timeoutMs: 700, pollIntervalMs: 80 },
+      platform: 'android', verificationMode: 'none', responseMode: 'compact'
+    })
+    assert.equal(lastWait.condition, 'visible')
+    assert.equal(lastWait.timeout_ms, 700)
+    assert.equal(lastWait.poll_interval_ms, 80)
+    assert.equal(lastWait.singleAttempt, false)
+    assert.equal(lastWait.rejectAmbiguous, false)
+    assert.equal(tapCount, 2)
+
+    resolution = { status: 'timeout', error: { code: 'AMBIGUOUS_TARGET' } }
+    const ambiguous = JSON.parse((await handleToolCall('tap_element', {
+      selector, platform: 'android', verificationMode: 'none', responseMode: 'compact'
+    })).content[0].text!)
+    assert.equal(ambiguous.failure_code, 'AMBIGUOUS_TARGET')
+    assert.equal(tapCount, 2)
+
+    resolution = { status: 'timeout', error: { code: 'ELEMENT_NOT_FOUND' } }
+    const missing = JSON.parse((await handleToolCall('tap_element', {
+      selector, platform: 'android', verificationMode: 'none', responseMode: 'compact'
+    })).content[0].text!)
+    assert.equal(missing.failure_code, 'ELEMENT_NOT_FOUND')
+    assert.equal(missing.dispatch_started, false)
+    assert.equal(missing.retryable, true)
+    assert.equal(tapCount, 2)
+
+    const invalid = await handleToolCall('tap_element', {
+      elementId: 'old', selector, waitFor: {}, platform: 'android'
+    })
+    assert.match(JSON.parse(invalid.content[0].text!).error.message, /Invalid input/)
+    assert.equal(tapCount, 2)
+  } finally {
+    ToolsInteract.waitForUIHandler = originalWait
+    ToolsInteract.tapElementHandler = originalTap
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/system/get_system_status.test.ts

@@ -9,6 +9,9 @@ async function run() {
   assert(typeof (payload as any).status === 'string')
   assert(Array.isArray(payload.issues))
   assert((payload as any).summary && typeof (payload as any).summary.overall === 'string')
+  assert((payload as any).host && typeof (payload as any).host.os === 'string')
+  assert((payload as any).android && typeof (payload as any).android.status === 'string')
+  assert((payload as any).ios && typeof (payload as any).ios.status === 'string')
 
   const adb = ensureAdbAvailable()
   assert(adb && typeof adb.ok === 'boolean')

package/test/unit/system/system_status.test.ts

@@ -74,6 +74,7 @@ async function run() {
     XCRUN_VERSION_OUTPUT: process.env.XCRUN_VERSION_OUTPUT,
     XCRUN_VERSION_STATUS: process.env.XCRUN_VERSION_STATUS,
     SIMCTL_LIST_OUTPUT: process.env.SIMCTL_LIST_OUTPUT,
+    MOBILE_DEBUG_MCP_HOST_OS: process.env.MOBILE_DEBUG_MCP_HOST_OS,
   }
 
   try {
@@ -82,6 +83,7 @@ async function run() {
     process.env.XCRUN_PATH = xcrunPath
 
     setScenario({
+      MOBILE_DEBUG_MCP_HOST_OS: 'darwin',
       ADB_VERSION_STATUS: '0',
       ADB_VERSION_OUTPUT: '8.1.0\n',
       ADB_DEVICES_OUTPUT: 'List of devices attached\nemulator-5554\tdevice product:sdk\n',
@@ -94,12 +96,16 @@ async function run() {
     const healthy = await systemStatus.getSystemStatus()
     assert.strictEqual(healthy.success, true)
     assert.strictEqual((healthy as any).status, 'ready')
+    assert.strictEqual((healthy as any).host.supported, true)
     assert.strictEqual(healthy.adbAvailable, true)
     assert.strictEqual(typeof healthy.adbVersion, 'string')
+    assert.strictEqual((healthy as any).android.status, 'ready')
+    assert.strictEqual((healthy as any).ios.status, 'ready')
     assert.strictEqual((healthy as any).summary.android.ready, true)
     assert.strictEqual(typeof (healthy as any).summary.ios.summary, 'string')
 
     setScenario({
+      MOBILE_DEBUG_MCP_HOST_OS: 'darwin',
       ADB_VERSION_STATUS: '1',
       ADB_VERSION_OUTPUT: 'not found',
       ADB_DEVICES_OUTPUT: 'List of devices attached\n',
@@ -112,6 +118,7 @@ async function run() {
     assert(missingAdb.issues.some((issue: string) => issue.includes('ADB')))
 
     setScenario({
+      MOBILE_DEBUG_MCP_HOST_OS: 'darwin',
       ADB_VERSION_STATUS: '0',
       ADB_VERSION_OUTPUT: '8.1.0\n',
       ADB_DEVICES_OUTPUT: 'List of devices attached\nserial1\tunauthorized\nserial2\toffline\n',
@@ -125,6 +132,7 @@ async function run() {
     assert(unauthorized.issues.some((issue: string) => issue.includes('offline')))
 
     setScenario({
+      MOBILE_DEBUG_MCP_HOST_OS: 'darwin',
       ADB_VERSION_STATUS: '0',
       ADB_VERSION_OUTPUT: '8.1.0\n',
       ADB_DEVICES_OUTPUT: 'List of devices attached\nemulator-5554\tdevice product:sdk\n',
@@ -136,6 +144,38 @@ async function run() {
     assert.strictEqual(missingXcrun.adbAvailable, true)
     assert.strictEqual(Array.isArray(missingXcrun.issues), true)
     assert.strictEqual((missingXcrun as any).summary.ios.ready, false)
+    assert.strictEqual((missingXcrun as any).ios.status, 'unavailable')
+
+    setScenario({
+      MOBILE_DEBUG_MCP_HOST_OS: 'win32',
+      ADB_VERSION_STATUS: '0',
+      ADB_VERSION_OUTPUT: '8.1.0\n',
+      ADB_DEVICES_OUTPUT: 'List of devices attached\nemulator-5554\tdevice product:sdk\n',
+      XCRUN_VERSION_STATUS: '1',
+      XCRUN_VERSION_OUTPUT: 'not found',
+    })
+    const windowsHost = await systemStatus.getSystemStatus()
+    assert.strictEqual((windowsHost as any).host.os, 'windows')
+    assert.strictEqual((windowsHost as any).host.supported, true)
+    assert.strictEqual((windowsHost as any).ios.status, 'unsupported')
+    assert.deepStrictEqual((windowsHost as any).ios.tools, {})
+    assert.deepStrictEqual((windowsHost as any).ios.providers, {})
+    assert.deepStrictEqual((windowsHost as any).ios.capabilities, {})
+    assert.deepStrictEqual((windowsHost as any).ios.devices, [])
+    assert.strictEqual((windowsHost as any).ios.failures[0].code, 'PLATFORM_UNAVAILABLE')
+    assert.strictEqual((windowsHost as any).summary.ios.ready, false)
+
+    setScenario({ MOBILE_DEBUG_MCP_HOST_OS: 'freebsd' })
+    const unsupported = await systemStatus.getSystemStatus()
+    assert.strictEqual((unsupported as any).host.os, 'freebsd')
+    assert.strictEqual((unsupported as any).host.supported, false)
+    assert.strictEqual((unsupported as any).android.status, 'unsupported')
+    assert.strictEqual((unsupported as any).ios.status, 'unsupported')
+    assert.strictEqual((unsupported as any).android.failures[0].code, 'HOST_OS_UNSUPPORTED')
+    assert.strictEqual((unsupported as any).ios.failures[0].code, 'HOST_OS_UNSUPPORTED')
+    assert.strictEqual(unsupported.adbAvailable, false)
+    assert.strictEqual(unsupported.iosAvailable, false)
+    assert.strictEqual((unsupported as any).summary.overall, 'blocked')
 
     console.log('system_status checks passed')
   } finally {

package/test/unit/utils/idb_health.test.ts

@@ -0,0 +1,74 @@
+import assert from 'assert'
+import fs from 'fs/promises'
+import os from 'os'
+import path from 'path'
+
+import { isIDBInstalled, probeIdb } from '../../../src/utils/cli/idb/idb-helper.js'
+
+async function run() {
+  const binDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-idb-health-'))
+  const idbPath = path.join(binDir, 'idb')
+  const python3Path = path.join(binDir, 'python3')
+  const pythonPath = path.join(binDir, 'python')
+  const pythonLog = path.join(binDir, 'python.log')
+  const originalIdbPath = process.env.MCP_IDB_PATH
+  const originalPath = process.env.PATH
+
+  try {
+    await fs.writeFile(idbPath, `#!/bin/sh
+if [ "$1" = "list-targets" ] && [ "$2" = "--json" ]; then
+  printf '{"targets":[]}\n'
+  exit 0
+fi
+if [ "$1" = "--version" ]; then
+  printf 'idb: error: unrecognized arguments: --version\n' >&2
+  exit 2
+fi
+exit 0
+`, { mode: 0o755 })
+
+    await fs.writeFile(python3Path, `#!/bin/sh
+printf 'python3 called\\n' >> "${pythonLog}"
+exit 0
+`, { mode: 0o755 })
+
+    await fs.writeFile(pythonPath, `#!/bin/sh
+printf 'python called\\n' >> "${pythonLog}"
+exit 0
+`, { mode: 0o755 })
+
+    process.env.MCP_IDB_PATH = idbPath
+    process.env.PATH = `${binDir}${path.delimiter}${originalPath || ''}`
+
+    const probe = probeIdb(idbPath)
+    assert.strictEqual(probe.ok, true)
+    assert.strictEqual(isIDBInstalled(), true)
+    assert(probe.raw === null || typeof probe.raw === 'string')
+
+    await fs.rm(pythonLog, { force: true }).catch(() => {})
+    const failedIdbPath = path.join(binDir, 'idb-failing')
+    await fs.writeFile(failedIdbPath, `#!/bin/sh
+if [ "$1" = "list-targets" ] && [ "$2" = "--json" ]; then
+  printf 'idb unavailable\\n' >&2
+  exit 2
+fi
+exit 2
+`, { mode: 0o755 })
+
+    const failureProbe = probeIdb(failedIdbPath)
+    assert.strictEqual(failureProbe.ok, false)
+    assert.strictEqual(await fs.readFile(pythonLog, 'utf8').catch(() => ''), '')
+
+    console.log('idb health probe test passed')
+  } finally {
+    if (originalIdbPath === undefined) delete process.env.MCP_IDB_PATH
+    else process.env.MCP_IDB_PATH = originalIdbPath
+
+    if (originalPath === undefined) delete process.env.PATH
+    else process.env.PATH = originalPath
+
+    await fs.rm(binDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+run().catch((error) => { console.error(error); process.exit(1) })