name: xcode-mcp-for-pi-agent 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.

Xcode MCP Usage Guidelines

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.

Setup

Xcode MCP must be configured in ~/.mcporter/mcporter.json:

{
  "mcpServers": {
    "xcode": {
      "command": "xcrun",
      "args": ["mcpbridge"],
      "env": {}
    }
  }
}

Verify the connection:

mcporter list xcode

Calling Tools

All Xcode MCP tools are called via mcporter:

# List available tools
mcporter list xcode

# Call a tool with key:value args
mcporter call xcode.<tool_name> param1:value1 param2:value2

# Call with function-call syntax
mcporter call 'xcode.<tool_name>(param1: "value1", param2: "value2")'

Complete Xcode MCP Tools Reference

Window & Project Management

Tool	mcporter call	Token Cost
List open Xcode windows (get tabIdentifier)	`mcporter call xcode.XcodeListWindows`	Low ✓

Build Operations

Tool	mcporter call	Token Cost
Build the Xcode project	`mcporter call xcode.BuildProject`	Medium ✓
Get build log with errors/warnings	`mcporter call xcode.GetBuildLog`	Medium ✓
List issues in Issue Navigator	`mcporter call xcode.XcodeListNavigatorIssues`	Low ✓

Testing

Tool	mcporter call	Token Cost
Get available tests from test plan	`mcporter call xcode.GetTestList`	Low ✓
Run all tests	`mcporter call xcode.RunAllTests`	Medium
Run specific tests (preferred)	`mcporter call xcode.RunSomeTests`	Medium ✓

Preview & Execution

Tool	mcporter call	Token Cost
Render SwiftUI Preview snapshot	`mcporter call xcode.RenderPreview`	Medium ✓
Execute code snippet in file context	`mcporter call xcode.ExecuteSnippet`	Medium ✓

Diagnostics

Tool	mcporter call	Token Cost
Get compiler diagnostics for specific file	`mcporter call xcode.XcodeRefreshCodeIssuesInFile`	Low ✓
Get SourceKit diagnostics (all open files)	`mcporter call xcode.getDiagnostics`	Low ✓

Documentation

Tool	mcporter call	Token Cost
Search Apple Developer Documentation	`mcporter call xcode.DocumentationSearch`	Low ✓

File Operations (HIGH TOKEN - NEVER USE)

MCP Tool	Use Instead	Why
`xcode.XcodeRead`	`Read` tool / `cat`	High token consumption
`xcode.XcodeWrite`	`Write` tool	High token consumption
`xcode.XcodeUpdate`	`Edit` tool	High token consumption
`xcode.XcodeGrep`	`rg` / `grep`	High token consumption
`xcode.XcodeGlob`	`find` / `glob`	High token consumption
`xcode.XcodeLS`	`ls` command	High token consumption
`xcode.XcodeRM`	`rm` command	High token consumption
`xcode.XcodeMakeDir`	`mkdir` command	High token consumption
`xcode.XcodeMV`	`mv` command	High token consumption

Recommended Workflows

1. Code Change & Build Flow

1. Search code      → rg "pattern" --type swift
2. Read file        → Read tool / cat
3. Edit file        → Edit tool
4. Syntax check     → mcporter call xcode.getDiagnostics
5. Build            → mcporter call xcode.BuildProject
6. Check errors     → mcporter call xcode.GetBuildLog (if build fails)

2. Test Writing & Running Flow

1. Read test file   → Read tool / cat
2. Write/edit test  → Edit tool
3. Get test list    → mcporter call xcode.GetTestList
4. Run tests        → mcporter call xcode.RunSomeTests (specific tests)
5. Check results    → Review test output

3. SwiftUI Preview Flow

1. Edit view        → Edit tool
2. Render preview   → mcporter call xcode.RenderPreview
3. Iterate          → Repeat as needed

4. Debug Flow

1. Check diagnostics → mcporter call xcode.getDiagnostics
2. Build project     → mcporter call xcode.BuildProject
3. Get build log     → mcporter call xcode.GetBuildLog severity:error
4. Fix issues        → Edit tool
5. Rebuild           → mcporter call xcode.BuildProject

5. Documentation Search

1. Search docs       → mcporter call xcode.DocumentationSearch query:"SwiftUI NavigationStack"
2. Review results    → Use information in implementation

Fallback Commands (When MCP or mcporter Unavailable)

If Xcode MCP is disconnected, mcporter is not installed, or the connection fails, use these xcodebuild commands directly:

Build Commands

# Debug build (simulator) - replace <SchemeName> with your project's scheme
xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Release build (device)
xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build

# Build with workspace (for CocoaPods projects)
xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Build with project file
xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# List available schemes
xcodebuild -list

Test Commands

# Run all tests
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -configuration Debug

# Run specific test class
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>

# Run specific test method
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>/<testMethodName>

# Run with code coverage
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -configuration Debug -enableCodeCoverage YES

# List available simulators
xcrun simctl list devices available

Clean Build

xcodebuild clean -scheme <SchemeName>

Quick Reference

USE mcporter + Xcode MCP For:

✅ xcode.BuildProject — Building
✅ xcode.GetBuildLog — Build errors
✅ xcode.RunSomeTests — Running specific tests
✅ xcode.GetTestList — Listing tests
✅ xcode.RenderPreview — SwiftUI previews
✅ xcode.ExecuteSnippet — Code execution
✅ xcode.DocumentationSearch — Apple docs
✅ xcode.XcodeListWindows — Get tabIdentifier
✅ xcode.getDiagnostics — SourceKit errors

NEVER USE Xcode MCP For:

❌ xcode.XcodeRead → Use Read tool / cat
❌ xcode.XcodeWrite → Use Write tool
❌ xcode.XcodeUpdate → Use Edit tool
❌ xcode.XcodeGrep → Use rg or grep
❌ xcode.XcodeGlob → Use find / glob
❌ xcode.XcodeLS → Use ls command
❌ File operations → Use standard tools

Token Efficiency Summary

Operation	Best Choice	Token Impact
Quick syntax check	`mcporter call xcode.getDiagnostics`	🟢 Low
Full build	`mcporter call xcode.BuildProject`	🟡 Medium
Run specific tests	`mcporter call xcode.RunSomeTests`	🟡 Medium
Run all tests	`mcporter call xcode.RunAllTests`	🟠 High
Read file	`Read` tool / `cat`	🟢 Low
Edit file	`Edit` tool	🟢 Low
Search code	`rg` / `grep`	🟢 Low
List files	`ls` / `find`	🟢 Low

xcode-mcp (for pi agent)