Agent Skills: iOS Debugger Agent

iOS Debugger Agent

Overview

Use XcodeBuildMCP to build and run the current project scheme on a booted iOS simulator, interact with the UI, and capture logs. Prefer the MCP tools for simulator control, logs, and view inspection.

Core Workflow

Follow this sequence unless the user asks for a narrower action.

1) Discover the booted simulator

• Call mcp__XcodeBuildMCP__list_sims and select the simulator with state Booted.
• If none are booted, ask the user to boot one (do not boot automatically unless asked).

2) Set session defaults

• Call mcp__XcodeBuildMCP__session-set-defaults with:
  • projectPath or workspacePath (whichever the repo uses)
  • scheme for the current app
  • simulatorId from the booted device
  • Optional: configuration: "Debug", useLatestOS: true

3) Build + run (when requested)

• Call mcp__XcodeBuildMCP__build_run_sim.
• If the app is already built and only launch is requested, use mcp__XcodeBuildMCP__launch_app_sim.
• If bundle id is unknown:
  1. mcp__XcodeBuildMCP__get_sim_app_path
  2. mcp__XcodeBuildMCP__get_app_bundle_id

UI Interaction & Debugging

Use these when asked to inspect or interact with the running app.

| Action | MCP Tool | Notes | |--------|----------|-------| | Describe UI | mcp__XcodeBuildMCP__describe_ui | Run before tapping or swiping | | Tap | mcp__XcodeBuildMCP__tap | Prefer id or label; use coordinates only if needed | | Type | mcp__XcodeBuildMCP__type_text | After focusing a field | | Gestures | mcp__XcodeBuildMCP__gesture | For common scrolls and edge swipes | | Screenshot | mcp__XcodeBuildMCP__screenshot | For visual confirmation |

Interaction Flow

1. describe_ui → Understand current screen
2. tap/type/gesture → Perform interaction
3. describe_ui → Verify result
4. screenshot → Visual confirmation (optional)

Logs & Console Output

Start capturing logs

mcp__XcodeBuildMCP__start_sim_log_cap

Parameters:

• bundleId: The app's bundle identifier

Stop and retrieve logs

mcp__XcodeBuildMCP__stop_sim_log_cap

Summarize important lines from the captured output.

Console output

For console output, set captureConsole: true and relaunch if required.

Common Scenarios

Build and Run Fresh

1. list_sims → Get booted simulator
2. session-set-defaults → Configure project/scheme/simulator
3. build_run_sim → Build and launch

Debug a Crash

1. start_sim_log_cap → Begin capturing
2. Reproduce the crash
3. stop_sim_log_cap → Get logs
4. Analyze crash logs for stack trace

UI Testing Flow

1. describe_ui → Get current state
2. tap on element → Interact
3. describe_ui → Verify change
4. screenshot → Document state

Check Network Requests

1. start_sim_log_cap with network subsystem filter
2. Trigger network action in app
3. stop_sim_log_cap → Analyze requests

Troubleshooting

Build fails

• Verify scheme name matches exactly
• Check if workspace vs project path is correct
• Try with preferXcodebuild: true for complex setups

Wrong app launches

• Confirm scheme name
• Get bundle ID with get_app_bundle_id
• Verify simulator ID is correct

UI elements not hittable

• Re-run describe_ui after layout changes
• Check if element is off-screen
• Verify accessibility is enabled

No logs captured

• Ensure bundle ID is correct
• Check if app is actually running
• Try with broader subsystem filter

Quick Reference

Essential Commands

# List simulators
mcp__XcodeBuildMCP__list_sims

# Set defaults
mcp__XcodeBuildMCP__session-set-defaults
  projectPath: /path/to/Project.xcodeproj
  scheme: MyApp
  simulatorId: <UUID>

# Build and run
mcp__XcodeBuildMCP__build_run_sim

# Just launch (already built)
mcp__XcodeBuildMCP__launch_app_sim
  bundleId: com.example.MyApp

# UI inspection
mcp__XcodeBuildMCP__describe_ui

# Tap element
mcp__XcodeBuildMCP__tap
  element: "Button Title" | id: "accessibilityId" | x: 100, y: 200

# Type text
mcp__XcodeBuildMCP__type_text
  text: "Hello World"

# Screenshot
mcp__XcodeBuildMCP__screenshot

# Start logs
mcp__XcodeBuildMCP__start_sim_log_cap
  bundleId: com.example.MyApp

# Stop logs
mcp__XcodeBuildMCP__stop_sim_log_cap

Gesture Types

• scroll_up / scroll_down
• scroll_left / scroll_right
• swipe_from_edge_left / swipe_from_edge_right
• pinch_in / pinch_out
• long_press

Notes

• Always run describe_ui before interacting to understand current state
• Use accessibility labels/identifiers over coordinates when possible
• Logs are most useful in Debug configuration
• Screenshots help document test scenarios