ios-safari-debug

iOS Safari Debugging

Use this skill to inspect and debug Safari tabs on a connected iOS device through ios-webkit-debug-proxy (iwdp).

Prerequisites

1. Check iwdp status — call iwdp_status first. It checks if ios-webkit-debug-proxy is running and auto-starts it if needed (no manual shell commands required).

2. An iOS device must be connected via USB with Safari open and Web Inspector enabled (Settings > Safari > Advanced > Web Inspector).

Port Layout

• Port 9221 — listing port: returns all connected devices
• Port 9222 — first device's pages
• Port 9223 — second device's pages (and so on)

Each device entry from port 9221 includes a URL field (e.g., localhost:9222) indicating which port to query for that device's pages.

Workflow

1. Ensure iwdp is running — call iwdp_status to verify (it auto-starts if needed).

2. List devices — use list_devices to see connected iOS devices and their port assignments.

3. List pages — use list_pages (optionally with port for a specific device) to discover open Safari tabs. Each entry includes a title, URL, and webSocketDebuggerUrl.

4. Select a page — use select_page with the WebSocket URL from the listing to connect to the target tab.

5. Use debugging tools for the task at hand. Available tools include:

   • navigate — go to a URL
   • evaluate_script — run JavaScript in the page
   • take_screenshot — capture the page as a PNG file (returns path — use Read to view)
   • get_document / query_selector / get_outer_html — inspect the DOM
   • click / fill / type_text — interact with page elements
   • get_cookies / set_cookie / delete_cookie — manage cookies (incl. httpOnly)
   • get_local_storage / get_session_storage — read web storage
   • get_computed_style / get_matched_styles — inspect CSS
   • network_enable / list_network_requests — monitor network traffic
   • get_console_messages — collect console output
   • Debugger, Timeline, Memory, Profiler, and more

Common Workflows

Screenshot + Evaluate

1. take_screenshot
2. evaluate_script: "document.title"

Network Monitoring

Start monitoring before navigating to capture all requests:

1. network_enable
2. navigate to the target URL
3. list_network_requests
4. get_response_body for individual responses

Cookie Inspection

View all cookies including httpOnly ones that JavaScript cannot access:

1. get_cookies
2. Examine secure/httpOnly flags, domains, and expiry

DOM Exploration

1. get_document (with depth)
2. query_selector to find specific elements
3. get_outer_html to see element markup
4. get_attributes for element attributes

Form Interaction

1. query_selector to find the form fields
2. fill each input with a value
3. click the submit button
4. take_screenshot to verify the result

CLI Tool (iwdp-cli)

Use MCP tools by default. Only use the CLI when the user explicitly requests it.

The iwdp-cli binary provides the same capabilities as the MCP tools but from the command line. Install it with go install github.com/nnemirovsky/iwdp-mcp/cmd/iwdp-cli@latest.

Usage Pattern

iwdp-cli <command> [args...] [ws-url]

The ws-url argument (WebSocket URL from iwdp-cli pages) is always optional and placed last. If omitted, the CLI auto-connects to the first available page.

Core Commands

iwdp-cli devices                    # List connected iOS devices
iwdp-cli pages [port]               # List Safari tabs (default port: 9222)
iwdp-cli status                     # Check if iwdp is running
iwdp-cli eval "document.title"      # Evaluate JavaScript
iwdp-cli navigate "https://..."     # Navigate to URL
iwdp-cli reload [--ignore-cache]    # Reload page
iwdp-cli screenshot [-o file.png]   # Take screenshot
iwdp-cli cookies                    # Show all cookies (incl. httpOnly)
iwdp-cli dom [selector]             # Inspect DOM tree or element
iwdp-cli console                    # Stream console messages (Ctrl+C)
iwdp-cli network                    # Stream network requests (Ctrl+C)

DOM & CSS

iwdp-cli query-selector-all "div.item"     # Find all matching elements
iwdp-cli get-attributes 5                   # Get node attributes
iwdp-cli get-computed-style 5               # Get computed style
iwdp-cli get-matched-styles 5               # Get matching CSS rules
iwdp-cli highlight-node 5                   # Highlight element in browser

Interaction

iwdp-cli click "#submit-btn"              # Click element
iwdp-cli fill "#email" "[email protected]" # Fill input
iwdp-cli type-text "hello"                # Type into focused element

Storage

iwdp-cli set-cookie name val .example.com  # Set cookie
iwdp-cli delete-cookie name "https://..."  # Delete cookie
iwdp-cli get-local-storage "https://..."   # Get localStorage
iwdp-cli get-session-storage "https://..." # Get sessionStorage

Debugger

iwdp-cli debugger-enable
iwdp-cli set-breakpoint "app.js" 42
iwdp-cli pause / resume / step-over / step-into / step-out
iwdp-cli get-script-source "1"
iwdp-cli eval-on-frame "0" "myVar"

Performance & Profiling

Duration-based commands collect for 3 seconds by default. Use -d N to change.

iwdp-cli timeline-record [-d 5]    # Record timeline events
iwdp-cli memory-track [-d 5]       # Track memory usage
iwdp-cli heap-snapshot              # Take heap snapshot
iwdp-cli heap-gc                    # Force garbage collection
iwdp-cli cpu-profile [-d 5]        # CPU profiling
iwdp-cli script-profile [-d 5]     # Script execution profiling

Full Command List

Run iwdp-cli help to see all 90+ commands organized by category.

Tips

• Use list_devices first if you have multiple iOS devices connected. It shows port assignments.
• list_pages defaults to port 9222 (first device). Pass the port from list_devices for other devices.
• get_cookies returns httpOnly and secure cookies that document.cookie cannot access.
• Network/console monitoring only captures events while active. Enable before triggering traffic.
• evaluate_script runs arbitrary JS in the page context. Use it for anything the specialized tools don't cover.
• Screenshots are saved as PNG files. Use the Read tool to view the returned file path.
• Large results (DOM trees, network logs, JS output) are automatically saved to temp files when they exceed the inline size limit.