CHANGELOG.md

Changelog

[Unreleased]

Added

• Added --from-result to the Claude UI benchmark harness so existing result.json artifacts can be rendered as text or JSON without rerunning Claude.
• Added nextSteps hint lines to MCP structuredContent and CLI --output json envelopes so agents can consume follow-up actions without scraping text. CLI JSON renders shell command lines; MCP structured content renders MCP tool-call hints. Structured result schemas that include nextSteps now use schema version 2; existing version 1 schema files remain available for current validators.
• Added snapshot_ui sinceScreenHash / CLI --since-screen-hash so callers can skip full runtime snapshot output when the screen hash is unchanged.
• Added batch for executing multiple AXe UI automation steps in one simulator session.
• Added wait_for_ui for polling runtime UI snapshots until UI predicates such as existence, enabled state, focus, text, or settled layout are satisfied. textContains can also wait on visible text without a selector when the match is unique.
• Added structured element-ref batch tap steps, preserved same-screen refs after successful tap and batch actions, and improved UI automation guidance and next steps for one-observation interactions.
• Added a replaceExisting option to type_text so agents can replace an existing text-field value instead of accidentally appending to it.
• Added drag for element-ref based drag gestures, enabling agents to expand foreground sheets and drag real scroll/list regions without raw coordinate guesses.

Changed

• Changed Claude UI benchmark suite runs to create a temporary simulator by default and delete only that harness-created simulator after the suite finishes.
• Changed Claude UI benchmark exact tool sequence drift to warn by default, with sequence.mode: fail available for strict suites.
• Successful mutating UI automation calls now always attempt to refresh the runtime snapshot after the action instead of preserving or patching cached switch state.
• Runtime snapshot guidance no longer advertises synthetic sheet swipe targets for foreground sheets. Agents should use real sheet grabber expansion and real descendant scroll/list targets with drag instead of inferred app/window-root sheet swipes.

Fixed

