You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+20-3Lines changed: 20 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,38 @@
1
1
# Changelog
2
2
3
3
## [Unreleased]
4
+
5
+
### Breaking
6
+
- 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 a change in behaviour, previously it would load all workflows and therefore tools by default.
7
+
8
+
This change is to reduce the number of tools loaded by default and requires the user to opt-in to enable the use of additional sets of tools based on their project or workflow requirements.
9
+
10
+
The reason the simulator workflow is the default is because it is the most common use case based on opt-in analytics data.
11
+
12
+
For more information see the [CONFIGURATION.md](docs/CONFIGURATION.md) documentation.
13
+
14
+
- Tool names and descriptions have been made more concise to redune token consumption. Tool argument names that are self explanatory have had their descriptions removed entirely.
15
+
4
16
### Added
5
17
- Add Smithery support for packaging/distribution.
- Add session-status MCP resource with session identifiers.
8
20
- Add UI automation guard that blocks UI tools when the debugger is paused.
9
-
- Add manage-workflows tool for live workflow selection updates.
10
-
- Add a bundled XcodeBuildMCP skill to improve MCP client tool discovery.
21
+
- 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)
22
+
- Add XcodeBuildMCP skill to improve MCP client tool use/discovery, this needs to be installed see [README.md](README.md) for more information.
23
+
- Added support for `.xcodebuildmcp/config.yaml` files for runtime configuration, this is a more flexible and powerful way to configure XcodeBuildMCP than environment variables.
24
+
- Added support for session-aware defaults that are persisted between sessions in the config file.
- Auto-include workflow-discovery when workflow selection is configured.
16
30
- Remove dynamic tool discovery (`discover_tools`) and `XCODEBUILDMCP_DYNAMIC_TOOLS`. Use `XCODEBUILDMCP_ENABLED_WORKFLOWS` to limit startup tool registration.
17
31
- Add MCP tool annotations to all tools.
18
-
32
+
- Route runtime configuration reads through the config store with layered precedence.
33
+
- Treat missing/empty `enabledWorkflows` as "load all workflows".
34
+
- Add config.yaml support for DAP/log capture tuning (`dapRequestTimeoutMs`, `dapLogEvents`, `launchJsonWaitMs`).
35
+
19
36
### Fixed
20
37
- Update UI automation guard guidance to point at `debug_continue` when paused.
21
38
- Fix tool loading bugs in static tool registration.
XcodeBuildMCP is configured through environment variables provided by your MCP client. Here is a single example showing how to add options to a typical MCP config:
By default, XcodeBuildMCP loads the `simulator` workflow at startup (plus `session-management`). If you want a smaller or different tool surface, set `XCODEBUILDMCP_ENABLED_WORKFLOWS` to a comma-separated list of workflow directory names. The `session-management` workflow is always auto-included since other tools depend on it. When `XCODEBUILDMCP_DEBUG=true`, the `doctor` workflow is also auto-included.
21
-
22
-
**Available workflows:**
23
-
-`device` (14 tools) - iOS Device Development
24
-
-`simulator` (19 tools) - iOS Simulator Development
XcodeBuildMCP includes experimental support for incremental builds. This feature is disabled by default and can be enabled by setting the `INCREMENTAL_BUILDS_ENABLED` environment variable to `true`.
41
-
42
-
> [!IMPORTANT]
43
-
> Incremental builds are highly experimental and your mileage may vary. Please report issues to the [issue tracker](https://github.com/cameroncooke/XcodeBuildMCP/issues).
3
+
XcodeBuildMCP reads configuration from a project config file and environment variables. The config file is optional but provides deterministic, repo-scoped behavior for every session.
44
4
45
-
## Experimental workflow discovery
46
-
47
-
Set `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY=true` to auto-include the `workflow-discovery` workflow at startup.
48
-
49
-
The workflow discovery tool lets agents and clients enable or disable workflows at runtime. This can reduce upfront context by loading only what is needed as the session evolves. Note: most clients do not yet support the MCP notifications required for an agent harness to re-query the tool list after changes.
50
-
51
-
## Session-aware opt-out
5
+
## Precedence
6
+
For runtime config (non-session defaults), precedence is:
7
+
1.`.xcodebuildmcp/config.yaml`
8
+
2. Environment variables
52
9
53
-
By default, XcodeBuildMCP uses a session-aware mode: the LLM (or client) sets shared defaults once (simulator, device, project/workspace, scheme, etc.), and all tools reuse them. This cuts context bloat not just in each call payload, but also in the tool schemas themselves.
10
+
## Config file (config.yaml)
54
11
55
-
If you prefer the older, explicit style where each tool requires its own parameters, set `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS=true`. This restores the legacy schemas with per-call parameters while still honoring any session defaults you choose to set.
56
-
57
-
Leave this unset for the streamlined session-aware experience; enable it to force explicit parameters on each tool call.
58
-
59
-
## Project config (config.yaml)
60
-
61
-
You can provide deterministic session defaults for every AI coding session by creating a project config file at:
12
+
Create a config file at your workspace root.
62
13
63
14
```
64
15
<workspace-root>/.xcodebuildmcp/config.yaml
65
16
```
66
17
67
-
Notes:
68
-
- Put the file in your **workspace root** (where your Xcode project is located).
69
-
- Agents can persist changes by calling `session_set_defaults` with `"persist": true` (see below).
- Relative paths in `projectPath`, `workspacePath`, and `derivedDataPath` resolve against the workspace root at load time.
43
+
Notes:
44
+
- `schemaVersion` is required and currently only supports `1`.
94
45
- If both `projectPath` and `workspacePath` are set, **workspacePath wins**.
95
46
- If both `simulatorId` and `simulatorName` are set, **simulatorId wins**.
96
47
97
48
### Persisting defaults from an agent
98
49
99
50
By default, when the agent calls `session_set_defaults`, defaults are only stored in memory for that session. To persist them to the config file, ask the agent to set the `persist` flag to `true`.
100
51
52
+
## Workflow selection
53
+
54
+
By default, XcodeBuildMCP loads all workflows at startup.
55
+
56
+
You can configure workflows in either:
57
+
- `enabledWorkflows`in `config.yaml` (preferred), or
58
+
- via environment variable `XCODEBUILDMCP_ENABLED_WORKFLOWS` (comma-separated)
59
+
60
+
Notes:
61
+
- If `enabledWorkflows` is omitted, empty or not set, only the default `simulator` workflow is loaded.
62
+
63
+
See [TOOLS.md](TOOLS.md) for a list of available workflows and tools.
64
+
65
+
## Debug logging
66
+
67
+
Enable debug logging with:
68
+
- `debug: true` in `config.yaml` (preferred), or
69
+
- via environment variable `XCODEBUILDMCP_DEBUG=true`
70
+
71
+
This enables an extra doctor tool that agents can run to get MCP and system environment information useful for debugging issues with XcodeBuildMCP.
72
+
73
+
## Incremental build support
74
+
75
+
Enable incremental builds with either:
76
+
- `incrementalBuildsEnabled: true` in `config.yaml` (preferred), or
77
+
- via environment variable `INCREMENTAL_BUILDS_ENABLED=true`
78
+
101
79
> [!IMPORTANT]
102
-
> The write is **patch-only**: only keys provided in that call are written (plus any removals needed for mutual exclusivity).
80
+
> Incremental builds are experimental and won't work for all projects. If you encounter issues, you can disable the option. The agent can also bypass incremental builds by passing a flag when calling build tools.
81
+
82
+
## Experimental workflow discovery
83
+
84
+
Enable via:
85
+
- `experimentalWorkflowDiscovery: true` in `config.yaml` (preferred), or
86
+
- via environment variable `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY=true`
87
+
88
+
Enables experimental workflow discovery, this feature adds a `manage-workflows` tool that the agent can use to add/remove workflows at runtime. This requires clients to support tools changed notifications and therefore is an opt-in and experimental feature.
89
+
90
+
> [!IMPORTANT]
91
+
> At time of writing neither Cursor, Claude Code or Codex support tools changed notifications.
92
+
93
+
## Session-aware opt-out
94
+
95
+
Disable session-aware schemas with:
96
+
- `disableSessionDefaults: true` in `config.yaml` (preferred), or
97
+
- via environment variable `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS=true`
98
+
99
+
Disables the session-aware defaults feature. This means that the agent will need to set the defaults for each tool call explictly. This is not recommended and will use more tokens per call. It's recommended to only enable this if your specific requirements need the build, device and simulator settings change frequently in a single coding session, i.e. monorepos with multiple projects.
100
+
101
+
## UI automation guard
102
+
103
+
Control UI automation when a debugger is paused with:
104
+
- `uiDebuggerGuardMode: "error"| "warn" | "off"` in `config.yaml` (preferred), or
105
+
- via environment variable `XCODEBUILDMCP_UI_DEBUGGER_GUARD_MODE=error|warn|off`
106
+
107
+
This feature is used to block UI tools when the debugger is paused, this is to prevent the agent from executing UI tools that will fail or return incorrect results when the debugger is paused.
108
+
109
+
Default is `error` when unset.
103
110
104
111
## Sentry telemetry opt-out
105
112
106
-
If you do not wish to send error logs to Sentry, set `XCODEBUILDMCP_SENTRY_DISABLED=true`.
113
+
Disable Sentry with:
114
+
- `XCODEBUILDMCP_SENTRY_DISABLED=true`
115
+
116
+
By default we send error logs to Sentry, this can be disabled to prevent any error logs from being sent.
117
+
118
+
See [PRIVACY.md](PRIVACY.md) for more information.
107
119
108
120
## AXe binary override
109
121
110
-
UI automation and simulator video capture require the AXe binary. By default, XcodeBuildMCP uses the bundled AXe when available, then falls back to `PATH`. To force a specific binary location, set `XCODEBUILDMCP_AXE_PATH` (preferred). `AXE_PATH` is also recognized for compatibility.
122
+
UI automation and simulator video capture require AXe. By default AXe is bundled with XcodeBuildMCP, but you can override the path to use a different version of AXe by setting these options.
111
123
112
-
Example:
124
+
Configure the binary path with:
125
+
- `axePath: "/opt/axe/bin/axe"` in `config.yaml` (preferred), or
126
+
- via environment variable `XCODEBUILDMCP_AXE_PATH=/opt/axe/bin/axe`
113
127
114
-
```
115
-
XCODEBUILDMCP_AXE_PATH=/opt/axe/bin/axe
116
-
```
128
+
For more information about AXe see: [https://github.com/cameroncooke/axe](https://github.com/cameroncooke/axe).
129
+
130
+
## Template overrides
131
+
132
+
The macOS and iOS scaffold tools pull templates from https://github.com/cameroncooke/XcodeBuildMCP-macOS-Template and https://github.com/cameroncooke/XcodeBuildMCP-iOS-Template respectively.
133
+
134
+
If you want to use your own source/fork for templates you can override the default locations and versions by setting these options.
135
+
136
+
Set custom template locations and versions with:
137
+
- `iosTemplatePath`/ `macosTemplatePath` in `config.yaml` (preferred), or
138
+
- via environment variable `XCODEBUILDMCP_IOS_TEMPLATE_PATH=/path/to/ios/templates`
139
+
- via environment variable `XCODEBUILDMCP_MACOS_TEMPLATE_PATH=/path/to/macos/templates`
140
+
- `iosTemplateVersion`/ `macosTemplateVersion` in `config.yaml`, or
141
+
- `XCODEBUILD_MCP_IOS_TEMPLATE_VERSION=v1.2.3`
142
+
- `XCODEBUILD_MCP_MACOS_TEMPLATE_VERSION=v1.2.3`
143
+
144
+
These override the default template versions bundled in the package.
145
+
146
+
## Debugger backend
147
+
148
+
Select the debugger backend with:
149
+
- `debuggerBackend: "dap"| "lldb-cli"` in `config.yaml`, or
150
+
- `XCODEBUILDMCP_DEBUGGER_BACKEND=dap|lldb-cli`
151
+
152
+
This overridens the debugger backend and defaults to `dap`. It's not generally recommended to change this.
153
+
154
+
## DAP backend settings
155
+
156
+
Tune the DAP backend with:
157
+
- `dapRequestTimeoutMs: 30000` in `config.yaml`, or
158
+
- `XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS=30000`
159
+
160
+
This overrides the default request timeout of 30 seconds.
161
+
162
+
Enable DAP event logging with:
163
+
- `dapLogEvents: true` in `config.yaml`, or
164
+
- `XCODEBUILDMCP_DAP_LOG_EVENTS=true`
165
+
166
+
This enables logging of DAP events to the console.
167
+
168
+
## Device log capture JSON wait
169
+
170
+
Control how long we wait for devicectl JSON output with:
171
+
- `launchJsonWaitMs: 8000` in `config.yaml`, or
172
+
- `XBMCP_LAUNCH_JSON_WAIT_MS=8000`
173
+
174
+
This overrides the default wait time of 8 seconds for devicectl JSON output.
Copy file name to clipboardExpand all lines: docs/SESSION_DEFAULTS.md
+6-10Lines changed: 6 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,25 +7,21 @@ By default, XcodeBuildMCP uses a session-aware mode. The client sets shared defa
7
7
- Tools reuse those defaults automatically.
8
8
- Agent can call `session_show_defaults` to inspect current values.
9
9
- Agent can call `session_clear_defaults` to clear values when switching contexts.
10
-
- Defaults can also be seeded from `.xcodebuildmcp/config.yaml` at server startup.
10
+
- Defaults can be seeded from `.xcodebuildmcp/config.yaml` at server startup.
11
11
12
12
See the session-management tools in [TOOLS.md](TOOLS.md).
13
13
14
14
## Opting out
15
-
If you prefer explicit parameters on every tool call, set:
15
+
If you prefer explicit parameters on every tool call, set`disableSessionDefaults: true` in your `.xcodebuildmcp/config.yaml` file.
16
16
17
-
```json
18
-
"env": {
19
-
"XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS": "true"
20
-
}
21
-
```
17
+
This restores the legacy schemas with per-call parameters while still honoring any defaults you choose to set.
22
18
23
-
This restores the legacy schemas with per-call parameters while still honoring any defaults you choose to set. Though this is not recommended, it can be useful in certain scenarios where you are working on monorepos or multiple projects at once.
19
+
See [CONFIGURATION.md](CONFIGURATION.md) for more information.
24
20
25
21
## Persisting defaults
26
-
Session defaults can be persisted between sessions by asking your agent to set the defaults with the `persist` flag set to `true`. This will save the defaults into `.xcodebuildmcp/config.yaml` at the root of your project's workspace.
22
+
Session defaults can be persisted between sessions by setting the `persist` flag to `true` on `session_set_defaults`. This writes to `.xcodebuildmcp/config.yaml` at the root of your workspace.
27
23
28
-
The persisted config is patch-only (only provided keys are written).
24
+
The persistence is patch-only: only keys provided in that call are written (plus any removals needed for mutual exclusivity).
29
25
30
26
You can also manually create the config file to essentially seed the defaults at startup; see [CONFIGURATION.md](CONFIGURATION.md) for more information.
-`stop_device_log_cap` - Stop device app and return logs.
38
+
-`stop_sim_log_cap` - Stop sim app and return logs.
39
39
### macOS Development (`macos`)
40
40
**Purpose**: Complete macOS development workflow for both .xcodeproj and .xcworkspace files. Build, test, deploy, and manage macOS applications. (6 tools)
41
41
@@ -126,4 +126,4 @@ XcodeBuildMCP provides 72 tools organized into 14 workflow groups for comprehens
126
126
127
127
---
128
128
129
-
*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-27*
129
+
*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-28*
0 commit comments