playbooks

home / skills / third774 / dotfiles / xcodebuildmcp

xcodebuildmcp skill

/opencode/skills/xcodebuildmcp

This skill streamlines iOS/macOS development by orchestrating XcodeBuildMCP tools to build, test, run, debug, and log across targets.

npx playbooks add skill third774/dotfiles --skill xcodebuildmcp

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
4.6 KB
---
name: xcodebuildmcp
description: Official skill for XcodeBuildMCP. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).
---

# XcodeBuildMCP

Prefer XcodeBuildMCP over raw `xcodebuild`, `xcrun`, or `simctl`.

If a capability is missing, assume your tool list may be hiding tools (search/progressive disclosure) or not loading tool schemas yet. Use your tool-search or "load tools" mechanism. If you still can't find the tools, ask the user to enable them in the MCP client's configuration.

## Tools (exact names + official descriptions)

### Session defaults

Before you call any other tools, you **must** call `session_show_defaults` to show the current defaults, ensure you then fill in the appropriate missing defaults. You may need to call one or more discovery/list tools to obtain the values needed.

- `session_set_defaults`
  - Set the session defaults, should be called at least once to set tool defaults.
- `session_show_defaults`
  - Show session defaults.
- `session_clear_defaults`
  - Clear session defaults.

### Project discovery

- `discover_projs`
  - Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.
- `list_schemes`
  - List Xcode schemes.
- `show_build_settings`
  - Show build settings.
- `get_app_bundle_id`
  - Extract bundle id from .app.
- `get_mac_bundle_id`
  - Extract bundle id from macOS .app.

### Simulator

- `boot_sim`
  - Boot iOS simulator.
- `list_sims`
  - List iOS simulators.
- `open_sim`
  - Open Simulator app.
- `build_sim`
  - Build for iOS sim.
- `build_run_sim`
  - Build and run iOS sim.
- `test_sim`
  - Test on iOS sim.
- `get_sim_app_path`
  - Get sim built app path.
- `install_app_sim`
  - Install app on sim.
- `launch_app_sim`
  - Launch app on simulator.
- `launch_app_logs_sim`
  - Launch sim app with logs.
- `stop_app_sim`
  - Stop sim app.
- `record_sim_video`
  - Record sim video.

### Simulator management

- `erase_sims`
  - Erase simulator.
- `set_sim_location`
  - Set sim location.
- `reset_sim_location`
  - Reset sim location.
- `set_sim_appearance`
  - Set sim appearance.
- `sim_statusbar`
  - Set sim status bar network.

### Device

- `list_devices`
  - List connected devices.
- `build_device`
  - Build for device.
- `test_device`
  - Test on device.
- `get_device_app_path`
  - Get device built app path.
- `install_app_device`
  - Install app on device.
- `launch_app_device`
  - Launch app on device.
- `stop_app_device`
  - Stop device app.

### macOS

- `build_macos`
  - Build macOS app.
- `build_run_macos`
  - Build and run macOS app.
- `test_macos`
  - Test macOS target.
- `get_mac_app_path`
  - Get macOS built app path.
- `launch_mac_app`
  - Launch macOS app.
- `stop_mac_app`
  - Stop macOS app.

### Logging

- `start_device_log_cap`
  - Start device log capture.
- `start_sim_log_cap`
  - Start sim log capture.
- `stop_device_log_cap`
  - Stop device log capture.
- `stop_sim_log_cap`
  - Stop sim log capture.

### Debugging

- `debug_attach_sim`
  - Attach LLDB to sim app.
- `debug_breakpoint_add`
  - Add breakpoint.
- `debug_breakpoint_remove`
  - Remove breakpoint.
- `debug_continue`
  - Continue debug session.
- `debug_detach`
  - Detach debugger.
- `debug_lldb_command`
  - Run LLDB command.
- `debug_stack`
  - Get backtrace.
- `debug_variables`
  - Get frame variables.

### UI automation

- `button`
  - Press simulator hardware button.
