Skip to content

Commit c07a7a8

Browse files
cameroncookecameroncooke
committed
ref(setup): Make target prompts workflow-driven
Collect simulator and device defaults based on the workflows a user selects instead of tying setup questions to the output format. This keeps yaml and mcp-json setup aligned and lets users skip pinning a default target when they do not want one. Reframe the docs so config.yaml remains the canonical config surface and env vars are described as bootstrap values for constrained MCP clients.
1 parent c11eabd commit c07a7a8

File tree

4 files changed

+724
-192
lines changed

4 files changed

+724
-192
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@
44

55
### Added
66

7-
- Added environment variable support for all session defaults (e.g., `XCODEBUILDMCP_WORKSPACE_PATH`, `XCODEBUILDMCP_SCHEME`, `XCODEBUILDMCP_PLATFORM`), enabling full configuration via the MCP client `env` field without requiring a config file ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
8-
- Added `--format mcp-json` flag to `xcodebuildmcp setup` that outputs a ready-to-paste MCP client config JSON block instead of writing `config.yaml` ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
9-
- Added copy-pastable MCP config examples for macOS, iOS, multi-platform, tvOS, and watchOS projects to [docs/CONFIGURATION.md](docs/CONFIGURATION.md) ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
7+
- Added environment variable support for flat session default bootstrap values (for example `XCODEBUILDMCP_WORKSPACE_PATH`, `XCODEBUILDMCP_SCHEME`, and `XCODEBUILDMCP_PLATFORM`) so constrained MCP clients can supply startup defaults without changing project config files ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
8+
- Added `--format mcp-json` flag to `xcodebuildmcp setup` that exports an env-based MCP bootstrap config block instead of writing `config.yaml` ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
9+
- Added MCP bootstrap config examples to [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for clients that need env-based startup defaults ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
1010

1111
### Changed
1212

13-
- Environment variables are now documented as the recommended configuration method for MCP client integration, replacing the previous "legacy" designation. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
13+
- Clarified configuration layering: `session_set_defaults` overrides `config.yaml`, which overrides env-based bootstrap values. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
1414

1515
## [2.2.1]
1616

@@ -407,4 +407,3 @@ Please note that the UI automation features are an early preview and currently i
407407
- Initial release of XcodeBuildMCP
408408
- Basic support for building iOS and macOS applications
409409

410-

‎docs/CONFIGURATION.md‎

Lines changed: 83 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ XcodeBuildMCP reads configuration from environment variables and/or a project co
44

55
## Contents
66

7-
- [Environment variables](#environment-variables)
87
- [Config file](#config-file)
98
- [Configuration layering](#configuration-layering)
9+
- [Environment variables](#environment-variables)
1010
- [Session defaults](#session-defaults)
1111
- [Workflow selection](#workflow-selection)
1212
- [Build settings](#build-settings)
@@ -18,158 +18,6 @@ XcodeBuildMCP reads configuration from environment variables and/or a project co
1818

1919
---
2020

21-
## Environment variables
22-
23-
Environment variables are the recommended configuration method for MCP client integration. Set them in the `env` field of your MCP client config (e.g., `mcp_config.json` for Windsurf, `.vscode/mcp.json` for VS Code, `claude_desktop_config.json` for Claude Desktop).
24-
25-
This approach works reliably across all MCP clients regardless of working directory, and avoids the need for filesystem-based config discovery.
26-
27-
### General settings
28-
29-
| Config option | Environment variable |
30-
|---------------|---------------------|
31-
| `enabledWorkflows` | `XCODEBUILDMCP_ENABLED_WORKFLOWS` (comma-separated) |
32-
| `experimentalWorkflowDiscovery` | `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY` |
33-
| `disableSessionDefaults` | `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS` |
34-
| `disableXcodeAutoSync` | `XCODEBUILDMCP_DISABLE_XCODE_AUTO_SYNC` |
35-
| `incrementalBuildsEnabled` | `INCREMENTAL_BUILDS_ENABLED` |
36-
| `debug` | `XCODEBUILDMCP_DEBUG` |
37-
| `sentryDisabled` | `XCODEBUILDMCP_SENTRY_DISABLED` |
38-
| `debuggerBackend` | `XCODEBUILDMCP_DEBUGGER_BACKEND` |
39-
| `dapRequestTimeoutMs` | `XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS` |
40-
| `dapLogEvents` | `XCODEBUILDMCP_DAP_LOG_EVENTS` |
41-
| `launchJsonWaitMs` | `XBMCP_LAUNCH_JSON_WAIT_MS` |
42-
| `uiDebuggerGuardMode` | `XCODEBUILDMCP_UI_DEBUGGER_GUARD_MODE` |
43-
| `axePath` | `XCODEBUILDMCP_AXE_PATH` |
44-
| `iosTemplatePath` | `XCODEBUILDMCP_IOS_TEMPLATE_PATH` |
45-
| `iosTemplateVersion` | `XCODEBUILD_MCP_IOS_TEMPLATE_VERSION` |
46-
| `macosTemplatePath` | `XCODEBUILDMCP_MACOS_TEMPLATE_PATH` |
47-
| `macosTemplateVersion` | `XCODEBUILD_MCP_MACOS_TEMPLATE_VERSION` |
48-
49-
### Session default settings
50-
51-
| Session default | Environment variable |
52-
|----------------|---------------------|
53-
| `workspacePath` | `XCODEBUILDMCP_WORKSPACE_PATH` |
54-
| `projectPath` | `XCODEBUILDMCP_PROJECT_PATH` |
55-
| `scheme` | `XCODEBUILDMCP_SCHEME` |
56-
| `configuration` | `XCODEBUILDMCP_CONFIGURATION` |
57-
| `simulatorName` | `XCODEBUILDMCP_SIMULATOR_NAME` |
58-
| `simulatorId` | `XCODEBUILDMCP_SIMULATOR_ID` |
59-
| `simulatorPlatform` | `XCODEBUILDMCP_SIMULATOR_PLATFORM` |
60-
| `deviceId` | `XCODEBUILDMCP_DEVICE_ID` |
61-
| `platform` | `XCODEBUILDMCP_PLATFORM` |
62-
| `useLatestOS` | `XCODEBUILDMCP_USE_LATEST_OS` |
63-
| `arch` | `XCODEBUILDMCP_ARCH` |
64-
| `suppressWarnings` | `XCODEBUILDMCP_SUPPRESS_WARNINGS` |
65-
| `derivedDataPath` | `XCODEBUILDMCP_DERIVED_DATA_PATH` |
66-
| `preferXcodebuild` | `XCODEBUILDMCP_PREFER_XCODEBUILD` |
67-
| `bundleId` | `XCODEBUILDMCP_BUNDLE_ID` |
68-
69-
### Example MCP configs
70-
71-
Use one of these as a starting point and fill in your workspace path and scheme.
72-
73-
**macOS app**
74-
75-
```json
76-
{
77-
"mcpServers": {
78-
"XcodeBuildMCP": {
79-
"command": "npx",
80-
"args": ["-y", "xcodebuildmcp@latest", "mcp"],
81-
"env": {
82-
"XCODEBUILDMCP_ENABLED_WORKFLOWS": "coverage,debugging,doctor,logging,macos,project-discovery,project-scaffolding,swift-package,ui-automation,utilities,xcode-ide",
83-
"XCODEBUILDMCP_WORKSPACE_PATH": "/Users/me/MyApp/MyApp.xcworkspace",
84-
"XCODEBUILDMCP_SCHEME": "MyApp",
85-
"XCODEBUILDMCP_PLATFORM": "macOS"
86-
}
87-
}
88-
}
89-
}
90-
```
91-
92-
> `macos` provides build/run/test/stop tools for macOS apps. No simulator workflow needed — macOS apps run natively.
93-
94-
---
95-
96-
**iOS app**
97-
98-
```json
99-
{
100-
"mcpServers": {
101-
"XcodeBuildMCP": {
102-
"command": "npx",
103-
"args": ["-y", "xcodebuildmcp@latest", "mcp"],
104-
"env": {
105-
"XCODEBUILDMCP_ENABLED_WORKFLOWS": "coverage,debugging,doctor,logging,project-discovery,project-scaffolding,simulator,swift-package,ui-automation,utilities,xcode-ide",
106-
"XCODEBUILDMCP_WORKSPACE_PATH": "/Users/me/MyApp/MyApp.xcworkspace",
107-
"XCODEBUILDMCP_SCHEME": "MyApp",
108-
"XCODEBUILDMCP_PLATFORM": "iOS Simulator",
109-
"XCODEBUILDMCP_SIMULATOR_NAME": "iPhone 16 Pro"
110-
}
111-
}
112-
}
113-
}
114-
```
115-
116-
> `simulator` provides build/run/test/install tools targeting iOS Simulator. Use `XCODEBUILDMCP_SIMULATOR_NAME` or `XCODEBUILDMCP_SIMULATOR_ID` to pin the target device.
117-
118-
---
119-
120-
**iOS + macOS (multi-platform or Catalyst)**
121-
122-
```json
123-
{
124-
"mcpServers": {
125-
"XcodeBuildMCP": {
126-
"command": "npx",
127-
"args": ["-y", "xcodebuildmcp@latest", "mcp"],
128-
"env": {
129-
"XCODEBUILDMCP_ENABLED_WORKFLOWS": "coverage,debugging,doctor,logging,macos,project-discovery,project-scaffolding,simulator,swift-package,ui-automation,utilities,xcode-ide",
130-
"XCODEBUILDMCP_WORKSPACE_PATH": "/Users/me/MyApp/MyApp.xcworkspace",
131-
"XCODEBUILDMCP_SCHEME": "MyApp"
132-
}
133-
}
134-
}
135-
}
136-
```
137-
138-
> Include both `simulator` and `macos` when the project supports multiple platforms. Omit `XCODEBUILDMCP_PLATFORM` to let the agent choose per-command.
139-
140-
---
141-
142-
**tvOS or watchOS app**
143-
144-
```json
145-
{
146-
"mcpServers": {
147-
"XcodeBuildMCP": {
148-
"command": "npx",
149-
"args": ["-y", "xcodebuildmcp@latest", "mcp"],
150-
"env": {
151-
"XCODEBUILDMCP_ENABLED_WORKFLOWS": "debugging,doctor,logging,project-discovery,simulator,swift-package,utilities,xcode-ide",
152-
"XCODEBUILDMCP_WORKSPACE_PATH": "/Users/me/MyApp/MyApp.xcworkspace",
153-
"XCODEBUILDMCP_SCHEME": "MyApp",
154-
"XCODEBUILDMCP_PLATFORM": "tvOS Simulator"
155-
}
156-
}
157-
}
158-
}
159-
```
160-
161-
> Replace `tvOS Simulator` with `watchOS Simulator` for watchOS. Coverage and UI automation are not available on these platforms.
162-
163-
---
164-
165-
You can also generate a config block interactively:
166-
167-
```bash
168-
xcodebuildmcp setup --format mcp-json
169-
```
170-
171-
---
172-
17321
## Config file
17422

17523
The config file provides repo-scoped, version-controllable configuration. Create it at your workspace root:
@@ -500,12 +348,92 @@ When multiple configuration sources are present, they are merged with clear prec
500348

501349
This follows the same pattern as tools like `git config` (`--flag` > `--local` > `--global`). Each layer serves a different context:
502350

503-
- **Env vars** are the portable MCP client integration path — they work regardless of working directory and are supported by every MCP client.
504-
- **Config file** is for repo-scoped, version-controlled settings and interactive CLI usage.
351+
- **Config file** is the canonical home for structured, repo-scoped, version-controlled settings.
352+
- **Env vars** are best used to bootstrap flat startup defaults for MCP clients with limited workspace support.
505353
- **Tool calls** are for agent-driven runtime adjustments.
506354

507355
---
508356

357+
## Environment variables
358+
359+
Environment variables are supported for MCP client integration when a client cannot reliably provide workspace context to the server. Set them in the `env` field of your MCP client config (for example `mcp_config.json` for Windsurf, `.vscode/mcp.json` for VS Code, or `claude_desktop_config.json` for Claude Desktop).
360+
361+
Use env vars for flat bootstrap values such as startup workflow selection, project path, scheme, simulator selector, or other scalar defaults. Keep structured project-owned configuration in `config.yaml`.
362+
363+
### General settings
364+
365+
| Config option | Environment variable |
366+
|---------------|---------------------|
367+
| `enabledWorkflows` | `XCODEBUILDMCP_ENABLED_WORKFLOWS` (comma-separated) |
368+
| `experimentalWorkflowDiscovery` | `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY` |
369+
| `disableSessionDefaults` | `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS` |
370+
| `disableXcodeAutoSync` | `XCODEBUILDMCP_DISABLE_XCODE_AUTO_SYNC` |
371+
| `incrementalBuildsEnabled` | `INCREMENTAL_BUILDS_ENABLED` |
372+
| `debug` | `XCODEBUILDMCP_DEBUG` |
373+
| `sentryDisabled` | `XCODEBUILDMCP_SENTRY_DISABLED` |
374+
| `debuggerBackend` | `XCODEBUILDMCP_DEBUGGER_BACKEND` |
375+
| `dapRequestTimeoutMs` | `XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS` |
376+
| `dapLogEvents` | `XCODEBUILDMCP_DAP_LOG_EVENTS` |
377+
| `launchJsonWaitMs` | `XBMCP_LAUNCH_JSON_WAIT_MS` |
378+
| `uiDebuggerGuardMode` | `XCODEBUILDMCP_UI_DEBUGGER_GUARD_MODE` |
379+
| `axePath` | `XCODEBUILDMCP_AXE_PATH` |
380+
| `iosTemplatePath` | `XCODEBUILDMCP_IOS_TEMPLATE_PATH` |
381+
| `iosTemplateVersion` | `XCODEBUILD_MCP_IOS_TEMPLATE_VERSION` |
382+
| `macosTemplatePath` | `XCODEBUILDMCP_MACOS_TEMPLATE_PATH` |
383+
| `macosTemplateVersion` | `XCODEBUILD_MCP_MACOS_TEMPLATE_VERSION` |
384+
385+
### Session default bootstrap values
386+
387+
| Session default | Environment variable |
388+
|----------------|---------------------|
389+
| `workspacePath` | `XCODEBUILDMCP_WORKSPACE_PATH` |
390+
| `projectPath` | `XCODEBUILDMCP_PROJECT_PATH` |
391+
| `scheme` | `XCODEBUILDMCP_SCHEME` |
392+
| `configuration` | `XCODEBUILDMCP_CONFIGURATION` |
393+
| `simulatorName` | `XCODEBUILDMCP_SIMULATOR_NAME` |
394+
| `simulatorId` | `XCODEBUILDMCP_SIMULATOR_ID` |
395+
| `simulatorPlatform` | `XCODEBUILDMCP_SIMULATOR_PLATFORM` |
396+
| `deviceId` | `XCODEBUILDMCP_DEVICE_ID` |
397+
| `platform` | `XCODEBUILDMCP_PLATFORM` |
398+
| `useLatestOS` | `XCODEBUILDMCP_USE_LATEST_OS` |
399+
| `arch` | `XCODEBUILDMCP_ARCH` |
400+
| `suppressWarnings` | `XCODEBUILDMCP_SUPPRESS_WARNINGS` |
401+
| `derivedDataPath` | `XCODEBUILDMCP_DERIVED_DATA_PATH` |
402+
| `preferXcodebuild` | `XCODEBUILDMCP_PREFER_XCODEBUILD` |
403+
| `bundleId` | `XCODEBUILDMCP_BUNDLE_ID` |
404+
405+
### Example MCP config
406+
407+
Use this when your MCP client needs env-based bootstrap defaults:
408+
409+
```json
410+
{
411+
"mcpServers": {
412+
"XcodeBuildMCP": {
413+
"command": "npx",
414+
"args": ["-y", "xcodebuildmcp@latest", "mcp"],
415+
"env": {
416+
"XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,debugging,logging",
417+
"XCODEBUILDMCP_WORKSPACE_PATH": "/Users/me/MyApp/MyApp.xcworkspace",
418+
"XCODEBUILDMCP_SCHEME": "MyApp",
419+
"XCODEBUILDMCP_PLATFORM": "iOS Simulator",
420+
"XCODEBUILDMCP_SIMULATOR_NAME": "iPhone 16 Pro"
421+
}
422+
}
423+
}
424+
}
425+
```
426+
427+
You can also export a bootstrap block interactively:
428+
429+
```bash
430+
xcodebuildmcp setup --format mcp-json
431+
```
432+
433+
That export is intended for MCP client bootstrap. It does not replace `config.yaml` as the canonical project configuration.
434+
435+
---
436+
509437
## Related docs
510438

511439
- Session defaults: [SESSION_DEFAULTS.md](SESSION_DEFAULTS.md)

0 commit comments

Comments
 (0)