1
---
2
name: xcode-mcp-for-pi-agent
3
description: Guidelines for efficient Xcode MCP tool usage via mcporter CLI. 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. Use this skill whenever working with Xcode projects, iOS/macOS builds, SwiftUI previews, or Apple platform development.
4
---
5
6
# Xcode MCP Usage Guidelines
7
8
Xcode MCP tools are accessed via `mcporter` CLI, which bridges MCP servers to standard command-line tools. This skill defines when to use Xcode MCP and when to prefer standard tools.
9
10
## Setup
11
12
Xcode MCP must be configured in `~/.mcporter/mcporter.json`:
13
14
```json
15
{
16
"mcpServers": {
17
"xcode": {
18
"command": "xcrun",
19
"args": ["mcpbridge"],
20
"env": {}
21
}
22
}
23
}
24
```
25
26
Verify the connection:
27
```bash
28
mcporter list xcode
29
```
30
31
---
32
33
## Calling Tools
34
35
All Xcode MCP tools are called via mcporter:
36
37
```bash
38
# List available tools
39
mcporter list xcode
40
41
# Call a tool with key:value args
42
mcporter call xcode.<tool_name> param1:value1 param2:value2
43
44
# Call with function-call syntax
45
mcporter call 'xcode.<tool_name>(param1: "value1", param2: "value2")'
46
```
47
48
---
49
50
## Complete Xcode MCP Tools Reference
51
52
### Window & Project Management
53
| Tool | mcporter call | Token Cost |
54
|------|---------------|------------|
55
| List open Xcode windows (get tabIdentifier) | `mcporter call xcode.XcodeListWindows` | Low ✓ |
56
57
### Build Operations
58
| Tool | mcporter call | Token Cost |
59
|------|---------------|------------|
60
| Build the Xcode project | `mcporter call xcode.BuildProject` | Medium ✓ |
61
| Get build log with errors/warnings | `mcporter call xcode.GetBuildLog` | Medium ✓ |
62
| List issues in Issue Navigator | `mcporter call xcode.XcodeListNavigatorIssues` | Low ✓ |
63
64
### Testing
65
| Tool | mcporter call | Token Cost |
66
|------|---------------|------------|
67
| Get available tests from test plan | `mcporter call xcode.GetTestList` | Low ✓ |
68
| Run all tests | `mcporter call xcode.RunAllTests` | Medium |
69
| Run specific tests (preferred) | `mcporter call xcode.RunSomeTests` | Medium ✓ |
70
71
### Preview & Execution
72
| Tool | mcporter call | Token Cost |
73
|------|---------------|------------|
74
| Render SwiftUI Preview snapshot | `mcporter call xcode.RenderPreview` | Medium ✓ |
75
| Execute code snippet in file context | `mcporter call xcode.ExecuteSnippet` | Medium ✓ |
76
77
### Diagnostics
78
| Tool | mcporter call | Token Cost |
79
|------|---------------|------------|
80
| Get compiler diagnostics for specific file | `mcporter call xcode.XcodeRefreshCodeIssuesInFile` | Low ✓ |
81
| Get SourceKit diagnostics (all open files) | `mcporter call xcode.getDiagnostics` | Low ✓ |
82
83
### Documentation
84
| Tool | mcporter call | Token Cost |
85
|------|---------------|------------|
86
| Search Apple Developer Documentation | `mcporter call xcode.DocumentationSearch` | Low ✓ |
87
88
### File Operations (HIGH TOKEN - NEVER USE)
89
| MCP Tool | Use Instead | Why |
90
|----------|-------------|-----|
91
| `xcode.XcodeRead` | `Read` tool / `cat` | High token consumption |
92
| `xcode.XcodeWrite` | `Write` tool | High token consumption |
93
| `xcode.XcodeUpdate` | `Edit` tool | High token consumption |
94
| `xcode.XcodeGrep` | `rg` / `grep` | High token consumption |
95
| `xcode.XcodeGlob` | `find` / `glob` | High token consumption |
96
| `xcode.XcodeLS` | `ls` command | High token consumption |
97
| `xcode.XcodeRM` | `rm` command | High token consumption |
98
| `xcode.XcodeMakeDir` | `mkdir` command | High token consumption |
99
| `xcode.XcodeMV` | `mv` command | High token consumption |
100
101
---
102
103
## Recommended Workflows
104
105
### 1. Code Change & Build Flow
106
```
107
1. Search code → rg "pattern" --type swift
108
2. Read file → Read tool / cat
109
3. Edit file → Edit tool
110
4. Syntax check → mcporter call xcode.getDiagnostics
111
5. Build → mcporter call xcode.BuildProject
112
6. Check errors → mcporter call xcode.GetBuildLog (if build fails)
113
```
114
115
### 2. Test Writing & Running Flow
116
```
117
1. Read test file → Read tool / cat
118
2. Write/edit test → Edit tool
119
3. Get test list → mcporter call xcode.GetTestList
120
4. Run tests → mcporter call xcode.RunSomeTests (specific tests)
121
5. Check results → Review test output
122
```
123
124
### 3. SwiftUI Preview Flow
125
```
126
1. Edit view → Edit tool
127
2. Render preview → mcporter call xcode.RenderPreview
128
3. Iterate → Repeat as needed
129
```
130
131
### 4. Debug Flow
132
```
133
1. Check diagnostics → mcporter call xcode.getDiagnostics
134
2. Build project → mcporter call xcode.BuildProject
135
3. Get build log → mcporter call xcode.GetBuildLog severity:error
136
4. Fix issues → Edit tool
137
5. Rebuild → mcporter call xcode.BuildProject
138
```
139
140
### 5. Documentation Search
141
```
142
1. Search docs → mcporter call xcode.DocumentationSearch query:"SwiftUI NavigationStack"
143
2. Review results → Use information in implementation
144
```
145
146
---
147
148
## Fallback Commands (When MCP or mcporter Unavailable)
149
150
If Xcode MCP is disconnected, mcporter is not installed, or the connection fails, use these xcodebuild commands directly:
151
152
### Build Commands
153
```bash
154
# Debug build (simulator) - replace <SchemeName> with your project's scheme
155
xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
156
157
# Release build (device)
158
xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build
159
160
# Build with workspace (for CocoaPods projects)
161
xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
162
163
# Build with project file
164
xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
165
166
# List available schemes
167
xcodebuild -list
168
```
169
170
### Test Commands
171
```bash
172
# Run all tests
173
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
174
-destination "platform=iOS Simulator,name=iPhone 16" \
175
-configuration Debug
176
177
# Run specific test class
178
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
179
-destination "platform=iOS Simulator,name=iPhone 16" \
180
-only-testing:<TestTarget>/<TestClassName>
181
182
# Run specific test method
183
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
184
-destination "platform=iOS Simulator,name=iPhone 16" \
185
-only-testing:<TestTarget>/<TestClassName>/<testMethodName>
186
187
# Run with code coverage
188
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
189
-configuration Debug -enableCodeCoverage YES
190
191
# List available simulators
192
xcrun simctl list devices available
193
```
194
195
### Clean Build
196
```bash
197
xcodebuild clean -scheme <SchemeName>
198
```
199
200
---
201
202
## Quick Reference
203
204
### USE mcporter + Xcode MCP For:
205
- ✅ `xcode.BuildProject` — Building
206
- ✅ `xcode.GetBuildLog` — Build errors
207
- ✅ `xcode.RunSomeTests` — Running specific tests
208
- ✅ `xcode.GetTestList` — Listing tests
209
- ✅ `xcode.RenderPreview` — SwiftUI previews
210
- ✅ `xcode.ExecuteSnippet` — Code execution
211
- ✅ `xcode.DocumentationSearch` — Apple docs
212
- ✅ `xcode.XcodeListWindows` — Get tabIdentifier
213
- ✅ `xcode.getDiagnostics` — SourceKit errors
214
215
### NEVER USE Xcode MCP For:
216
- ❌ `xcode.XcodeRead` → Use `Read` tool / `cat`
217
- ❌ `xcode.XcodeWrite` → Use `Write` tool
218
- ❌ `xcode.XcodeUpdate` → Use `Edit` tool
219
- ❌ `xcode.XcodeGrep` → Use `rg` or `grep`
220
- ❌ `xcode.XcodeGlob` → Use `find` / `glob`
221
- ❌ `xcode.XcodeLS` → Use `ls` command
222
- ❌ File operations → Use standard tools
223
224
---
225
226
## Token Efficiency Summary
227
228
| Operation | Best Choice | Token Impact |
229
|-----------|-------------|--------------|
230
| Quick syntax check | `mcporter call xcode.getDiagnostics` | 🟢 Low |
231
| Full build | `mcporter call xcode.BuildProject` | 🟡 Medium |
232
| Run specific tests | `mcporter call xcode.RunSomeTests` | 🟡 Medium |
233
| Run all tests | `mcporter call xcode.RunAllTests` | 🟠 High |
234
| Read file | `Read` tool / `cat` | 🟢 Low |
235
| Edit file | `Edit` tool | 🟢 Low |
236
| Search code | `rg` / `grep` | 🟢 Low |
237
| List files | `ls` / `find` | 🟢 Low |