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.

When to Use

• When the user asks to run, debug, or inspect an iOS app on a simulator.
• When you need simulator UI interaction, screenshots, or runtime logs via XcodeBuildMCP.

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 build fails, check the error output and retry (optionally with

  preferXcodebuild: true

  ) or escalate to the user before attempting any UI interaction.
• After a successful build, verify the app launched by calling

  mcp__XcodeBuildMCP__describe_ui

  or

  mcp__XcodeBuildMCP__screenshot

  before proceeding to UI interaction.
• 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.

• Describe UI:

  mcp__XcodeBuildMCP__describe_ui

  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.

Logs & Console Output

• Start logs:

  mcp__XcodeBuildMCP__start_sim_log_cap

  with the app bundle id.
• Stop logs:

  mcp__XcodeBuildMCP__stop_sim_log_cap

  and summarize important lines.
• For console output, set

  captureConsole: true

  and relaunch if required.

Troubleshooting

• If build fails, ask whether to retry with

  preferXcodebuild: true

  .
• If the wrong app launches, confirm the scheme and bundle id.
• If UI elements are not hittable, re-run

  describe_ui

  after layout changes.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.