Xcode MCP工具指南

---
name: xcode-mcp
description: Xcode MCP 工具高效使用指南。此技能应用于理解何时使用 Xcode MCP 工具而非标准工具。Xcode MCP 消耗大量 token - 仅用于构建、测试、模拟器、预览和 SourceKit 诊断。切勿用于文件读/写/grep 操作。
---

# Xcode MCP 使用指南

Xcode MCP 工具消耗大量 token。此技能定义了何时使用 Xcode MCP 以及何时优先使用标准工具。

## 完整的 Xcode MCP 工具参考

### 窗口与项目管理
| 工具 | 描述 | Token 成本 |
|------|-------------|------------|
| `mcp__xcode__XcodeListWindows` | 列出打开的 Xcode 窗口（获取 tabIdentifier） | 低 ✓ |

### 构建操作
| 工具 | 描述 | Token 成本 |
|------|-------------|------------|
| `mcp__xcode__BuildProject` | 构建 Xcode 项目 | 中 ✓ |
| `mcp__xcode__GetBuildLog` | 获取包含错误/警告的构建日志 | 中 ✓ |
| `mcp__xcode__XcodeListNavigatorIssues` | 列出问题导航器中的问题 | 低 ✓ |

### 测试
| 工具 | 描述 | Token 成本 |
|------|-------------|------------|
| `mcp__xcode__GetTestList` | 从测试计划中获取可用测试 | 低 ✓ |
| `mcp__xcode__RunAllTests` | 运行所有测试 | 中 |
| `mcp__xcode__RunSomeTests` | 运行特定测试（推荐） | 中 ✓ |

### 预览与执行
| 工具 | 描述 | Token 成本 |
|------|-------------|------------|
| `mcp__xcode__RenderPreview` | 渲染 SwiftUI 预览快照 | 中 ✓ |
| `mcp__xcode__ExecuteSnippet` | 在文件上下文中执行代码片段 | 中 ✓ |

### 诊断
| 工具 | 描述 | Token 成本 |
|------|-------------|------------|
| `mcp__xcode__XcodeRefreshCodeIssuesInFile` | 获取特定文件的编译器诊断 | 低 ✓ |
| `mcp__ide__getDiagnostics` | 获取 SourceKit 诊断（所有打开的文件） | 低 ✓ |

### 文档
| 工具 | 描述 | Token 成本 |
|------|-------------|------------|
| `mcp__xcode__DocumentationSearch` | 搜索 Apple 开发者文档 | 低 ✓ |

### 文件操作（高 Token - 切勿使用）
| 工具 | 替代方案 | 原因 |
|------|-------------|-----|
| `mcp__xcode__XcodeRead` | `Read` 工具 | 高 Token 消耗 |
| `mcp__xcode__XcodeWrite` | `Write` 工具 | 高 Token 消耗 |
| `mcp__xcode__XcodeUpdate` | `Edit` 工具 | 高 Token 消耗 |
| `mcp__xcode__XcodeGrep` | `rg` / `Grep` 工具 | 高 Token 消耗 |
| `mcp__xcode__XcodeGlob` | `Glob` 工具 | 高 Token 消耗 |
| `mcp__xcode__XcodeLS` | `ls` 命令 | 高 Token 消耗 |
| `mcp__xcode__XcodeRM` | `rm` 命令 | 高 Token 消耗 |
| `mcp__xcode__XcodeMakeDir` | `mkdir` 命令 | 高 Token 消耗 |
| `mcp__xcode__XcodeMV` | `mv` 命令 | 高 Token 消耗 |

---

## 推荐工作流程

### 1. 代码更改与构建流程
```
1. 搜索代码      → rg "pattern" --type swift
2. 读取文件        → Read tool
3. 编辑文件        → Edit tool
4. 语法检查     → mcp__ide__getDiagnostics
5. 构建            → mcp__xcode__BuildProject
6. 检查错误     → mcp__xcode__GetBuildLog (如果构建失败)
```

### 2. 测试编写与运行流程
```
1. 读取测试文件   → Read tool
2. 编写/编辑测试  → Edit tool
3. 获取测试列表    → mcp__xcode__GetTestList
4. 运行测试        → mcp__xcode__RunSomeTests (特定测试)
5. 检查结果        → 审查测试输出
```

### 3. SwiftUI 预览流程
```
1. 编辑视图        → Edit tool
2. 渲染预览   → mcp__xcode__RenderPreview
3. 迭代          → 根据需要重复
```

### 4. 调试流程
```
1. 检查诊断 → mcp__ide__getDiagnostics (快速语法检查)
2. 构建项目     → mcp__xcode__BuildProject
3. 获取构建日志     → mcp__xcode__GetBuildLog (严重性：错误)
4. 修复问题        → Edit tool
5. 重新构建           → mcp__xcode__BuildProject
```

### 5. 文档搜索
```
1. 搜索文档       → mcp__xcode__DocumentationSearch
2. 审查结果    → 在实现中使用信息
```

---

## 备用命令（当 MCP 不可用时）

如果 Xcode MCP 断开连接或不可用，请使用这些 xcodebuild 命令：

### 构建命令
```bash
# 调试构建（模拟器）- 将 <SchemeName> 替换为您的项目方案
xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# 发布构建（设备）
xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build

# 使用工作区构建（适用于 CocoaPods 项目）
xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# 使用项目文件构建
xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# 列出可用方案
xcodebuild -list
```

### 测试命令
```bash
# 运行所有测试
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -configuration Debug

# 运行特定测试类
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>

# 运行特定测试方法
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>/<testMethodName>

# 运行代码覆盖率测试
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -configuration Debug -enableCodeCoverage YES

# 列出可用模拟器
xcrun simctl list devices available
```

### 清理构建
```bash
xcodebuild clean -scheme <SchemeName>

```

---

## 快速参考

### 使用 Xcode MCP 的情况：
- ✅ `BuildProject` - 构建
- ✅ `GetBuildLog` - 构建错误
- ✅ `RunSomeTests` - 运行特定测试
- ✅ `GetTestList` - 列出测试
- ✅ `RenderPreview` - SwiftUI 预览
- ✅ `ExecuteSnippet` - 代码执行
- ✅ `DocumentationSearch` - Apple 文档
- ✅ `XcodeListWindows` - 获取 tabIdentifier
- ✅ `mcp__ide__getDiagnostics` - SourceKit 错误

### 绝不使用 Xcode MCP 的情况：
- ❌ `XcodeRead` → 使用 `Read` 工具
- ❌ `XcodeWrite` → 使用 `Write` 工具
- ❌ `XcodeUpdate` → 使用 `Edit` 工具
- ❌ `XcodeGrep` → 使用 `rg` 或 `Grep` 工具
- ❌ `XcodeGlob` → 使用 `Glob` 工具
- ❌ `XcodeLS` → 使用 `ls` 命令
- ❌ 文件操作 → 使用标准工具

---

## Token 效率总结

| 操作 | 最佳选择 | Token 影响 |
|-----------|-------------|--------------|
| 快速语法检查 | `mcp__ide__getDiagnostics` | 🟢 低 |
| 完整构建 | `mcp__xcode__BuildProject` | 🟡 中 |
| 运行特定测试 | `mcp__xcode__RunSomeTests` | 🟡 中 |
| 运行所有测试 | `mcp__xcode__RunAllTests` | 🟠 高 |
| 读取文件 | `Read` 工具 | 🟠 高 |
| 编辑文件 | `Edit` 工具 | 🟠 高|
| 搜索代码 | `rg` / `Grep` | 🟢 低 |
| 列出文件 | `ls` / `Glob` | 🟢 低 |