Skip to content

Commit 2db0694

Browse files
cameroncookecameroncooke
committed
Update docs
1 parent c5929ed commit 2db0694

File tree

2 files changed

+116
-183
lines changed

2 files changed

+116
-183
lines changed

‎README.md‎

Lines changed: 79 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -19,18 +19,20 @@ A Model Context Protocol (MCP) server that provides Xcode-related tools for inte
1919
- [Getting started](#getting-started)
2020
- [Prerequisites](#prerequisites)
2121
- [Configure your MCP client](#configure-your-mcp-client)
22-
- [Quick install](#quick-install)
23-
- [Manual installation](#manual-installation)
24-
- [Alternative installation method using mise](#alternative-installation-method-using-mise)
25-
- [Installing via Smithery](#installing-via-smithery)
22+
- [One click install](#one-click-install)
23+
- [General installation](#general-installation)
24+
- [Specific client installation instructions](#specific-client-installation-instructions)
25+
- [OpenAI Codex CLI](#openai-codex-cli)
26+
- [Claude Code CLI](#claude-code-cli)
27+
- [Smithery](#smithery)
2628
- [MCP Compatibility](#mcp-compatibility)
2729
- [Incremental build support](#incremental-build-support)
2830
- [Dynamic Tools](#dynamic-tools)
2931
- [What is Dynamic Tools?](#what-is-dynamic-tools)
3032
- [How to Enable Dynamic Tools](#how-to-enable-dynamic-tools)
31-
- [Selective Workflow Loading (Static Mode)](#selective-workflow-loading-static-mode)
3233
- [Usage Example](#usage-example)
3334
- [Client Compatibility](#client-compatibility)
35+
- [Selective Workflow Loading (Static Mode)](#selective-workflow-loading-static-mode)
3436
- [Code Signing for Device Deployment](#code-signing-for-device-deployment)
3537
- [Troubleshooting](#troubleshooting)
3638
- [Doctor Tool](#doctor-tool)
@@ -117,76 +119,68 @@ For clients that support MCP resources XcodeBuildMCP provides efficient URI-base
117119

118120
### Configure your MCP client
119121

120-
#### Quick install
122+
#### One click install
121123

122124
For a quick install, you can use the following links:
123125

124-
- [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=XcodeBuildMCP&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IC15IHhjb2RlYnVpbGRtY3BAbGF0ZXN0IiwiZW52Ijp7IklOQ1JFTUVOVEFMX0JVSUxEU19FTkFCTEVEIjoiZmFsc2UiLCJYQ09ERUJVSUxETUNQX1NFTlRSWV9ESVNBQkxFRCI6ImZhbHNlIn19)
125-
- [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect/mcp/install?name=XcodeBuildMCP&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%5D%7D)
126-
- [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect/mcp/install?name=XcodeBuildMCP&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%5D%7D&quality=insiders)
126+
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=XcodeBuildMCP&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IC15IHhjb2RlYnVpbGRtY3BAbGF0ZXN0IiwiZW52Ijp7IklOQ1JFTUVOVEFMX0JVSUxEU19FTkFCTEVEIjoiZmFsc2UiLCJYQ09ERUJVSUxETUNQX1NFTlRSWV9ESVNBQkxFRCI6ImZhbHNlIn19)
127+
128+
[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect/mcp/install?name=XcodeBuildMCP&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%5D%7D)
129+
130+
[<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect/mcp/install?name=XcodeBuildMCP&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%5D%7D&quality=insiders)
127131

128-
#### Manual installation
132+
#### General installation
129133

130-
Configure your MCP client (Windsurf, Cursor, Claude Desktop, Claude Code etc.) to use the XcodeBuildMCP server by ammending your client application's MCP configuration.
134+
Most MCP clients (Cursor, VS Code, Windsurf, Claude Desktop etc) have standardised on the following JSON configuration format, just add the the following to your client's JSON configuration's `mcpServers` object:
131135

132136
```json
133-
{
134-
"mcpServers": {
135-
"XcodeBuildMCP": {
136-
"command": "npx",
137-
"args": [
138-
"-y",
139-
"xcodebuildmcp@latest"
140-
]
141-
}
142-
}
137+
"XcodeBuildMCP": {
138+
"command": "npx",
139+
"args": [
140+
"-y",
141+
"xcodebuildmcp@latest"
142+
]
143143
}
144144
```
145145

146-
#### Alternative installation method using mise
146+
#### Specific client installation instructions
147147

148-
Alternatively, you can use XcodeBuildMCP without a specific installation of Node.js by using `mise` to install it:
148+
##### OpenAI Codex CLI
149149

150-
```bash
151-
# macOS (Homebrew)
152-
brew install mise
150+
Codex uses a toml configuration file to configure MCP servers. To configure XcodeBuildMCP with [OpenAI's Codex CLI](https://github.com/openai/codex), add the following configuration to your Codex CLI config file:
153151

154-
# Other installation methods
155-
# See https://mise.jdx.dev/getting-started.html
152+
```toml
153+
[mcp_servers.XcodeBuildMCP]
154+
command = "npx"
155+
args = ["-y", "xcodebuildmcp@latest"]
156+
env = { "INCREMENTAL_BUILDS_ENABLED" = "false", "XCODEBUILDMCP_SENTRY_DISABLED" = "false" }
156157
```
157158

158-
Then configure your MCP client to use mise to install XcodeBuildMCP:
159+
For more information see [OpenAI Codex MCP Server Configuration](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers) documentation.
159160

160-
```json
161-
{
162-
"mcpServers": {
163-
"XcodeBuildMCP": {
164-
"command": "mise",
165-
"args": [
166-
"x",
167-
"npm:xcodebuildmcp@1.12.2",
168-
"--",
169-
"xcodebuildmcp"
170-
]
171-
}
172-
}
173-
}
174-
```
161+
##### Claude Code CLI
175162

176-
> [!NOTE]
177-
> When using mise avoid using the @latest tag as mise will cache the package and may not update to the latest version automatically, instead prefer an explicit version number.
163+
To use XcodeBuildMCP with [Claude Code](https://code.anthropic.com), you can add it via the command line:
178164

179-
> [!IMPORTANT]
180-
> Please note that XcodeBuildMCP will request xcodebuild to skip macro validation. This is to avoid errors when building projects that use Swift Macros.
165+
```bash
166+
# Add XcodeBuildMCP server to Claude Code
167+
claude mcp add XcodeBuildMCP npx xcodebuildmcp@latest
181168

182-
#### Installing via Smithery
169+
# Or with environment variables
170+
claude mcp add XcodeBuildMCP npx xcodebuildmcp@latest -H INCREMENTAL_BUILDS_ENABLED=false -H XCODEBUILDMCP_SENTRY_DISABLED=false
171+
```
172+
173+
##### Smithery
183174

184175
To install XcodeBuildMCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@cameroncooke/XcodeBuildMCP):
185176

186177
```bash
187178
npx -y @smithery/cli install @cameroncooke/XcodeBuildMCP --client claude
188179
```
189180

181+
> [!IMPORTANT]
182+
> Please note that XcodeBuildMCP will request xcodebuild to skip macro validation. This is to avoid errors when building projects that use Swift Macros.
183+
190184
#### MCP Compatibility
191185

192186
XcodeBuildMCP supports both MCP tools, resources and sampling. At time of writing the following editors have varying levels of MCP feature support:
@@ -205,20 +199,12 @@ XcodeBuildMCP includes experimental support for incremental builds. This feature
205199

206200
To enable incremental builds, set the `INCREMENTAL_BUILDS_ENABLED` environment variable to `true`:
207201

208-
Example MCP client configuration:
202+
Example MCP configuration:
209203
```json
210-
{
211-
"mcpServers": {
212-
"XcodeBuildMCP": {
213-
"command": "npx",
214-
"args": [
215-
"-y",
216-
"xcodebuildmcp@latest"
217-
],
218-
"env": {
219-
"INCREMENTAL_BUILDS_ENABLED": "true"
220-
}
221-
}
204+
"XcodeBuildMCP": {
205+
...
206+
"env": {
207+
"INCREMENTAL_BUILDS_ENABLED": "true"
222208
}
223209
}
224210
```
@@ -245,39 +231,42 @@ To enable dynamic tools, set the `XCODEBUILDMCP_DYNAMIC_TOOLS` environment varia
245231

246232
Example MCP client configuration:
247233
```json
248-
{
249-
"mcpServers": {
250-
"XcodeBuildMCP": {
251-
"command": "npx",
252-
"args": [
253-
"-y",
254-
"xcodebuildmcp@latest"
255-
],
256-
"env": {
257-
"XCODEBUILDMCP_DYNAMIC_TOOLS": "true"
258-
}
259-
}
234+
"XcodeBuildMCP": {
235+
...
236+
"env": {
237+
"XCODEBUILDMCP_DYNAMIC_TOOLS": "true"
260238
}
261239
}
262240
```
263241

242+
### Usage Example
243+
244+
Once enabled, AI agents automatically discover and load relevant tools based on context. For example, when you mention working on an iOS app or the agent detects iOS development tasks in your workspace, it will automatically use the `discover_tools` tool to load the appropriate simulator and project tools needed for your workflow.
245+
246+
### Client Compatibility
247+
248+
Dynamic Tools requires MCP clients that support **MCP Sampling** for the AI-powered tool discovery to function:
249+
250+
| Editor | Dynamic Tools Support |
251+
|--------|----------------------|
252+
| **VS Code** | ✅ |
253+
| **Cursor** | ❌ (No MCP Sampling) |
254+
| **Windsurf** | ❌ (No MCP Sampling) |
255+
| **Claude Code** | ❌ (No MCP Sampling) |
256+
| **Claude Desktop** | ❌ (No MCP Sampling) |
257+
258+
> [!NOTE]
259+
> For clients that don't support MCP Sampling, XcodeBuildMCP will automatically fall back to Static Mode, loading all tools at startup regardless of the `XCODEBUILDMCP_DYNAMIC_TOOLS` setting.
260+
264261
### Selective Workflow Loading (Static Mode)
265262

266263
For clients that don't support MCP Sampling but still want to reduce context window usage, you can selectively load only specific workflows using the `XCODEBUILDMCP_ENABLED_WORKFLOWS` environment variable:
267264

268265
```json
269-
{
270-
"mcpServers": {
271-
"XcodeBuildMCP": {
272-
"command": "npx",
273-
"args": [
274-
"-y",
275-
"xcodebuildmcp@latest"
276-
],
277-
"env": {
278-
"XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,project-discovery"
279-
}
280-
}
266+
"XcodeBuildMCP": {
267+
...
268+
"env": {
269+
"XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,project-discovery"
281270
}
282271
}
283272
```
@@ -299,25 +288,6 @@ For clients that don't support MCP Sampling but still want to reduce context win
299288
> [!NOTE]
300289
> The `XCODEBUILDMCP_ENABLED_WORKFLOWS` setting only works in Static Mode. If `XCODEBUILDMCP_DYNAMIC_TOOLS=true` is set, the selective workflow setting will be ignored.
301290
302-
### Usage Example
303-
304-
Once enabled, AI agents automatically discover and load relevant tools based on context. For example, when you mention working on an iOS app or the agent detects iOS development tasks in your workspace, it will automatically use the `discover_tools` tool to load the appropriate simulator and project tools needed for your workflow.
305-
306-
### Client Compatibility
307-
308-
Dynamic Tools requires MCP clients that support **MCP Sampling** for the AI-powered tool discovery to function:
309-
310-
| Editor | Dynamic Tools Support |
311-
|--------|----------------------|
312-
| **VS Code** | ✅ |
313-
| **Cursor** | ❌ (No MCP Sampling) |
314-
| **Windsurf** | ❌ (No MCP Sampling) |
315-
| **Claude Code** | ❌ (No MCP Sampling) |
316-
| **Claude Desktop** | ❌ (No MCP Sampling) |
317-
318-
> [!NOTE]
319-
> For clients that don't support MCP Sampling, XcodeBuildMCP will automatically fall back to Static Mode, loading all tools at startup regardless of the `XCODEBUILDMCP_DYNAMIC_TOOLS` setting.
320-
321291
## Code Signing for Device Deployment
322292

323293
For device deployment features to work, code signing must be properly configured in Xcode **before** using XcodeBuildMCP device tools:
@@ -366,18 +336,10 @@ This project uses [Sentry](https://sentry.io/) for error monitoring and diagnost
366336

367337
Example MCP client configuration:
368338
```json
369-
{
370-
"mcpServers": {
371-
"XcodeBuildMCP": {
372-
"command": "npx",
373-
"args": [
374-
"-y",
375-
"xcodebuildmcp@latest"
376-
],
377-
"env": {
378-
"XCODEBUILDMCP_SENTRY_DISABLED": "true"
379-
}
380-
}
339+
"XcodeBuildMCP": {
340+
...
341+
"env": {
342+
"XCODEBUILDMCP_SENTRY_DISABLED": "true"
381343
}
382344
}
383345
```

0 commit comments

Comments
 (0)