中文译文

Xcode MCP 使用指南

Xcode MCP 工具通过 mcporter CLI 访问，后者将 MCP 服务器桥接到标准命令行工具。本技能定义了何时使用 Xcode MCP，以及何时优先使用标准工具。

设置

Xcode MCP 必须在 ~/.mcporter/mcporter.json 中配置：

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

验证连接：

mcporter list xcode

调用工具

所有 Xcode MCP 工具都通过 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")'

完整的 Xcode MCP 工具参考

窗口与项目管理

工具	mcporter 调用	Token 成本
列出打开的 Xcode 窗口（获取 tabIdentifier）	`mcporter call xcode.XcodeListWindows`	低 ✓

构建操作

工具	mcporter 调用	Token 成本
构建 Xcode 项目	`mcporter call xcode.BuildProject`	中 ✓
获取包含错误/警告的构建日志	`mcporter call xcode.GetBuildLog`	中 ✓
列出 Issue Navigator 中的问题	`mcporter call xcode.XcodeListNavigatorIssues`	低 ✓

测试

工具	mcporter 调用	Token 成本
从测试计划获取可用测试	`mcporter call xcode.GetTestList`	低 ✓
运行所有测试	`mcporter call xcode.RunAllTests`	中
运行特定测试（首选）	`mcporter call xcode.RunSomeTests`	中 ✓

预览与执行

工具	mcporter 调用	Token 成本
渲染 SwiftUI Preview 快照	`mcporter call xcode.RenderPreview`	中 ✓
在文件上下文中执行代码片段	`mcporter call xcode.ExecuteSnippet`	中 ✓

诊断

工具	mcporter 调用	Token 成本
获取特定文件的编译器诊断信息	`mcporter call xcode.XcodeRefreshCodeIssuesInFile`	低 ✓
获取 SourceKit 诊断信息（所有打开的文件）	`mcporter call xcode.getDiagnostics`	低 ✓

文档

工具	mcporter 调用	Token 成本
搜索 Apple Developer 文档	`mcporter call xcode.DocumentationSearch`	低 ✓

文件操作（高 TOKEN - 绝不使用）

MCP 工具	改用	原因
`xcode.XcodeRead`	`Read` 工具 / `cat`	Token 消耗高
`xcode.XcodeWrite`	`Write` 工具	Token 消耗高
`xcode.XcodeUpdate`	`Edit` 工具	Token 消耗高
`xcode.XcodeGrep`	`rg` / `grep`	Token 消耗高
`xcode.XcodeGlob`	`find` / `glob`	Token 消耗高
`xcode.XcodeLS`	`ls` 命令	Token 消耗高
`xcode.XcodeRM`	`rm` 命令	Token 消耗高
`xcode.XcodeMakeDir`	`mkdir` 命令	Token 消耗高
`xcode.XcodeMV`	`mv` 命令	Token 消耗高

备用命令（当 MCP 或 mcporter 不可用时）

如果 Xcode MCP 断开连接、mcporter 未安装，或连接失败，请直接使用这些 xcodebuild 命令：

构建命令

# 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

测试命令

# 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

干净构建

xcodebuild clean -scheme <SchemeName>

快速参考

在以下情况使用 mcporter + Xcode MCP：

✅ xcode.BuildProject — 构建
✅ xcode.GetBuildLog — 构建错误
✅ xcode.RunSomeTests — 运行特定测试
✅ xcode.GetTestList — 列出测试
✅ xcode.RenderPreview — SwiftUI 预览
✅ xcode.ExecuteSnippet — 代码执行
✅ xcode.DocumentationSearch — Apple 文档
✅ xcode.XcodeListWindows — 获取 tabIdentifier
✅ xcode.getDiagnostics — SourceKit 错误

绝不将 Xcode MCP 用于：

❌ xcode.XcodeRead → 使用 Read 工具 / cat
❌ xcode.XcodeWrite → 使用 Write 工具
❌ xcode.XcodeUpdate → 使用 Edit 工具
❌ xcode.XcodeGrep → 使用 rg 或 grep
❌ xcode.XcodeGlob → 使用 find / glob
❌ xcode.XcodeLS → 使用 ls 命令
❌ 文件操作 → 使用标准工具

Token 效率总结

操作	最佳选择	Token 影响
快速语法检查	`mcporter call xcode.getDiagnostics`	🟢 低
完整构建	`mcporter call xcode.BuildProject`	🟡 中
运行特定测试	`mcporter call xcode.RunSomeTests`	🟡 中
运行所有测试	`mcporter call xcode.RunAllTests`	🟠 高
读取文件	`Read` 工具 / `cat`	🟢 低
编辑文件	`Edit` 工具	🟢 低
搜索代码	`rg` / `grep`	🟢 低
列出文件	`ls` / `find`	🟢 低

English original

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