axiom-xcode-mcp-ref

Xcode MCP 工具参考

Xcode 的 MCP 服务（xcrun mcpbridge）公开的全部 20 个工具的完整参考。

来源：Xcode 26.3 的 tools/list 响应。已对照 Keith Smiley 的 gist（2025-07-15）进行验证。

重要：20 个工具中有 18 个需要 tabIdentifier。请始终先调用 XcodeListWindows。

发现

XcodeListWindows

返回已打开的 Xcode 窗口。请先调用此工具以获取 tabIdentifier 值。

• 参数：无
• 返回：{ message: string } — 已打开窗口的描述
• 备注：唯一不需要 tabIdentifier 的工具。

---

文件操作

XcodeRead

读取文件内容（cat -n 格式，默认 600 行）。

• 参数：
  • tabIdentifier（string，必需）
  • filePath（string，必需）— 相对于项目的路径或绝对路径
  • limit（integer，可选）— 返回的最大行数
  • offset（integer，可选）— 起始行号
• 返回：{ content, filePath, fileSize, linesRead, startLine, totalLines }

XcodeWrite

创建或覆盖文件。自动将新文件添加到项目结构中。

• 参数：
  • tabIdentifier（string，必需）
  • filePath（string，必需）
  • content（string，必需）
• 返回：{ success, filePath, absolutePath, bytesWritten, linesWritten, wasExistingFile, message }

XcodeUpdate

通过文本替换编辑现有文件。

• 参数：
  • tabIdentifier（string，必需）
  • filePath（string，必需）
  • oldString（string，必需）— 要查找的文本
  • newString（string，必需）— 替换文本
  • replaceAll（boolean，可选，默认 false）— 替换所有匹配项
• 返回：{ filePath, editsApplied, success, originalContentLength, modifiedContentLength, message }
• 备注：默认只替换一次。除非 replaceAll 为 true，否则每个 oldString 都必须唯一。编辑现有文件时，优先使用此工具，而不是 XcodeWrite。

XcodeGlob

查找与通配符模式匹配的文件。