• Fixed Claude UI benchmark preflight so transient malformed or still-loading UI snapshots no longer crash the harness or finish before app UI is observable.
• Fixed Claude UI benchmark preflight so configured first-run dismissals require a concrete simulator ID and suite-provided simulator IDs are recorded in command logs.
• Fixed Claude UI benchmark config handling so invalid failurePatterns regexes and sessionDefaults fail before a suite starts and partial allowedVariance overrides preserve defaults for omitted metrics.
• Fixed Claude UI benchmark temporary simulator cleanup so simulators created by the harness are deleted even when post-creation setup fails.
• Fixed UI action snapshot refreshes so timeout while waiting for a settled post-action snapshot returns a recoverable warning instead of unstable element refs.
• Fixed Claude UI benchmark suite runs so temporary simulators are applied through an isolated per-run MCP config instead of being overridden by repo or example-project config defaults.
• Fixed simulator launch failures before simulator-name resolution so they are not reported as macOS launch failures.
• Fixed CLI JSON output so simulator-name resolution failures return the structured error envelope instead of plain stderr.
• Fixed accessibility hierarchy tips so UI automation guidance prefers runtime element refs over raw coordinate guessing.
• Fixed swipe distance handling so distance is a normalized stroke fraction used for endpoint calculation, and improved sheet/list scroll guidance so real descendant scroll containers are preferred over application/window root fallbacks.
• Fixed compact runtime snapshots so top-level app and window refs are not advertised as swipe targets just because a generic descendant overflows their frame.
• Fixed wait_for_ui focus waits so elements that do not expose focus state return a typed recoverable error instead of timing out.
• Fixed invalid touch calls so structured output no longer reports a fake touch event when neither down nor up was requested.
• Fixed compact runtime snapshots so standalone other elements, such as keyboard suggestions, are not advertised as swipe targets unless they behave like scrollable containers.
• Fixed runtime snapshots so off-screen elements, and clipped elements whose activation point is offscreen, are not advertised as actionable targets.
• Fixed full-screen swipe gestures so app-level scroll refs avoid unsafe screen edges such as the status bar and notch area.
• Clarified runtime snapshot tips so agents know element refs are snapshot-specific and must come from the latest snapshot_ui or wait_for_ui output, and only show swipe guidance when the snapshot includes a scroll ref.
• Made wait_for_ui textContains matching case-insensitive so assertions survive platform text normalization such as keyboard auto-capitalization, treat duplicate exact text matches as successful presence assertions, narrow broad selectors by text before reporting ambiguity, reject text on non-textContains predicates instead of silently ignoring it, and keep recoverable-error candidates compact in structured output.
• Fixed tap on SwiftUI switch element refs by using a touch down/up activation instead of AXe's coordinate tap path.
• Fixed selector fallback for AXe duplicate-match diagnostics that include parenthesized match counts.
• Fixed semantic taps and text-field focusing so element refs with duplicate AXe selectors use their resolved snapshot coordinates immediately.
• Fixed bottom-clipped UI automation targets so taps, touches, and long presses use a visible activation point instead of the hidden center of the accessibility frame.
• Fixed app-level horizontal swipes so full-screen refs use a content-area y-coordinate instead of missing horizontal carousels by swiping near the hero area.
• Fixed CLI commands with simulatorId-only contracts so simulatorName session defaults are resolved to a simulator ID without adding conflicting simulator arguments to tools that already accept simulatorName, and fixed simulator lifecycle tools so name-only defaults resolve before simctl operations.
• Fixed snapshot_ui and wait_for_ui next steps so they use the resolved simulator ID instead of leaking SIMULATOR_UUID placeholders.
• Fixed the Weather example app so saved-location rows are not reused as search-result rows after editing locations.
• Fixed the Weather example app's current-location button so it selects the current saved location instead of appearing as a no-op UI automation target.
• Fixed type_text so AXe-unsupported international/accented characters fail before focusing the field, with a clear recoverable error instead of a generic typing failure.
• Fixed snapshot_ui next-step guidance so the suggested tap ref prefers useful tappable controls over text fields, sheet grabbers, close buttons, and clear-search buttons.
• Fixed compact runtime snapshot JSON so target ordering matches compact text output and prioritizes useful content targets before low-value sheet chrome.
• Fixed wait_for_ui success output so compact text and JSON include the matched elements that satisfied the wait predicate.
• Fixed wait_for_ui textContains so duplicate elements with the same matching visible text satisfy presence-style assertions instead of reporting ambiguity.
• Fixed CLI --style minimal so final text output suppresses generated next steps for daemon-routed tools as intended.
• Fixed snapshot_ui next-step guidance so snapshots with no tappable targets no longer suggest tapping the first non-actionable element.
• Fixed next-step rendering for tools shared across workflows so follow-up commands prefer the workflow that produced the result instead of drifting to another workflow alias.
• Fixed snapshot_ui next-step guidance so calculator-style utility and operator buttons no longer outrank more useful digit/content controls.
• Fixed snapshot_ui compact text, JSON, and next-step guidance so already-selected segmented controls no longer outrank unselected choices.
• Fixed compact runtime snapshots and next-step guidance so sheet grabbers remain visible as low-priority targets, allowing agents to expand or dismiss sheets without outranking useful content controls.
• Fixed compact wait-match rows so static assertion matches render with none instead of exposing low-level long-press/touch actions as if they were primary agent actions.
• Fixed compact runtime snapshot ordering and next-step guidance so destructive controls such as Remove/Delete are demoted behind safer content and navigation targets.
• Clarified simulator keyboard shortcut failures when Simulator.app is running without a visible device window.
• Fixed hardware button automation so successful button presses wait briefly for system UI transitions before returning, reducing stale immediate follow-up snapshots.
• Fixed runtime snapshots so modal sheet hosts remain swipeable after the currently visible sheet content fits inside the viewport.
• Fixed wait_for_ui validation so unknown JSON fields are rejected instead of silently broadening waits.
• Fixed CLI numeric array flags so comma-separated values such as --key-codes 23,18,14 are parsed as numbers instead of failing validation.
• Fixed runtime snapshots so unlabeled internal custom-action nodes, such as SpringBoard icon subviews, are no longer advertised as likely tap targets.
• Fixed AXe bundling so downloaded artifacts must report the pinned AXe version, and dirty local AXe builds require an explicit opt-in.
• Fixed runtime snapshot tips so compact output names all target-ref action tools, including long_press and touch.
• Clarified key press and key sequence tool descriptions so agents know key codes are AXe/macOS virtual key codes and should prefer type_text for text entry.
• Clarified wait_for_ui timeout recovery hints so agents know selector fields match exact values and should use textContains for partial visible text.
• Fixed UI action success next steps so agents are prompted to refresh runtime snapshots before reusing element refs after actions such as swipes.
• Fixed snapshot_ui next-step guidance so state-changing controls such as segmented units and switches remain available in targets without being promoted as generic tap or batch suggestions.
• Fixed snapshot_ui tap next-step priority so content-rich cards are suggested before navigation controls like Settings.
• Fixed successful UI action results so they include a fresh runtime snapshot and actionable next steps, reducing follow-up refresh calls after taps, typing, swipes, and batches.
• Fixed same-simulator UI automation transactions so runtime snapshot resolution, actions, invalidation, and refreshes cannot interleave within one MCP or daemon process.

[2.5.2]

Changed

• Updated the bundled AXe binary used by UI automation tools to 1.7.0.

Fixed

