161 lines
3.9 KiB
Markdown
161 lines
3.9 KiB
Markdown
|
|
# XcodeBuildMCP for iOS in VS Code
|
|
|
|
You are here: [AI Docs Home](../index.md) > XcodeBuildMCP for iOS in VS Code
|
|
|
|
## Contents
|
|
- Overview
|
|
- Requirements
|
|
- One-time Repo Setup
|
|
- XcodeBuildMCP Installation & Configuration
|
|
- Using XcodeBuildMCP in Copilot Chat
|
|
- Common Actions & Prompts
|
|
- Troubleshooting
|
|
- References
|
|
- Next Steps
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
XcodeBuildMCP lets you run Xcode build and test tasks from within VS Code, using agent workflows and Copilot Chat. This reduces context switching and makes iOS automation repeatable.
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- macOS with Xcode installed (includes iOS Simulator)
|
|
- VS Code with GitHub Copilot Chat enabled
|
|
- MCP tools configured in VS Code (repo includes .vscode/mcp.json)
|
|
- Node.js 18+ (required by the MCP host)
|
|
- This repo opened in VS Code (workspace root)
|
|
|
|
Optional but commonly needed for successful builds:
|
|
- Ruby + Bundler
|
|
- CocoaPods
|
|
- Flutter + FVM (if working on the Flutter module)
|
|
|
|
---
|
|
|
|
## One-time Repo Setup
|
|
|
|
Run the standard project setup so builds succeed:
|
|
|
|
1. `./scripts/setup.sh`
|
|
2. `bundle exec pod install`
|
|
3. If using Flutter: `cd ../oneappmodule-2.0/apps/oneapp && fvm flutter pub get`
|
|
|
|
---
|
|
|
|
## XcodeBuildMCP Installation & Configuration
|
|
|
|
### 1. Install XcodeBuildMCP
|
|
|
|
```bash
|
|
brew tap getsentry/xcodebuildmcp
|
|
brew install xcodebuildmcp
|
|
```
|
|
|
|
### 2. Configure XcodeBuildMCP
|
|
|
|
- The repo should include `.xcodebuildmcp/config.yaml`. Make sure it points to the correct workspace, scheme, and simulator.
|
|
|
|
Example (Toyota):
|
|
|
|
```yaml
|
|
schemaVersion: 1
|
|
sessionDefaults:
|
|
workspacePath: ./OneApp.xcworkspace
|
|
scheme: ToyotaOneApp
|
|
configuration: Debug
|
|
simulatorName: iPhone 17 Pro Max
|
|
simulatorId: <SIMULATOR_UDID>
|
|
useLatestOS: true
|
|
```
|
|
|
|
Notes:
|
|
- Use either `simulatorName` or `simulatorId`. If both are set, `simulatorId` takes precedence.
|
|
- The simulator must be installed and booted before running build/run.
|
|
|
|
### 3. Configure MCP in VS Code
|
|
|
|
- Ensure `.vscode/mcp.json` exists:
|
|
|
|
```json
|
|
{
|
|
"servers": {
|
|
"XcodeBuildMCP": {
|
|
"command": "xcodebuildmcp",
|
|
"args": ["mcp"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
- Restart VS Code or reload the window. Copilot should discover the tools.
|
|
|
|
---
|
|
|
|
## Using XcodeBuildMCP in Copilot Chat
|
|
|
|
From Copilot Chat, you can ask to build and run via XcodeBuildMCP. Example prompts:
|
|
|
|
- "build and run ToyotaOneApp on the iPhone 17 Pro Max simulator"
|
|
- "launch ToyotaOneApp without building (use the existing build)"
|
|
- "take a screenshot of the home screen"
|
|
|
|
Common tool actions the agent will use:
|
|
- list_devices, list_schemes
|
|
- session_set_defaults
|
|
- build_run_sim
|
|
- launch_app_sim (no build)
|
|
- screenshot
|
|
|
|
---
|
|
|
|
## Common Actions & Prompts
|
|
|
|
- **Build:**
|
|
"Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets."
|
|
|
|
- **Unit Tests:**
|
|
"Run unit tests with XcodeBuildMCP and list failing tests with file names."
|
|
|
|
- **UI Tests:**
|
|
"Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures."
|
|
|
|
- **Screenshots:**
|
|
"Run the UI test that captures screenshots and list the output paths."
|
|
|
|
- **Run without building:**
|
|
"launch ToyotaOneApp without building"
|
|
|
|
- **Home screen screenshot (example flow):**
|
|
1. "launch ToyotaOneApp without building"
|
|
2. Wait for the app to load the home screen
|
|
3. "take a screenshot of the home screen"
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
- **Build DB locked:** another build is running. Stop it and retry.
|
|
- **Wrong scheme or workspace:** confirm in `.xcodebuildmcp/config.yaml`.
|
|
- **Simulator not found:** install/boot the simulator in Xcode or Simulator.app.
|
|
- If MCP tools are not available in VS Code, confirm `.vscode/mcp.json` is present and enabled.
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- https://github.com/getsentry/XcodeBuildMCP
|
|
- https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-agentic-coding/
|
|
- https://code.visualstudio.com/docs/copilot/customization/mcp-servers
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- For iOS setup basics, read [iOS Setup](ios.md).
|
|
- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).
|