Skip to content

Commit 6f1c55b

Browse files
cameroncookeclaude
cameroncooke
and
claude
committed
docs: Add v2.0.0 migration guide
Add migration guide covering the two breaking changes in v2.0.0: the required `mcp` subcommand for server launch, and the default workflow change from all workflows to simulator-only. Also covers the new CLI, agent skills, MCP vs CLI trade-offs, and the new project-level config file. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent ffe966f commit 6f1c55b

1 file changed

Lines changed: 246 additions & 0 deletions

File tree

‎docs/MIGRATION_V2.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# Migrating to XcodeBuildMCP v2.0.0
2+
3+
This guide covers breaking changes and required actions when upgrading from v1.x to v2.0.0.
4+
5+
## Quick migration
6+
7+
There are two breaking changes. Most users only need to do step 1.
8+
9+
**1. Append `mcp` to your server launch command.**
10+
11+
The `xcodebuildmcp` binary is now a CLI. To start the MCP server you must pass the `mcp` subcommand. Without it the MCP client will fail to connect.
12+
13+
```
14+
# v1.x
15+
npx -y xcodebuildmcp@latest
16+
17+
# v2.0.0
18+
npx -y xcodebuildmcp@latest mcp
19+
```
20+
21+
If you installed via a CLI command, remove and re-add:
22+
23+
```bash
24+
# Claude Code
25+
claude mcp remove XcodeBuildMCP
26+
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
27+
28+
# Codex CLI
29+
codex mcp remove XcodeBuildMCP
30+
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
31+
```
32+
33+
If you manage a configuration file directly, add `"mcp"` as the last entry in the `args` array. See [section 1](#1-mcp-server-launch-requires-the-mcp-subcommand) for file locations and examples.
34+
35+
**2. Check your workflow configuration (if needed).**
36+
37+
v2.0.0 defaults to loading only the `simulator` workflow instead of all workflows. If you already set `enabledWorkflows` or `XCODEBUILDMCP_ENABLED_WORKFLOWS`, nothing changes for you.
38+
39+
If you relied on the previous default and need additional workflows, add them to `.xcodebuildmcp/config.yaml`:
40+
41+
```yaml
42+
schemaVersion: 1
43+
enabledWorkflows:
44+
- simulator
45+
- ui-automation
46+
- debugging
47+
```
48+
49+
See [section 2](#2-default-workflows-changed) for the rationale and full list of available workflows.
50+
51+
---
52+
53+
# Detailed reference
54+
55+
## 1. MCP server launch requires the `mcp` subcommand
56+
57+
The `xcodebuildmcp` binary is now a CLI first. To start the MCP server, you must pass the `mcp` subcommand at the end of the launch command. Without it, the binary enters CLI mode and the MCP client will fail to connect.
58+
59+
Wherever your v1.x setup invoked `xcodebuildmcp` (or `npx -y xcodebuildmcp@latest`), append `mcp` so the final token of the command is `mcp`.
60+
61+
### Option A: Remove and re-add via CLI
62+
63+
If you originally installed using a CLI command (e.g. `claude mcp add`, `codex mcp add`), remove the existing entry and re-add with the updated command.
64+
65+
**Claude Code:**
66+
67+
```bash
68+
claude mcp remove XcodeBuildMCP
69+
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
70+
```
71+
72+
**Codex CLI:**
73+
74+
```bash
75+
codex mcp remove XcodeBuildMCP
76+
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
77+
```
78+
79+
### Option B: Edit the configuration file directly
80+
81+
If you manage MCP servers through a configuration file, open it and add `"mcp"` as the last entry in the `args` array.
82+
83+
Common file locations:
84+
85+
| Client | Configuration file |
86+
|--------|--------------------|
87+
| Claude Code | `~/.claude.json` |
88+
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
89+
| Cursor (project) | `.cursor/mcp.json` |
90+
| Cursor (global) | `~/.cursor/mcp.json` |
91+
| VS Code (project) | `.vscode/mcp.json` |
92+
| VS Code (global) | `~/Library/Application Support/Code/User/mcp.json` |
93+
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
94+
| Trae | `~/Library/Application Support/Trae/User/mcp.json` |
95+
| Codex CLI | `~/.codex/config.toml` |
96+
97+
JSON example:
98+
99+
```json
100+
"XcodeBuildMCP": {
101+
"command": "npx",
102+
"args": ["-y", "xcodebuildmcp@latest", "mcp"]
103+
}
104+
```
105+
106+
TOML example (Codex CLI):
107+
108+
```toml
109+
[mcp_servers.XcodeBuildMCP]
110+
command = "npx"
111+
args = ["-y", "xcodebuildmcp@latest", "mcp"]
112+
```
113+
114+
For the full set of client-specific examples, see the [README](../README.md#installation).
115+
116+
---
117+
118+
## 2. Default workflows changed
119+
120+
### Why this changed
121+
122+
In v1.x, all workflows loaded by default, exposing 70+ tools. Every tool definition and its schema is sent to the LLM on each turn, consuming context window space throughout the session. While most LLM providers cache these tokens to reduce re-inference cost, they still occupy context that could otherwise be used for your code and conversation.
123+
124+
v2.0.0 defaults to loading only the **`simulator` workflow** (21 tools). Simulator development is the most common use case, so this covers the majority of users while keeping the token footprint small.
125+
126+
Other workflows -- `ui-automation`, `debugging`, `device`, `macos`, and more -- are now opt-in. This gives you direct control over the trade-off between tool breadth and token cost. Enable only what you need, when you need it.
127+
128+
### Who is affected
129+
130+
- **Already set** `enabledWorkflows` or `XCODEBUILDMCP_ENABLED_WORKFLOWS`? Nothing changes.
131+
- **Relied on the default** (all workflows)? You will now only see simulator tools until you opt in to additional workflows.
132+
133+
### How to enable additional workflows
134+
135+
#### Config file (recommended)
136+
137+
Create or update `.xcodebuildmcp/config.yaml` in your workspace root:
138+
139+
```yaml
140+
schemaVersion: 1
141+
enabledWorkflows:
142+
- simulator
143+
- device
144+
- macos
145+
- ui-automation
146+
- debugging
147+
- swift-package
148+
```
149+
150+
#### Environment variable
151+
152+
Set `XCODEBUILDMCP_ENABLED_WORKFLOWS` in your MCP client configuration:
153+
154+
```json
155+
"XcodeBuildMCP": {
156+
"command": "npx",
157+
"args": ["-y", "xcodebuildmcp@latest", "mcp"],
158+
"env": {
159+
"XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,macos,ui-automation,debugging,swift-package"
160+
}
161+
}
162+
```
163+
164+
### Available workflows
165+
166+
| Workflow ID | Description |
167+
|-------------|-------------|
168+
| `simulator` | iOS simulator build, run, test, screenshots, logs (default) |
169+
| `device` | Physical device build, deploy, test, logs |
170+
| `macos` | macOS build, run, test |
171+
| `swift-package` | Swift Package Manager build, test, run |
172+
| `ui-automation` | Tap, swipe, text input, UI hierarchy inspection |
173+
| `debugging` | LLDB attach, breakpoints, variable inspection |
174+
| `logging` | Simulator and device log capture |
175+
| `simulator-management` | Boot, list, open simulators |
176+
| `utilities` | Clean build products |
177+
| `project-discovery` | Discover projects and workspaces |
178+
| `project-scaffolding` | Create new projects from templates |
179+
| `session-management` | Session defaults management |
180+
| `doctor` | Diagnostic tool (requires debug mode) |
181+
| `workflow-discovery` | Runtime workflow management (experimental) |
182+
| `xcode-ide` | Xcode IDE MCP bridge proxy (Xcode 26.3+) |
183+
184+
For full details on configuration options see [CONFIGURATION.md](CONFIGURATION.md). For session defaults (project, scheme, simulator, etc.) see [SESSION_DEFAULTS.md](SESSION_DEFAULTS.md).
185+
186+
---
187+
188+
## 3. CLI and skills
189+
190+
### xcodebuildmcp is now a CLI
191+
192+
The `xcodebuildmcp` command can now be used directly in the terminal without an MCP client:
193+
194+
```bash
195+
# Install globally
196+
npm install -g xcodebuildmcp@latest
197+
198+
# List available tools
199+
xcodebuildmcp tools
200+
201+
# Build and run on simulator
202+
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj
203+
204+
# Take a screenshot
205+
xcodebuildmcp simulator screenshot
206+
207+
# Tap a button
208+
xcodebuildmcp ui-automation tap --label "Submit"
209+
```
210+
211+
See [CLI.md](CLI.md) for full documentation.
212+
213+
### MCP vs CLI for coding agents
214+
215+
**The MCP server is the recommended way to use XcodeBuildMCP with coding agents and will yield the best results.** The CLI is provided as an alternative and for scripting/CI use cases.
216+
217+
Why MCP is preferred:
218+
219+
- **Automatic tool discovery** -- tools are registered with the agent at session start, so the agent always knows what is available and how to call it.
220+
- **Session defaults** -- the MCP server maintains stateful defaults (project path, scheme, simulator, etc.) across tool calls, so the agent does not have to recall and re-supply project details on every invocation. This significantly reduces errors.
221+
- **Stateful operations** -- log capture, debugging sessions, and other long-running operations are fully managed by the server.
222+
223+
The CLI avoids the per-turn context cost of MCP tool definitions since the agent invokes commands directly with no tool schemas to transmit. However, this comes with trade-offs: session defaults are not available in CLI mode, so the agent must pass all parameters explicitly on every call. Agents also tend to consume significant tokens repeatedly calling `--help` to re-discover commands and arguments. The CLI skill helps reduce this discovery overhead, but in practice MCP tools are almost always used more reliably by agents.
224+
225+
### Agent skills (optional)
226+
227+
v2.0.0 introduces optional skill files that prime your coding agent with usage instructions:
228+
229+
- **CLI Skill** -- strongly recommended when using the CLI with a coding agent.
230+
- **MCP Skill** -- optional when using the MCP server; gives the agent better context on available tools.
231+
232+
Install via the interactive installer:
233+
234+
```bash
235+
curl -fsSL https://raw.githubusercontent.com/cameroncooke/XcodeBuildMCP/v2.0.0/scripts/install-skill.sh -o install-skill.sh && bash install-skill.sh
236+
```
237+
238+
See [SKILLS.md](SKILLS.md) for more details.
239+
240+
---
241+
242+
## 4. New project-level configuration file
243+
244+
v2.0.0 adds support for a YAML config file at `.xcodebuildmcp/config.yaml`. This replaces the need for environment variables and provides deterministic, repo-scoped behavior. Environment variables still work but the config file takes precedence.
245+
246+
See [CONFIGURATION.md](CONFIGURATION.md) for the full reference.

0 commit comments

Comments
 (0)