TokenToSea提示词广场
English 控制台

Xcode MCP 使用指南

编程开发·系统提示 / 角色

在聊天中使用

智能体指南：通过 mcporter CLI 仅在构建、测试、模拟器、预览和诊断时调用 Xcode MCP，以节省 token。

---  
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 访问，该 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> 替换为项目的 scheme
xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

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

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

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

# 列出可用的 scheme
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` | 🟢 低 |

相关推荐

更多