Release v2.0.0-beta.1

Release v2.0.0-beta.1

Installation

npm install -g xcodebuildmcp@2.0.0-beta.1

Or use with npx:

npx xcodebuildmcp@2.0.0-beta.1

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.0.0-beta.1

Release notes

Breaking

Workflow selection

• By default when the enabledWorkflows configuration option or XCODEBUILDMCP_ENABLED_WORKFLOWS environment variable is not set or empty, XcodeBuildMCP will default to loading only the simulator workflow. This is a change in behaviour; previously it would load all workflows and therefore tools by default.

This change reduces the number of tools loaded by default and requires the user to opt in to enable additional sets of tools based on their project or workflow requirements.

The simulator workflow is the default because it is the most common use case based on opt-in analytics data.

For more information see the CONFIGURATION.md documentation.

• Tool names and descriptions have been made more concise to reduce token consumption. Tool argument names that are self-explanatory have had their descriptions removed entirely.

XcodeBuildMCP is now a first-class CLI

• XcodeBuildMCP now has a first class CLI interface. This allows you or your agent to invoke tools directly from the terminal which can help reduce the upfront context costs of MCP.

• When calling xcodebuildmcp without any arguments it will default to CLI mode, this is a breaking change, you must update your mcp client's configuration to pass the mcp argument:

From:

"XcodeBuildMCP": {
  "command": "npx",
  "args": [
    "-y",
    "xcodebuildmcp@latest"
  ]
}

To:

"XcodeBuildMCP": {
  "command": "npx",
  "args": [
    "-y",
    "xcodebuildmcp@2.0.0-beta.1",
    "mcp" // <--- add this argument
  ]
}

To lean more about the CLI interface see the CLI.md documentation.

New!

• Add DAP-based debugger backend and simulator debugging toolset (attach, breakpoints, stack, variables, LLDB command).
• XcodeBuildMCP uses a new project config file at .xcodebuildmcp/config.yaml for runtime configuration, this is a more flexible and powerful way to configure XcodeBuildMCP than environment variables.

Added

• Add session-status MCP resource with session identifiers.
• Add UI automation guard that blocks UI tools when the debugger is paused.
• Add manage-workflows tool to allow agents to change the workflows enable/disabling tools at runtime. This requires clients to support tools changed notifications. (opt-in only)
• Add XcodeBuildMCP skill to improve MCP client tool use/discovery, this needs to be installed see README.md for more information.
• Added support for session-aware defaults that are persisted between sessions in the config file.

Changed

• Migrate to Zod v4.
• Remove dynamic tool discovery (discover_tools) and XCODEBUILDMCP_DYNAMIC_TOOLS. Use XCODEBUILDMCP_ENABLED_WORKFLOWS to limit startup tool registration.
• Add MCP tool annotations to all tools.

Fixed

• Update UI automation guard guidance to point at debug_continue when paused.
• Fix tool loading bugs in static tool registration.
• Fix xcodemake command argument corruption when project directory path appears as substring in non-path arguments.
• Fix snapshot_ui warning state being isolated per UI automation tool, causing false warnings.
• Fixed screenshot tool capturing rotated images when simulator is in landscape orientation by detecting window dimensions and applying +90° rotation to correct the framebuffer capture. (#186 by @VincentStark)
• Fixed Sentry ESM compatibility by upgrading @sentry/node from 10.5.0 to 10.37.0 and @sentry/cli from 2.43.1 to 3.1.0 (Fixes XCODEBUILD-MCP-13SX)