• Fixed a log-capture vulnerability where a crafted bundleId or custom subsystem filter could broaden simulator log streams to capture output from other apps or Apple system subsystems. Bundle IDs and subsystem filters are now validated against a strict allowlist before reaching the predicate (#407 by @sebastiondev).
• Fixed debug_attach_sim so an explicit pid overrides an inherited bundleId session default before mutual-exclusion validation (#410).

[2.5.1]

Fixed

• Fixed portable macOS/Homebrew installs missing structured output schemas, which prevented MCP clients from loading tools.

[2.5.0]

Breaking

Standalone log-capture tools removed

The old logging workflow and its standalone log-capture tools (start_sim_log_cap, stop_sim_log_cap, start_device_log_cap, stop_device_log_cap, and launch_app_logs_sim) have been removed. This affects users, scripts, and agents that call those tool names directly.

Use the launch or build-and-run tools instead. They return runtime log paths as part of the normal result, so agents no longer need a separate start/stop log-capture sequence.

Before:

xcodebuildmcp logging start-sim-log-cap --simulator-id <UDID> --bundle-id com.example.MyApp
xcodebuildmcp simulator launch-app --simulator-id <UDID> --bundle-id com.example.MyApp
xcodebuildmcp logging stop-sim-log-cap --pid <PID>

After:

xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj

# Or, for an app that is already installed on a simulator:
xcodebuildmcp simulator launch-app --simulator-id <UDID> --bundle-id com.example.MyApp

For MCP clients, use build_run_sim or launch_app_sim and read the returned runtime log path.

Runtime launch arguments now use launchArgs

Build-and-run and launch-only tools now separate build settings from app launch arguments. This affects users, scripts, and agents that previously passed runtime arguments through extraArgs or the launch-only args input.

If you do nothing, app runtime arguments may not reach the launched process, and launch-only calls that still use args will fail validation. Move app arguments to launchArgs; keep extraArgs only for xcodebuild flags and build setting overrides.

Before:

xcodebuildmcp simulator build-and-run --json '{
  "scheme": "MyApp",
  "projectPath": "./MyApp.xcodeproj",
  "extraArgs": ["--uitesting"]
}'

After:

xcodebuildmcp simulator build-and-run --json '{
  "scheme": "MyApp",
  "projectPath": "./MyApp.xcodeproj",
  "launchArgs": ["--uitesting"]
}'

Launch-only tools use the same input:

xcodebuildmcp simulator launch-app --json '{
  "simulatorId": "<UDID>",
  "bundleId": "com.example.MyApp",
  "launchArgs": ["--uitesting"]
}'

For MCP clients, use launchArgs on build_run_sim, build_run_device, build_run_macos, launch_app_sim, launch_app_device, and launch_mac_app. See CLI.

New! Structured outputs

XcodeBuildMCP now returns structured, machine-readable results across supported MCP clients and the CLI. Agents and scripts no longer have to scrape prose to find build status, log paths, bundle IDs, process IDs, test failures, or app paths. The human-readable text remains available, but every supported result now has a consistent envelope with the same fields:

{
  "schema": "xcodebuildmcp.output.build-run-result",
  "schemaVersion": "1",
  "didError": false,
  "error": null,
  "data": { }
}

For agents, this reduces token usage and makes tool results easier to act on reliably. Instead of rereading a full text transcript to find the build log, runtime log, or launched process, the agent can jump straight to fields such as data.artifacts.buildLogPath, data.artifacts.runtimeLogPath, data.artifacts.osLogPath, data.artifacts.appPath, data.artifacts.bundleId, and data.artifacts.processId.

MCP clients

MCP clients that support structured tool results receive structuredContent alongside the existing text response. The text remains useful for humans and older clients; supported clients can use the structured fields directly.

Example Build & Run result shape:

{
  "schema": "xcodebuildmcp.output.build-run-result",
  "schemaVersion": "1",
  "didError": false,
  "error": null,
  "data": {
    "summary": { "status": "SUCCEEDED", "durationMs": 1234, "target": "simulator" },
    "artifacts": {
      "appPath": "~/Library/Developer/XcodeBuildMCP/DerivedData/.../CalculatorApp.app",
      "bundleId": "io.sentry.calculatorapp",
      "processId": 99999,
      "buildLogPath": "~/Library/Developer/XcodeBuildMCP/logs/build_run_sim_...log",
      "runtimeLogPath": "~/Library/Developer/XcodeBuildMCP/logs/io.sentry.calculatorapp_...log",
      "osLogPath": "~/Library/Developer/XcodeBuildMCP/logs/io.sentry.calculatorapp_oslog_...log"
    }
  }
}

CLI JSON output

The CLI now supports --output text|json|jsonl|raw for tool commands. text remains the default. Use --output json when a script, CI job, or agent needs one final result document:

xcodebuildmcp simulator build-and-run --output json