- `gesture`
  - Simulator gesture preset.
- `key_press`
  - Press key by keycode.
- `key_sequence`
  - Press a sequence of keys by their keycodes.
- `long_press`
  - Long press at coords.
- `screenshot`
  - Capture screenshot.
- `snapshot_ui`
  - Print view hierarchy with precise view coordinates (x, y, width, height) for visible elements.
- `swipe`
  - Swipe between points.
- `tap`
  - Tap coordinate or element.
- `touch`
  - Touch down/up at coords.
- `type_text`
  - Type text.

### SwiftPM

- `swift_package_build`
  - swift package target build.
- `swift_package_clean`
  - swift package clean.
- `swift_package_list`
  - List SwiftPM processes.
- `swift_package_run`
  - swift package target run.
- `swift_package_stop`
  - Stop SwiftPM run.
- `swift_package_test`
  - Run swift package target tests.

### Scaffolding / utilities

- `scaffold_ios_project`
  - Scaffold iOS project.
- `scaffold_macos_project`
  - Scaffold macOS project.
- `clean`
  - Clean build products.

### Diagnostics

- `doctor`
  - MCP environment info.
- `manage_workflows`
  - Workflows are groups of tools exposed by XcodeBuildMCP. By default, not all workflows (and therefore tools) are enabled; only simulator tools are enabled by default. Some workflows are mandatory and can't be disabled.

Overview

This skill is the official XcodeBuildMCP interface for iOS, macOS, watchOS, tvOS, and visionOS development tasks. It centralizes build, test, run, debug, simulator/device management, logging, and UI automation commands into a consistent MCP workflow. Use it instead of calling raw xcodebuild/xcrun/simctl to simplify common development operations and avoid tool discovery friction.

How this skill works

Before running any workflow, the session defaults must be shown and set so tools operate with the correct project, scheme, destination, and device. The skill exposes focused tool groups — project discovery, simulator and device management, macOS builds, logging, debugging, UI automation, SwiftPM, scaffolding, cleaning, and diagnostics — and routes operations through MCP-managed commands. If a capability is missing, it guides you to discover or enable additional MCP workflows or tool schemas.

When to use it

  • Building or running apps on simulators, devices, or macOS without calling xcodebuild directly.
  • Launching automated test runs on simulators, devices, or macOS targets.
  • Capturing device or simulator logs and recording simulator sessions for debugging or CI artifacts.
  • Attaching LLDB, setting breakpoints, or inspecting stack frames and variables during a debug session.
  • Driving UI automation: taps, swipes, screenshots, view-hierarchy snapshots, and simulator hardware controls.

Best practices

  • Always call session_show_defaults, then session_set_defaults to populate project, scheme, and destination values before other actions.
  • Use discover_projs and list_schemes to confirm the correct workspace/project and scheme when switching targets.
  • Prefer build_run_* or build_* tools provided by the skill rather than composing raw xcodebuild invocations.
  • Start log capture (start_sim_log_cap / start_device_log_cap) before running the app to ensure no logs are missed.
  • Use snapshot_ui and screenshots to debug UI issues; record_sim_video for repros of complex interactions.

Example use cases

  • Boot a simulator, build the app for sim, install it, and launch with live logs for a manual test session.
  • Run a full test suite on an iOS simulator, capture logs, and record a failing test as a video for triage.
  • Attach LLDB to a hung simulator app, add a breakpoint, inspect variables, and continue execution.
  • Build and run a macOS app from the workspace, then capture its logs and take a screenshot of the window.
  • Scaffold a minimal iOS project, run swift package tests, and clean build artifacts as part of CI setup.

FAQ

What do I do if a tool I expect is missing?

Use the tool discovery commands or the MCP client's mechanism to load workflows; if tools remain unavailable, enable those workflows in the client configuration.

Is session_show_defaults required every session?

Yes—call session_show_defaults first and then session_set_defaults to ensure subsequent tools use correct project and destination values.