Xcode MCP 使用指南（面向AI代理）

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 # 使用项目文件构建 xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # 列出可用 schemes 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` | 低 |