• 参数：
  • tabIdentifier（string，必需）
  • pattern（string，可选，默认 **/*）— glob 模式
  • path（string，可选）— 要搜索的目录
• 返回：{ matches[], pattern, searchPath, truncated, totalFound, message }

XcodeGrep

使用正则表达式搜索文件内容。

• 参数：
  • tabIdentifier（string，必需）
  • pattern（string，必需）— 正则表达式模式
  • glob（string，可选）— 文件模式筛选条件
  • path（string，可选）— 目录范围
  • type（string，可选）— 文件类型筛选条件
  • ignoreCase（boolean，可选）
  • multiline（boolean，可选）
  • outputMode（enum，可选）— content、filesWithMatches、count
  • linesContext（integer，可选）— 上下文行数
  • linesBefore（integer，可选）
  • linesAfter（integer，可选）
  • headLimit（integer，可选）— 最大结果数
  • showLineNumbers（boolean，可选）
• 返回：{ results[], pattern, searchPath, matchCount, truncated, message }
• 备注：与 ripgrep 的接口相似。使用 outputMode 控制结果格式。

XcodeLS

列出目录内容。

• 参数：
  • tabIdentifier（string，必需）
  • path（string，必需）
  • recursive（boolean，可选，默认 true）
  • ignore（字符串数组，可选）— 要跳过的模式
• 返回：{ items[], path }

XcodeMakeDir

在项目中创建目录。

• 参数：
  • tabIdentifier（string，必需）
  • directoryPath（string，必需）
• 返回：{ success, message, createdPath }

XcodeRM

从项目中移除文件或目录。默认使用废纸篓。

• 参数：
  • tabIdentifier（string，必需）
  • path（string，必需）
  • deleteFiles（boolean，可选，默认 true）— 移至废纸篓
  • recursive（boolean，可选）
• 返回：{ removedPath, success, message }

XcodeMV

移动或复制文件。

• 参数：
  • tabIdentifier（字符串，必填）
  • sourcePath（字符串，必填）
  • destinationPath（字符串，必填）
  • operation（枚举，可选）— move 或 copy
  • overwriteExisting（布尔值，可选）
• 返回：{ success, operation, message, sourceOriginalPath, destinationFinalPath }
• 注意：不仅可以移动，也可以复制。可能会破坏导入；请与用户确认。

---

构建与测试

BuildProject

构建项目并等待完成。

• 参数：
  • tabIdentifier（字符串，必填）
• 返回：{ buildResult, elapsedTime, errors[] }
• 注意：每个错误都包含 classification、filePath、lineNumber 和 message。

GetBuildLog

获取构建日志，可选择性地进行筛选。

• 参数：
  • tabIdentifier（字符串，必填）
  • severity（枚举，可选）— remark、warning、error
  • pattern（字符串，可选）— 正则表达式筛选条件
  • glob（字符串，可选）— 文件模式筛选条件
• 返回：{ buildIsRunning, buildLogEntries[], buildResult, fullLogPath, truncated, totalFound }
• 注意：返回结构化条目，而非原始文本。每个条目都包含 buildTask 和 emittedIssues[]。

RunAllTests

根据活动方案的测试计划运行完整测试套件。

• 参数：
  • tabIdentifier（字符串，必填）
• 返回：{ summary, counts, results[], schemeName, activeTestPlanName }
• 注意：counts 包含 total、passed、failed、skipped、expectedFailures 和 notRun。每个结果都包含 targetName、identifier、displayName 和 state。

RunSomeTests

根据标识符运行指定测试。

• 参数：
  • tabIdentifier（字符串，必填）
  • tests（数组，必填）— 每个元素：{ targetName: string, testIdentifier: string }
• 返回：与 RunAllTests 的格式相同
• 注意：使用 GetTestList 查找有效的测试标识符。

GetTestList

列出活动测试计划中的可用测试。

• 参数：
  • tabIdentifier（字符串，必填）
• 返回：{ tests[], schemeName, activeTestPlanName }
• 注意：每个测试都包含 targetName、identifier、displayName、isEnabled、filePath、lineNumber 和 tags[]。

---

诊断

XcodeListNavigatorIssues

获取 Xcode 的问题导航器中的问题。

• 参数：
  • tabIdentifier（字符串，必填）
  • severity（枚举，可选）— remark、warning、error
  • pattern（字符串，可选）— 正则表达式筛选条件
  • glob（字符串，可选）— 文件模式筛选条件
• 返回：{ issues[], truncated, totalFound, message }
• 注意：每个问题都包含 message、severity、path、line、category 和 vitality（fresh/stale）。结果经过结构化处理和去重。

XcodeRefreshCodeIssuesInFile

刷新指定文件的诊断信息。

• 参数：
  • tabIdentifier（字符串，必填）
  • filePath（字符串，必填）
• 返回：{ filePath, diagnosticsCount, content, success }
• 注意：触发 Xcode 重新分析该文件。

---

执行与渲染

ExecuteSnippet

在源文件的上下文中构建并运行代码片段。

• 参数：
  • tabIdentifier（字符串，必填）
  • codeSnippet（字符串，必填）— 要执行的代码
  • sourceFilePath（字符串，必填）— 代码片段运行时所处上下文的 Swift 文件（可访问该文件中的 fileprivate 声明）
  • timeout（整数，可选，默认值为 120）— 秒
• 返回：{ executionResults } — print 语句的控制台输出
• 注意：这不是通用 REPL。代码在指定文件的上下文中运行。没有 language 参数 — 仅支持 Swift。

RenderPreview

渲染 SwiftUI 预览快照。

• 参数：
  • tabIdentifier（字符串，必填）
  • sourceFilePath（字符串，必填）— 包含 #Preview 的 Swift 文件
  • previewDefinitionIndexInFile（整数，可选，默认值为 0）— 要渲染的 #Preview 在文件中的从零开始的索引
  • timeout（整数，可选，默认值为 120）
• 返回值：{ previewSnapshotPath } — 渲染图像的路径
• 备注：基于索引而非名称。文件中的第一个 #Preview 的索引为 0。

---

搜索

DocumentationSearch

通过语义搜索 Apple Developer Documentation。

• 参数：
  • query（字符串，必填）
  • frameworks（字符串数组，可选）— 将搜索范围限定为特定框架
• 返回值：{ documents[] } — 每项包含 title、uri、contents、score
• 备注：本地语义搜索（由 MLX 加速），而非网页搜索。

---

快速参考

类别	工具
发现	XcodeListWindows
文件读取	XcodeRead、XcodeGlob、XcodeGrep、XcodeLS
文件写入	XcodeWrite、XcodeUpdate、XcodeMakeDir
文件删除	XcodeRM、XcodeMV
构建	BuildProject、GetBuildLog
测试	RunAllTests、RunSomeTests、GetTestList
诊断	XcodeListNavigatorIssues、XcodeRefreshCodeIssuesInFile
执行	ExecuteSnippet
预览	RenderPreview
搜索	DocumentationSearch

常见参数模式

• tabIdentifier — 20 个工具中有 18 个要求此参数。始终先调用 XcodeListWindows。
• filePath — 用于 XcodeRead、XcodeWrite、XcodeUpdate、XcodeRefreshCodeIssuesInFile。可使用项目相对路径或绝对路径。
• path — 用于 XcodeLS、XcodeRM、XcodeGlob。目录路径。
• directoryPath — 用于 XcodeMakeDir。
• sourceFilePath — 用于 ExecuteSnippet、RenderPreview。必须是 Swift 源文件。

资源

技能：axiom-xcode-mcp-setup、axiom-xcode-mcp-tools