{
  "schema": "xcodebuildmcp.output.build-run-result",
  "schemaVersion": "1",
  "didError": false,
  "error": null,
  "data": {
    "request": { "scheme": "CalculatorApp", "platform": "iOS Simulator" },
    "summary": { "status": "SUCCEEDED", "durationMs": 1234, "target": "simulator" },
    "artifacts": { "buildLogPath": "~/Library/Developer/XcodeBuildMCP/logs/build_run_sim_...log" },
    "diagnostics": { "warnings": [], "errors": [] }
  }
}

Use --output jsonl for live progress as newline-delimited JSON, one event per line:

{"event":"build-result.invocation","operation":"BUILD","request":{"scheme":"CalculatorApp","platform":"iOS Simulator"}}
{"event":"build-result.build-stage","operation":"BUILD","stage":"COMPILING","message":"Compiling CalculatorApp"}
{"event":"build-result.build-summary","operation":"BUILD","status":"SUCCEEDED","durationMs":3421}

Failures use the same envelope as successes, so callers can rely on didError, error, data.summary, data.diagnostics, and test-specific fields like testCases and testFailures instead of handling every command differently.

Published schemas

The structured result contracts are published as JSON Schema and can be used to validate output or generate types:

https://xcodebuildmcp.com/schemas/structured-output/<schema-name>/<version>.schema.json

For example: xcodebuildmcp.output.build-run-result v1. See Output Formats for the full reference.

Added

