1
---
2
name: xcode-mcp
3
description: Guidelines for efficient Xcode MCP tool usage. This skill should be used to understand when to use Xcode MCP tools vs standard tools. Xcode MCP consumes many tokens - use only for build, test, simulator, preview, and SourceKit diagnostics. Never use for file read/write/grep operations.
4
---
5
6
# Xcode MCP Usage Guidelines
7
8
Xcode MCP tools consume significant tokens. This skill defines when to use Xcode MCP and when to prefer standard tools.
9
10
## Complete Xcode MCP Tools Reference
11
12
### Window & Project Management
13
| Tool | Description | Token Cost |
14
|------|-------------|------------|
15
| `mcp__xcode__XcodeListWindows` | List open Xcode windows (get tabIdentifier) | Low ✓ |
16
17
### Build Operations
18
| Tool | Description | Token Cost |
19
|------|-------------|------------|
20
| `mcp__xcode__BuildProject` | Build the Xcode project | Medium ✓ |
21
| `mcp__xcode__GetBuildLog` | Get build log with errors/warnings | Medium ✓ |
22
| `mcp__xcode__XcodeListNavigatorIssues` | List issues in Issue Navigator | Low ✓ |
23
24
### Testing
25
| Tool | Description | Token Cost |
26
|------|-------------|------------|
27
| `mcp__xcode__GetTestList` | Get available tests from test plan | Low ✓ |
28
| `mcp__xcode__RunAllTests` | Run all tests | Medium |
29
| `mcp__xcode__RunSomeTests` | Run specific tests (preferred) | Medium ✓ |
30
31
### Preview & Execution
32
| Tool | Description | Token Cost |
33
|------|-------------|------------|
34
| `mcp__xcode__RenderPreview` | Render SwiftUI Preview snapshot | Medium ✓ |
35
| `mcp__xcode__ExecuteSnippet` | Execute code snippet in file context | Medium ✓ |
36
37
### Diagnostics
38
| Tool | Description | Token Cost |
39
|------|-------------|------------|
40
| `mcp__xcode__XcodeRefreshCodeIssuesInFile` | Get compiler diagnostics for specific file | Low ✓ |
41
| `mcp__ide__getDiagnostics` | Get SourceKit diagnostics (all open files) | Low ✓ |
42
43
### Documentation
44
| Tool | Description | Token Cost |
45
|------|-------------|------------|
46
| `mcp__xcode__DocumentationSearch` | Search Apple Developer Documentation | Low ✓ |
47
48
### File Operations (HIGH TOKEN - NEVER USE)
49
| Tool | Alternative | Why |
50
|------|-------------|-----|
51
| `mcp__xcode__XcodeRead` | `Read` tool | High token consumption |
52
| `mcp__xcode__XcodeWrite` | `Write` tool | High token consumption |
53
| `mcp__xcode__XcodeUpdate` | `Edit` tool | High token consumption |
54
| `mcp__xcode__XcodeGrep` | `rg` / `Grep` tool | High token consumption |
55
| `mcp__xcode__XcodeGlob` | `Glob` tool | High token consumption |
56
| `mcp__xcode__XcodeLS` | `ls` command | High token consumption |
57
| `mcp__xcode__XcodeRM` | `rm` command | High token consumption |
58
| `mcp__xcode__XcodeMakeDir` | `mkdir` command | High token consumption |
59
| `mcp__xcode__XcodeMV` | `mv` command | High token consumption |
60
61
---
62
63
## Recommended Workflows
64
65
### 1. Code Change & Build Flow
66
```
67
1. Search code → rg "pattern" --type swift
68
2. Read file → Read tool
69
3. Edit file → Edit tool
70
4. Syntax check → mcp__ide__getDiagnostics
71
5. Build → mcp__xcode__BuildProject
72
6. Check errors → mcp__xcode__GetBuildLog (if build fails)
73
```
74
75
### 2. Test Writing & Running Flow
76
```
77
1. Read test file → Read tool
78
2. Write/edit test → Edit tool
79
3. Get test list → mcp__xcode__GetTestList
80
4. Run tests → mcp__xcode__RunSomeTests (specific tests)
81
5. Check results → Review test output
82
```
83
84
### 3. SwiftUI Preview Flow
85
```
86
1. Edit view → Edit tool
87
2. Render preview → mcp__xcode__RenderPreview
88
3. Iterate → Repeat as needed
89
```
90
91
### 4. Debug Flow
92
```
93
1. Check diagnostics → mcp__ide__getDiagnostics (quick syntax check)
94
2. Build project → mcp__xcode__BuildProject
95
3. Get build log → mcp__xcode__GetBuildLog (severity: error)
96
4. Fix issues → Edit tool
97
5. Rebuild → mcp__xcode__BuildProject
98
```
99
100
### 5. Documentation Search
101
```
102
1. Search docs → mcp__xcode__DocumentationSearch
103
2. Review results → Use information in implementation
104
```
105
106
---
107
108
## Fallback Commands (When MCP Unavailable)
109
110
If Xcode MCP is disconnected or unavailable, use these xcodebuild commands:
111
112
### Build Commands
113
```bash
114
# Debug build (simulator) - replace <SchemeName> with your project's scheme
115
xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
116
117
# Release build (device)
118
xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build
119
120
# Build with workspace (for CocoaPods projects)
121
xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
122
123
# Build with project file
124
xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
125
126
# List available schemes
127
xcodebuild -list
128
```
129
130
### Test Commands
131
```bash
132
# Run all tests
133
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
134
-destination "platform=iOS Simulator,name=iPhone 16" \
135
-configuration Debug
136
137
# Run specific test class
138
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
139
-destination "platform=iOS Simulator,name=iPhone 16" \
140
-only-testing:<TestTarget>/<TestClassName>
141
142
# Run specific test method
143
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
144
-destination "platform=iOS Simulator,name=iPhone 16" \
145
-only-testing:<TestTarget>/<TestClassName>/<testMethodName>
146
147
# Run with code coverage
148
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
149
-configuration Debug -enableCodeCoverage YES
150
151
# List available simulators
152
xcrun simctl list devices available
153
```
154
155
### Clean Build
156
```bash
157
xcodebuild clean -scheme <SchemeName>
158
159
```
160
161
---
162
163
## Quick Reference
164
165
### USE Xcode MCP For:
166
- ✅ `BuildProject` - Building
167
- ✅ `GetBuildLog` - Build errors
168
- ✅ `RunSomeTests` - Running specific tests
169
- ✅ `GetTestList` - Listing tests
170
- ✅ `RenderPreview` - SwiftUI previews
171
- ✅ `ExecuteSnippet` - Code execution
172
- ✅ `DocumentationSearch` - Apple docs
173
- ✅ `XcodeListWindows` - Get tabIdentifier
174
- ✅ `mcp__ide__getDiagnostics` - SourceKit errors
175
176
### NEVER USE Xcode MCP For:
177
- ❌ `XcodeRead` → Use `Read` tool
178
- ❌ `XcodeWrite` → Use `Write` tool
179
- ❌ `XcodeUpdate` → Use `Edit` tool
180
- ❌ `XcodeGrep` → Use `rg` or `Grep` tool
181
- ❌ `XcodeGlob` → Use `Glob` tool
182
- ❌ `XcodeLS` → Use `ls` command
183
- ❌ File operations → Use standard tools
184
185
---
186
187
## Token Efficiency Summary
188
189
| Operation | Best Choice | Token Impact |
190
|-----------|-------------|--------------|
191
| Quick syntax check | `mcp__ide__getDiagnostics` | 🟢 Low |
192
| Full build | `mcp__xcode__BuildProject` | 🟡 Medium |
193
| Run specific tests | `mcp__xcode__RunSomeTests` | 🟡 Medium |
194
| Run all tests | `mcp__xcode__RunAllTests` | 🟠 High |
195
| Read file | `Read` tool | 🟠 High |
196
| Edit file | `Edit` tool | 🟠 High|
197
| Search code | `rg` / `Grep` | 🟢 Low |
198
| List files | `ls` / `Glob` | 🟢 Low |