Pi代理Xcode MCP工具

---
name: xcode-mcp-for-pi-agent
description: 关于通过 mcporter CLI 高效使用 Xcode MCP 工具的指南。此技能应用于理解何时使用 Xcode MCP 工具而非标准工具。Xcode MCP 消耗大量 token——仅用于构建、测试、模拟器、预览和 SourceKit 诊断。切勿用于文件读/写/grep 操作。在处理 Xcode 项目、iOS/macOS 构建、SwiftUI 预览或 Apple 平台开发时，请使用此技能。
---

# Xcode MCP 使用指南

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

## 设置

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

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

验证连接：
```bash
mcporter list xcode
```

---

## 调用工具

所有 Xcode MCP 工具都通过 mcporter 调用：

```bash
# 列出可用工具
mcporter list xcode

# 使用 key:value 参数调用工具
mcporter call xcode.<tool_name> param1:value1 param2:value2

# 使用函数调用语法调用
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` | 中 ✓ |
| 在问题导航器中列出问题 | `mcporter call xcode.XcodeListNavigatorIssues` | 低 ✓ |

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

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

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

### 文档
| 工具 | mcporter 调用 | Token 成本 |
|------|---------------|------------|
| 搜索 Apple 开发者文档 | `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 消耗 |

---

## 推荐工作流程

### 1. 代码更改与构建流程
```
1. 搜索代码      → rg "pattern" --type swift
2. 读取文件        → Read 工具 / cat
3. 编辑文件        → Edit 工具
4. 语法检查     → mcporter call xcode.getDiagnostics
5. 构建            → mcporter call xcode.BuildProject
6. 检查错误     → mcporter call xcode.GetBuildLog (如果构建失败)
```

### 2. 测试编写与运行流程
```
1. 读取测试文件   → Read 工具 / cat
2. 编写/编辑测试  → Edit 工具
3. 获取测试列表    → mcporter call xcode.GetTestList
4. 运行测试        → mcporter call xcode.RunSomeTests (特定测试)
5. 检查结果    → 查看测试输出
```

### 3. SwiftUI 预览流程
```
1. 编辑视图        → Edit 工具
2. 渲染预览   → mcporter call xcode.RenderPreview
3. 迭代          → 根据需要重复
```

### 4. 调试流程
```
1. 检查诊断 → mcporter call xcode.getDiagnostics
2. 构建项目     → mcporter call xcode.BuildProject
3. 获取构建日志     → mcporter call xcode.GetBuildLog severity:error
4. 修复问题        → Edit 工具
5. 重新构建           → mcporter call xcode.BuildProject
```

### 5. 文档搜索
```
1. 搜索文档       → mcporter call xcode.DocumentationSearch query:"SwiftUI NavigationStack"
2. 查看结果    → 在实现中使用信息
```

---

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

如果 Xcode MCP 断开连接、mcporter 未安装或连接失败，请直接使用这些 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>
```

---

## 快速参考

### 使用 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` | 🟢 低 |