• Added xcodebuildmcp upgrade to check for available updates and upgrade in place, with --check for report-only use and --yes/-y for non-interactive upgrades.
• Added a platform-aware xcodebuildmcp setup wizard: choose macOS, iOS, tvOS, watchOS, or visionOS up front; get platform-appropriate workflow recommendations; skip simulator/device prompts for macOS-only projects; and reuse previous choices when re-running setup. Single-platform setups also include the platform in generated config and --format mcp-json output. See Setup (#365, based on work by @ichoosetoaccept).
• Added XCODEBUILDMCP_CWD so MCP clients that cannot choose the server's start directory can still point project config discovery and relative-path resolution at the right workspace. See Environment Variables.
• Added per-test timing output, so agents and scripts can identify slow tests without opening the full test report. JSON and structured results include a testCases list, and text output can show per-test durations with showTestTiming or XCODEBUILDMCP_SHOW_TEST_TIMING=1 (#339 by @codeman9).
• Added default result bundles for simulator, device, macOS, and Swift Package test runs, so agents can inspect detailed test artifacts without manually choosing a result bundle path.
• Added opt-in idle shutdown for unused MCP server processes via XCODEBUILDMCP_MCP_IDLE_TIMEOUT_MS, reducing leftover background processes for clients that keep server sessions open (#398). See Environment Variables.
• Added toggle_software_keyboard and toggle_connect_hardware_keyboard tools for showing/hiding the iOS Simulator software keyboard and connecting/disconnecting the Mac hardware keyboard. See Tools Reference (#346, #347 by @yjmeqt).
• Added tvOS, watchOS, and visionOS support to build_device, so physical-device builds are no longer limited to iOS. See Device Code Signing (#352 by @bitxeno).

Changed

• CLI build and test commands now show live progress while they are running instead of waiting until the command finishes. See Output Formats.
• CLI text output now shows file paths in a more readable Files: list by default. Use --file-path-render-style tree, filePathRenderStyle, or XCODEBUILDMCP_FILE_PATH_RENDER_STYLE if you prefer the compact tree layout used by MCP text responses (#402). See Output Formats.
• Xcode IDE tool results are now shorter in final output, with full details still accessible when needed. CLI JSON and JSONL output now work for Xcode IDE tool calls too (#396).
• Runtime log capture is more reliable across restarts, cleans itself up when apps stop or the server shuts down, and avoids stopping active log streams from another workspace (#382).
• XcodeBuildMCP now cleans up old logs and temporary build artifacts more reliably without disrupting concurrent active sessions (#391).
• Builds and tests now use an isolated DerivedData location per workspace or project when you have not set derivedDataPath, reducing cross-project build conflicts while keeping explicit derivedDataPath settings unchanged (#340, #341 by @codeman9).
• Long-form documentation has moved to xcodebuildmcp.com/docs, with the README focused on installation, setup, and quick links to the hosted guides.

Fixed

• Fixed shell-injection vulnerabilities when user-provided values were passed to Apple developer tools, log-capture queries, bundle ID extraction, and macOS launch flows (#289 by @sebastiondev, #390 by @voidborne-d).
• Fixed a path traversal vulnerability that could allow reading files outside the expected scope.
• Fixed portable macOS installs missing a required runtime dependency, which could make packaged installs fail when commands needed file matching.
• Fixed configured paths that begin with ~ or ~/ so project, workspace, DerivedData, AXe, and template paths resolve under the user's home directory instead of creating literal ~ folders. Absolute configured paths are now normalized before use (#283, supersedes #301 by @trmquang93).
• Fixed device build next-step guidance so agents no longer suggest unsupported --device-id or deviceId arguments (#287, #300 by @trmquang93, #350 by @MukundaKatta).
• Fixed Xcode IDE manual disconnect immediately reconnecting after the user explicitly disconnected it (#343, #344 by @shaun0927).
• Fixed simulator defaults refresh so stale simulator IDs are reconciled when both a simulator name and ID are configured, without rewriting shared project config files unnecessarily (#357).
• Fixed session profile output so the persisted field accurately reflects whether a profile switch was saved.
• Fixed long-running commands that could hang even after completing.
• Fixed build and test failures after command startup returning incomplete output; they now finish with a clear error result and log paths.
• Fixed final text and JSON results changing unexpectedly when commands also stream live progress (#360).
• Fixed test result output so agents can find xcresult bundle paths after simulator, device, macOS, and Swift Package test runs (#397).
• Fixed test summaries and progress output so CLI tests no longer show false compiler errors, mixed Swift Testing/XCTest suites are counted accurately, parameterized Swift Testing cases are not overcounted, and simulator test progress stays visible while tests run (#383, #392).
• Fixed device tool calls that use session defaults so they no longer fail when platform is omitted.

Various other internal improvements to stability, performance, and code quality.

[2.3.2]

Fixed

• Improved reliability of internal telemetry during shutdown (#302).

[2.3.1]

Fixed

• Fixed unnecessary tool confirmation prompts in MCP clients (such as Codex) that treat missing approval annotations as high-risk defaults (#297).

[2.3.0]

Added

• Added environment variable support for session defaults (e.g. XCODEBUILDMCP_WORKSPACE_PATH, XCODEBUILDMCP_SCHEME, XCODEBUILDMCP_PLATFORM) so MCP clients can supply startup defaults in their config without a project config file (#268 by @detailobsessed). See docs/CONFIGURATION.md.
• Added --format mcp-json flag to xcodebuildmcp setup that exports an env-based MCP client config block instead of writing config.yaml (#268 by @detailobsessed).

Changed

• Clarified configuration layering: session_set_defaults overrides config.yaml, which overrides environment variables. See docs/CONFIGURATION.md (#268 by @detailobsessed).
• Improved xcodebuildmcp setup reliability when optional targets (like physical devices) are unavailable.

Fixed

• Fixed .xcodebuildmcp/config.yaml being modified on startup when simulator metadata was refreshed (#230).
• Fixed orphaned MCP server processes that could remain running after the client disconnects (#273).
• Fixed list-schemes CLI command missing --project-path and --workspace-path flags (#271).
• Fixed Xcode IDE workflow tools not working when invoked from the CLI.
• Fixed Swift Package tools not properly waiting for process exit when stopping.

[2.2.1]

• Fix AXe bundling issue.

[2.2.0]

Added

• Added get_coverage_report and get_file_coverage tools for inspecting code coverage from test results — view per-target summaries or drill into function-level coverage and uncovered line ranges for specific files (#240 by @irangareddy). See docs/TOOLS.md.

• Added a unified build-and-run command for physical devices, matching the existing simulator workflow so agents can build and launch device apps in a single step.

• Added an interactive setup wizard via xcodebuildmcp setup that walks you through creating or updating .xcodebuildmcp/config.yaml — select workflows, pick a simulator, set your scheme and project, and configure debug options without editing YAML by hand. Non-interactive mode remains available for CI and scripting. See docs/CONFIGURATION.md.

  xcodebuildmcp setup

• Added AGENTS.md generation to the init command, providing prescriptive agent workflow instructions for your project.

• Added support for custom workflows in .xcodebuildmcp/config.yaml. Define your own workflow names and map them to an explicit list of tools, then reference them from enabledWorkflows like any built-in workflow. This lets you limit the tools your agent sees to exactly the ones you need. See docs/CONFIGURATION.md.

  enabledWorkflows: ["my-workflow"]
  customWorkflows:
    my-workflow:
      - build_run_sim
      - record_sim_video
      - screenshot

• Added AdaL CLI setup instructions (#242 by @Abdulrahmansoliman).

Changed

• CLI now auto-fills tool arguments from session defaults. If your config file sets a scheme, project path, or simulator, every CLI command picks those up automatically — no need to repeat --scheme, --project-path, and similar flags on every invocation. See docs/CLI.md.

  # .xcodebuildmcp/config.yaml
  sessionDefaults:
    scheme: MyApp
    projectPath: ./MyApp.xcodeproj
    simulatorName: iPhone 17 Pro

  # Before: every command needed explicit flags
  xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj
  
  # Now: flags are filled from session defaults
  xcodebuildmcp simulator build

  This also works with session defaults profiles, which is especially useful for monorepos. Define a profile per sub-project and the CLI uses the active profile's values. Override the profile for a single command with --profile. See docs/SESSION_DEFAULTS.md.

  # .xcodebuildmcp/config.yaml
  schemaVersion: 1
  sessionDefaultsProfiles:
    calculator:
      workspacePath: ./iOS_Calculator/CalculatorApp.xcworkspace
      scheme: CalculatorApp
      simulatorName: iPhone 17 Pro
    ios-test:
      projectPath: ./iOS/MCPTest.xcodeproj
      scheme: MCPTest
      simulatorName: iPhone 17 Pro
    spm:
      projectPath: ./spm
      scheme: spm
  activeSessionDefaultsProfile: calculator

  # Build using the active profile (calculator)
  xcodebuildmcp simulator build-and-run
  
  # Build a different sub-project without switching the active profile
  xcodebuildmcp simulator build-and-run --profile ios-test

• Default simulator updated from iPhone 16 to iPhone 17.

• Tool annotations now more accurately classify operations, reducing unnecessary confirmation prompts in MCP clients that respect annotations (#253 by @saschagordner).

• Improved agent workflow guidance with more prescriptive instructions for common tasks.

• Bundled AXe updated to 1.5.2.

Fixed

• Fixed Swift Package tools (swift_package_build, swift_package_test, swift_package_clean) hiding compiler diagnostics when stderr was empty (#255 by @doovers).
• Fixed stderr warnings (e.g. "multiple matching destinations") hiding actual test failures by prioritizing xcresult output when available (#254 by @czottmann).

Various other internal improvements to stability, performance, and code quality.

[2.1.0]

Added

• Added xcodebuildmcp init CLI command to install agent skills, replacing the standalone install-skill.sh script. Supports auto-detection of AI clients (Claude Code, Cursor, Codex), --print for unsupported clients, and --uninstall for removal. See docs/SKILLS.md.
• Added namespaced session defaults profiles, letting you save and switch between different project/scheme/simulator configurations without reconfiguring each time. See docs/SESSION_DEFAULTS.md.
• Added support for persisting custom environment variables in session defaults (#235 by @kamal). See docs/SESSION_DEFAULTS.md.
• Added Kiro client setup instructions (#222 by @manojmahapatra).

Added

• Added get_coverage_report tool to show per-target code coverage from xcresult bundles (#227)
• Added get_file_coverage tool to show function-level coverage and uncovered line ranges for specific files (#227)

Changed

• Faster MCP startup when the Xcode IDE workflow is enabled — tools are available sooner after connecting (#210). See docs/XCODE_IDE_MCPBRIDGE.md.
• Agents now use the combined build-and-run tool for simulator run intents, avoiding a redundant separate build step.
• Improved next-step suggestions so agents receive more accurate follow-up actions after each tool call.
• Updated UI automation tap guidance to prefer label and ID targets, reducing agent errors.

Fixed

• Fixed false positive error and warning detection when build output contained echoed source code (#218 by @nebooz).
• Fixed outdated tool names and parameters in the CLI skill file (#217 by @pocketpixels).
• Fixed Sentry telemetry scope to capture only internal runtime failures, removing unnecessary data collection (#204).
• Fixed a shell injection vulnerability in the release workflow (#229).
• Improved privacy redaction in the doctor command to better protect project names and paths in default output.

Removed

• Removed scripts/install-skill.sh in favour of xcodebuildmcp init.

Various other internal improvements to stability, performance, and code quality.

[2.0.7]

Changed

• XcodeBuildMCP has moved to the getsentry GitHub organization. Homebrew users should switch to the new tap: brew untap cameroncooke/xcodebuildmcp && brew tap getsentry/xcodebuildmcp. npm and npx users are unaffected.

[2.0.5] - 2026-02-10

Added

• Homebrew installation (brew tap getsentry/xcodebuildmcp && brew install xcodebuildmcp) — installs a self-contained binary with no Node.js dependency.

Removed

• Smithery distribution channel.

[2.0.0]

New! CLI

XcodeBuildMCP now includes a first-class CLI for direct terminal usage, scripting, and CI workflows. All the same tools available via MCP are accessible from the command line.

npm install -g xcodebuildmcp@beta
xcodebuildmcp tools # List available tools
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj

Stateful operations (log capture, debugging, video recording) are backed by a per-workspace background process that starts automatically and shuts down after idle. See docs/CLI.md for full documentation.

New! Configuration File

Project-level configuration via .xcodebuildmcp/config.yaml replaces the need for environment variables. Set your project path, scheme, simulator, enabled workflows, debug settings, and more in one place. Environment variables still work but the config file takes precedence.

schemaVersion: 1
enabledWorkflows:
  - simulator
  - ui-automation
  - debugging
sessionDefaults:
  scheme: MyApp
  projectPath: ./MyApp.xcodeproj
  simulatorName: iPhone 17

See docs/CONFIGURATION.md for the full reference.

New! Xcode IDE Integration

XcodeBuildMCP can now proxy tools from Xcode 26.3's built-in MCP bridge, giving your agent access to Xcode IDE capabilities like Preview rendering, the Issue Navigator, and documentation search. Enable the xcode-ide workflow to use this. Setup instructions for both Codex Agent and Claude Code Agent in Xcode are included. See docs/XCODE_IDE_MCPBRIDGE.md for details.

Added

• LLDB Debugging: Attach a debugger to simulator apps, set breakpoints, inspect variables, view the call stack, and run LLDB commands — all through your agent. Supports both DAP and LLDB-CLI backends. See docs/TOOLS.md for the debugging tools.
• Session default persistence: Session defaults can now be saved to the config file with persist: true, so your preferred project, scheme, and simulator are remembered across sessions.
• Log subsystem filtering: Filter simulator log capture by subsystem — choose app (default), all, swiftui (for Self._printChanges() output), or a custom list of subsystems.
• Agent skills: Optional skill files that prime your agent with usage instructions for the MCP server or CLI. Install via the provided shell script or manually. See docs/SKILLS.md.
• MCP tool annotations: All tools now include MCP-standard annotations (read-only vs. destructive, idempotent, etc.) for clients that support them.
• Simulator name resolution: Session defaults now accept a simulator name and automatically resolve it to a device ID.
• Launch environment variables: Launch tools now accept an optional env object so you can pass runtime environment variables when starting apps on simulator or device.

Changed

• Simulator tools are now the default workflow. Previously all workflows loaded by default, increasing context usage.
• Bundled AXe updated to 1.3.0.
• Landscape screenshots now orient correctly.
• Simulator platform detection and default refresh behavior are more reliable, so simulator commands stay aligned with your current defaults as they change.

Fixed

• Fixed incremental builds corrupting arguments when strings contained substrings matching build flags.
• Fixed build path handling so relative project, workspace, and derived data paths resolve correctly even when commands run from different working directories.
• Fixed working-directory leakage in incremental build setup that could affect concurrent requests.
• Fixed simulator screenshot matching for similarly named devices (for example, iPhone 15 and iPhone 15 Pro).

[1.15.1] - 2025-12-20

Changed

• Add suppressWarnings to suppress warnings from the build tools.
• Update AXe to 1.2.0
• Update tap tool to accept label/id as tap targets.

[1.15.0] - 2025-12-15

Added

• Add support for in-memory session defaults.

Changed

• Various bug fixes and improvements

[1.14.0] - 2025-09-22

• Add video capture tool for simulators

[1.13.1] - 2025-09-21

• Add simulator erase content and settings tool

[1.12.3] - 2025-08-22

• Pass environment variables to test runs on device, simulator, and macOS via an optional testRunnerEnv input (auto-prefixed as TEST_RUNNER_).

[1.12.2] - 2025-08-21

Fixed

• Clean tool: Fixed issue where clean would fail for simulators

[1.12.1] - 2025-08-18

Improved

• Sentry Logging: No longer logs domain errors to Sentry, now only logs MCP server errors.

[1.12.0] - 2025-08-17

Added

• Unify project/workspace and sim id/name tools into a single tools reducing the number of tools from 81 to 59, this helps reduce the client agent's context window size by 27%!
• Selective Workflow Loading: New XCODEBUILDMCP_ENABLED_WORKFLOWS environment variable allows loading only specific workflow groups in static mode, reducing context window usage for clients that don't support MCP sampling (Thanks to @codeman9 for their first contribution!)
• Rename diagnosics tool and cli to doctor
• Add Sentry instrumentation to track MCP usage statistics (can be disabled by setting XCODEBUILDMCP_SENTRY_DISABLED=true)
• Add support for MCP setLevel handler to allow clients to control the log level of the MCP server

[v1.11.2] - 2025-08-08

• Fixed "registerTools is not a function" errors during package upgrades

[v1.11.1] - 2025-08-07

• Improved tool discovery to be more accurate and context-aware

[v1.11.0] - 2025-08-07

• Major refactor/rewrite to improve code quality and maintainability in preparation for future development
• Added support for dynamic tools (VSCode only for now)
• Added support for MCP Resources (devices, simulators, environment info)
• Workaround for #66 and anthropics/claude-code#1804 issues where Claude Code would only see the first text content from tool responses

[v1.10.0] - 2025-06-10

Added

• App Lifecycle Management: New tools for stopping running applications
  • stop_app_device: Stop apps running on physical Apple devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro)
  • stop_app_sim: Stop apps running on iOS/watchOS/tvOS/visionOS simulators
  • stop_mac_app: Stop macOS applications by name or process ID
• Enhanced Launch Tools: Device launch tools now return process IDs for better app management
• Bundled AXe Distribution: AXe binary and frameworks now included in npm package for zero-setup UI automation

Fixed

• WiFi Device Detection: Improved detection of Apple devices connected over WiFi networks
• Device Connectivity: Better handling of paired devices with different connection states

Improved

• Simplified Installation: No separate AXe installation required - everything works out of the box

[v1.9.0] - 2025-06-09

• Added support for hardware devices over USB and Wi-Fi
• New tools for Apple device deployment:
  • install_app_device
  • launch_app_device
• Updated all simulator and device tools to be platform-agnostic, supporting all Apple platforms (iOS, iPadOS, watchOS, tvOS, visionOS)
• Changed get_ios_bundle_id to get_app_bundle_id with support for all Apple platforms

[v1.8.0] - 2025-06-07

• Added support for running tests on macOS, iOS simulators, and iOS devices
• New tools for testing:
  • test_macos_workspace
  • test_macos_project
  • test_ios_simulator_name_workspace
  • test_ios_simulator_name_project
  • test_ios_simulator_id_workspace
  • test_ios_simulator_id_project
  • test_ios_device_workspace
  • test_ios_device_project

[v1.7.0] - 2025-06-04

• Added support for Swift Package Manager (SPM)
• New tools for Swift Package Manager:
  • swift_package_build
  • swift_package_clean
  • swift_package_test
  • swift_package_run
  • swift_package_list
  • swift_package_stop

[v1.6.1] - 2025-06-03

• Improve UI tool hints

[v1.6.0] - 2025-06-03

• Moved project templates to external GitHub repositories for independent versioning
• Added support for downloading templates from GitHub releases
• Added local template override support via environment variables
• Added scaffold_ios_project and scaffold_macos_project tools for creating new projects
• Centralized template version management in package.json for easier updates

[v1.5.0] - 2025-06-01

• UI automation is no longer in beta!
• Added support for AXe UI automation
• Revised default installation instructions to prefer npx instead of mise

[v1.4.0] - 2025-05-11

• Merge the incremental build beta branch into main
• Add preferXcodebuild argument to build tools with improved error handling allowing the agent to force the use of xcodebuild over xcodemake for complex projects. It also adds a hint when incremental builds fail due to non-compiler errors, enabling the agent to automatically switch to xcodebuild for a recovery build attempt, improving reliability.

[v1.3.7] - 2025-05-08

• Fix Claude Code issue due to long tool names

[v1.4.0-beta.3] - 2025-05-07

• Fixed issue where incremental builds would only work for "Debug" build configurations

[v1.4.0-beta.2] - 2025-05-07

• Same as beta 1 but has the latest features from the main release channel

[v1.4.0-beta.1] - 2025-05-05

• Added experimental support for incremental builds (requires opt-in)

[v1.3.6] - 2025-05-07

• Added support for enabling/disabling tools via environment variables

[v1.3.5] - 2025-05-05

• Fixed the text input UI automation tool
• Improve the UI automation tool hints to reduce agent tool call errors
• Improved the project discovery tool to reduce agent tool call errors
• Added instructions for installing idb client manually

[v1.3.4] - 2025-05-04

• Improved Sentry integration

[v1.3.3] - 2025-05-04

• Added Sentry opt-out functionality

[v1.3.1] - 2025-05-03

• Added Sentry integration for error reporting

[v1.3.0] - 2025-04-28

• Added support for interacting with the simulator (tap, swipe etc.)
• Added support for capturing simulator screenshots

Please note that the UI automation features are an early preview and currently in beta your mileage may vary.

[v1.2.4] - 2025-04-24

• Improved xcodebuild reporting of warnings and errors in tool response
• Refactor build utils and remove redundant code

[v1.2.3] - 2025-04-23

• Added support for skipping macro validation

[v1.2.2] - 2025-04-23

• Improved log readability with version information for easier debugging
• Enhanced overall stability and performance

[v1.2.1] - 2025-04-23

• General stability improvements and bug fixes

[v1.2.0] - 2025-04-14

Added

• New simulator log capture feature: Easily view and debug your app's logs while running in the simulator
• Automatic project discovery: XcodeBuildMCP now finds your Xcode projects and workspaces automatically
• Support for both Intel and Apple Silicon Macs in macOS builds

Improved

• Cleaner, more readable build output with better error messages
• Faster build times and more reliable build process
• Enhanced documentation with clearer usage examples

[v1.1.0] - 2025-04-05

Added

• Real-time build progress reporting
• Separate tools for iOS and macOS builds
• Better workspace and project support

Improved

• Simplified build commands with better parameter handling
• More reliable clean operations for both projects and workspaces

[v1.0.2] - 2025-04-02

• Improved documentation with better examples and clearer instructions
• Easier version tracking for compatibility checks

[v1.0.1] - 2025-04-02

• Initial release of XcodeBuildMCP
• Basic support for building iOS and macOS applications