iPhone Control

Get the full UI element hierarchy of the current screen. Returns ALL element types (buttons, text, images, containers, etc.) that are currently visible on screen. Filters applied automatically: - Off-screen elements are excluded - Generic unlabeled container nodes are excluded For finding tappable elements specifically, prefer scan_ui instead.

{
  "tool": "describe_screen",
  "arguments": {
    "udid": "…",
    "nested": true
  }
}

Execute a single device action on the iPhone. Actions available: - tap: Tap at coordinates { x, y, duration? } - swipe: Swipe gesture { fromX, fromY, toX, toY, duration?, delta? } - button: Press button { button: 'HOME'|'LOCK'|'SIDE_BUTTON'|'APPLE_PAY'|'SIRI', duration? } - input-text: Type text { text } - key: Press key { key: number (HID keycode) | string (character), duration? } - key-sequence

{
  "tool": "device_action",
  "arguments": {
    "action": "tap",
    "params": {}
  }
}

Execute multiple device actions in sequence on the iPhone. Each action in the array should have: - action: 'tap' | 'swipe' | 'button' | 'input-text' | 'key' | 'key-sequence' - params: Action-specific parameters Use describe_after to see the screen state after all actions complete.

{
  "tool": "device_actions",
  "arguments": {
    "actions": []
  }
}

Capture a screenshot of the current iPhone screen. Returns the file path to a PNG image.

{
  "tool": "get_screenshot",
  "arguments": {
    "udid": "…"
  }
}

Find interactive UI elements (buttons, links, text fields, switches, icons, etc.) on the current screen. Returns only tappable/interactive elements with their coordinates. Use the "query" parameter to search for a specific element by label (e.g. "Add to Cart", "Settings"). When a query is provided: - First searches visible interactive elements matching the query - If not found on-screen, searches

{
  "tool": "scan_ui",
  "arguments": {
    "region": "full"
  }
}

List all available iPhones and simulators.

{
  "tool": "list_devices",
  "arguments": {}
}

Get the current execution context — which iPhone(s) or simulators are available. Call this first to discover available devices. Returns: - target: 'simulator' — one simulator booted, use the returned udid - target: 'device' — one physical device connected, use the returned udid. Inform user about viewer_url for screen viewing. - target: 'ambiguous' — multiple devices found. Ask the user which one

{
  "tool": "get_execution_context",
  "arguments": {}
}

Build, install, and launch WebDriverAgent on a physical iPhone. This is required before any other tool can interact with a physical device. Call this when get_execution_context shows a physical device with wdaRunning: false. The process takes 1-3 minutes (building WDA, installing on device, establishing connection). Prerequisites: - iPhone connected via USB and trusted - Developer Mode enabled o

{
  "tool": "setup_device",
  "arguments": {
    "udid": "…"
  }
}

Launch an app on the iPhone by bundle ID.

{
  "tool": "launch_app",
  "arguments": {
    "bundleId": "…"
  }
}

List installed apps on the iPhone.

{
  "tool": "list_apps",
  "arguments": {
    "udid": "…"
  }
}