# https://github.com/getsentry/XcodeBuildMCP 项目说明书

生成时间：2026-06-18 11:03:37 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [工具、Manifest 与工作流](#page-2)
- [构建/测试输出过滤、超时与诊断](#page-3)
- [UI 自动化、调试器集成、安全与扩展性](#page-4)

<a id='page-1'></a>

## 项目概览与系统架构

### 相关页面

相关主题：[工具、Manifest 与工作流](#page-2), [构建/测试输出过滤、超时与诊断](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/getsentry/XcodeBuildMCP/blob/main/README.md)
- [package.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/package.json)
- [src/server/server.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/server/server.ts)
- [src/runtime/tool-catalog.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/runtime/tool-catalog.ts)
- [src/runtime/types.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/runtime/types.ts)
- [src/cli/commands/tools.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/cli/commands/tools.ts)
- [src/cli/jsonl-event.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/cli/jsonl-event.ts)
- [src/snapshot-tests/__fixtures__/cli/json/project-discovery/discover-projs--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/project-discovery/discover-projs--success.json)
- [src/snapshot-tests/__fixtures__/cli/json/swift-package/run--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/swift-package/run--success.json)
- [src/snapshot-tests/__fixtures__/cli/json/ui-automation/snapshot-ui--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/ui-automation/snapshot-ui--success.json)
</details>

# 项目概览与系统架构

## 项目定位与核心能力

XcodeBuildMCP 是一个面向 Apple 平台（iOS、macOS、watchOS、tvOS、visionOS）开发的 **Model Context Protocol (MCP) 服务器与配套 CLI 工具**，目标用户是需要自动化构建、测试、模拟器/真机调试流程的 AI 代理与开发者 [README.md](https://github.com/getsentry/XcodeBuildMCP/blob/main/README.md)。

项目在 README 中明确声明其设计理念：**优先使用 XcodeBuildMCP 工具而非 shell 命令来完成 Apple 平台任务**，并提供以下能力矩阵：

| 能力领域 | 说明 |
|---|---|
| Session Defaults | 配置工程、Scheme、模拟器、设备默认值，避免重复传参 |
| Project Discovery | 发现 Xcode 工程/工作区，列出 Scheme，检查 Build Settings |
| Simulator Workflows | 在 iOS 模拟器上构建、运行、测试、安装、启动；管理模拟器状态 |
| UI Automation | 通过 AXe/Accessibility 进行无障碍驱动的 UI 交互与快照 |
| Logging | 启动 OSLog 捕获并在工具输出中结构化展示 |
| Swift Package | 直接对 Swift Package 执行 build/run/test/clean |

资料来源：[src/server/server.ts:1-40]()

## 系统级架构

XcodeBuildMCP 采用 **三层运行时 + 单一工具清单（manifest）** 的架构。同一份工具定义被复用到三种不同的宿主进程中：

```mermaid
graph TB
    subgraph Sources["源码层 (YAML Manifest + TS 实现)"]
        Manifest[Workflow Manifest<br/>tools / workflows / predicates]
        Impl[TypeScript Tool Handlers]
    end

    subgraph Catalog["运行时目录层"]
        TC[buildToolCatalogFromManifest]
        CLI[buildCliToolCatalogFromManifest]
        DM[buildDaemonToolCatalogFromManifest]
    end

    subgraph Runtimes["三种运行时"]
        MCP[MCP Server<br/>stdio transport]
        CLIBin[xcodebuildmcp CLI<br/>yargs]
        Daemon[Daemon 长驻进程]
    end

    subgraph External["外部宿主"]
        Agent[AI Agent / IDE]
        Shell[开发者终端]
    end

    Manifest --> TC --> MCP --> Agent
    Manifest --> CLI --> CLIBin --> Shell
    Manifest --> DM --> Daemon --> Agent
    Impl --> TC
    Impl --> CLI
    Impl --> DM
```

所有工具通过 [src/runtime/tool-catalog.ts]() 中的 `buildToolCatalogFromManifest` 统一加载；CLI 与 Daemon 分别有独立入口 `buildCliToolCatalogFromManifest` 与 `buildDaemonToolCatalogFromManifest`，它们共享同一份 manifest，但通过 `PredicateContext`（包含 `runtime` 字段 `'cli' | 'daemon' | 'mcp'`）控制可见性 资料来源：[src/runtime/tool-catalog.ts:1-80]()、[src/runtime/types.ts:1-60]()。

## 工具目录与清单系统

工具目录（ToolCatalog）由 `createToolCatalog` 构建，内部维护四张索引表以实现 O(1) 解析：CLI 名、MCP 名、Tool ID、以及 kebab-case 复数桶。重要设计是 **按 `mcpName` 去重**——这保证跨多个 workflow 共享的工具不会出现歧义解析 资料来源：[src/runtime/tool-catalog.ts:60-100]()。

每个 `ToolDefinition` 包含双重 schema（`cliSchema` 与 `mcpSchema`）、`annotations`、`outputSchema`、声明式 `nextStepTemplates` 以及一个 `stateful` 标志，用于区分有状态工具（如模拟器启动/调试器挂起）与无状态工具 资料来源：[src/runtime/types.ts:15-60]()。

工作流（workflow）是工具的逻辑分组，例如 `simulator`、`device`、`logging`、`ui-automation`、`swift-package`、`project-discovery`、`xcode-ide`。CLI 端通过 `CLI_EXCLUDED_WORKFLOWS` 黑名单过滤掉仅适用于 MCP 宿主的工作流，并通过 `isWorkflowEnabledForRuntime` 应用用户配置 资料来源：[src/cli/commands/tools.ts:1-80]()。

## 输出模型与协议层

XcodeBuildMCP 的输出统一基于 **领域片段（domain fragment）** 抽象。`toCliJsonlEvent` 将任意片段通过 `kind` 与 `fragment` 两个判别器机械地拼装为 `event` 字段（形如 `build.result`），其余字段透传——这意味着新增片段不需要在协议层做映射 资料来源：[src/cli/jsonl-event.ts:1-20]()。

MCP 端则走 `McpServer` + `StdioServerTransport` 的标准 SDK 通道，并通过 `instrumentMcpRequestLifecycle` 注入 Sentry 观测点，实现对每个 MCP 请求生命周期的可观测性 资料来源：[src/server/server.ts:1-50]()。

每个成功响应都带 `nextSteps` 数组，向代理推荐后续动作。例如 `discover-projs` 成功后会建议 `xcodebuildmcp simulator build-and-run`；UI 快照后会建议 `wait-for-ui` 或 `batch` 多个 tap 操作 资料来源：[src/snapshot-tests/__fixtures__/cli/json/project-discovery/discover-projs--success.json]()、[src/snapshot-tests/__fixtures__/cli/json/ui-automation/snapshot-ui--success.json]()。

## 已知问题与社区关注点

仓库 issue 跟踪的痛点大多围绕 **构建输出噪声、配置可移植性、严格模式**：

- **#177 构建输出不完整**：`xcodebuildmcp` 测试时未返回完整输出，代理被迫手动调用 `xcodebuild`，提示 CLI 与 MCP 输出流存在截断。
- **#68/#447 警告过滤失效**：`suppressWarnings: true` 在 `sessionDefaults` 中不生效，遗留代码库的 warning 会撑爆上下文。
- **#413 Strict mode**：社区呼吁新增"严格模式"，禁止代理通过 ad-hoc 参数覆盖 Build Settings，仅使用 session defaults。
- **#291 Prompt Injection 安全风险**：依赖项中的恶意字符串可能通过编译输出注入到 AI 上下文，需要在渲染层做信任边界处理。
- **#446 Xcode 27 兼容性**：内嵌的 AXe 工具假定 `SimulatorKit.framework` 位于 `Contents/Developer/Library/PrivateFrameworks/`，但 Xcode 27 已将其移至 `Contents/SharedFrameworks/`，需要路径探测逻辑。
- **#174 自定义超时**：当前 `build-sim` 缺少可配置超时，调试 stalled build 时无法强制中断迭代。
- **#356 Claude Cowork 沙箱**：Cowork 沙箱不继承 `claude_desktop_settings.json`，需在配置可发现性上做适配。

## 安装与运行时

项目通过 `wireit` 管理构建流水线，源码改动后 `npm run build` 触发 `tsup` 编译至 `build/**` 目录 资料来源：[package.json]()。运行时要求 Node.js ≥ 18.x、Xcode 16、macOS 宿主；通过 `brew tap getsentry/xcodebuildmcp && brew install xcodebuildmcp` 可无需 Node.js 环境直接安装 资料来源：[README.md]()。

最新 v2.6.2 版本修复了 `xcodebuildmcp upgrade` 在多版本升级时仍读取陈旧包管理器元数据的问题，改为直接查询 GitHub Releases 作为权威升级目标。

## See Also

- [工具目录与 Manifest 加载机制]()
- [MCP Server 生命周期与可观测性]()
- [CLI 输出协议（JSONL 与 Text 模式）]()
- [UI Automation 与 AXe 集成]()
- [Session Defaults 与 Strict Mode 设计讨论]()

---

<a id='page-2'></a>

## 工具、Manifest 与工作流

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [构建/测试输出过滤、超时与诊断](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/runtime/tool-catalog.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/runtime/tool-catalog.ts)
- [src/runtime/types.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/runtime/types.ts)
- [src/runtime/naming.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/runtime/naming.ts)
- [src/cli/commands/tools.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/cli/commands/tools.ts)
- [src/cli/jsonl-event.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/cli/jsonl-event.ts)
- [src/server/server.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/server/server.ts)
- [README.md](https://github.com/getsentry/XcodeBuildMCP/blob/main/README.md)
- [src/snapshot-tests/__fixtures__/cli/json/simulator/build--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/simulator/build--success.json)
</details>

# 工具、Manifest 与工作流

## 概述与角色

XcodeBuildMCP 是一个面向 Apple 平台(iOS、macOS、watchOS、tvOS、visionOS)开发的 Model Context Protocol (MCP) 服务器与 CLI 工具集 资料来源：[README.md:1-9]()。它将 `xcodebuild`、`simctl`、调试器等命令封装为统一的"工具 (Tool)"集合,并以"工作流 (Workflow)"为粒度进行组织,通过 YAML Manifest 系统进行声明式定义,在 MCP、CLI 与 Daemon 三种运行时之间共享同一份核心定义。

工具、Manifest 与工作流机制承担以下职责:

- 以声明式 YAML 描述每个工具的 schema、注解、next-step 模板与输出结构 资料来源：[src/runtime/types.ts:31-78]()
- 在加载时按运行时(CLI / Daemon / MCP)与可见性谓词过滤工具集合 资料来源：[src/runtime/tool-catalog.ts:62-103]()
- 在 CLI 端通过 kebab-case 命令名暴露,在 MCP 端按原始 `mcpName` 注册 资料来源：[src/runtime/types.ts:36-42]()
- 提供 `nextSteps` 提示、JSON/JSONL 事件流与结构化输出,支持 agent 驱动的下一步推断 资料来源：[src/runtime/types.ts:13-30]()

## Manifest 与工作流定义

Manifest 是工具和工作流的声明式描述文件,运行时通过 `loadManifest()` 加载并解析为 `ResolvedManifest` 资料来源：[src/runtime/tool-catalog.ts:62-79]()。每个工作流代表一组相关工具的容器,例如 `simulator`、`device`、`logging`、`ui-automation`、`swift-package`、`xcode-ide` 等,这些工作流名与 CLI 输出片段中的 `workflow` 字段以及 JSONL 事件枚举保持一致 资料来源：[src/snapshot-tests/__fixtures__/cli/json/simulator/build--success.json:1-25]()。

CLI 端会排除两个仅供 MCP 会话使用的工作流:`session-management` 与 `workflow-discovery`,它们不属于面向终端用户的命令层 资料来源：[src/cli/commands/tools.ts:13-13](),[src/cli/commands/tools.ts:54-58]()。

工具由 `ToolManifestEntry` 描述,包含 CLI/MCP 双 schema、注解、next-step 模板和输出 schema 引用 资料来源：[src/runtime/types.ts:31-78]()。`NextStepTemplate` 携带 `toolId`、`params` 与 `when` 字段,允许在成功或失败后向 agent 推荐下一步操作(如 `Stop Swift package run`、`Batch same-screen taps`),从而减少大模型上下文中的指令开销 资料来源：[src/runtime/types.ts:13-30](),[src/snapshot-tests/__fixtures__/cli/json/ui-automation/snapshot-ui--success.json:30-40]()。

## Tool Catalog 构建与运行时分发

`buildToolCatalogFromManifest` 是核心工厂方法,它接受运行时类型与 `PredicateContext`,遍历所有工作流并按以下顺序过滤:

1. 调用 `importToolModule` 加载工具实现模块 资料来源：[src/runtime/tool-catalog.ts:30-39]()
2. 使用 `isWorkflowAvailableForRuntime` 与 `isToolAvailableForRuntime` 检查运行时可用性 资料来源：[src/runtime/tool-catalog.ts:21-28]()
3. 通过 `isToolExposedForRuntime` 决定是否对外暴露 资料来源：[src/runtime/tool-catalog.ts:27-28]()
4. 用 `seenMcpNames` 集合按 `mcpName` 大小写不敏感去重,防止跨工作流共享工具造成解析歧义 资料来源：[src/runtime/tool-catalog.ts:52-60]()

最终通过 `createToolCatalog` 构建四类查找表:`byCliName`、`byMcpName`、`byToolId`、`byMcpKebab`,供解析阶段按需快速查询 资料来源：[src/runtime/tool-catalog.ts:46-80]()。

```mermaid
flowchart LR
    Manifest[YAML Manifest] --> Load[loadManifest]
    Load --> Filter{Predicate<br/>Filtering}
    Filter -->|CLI| CliCatalog[CLI Tool Catalog]
    Filter -->|MCP| McpCatalog[MCP Tool Catalog]
    Filter -->|Daemon| DaemonCatalog[Daemon Tool Catalog]
    CliCatalog --> Yargs[Yargs CLI]
    McpCatalog --> McpServer[McpServer]
```

CLI 目录构建器 `buildCliToolCatalogFromManifest` 在构造谓词上下文时强制设定 `runningUnderXcode: false`,因为 CLI 不会运行在 Xcode 进程内,这一约束保证了谓词在跨进程调用时的一致性 资料来源：[src/cli/commands/tools.ts:48-52](),[src/runtime/tool-catalog.ts:96-103]()。

## 命名、参数转换与输出渲染

工具在 MCP 端使用原始 `mcpName`(如 `build_sim`),在 CLI 端通过 `getEffectiveCliName` 获取 kebab-case 命令名(如 `build-sim`),`toKebabCase` 负责在 camelCase、PascalCase、snake_case 之间归一化转换 资料来源：[src/runtime/naming.ts:6-19](),[src/runtime/tool-catalog.ts:65-79]()。`convertArgvToToolParams` 则将 yargs 传入的 kebab-case argv 反向转换为工具实现所需的 camelCase 参数 资料来源：[src/runtime/naming.ts:39-58]()。

对于结构化输出,CLI 在 `--output jsonl` 模式下使用 `toCliJsonlEvent` 将领域片段(`AnyFragment`)转换为线协议事件:事件名由 `kind` 与 `fragment` 字段拼接为 `event: "<kind>.<fragment>"`(全小写),其余字段原样透传 资料来源：[src/cli/jsonl-event.ts:5-19]()。该机制使得新增片段时无需手动维护映射表,贡献者只需保持 `kind` / `fragment` 判别字段为 lowercase-kebab 即可 资料来源：[src/cli/jsonl-event.ts:12-18]()。

MCP 服务器通过 `McpServer` 注册工具,并使用 Sentry 进行请求生命周期埋点;`instrumentMcpRequestLifecycle` 负责观测请求的进入与退出,以便诊断工具调用异常 资料来源：[src/server/server.ts:18-25](),[src/server/server.ts:28-50]()。

## See Also

- 可见性谓词与运行时策略(`isWorkflowAvailableForRuntime`、`isToolExposedForRuntime`)
- 配置存储与会话默认值(`sessionDefaults` 与 strict mode 行为,见 issue #413)
- 领域片段与结构化输出 schema(`AnyFragment` 与 `outputSchema`)
- 输出渲染与 next-step 模板(`toCliJsonlEvent` 与 `NextStepTemplate`)
- 构建警告过滤与 `suppressWarnings` 行为(见 issue #447、#68)

---

<a id='page-3'></a>

## 构建/测试输出过滤、超时与诊断

### 相关页面

相关主题：[工具、Manifest 与工作流](#page-2), [UI 自动化、调试器集成、安全与扩展性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cli/jsonl-event.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/cli/jsonl-event.ts)
- [src/runtime/types.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/runtime/types.ts)
- [src/server/server.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/server/server.ts)
- [README.md](https://github.com/getsentry/XcodeBuildMCP/blob/main/README.md)
- [package.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/package.json)
- [src/snapshot-tests/__fixtures__/cli/json/simulator-management/toggle-software-keyboard--error-invalid-simulator.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/simulator-management/toggle-software-keyboard--error-invalid-simulator.json)
- [src/snapshot-tests/__fixtures__/cli/json/swift-package/run--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/swift-package/run--success.json)
- [src/snapshot-tests/__fixtures__/cli/text/simulator/build--success.txt](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/text/simulator/build--success.txt)
- [src/snapshot-tests/__fixtures__/cli/json/project-discovery/discover-projs--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/project-discovery/discover-projs--success.json)
- [src/snapshot-tests/__fixtures__/cli/text/xcode-ide/documentation-search--success.txt](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/text/xcode-ide/documentation-search--success.txt)
</details>

# 构建/测试输出过滤、超时与诊断

## 概述与设计目标

XcodeBuildMCP 是一个面向 Apple 平台（iOS、macOS、watchOS、tvOS、visionOS）开发的 MCP 服务器与 CLI 工具，为 AI 代理提供构建、测试与模拟器管理能力。资料来源：[README.md]()

为避免代理上下文被 `xcodebuild` 产生的海量日志（编译命令行、链接步骤、资源复制等）淹没，系统对构建/测试输出采用 **结构化诊断 + 可控文本摘要** 的双轨策略。资料来源：[src/snapshot-tests/__fixtures__/cli/text/simulator/build--success.txt]()

核心设计目标包括：

- **可机读诊断**：将警告与错误从原始 stdout/stderr 中提取为 JSON 数组 `diagnostics.warnings` / `diagnostics.errors`。资料来源：[src/snapshot-tests/__fixtures__/cli/json/swift-package/run--success.json]()
- **可读文本摘要**：CLI 文本输出展示成功状态、耗时与产物路径，避免代理必须解析整段日志。资料来源：[src/snapshot-tests/__fixtures__/cli/text/simulator/build--success.txt]()
- **原始日志可追溯**：完整 `xcodebuild` 日志落盘到 `~/Library/Developer/XcodeBuildMCP/workspaces/.../logs/`，便于事后排查。资料来源：[src/snapshot-tests/__fixtures__/cli/text/simulator/build--success.txt]()

## 诊断数据结构与输出外壳

所有面向代理的工具响应均使用统一的 `xcodebuildmcp.output.*` JSON 外壳，`schemaVersion: "2"` 表示第二代契约。资料来源：[src/snapshot-tests/__fixtures__/cli/json/project-discovery/discover-projs--success.json]()

| 字段 | 含义 |
| --- | --- |
| `schema` | 输出模式标识，例如 `xcodebuildmcp.output.simulator-action-result` |
| `didError` | 顶层错误标志，非空错误时为 `true` |
| `error` | 错误时的顶层错误消息字符串 |
| `data` | 业务数据；包含 `summary`、`diagnostics`、`artifacts` 等子对象 |
| `nextSteps` | 由 manifest 生成的提示性下一步命令数组 |

错误时 `data.diagnostics.errors` 数组会逐条列出失败原因，例如模拟器未找到的提示文本。资料来源：[src/snapshot-tests/__fixtures__/cli/json/simulator-management/toggle-software-keyboard--error-invalid-simulator.json]()

成功路径下 `diagnostics.warnings` 与 `diagnostics.errors` 通常为空数组，但保留字段以保证响应形状稳定。资料来源：[src/snapshot-tests/__fixtures__/cli/json/swift-package/run--success.json]()

CLI 同时提供 `--output jsonl` 模式，将内部 fragment 转换为 `{ event: "<kind>.<fragment>", ... }` 的流式事件，便于增量消费与解析。资料来源：[src/cli/jsonl-event.ts]()

```mermaid
flowchart LR
    A[xcodebuild 进程] --> B[stdout/stderr 流]
    B --> C[输出解析器]
    C --> D{didError?}
    D -- 是 --> E[填充 error + diagnostics.errors]
    D -- 否 --> F[填充 diagnostics.warnings]
    E --> G[JSON 外壳 + 文本摘要]
    F --> G
    G --> H[落盘 *.log 原始文件]
    G --> I[MCP/CLI 响应]
```

## 过滤、超时与外部调用辅助

MCP 工具注册时附带 `outputSchema`（结构化输出契约）与 `annotations`（注解），允许宿主对工具响应做进一步裁剪。资料来源：[src/runtime/types.ts]()

服务器层在创建时声明能力清单与说明文字，明确要求代理 **优先使用 XcodeBuildMCP 工具而非 shell 命令**，并提示会话默认值（session defaults）机制可减少重复参数。资料来源：[src/server/server.ts]()

对于 Xcode IDE 远程调用类工具（如 `DocumentationSearch`），响应不会内联到文本中，而是写入 `~/Library/Developer/XcodeBuildMCP/workspaces/.../state/xcode-ide/call-tool/...` 下的 JSON artifact，并在输出中给出路径。资料来源：[src/snapshot-tests/__fixtures__/cli/text/xcode-ide/documentation-search--success.txt]()

构建与运行类工具的文本输出末尾会附带 `Next steps:` 段落，提示可继续调用的 CLI 命令（如 `simulator get-app-path`），形成 **有限状态机式的工作流** 而非让代理自由猜测下一步。资料来源：[src/snapshot-tests/__fixtures__/cli/text/simulator/build--success.txt]()

## 已知限制与社区反馈

尽管结构化诊断已落地，社区仍反馈以下与本主题相关的痛点：

- **`suppressWarnings` 在 `sessionDefaults` 中不生效**（#447）：遗留工程警告较多时无法被有效过滤，仍会进入代理上下文。资料来源：[issue #447]()
- **`build_sim` 自定义超时缺失**（#174）：`xcodebuild` 卡死时无法由代理主动放弃，必须人工介入。资料来源：[issue #174]()
- **完整测试输出被截断**（#177）：调用 `xcodebuildmcp - Test Simulator (MCP)` 时仅返回部分 stderr，代理不得不回退到手动 `xcodebuild`。资料来源：[issue #177]()
- **构建输出中的提示注入风险**（#291）：恶意依赖可在构建日志中嵌入诱骗字符串并被 LLM 消费，使过滤机制同时承担安全意义。资料来源：[issue #291]()
- **OSLog 子系统过滤器被回退为硬编码**（#409）：`build_run_sim` / `launch_app_sim` 固定使用 `subsystem == "<bundleId>"`，无法再按调用方需求扩缩。资料来源：[issue #409]()

## 故障排查建议

针对上述限制，使用者可参考以下实践：

1. **优先使用 `xcodebuildmcp` 子命令而非原始 `xcodebuild`**，因前者会产出可机读的 `diagnostics` 数组。资料来源：[src/snapshot-tests/__fixtures__/cli/json/simulator-management/toggle-software-keyboard--error-invalid-simulator.json]()
2. **遇到卡死构建时手动分批重试**，并在 `sessionDefaults` 中固定 scheme/simulator 以减少参数漂移。资料来源：[src/server/server.ts]()
4. **查阅落盘的 `*.log` 与 `*-DocumentationSearch-*.json` artifact**，它们保留了被裁剪掉的原始响应。资料来源：[src/snapshot-tests/__fixtures__/cli/text/simulator/build--success.txt]()

## See Also

- 工具清单与会话默认值：[src/cli/commands/tools.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/cli/commands/tools.ts) 与 [src/server/server.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/server/server.ts)
- 模拟器管理与 UI 自动化输出示例：[src/snapshot-tests/__fixtures__/cli/json/ui-automation/](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/ui-automation/)
- 项目发现工作流输出示例：[src/snapshot-tests/__fixtures__/cli/json/project-discovery/](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/project-discovery/)

---

<a id='page-4'></a>

## UI 自动化、调试器集成、安全与扩展性

### 相关页面

相关主题：[工具、Manifest 与工作流](#page-2), [构建/测试输出过滤、超时与诊断](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/getsentry/XcodeBuildMCP/blob/main/README.md)
- [src/server/server.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/server/server.ts)
- [src/runtime/tool-catalog.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/runtime/tool-catalog.ts)
- [src/runtime/types.ts](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/runtime/types.ts)
- [src/snapshot-tests/__fixtures__/cli/json/ui-automation/snapshot-ui--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/ui-automation/snapshot-ui--success.json)
- [src/snapshot-tests/__fixtures__/cli/json/ui-automation/tap--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/ui-automation/tap--success.json)
- [src/snapshot-tests/__fixtures__/cli/json/ui-automation/wait-for-ui--success.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/src/snapshot-tests/__fixtures__/cli/json/ui-automation/wait-for-ui--success.json)
- [package.json](https://github.com/getsentry/XcodeBuildMCP/blob/main/package.json)
</details>

# UI 自动化、调试器集成、安全与扩展性

本页面聚焦 XcodeBuildMCP 在 UI 自动化、调试器集成、安全防护与系统扩展性四个维度的设计与实现要点。XcodeBuildMCP 是一款面向 iOS / macOS 项目的 Model Context Protocol (MCP) 服务器与 CLI 工具，其核心定位是让 AI Agent 通过结构化工具安全地操作 Xcode 与 iOS Simulator 生态 ([README.md:1-15]())。

## UI 自动化

XcodeBuildMCP 的 UI 自动化能力围绕 iOS Simulator 上的可访问性 (Accessibility, AX) 树展开。Agent 可以通过 `snapshot-ui` 工具抓取当前界面元素层级，并使用 `tap`、`long-press`、`key-press`、`key-sequence`、`touch` 等工具对元素引用 (`elementRef`) 发起交互。

### 元素引用与无障碍协议

无障碍快照以 JSON 结构返回，其中每个交互元素都被赋予稳定的 `elementRef`（如 `<REF>` 占位符），并标注类型（`tap` / `scroll` / `text`）与位置信息，便于后续跨工具复用 ([snapshot-ui--success.json]())。例如，`tap` 工具的返回结果会回显 `nextSteps`，提示 Agent 在同一界面内可继续执行的操作 ([tap--success.json]())。

```text
nextSteps:
  - Batch same-screen taps: xcodebuildmcp ui-automation batch --json '{...}'
  - Tap an elementRef: xcodebuildmcp ui-automation tap --simulator-id <UUID> --element-ref <REF>
```

### 等待与 AX 就绪性

`wait-for-ui` 工具支持 `exists` / `value` / `settled` 等谓词，并返回 `waitMatch.matches` 数组以确认匹配结果 ([wait-for-ui--success.json]())。当 `snapshot-ui` 在启动早期返回空层级时，社区提出应在工具内部加入 AX 就绪性轮询与重试逻辑，以避免 Agent 误判 UI 状态（参考 issue #408）。该建议尚未合入主分支，属于已知改进点。

### 已知平台兼容性问题

XcodeBuildMCP 通过捆绑的 AXe 二进制桥接 SimulatorKit 框架。Xcode 27 将 `SimulatorKit.framework` 从 `Contents/Developer/Library/PrivateFrameworks/` 迁移至 `Contents/SharedFrameworks/`，导致捆绑 AXe 加载失败（issue #446）。在升级至 Xcode 27 测试版前，应关注该问题的修复状态。

## 调试器集成

### LLDB 断点与 UI 快照缓存

UI 自动化工具与 LLDB 调试器共享 Simulator 运行时状态。社区报告了 `ui-automation tap` 命中 LLDB 断点后，应用被暂停并继续执行时，运行期 UI 快照缓存会丢失，导致对相同 `elementRef` 的下一次点击立即失败（issue #445）。这表明 UI 自动化缓存的生命周期与调试器状态机尚未完全解耦，是调试工作流下需要规避的故障模式。

### 输出完整性与过滤

社区反馈指出 `xcodebuildmcp` 在执行 `xcodebuild` 时常常截断或遗漏关键输出，导致 Agent 上下文不完整（issue #177）。同时，`suppressWarnings` 在 `sessionDefaults` 中设置后未生效的 bug（issue #447）说明警告过滤通道尚不稳定。`nextSteps` 字段作为结构化引导返回，可以在一定程度上缓解 Agent 上下文溢出 ([snapshot-ui--success.json]())。

## 安全

XcodeBuildMCP 将 Xcode 构建、测试与 Simulator 控制的全部输出直接暴露给 AI 助手消费。社区在 issue #291 中指出，恶意依赖项中的构建警告/错误信息可能包含攻击者控制的字符串，从而形成 Prompt Injection 攻击面。缓解策略建议包括：

- 对编译产物（`xcodebuild` 输出、`OSLog` 日志、依赖内容）进行脱敏与隔离
- 限制 `extraArgs` 这类"逃生舱口"参数，避免 Agent 临时改变关键构建设置
- 引入"严格模式"（issue #413），在严格模式下禁用 `extraArgs` 并强制使用 `sessionDefaults`，以缩小可被注入的输入面

```mermaid
flowchart LR
  A[AI Agent] -->|MCP Tool Call| B[XcodeBuildMCP Server]
  B -->|xcodebuild| C[Build System]
  C -->|Build Output / Logs| B
  B -->|Sanitized Result| A
  A -.Prompt Injection.-> C
```

如上流程图所示，XcodeBuildMCP 处于 Agent 与底层工具链之间，负有对外部内容做安全净化的责任。

## 扩展性

### 工具清单 (Tool Catalog) 与清单系统

`src/runtime/tool-catalog.ts` 中的 `buildToolCatalogFromManifest` 在 MCP、CLI、Daemon 三种运行时下复用同一份工具清单，每个工具由 `mcpSchema`（MCP 注册用）与 `cliSchema`（yargs 标志生成用）双形态定义 ([tool-catalog.ts]())。`buildCliToolCatalogFromManifest` 与 `listCliWorkflowIdsFromManifest` 通过 `buildCliPredicateContext` 决定 CLI 下哪些工作流可见，便于在受限环境下裁剪工具集。

### 工作流与下一步模板

`ToolDefinition` 携带 `nextStepTemplates`，允许清单文件声明结构化的下一步操作建议，从而让 Agent 在不依赖自由对话推断的情况下完成工具编排 ([types.ts]())。`workflow` 字段（如 `simulator`、`device`、`logging`）用于按主题聚合工具，与 MCP `instructions` 中描述的能力域一一对应 ([server.ts]())。

### 严格模式与会话默认值

社区提议的"严格模式"（issue #413）属于扩展性策略的一种：它通过关闭 `extraArgs` 通道并锁定 `sessionDefaults`，让多 Agent 协作时只能使用已审批的构建配置。这是从"工具暴露面"向"配置暴露面"收敛的扩展性原则。

## See Also

- [XcodeBuildMCP README](https://github.com/getsentry/XcodeBuildMCP/blob/main/README.md)
- [Build & Run on Simulator](https://github.com/getsentry/XcodeBuildMCP/wiki/Build-and-Run-on-Simulator)
- [Tool Manifest Reference](https://github.com/getsentry/XcodeBuildMCP/wiki/Tool-Manifest-Reference)
- [Security Best Practices](https://github.com/getsentry/XcodeBuildMCP/wiki/Security-Best-Practices)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：getsentry/XcodeBuildMCP

摘要：发现 23 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Clone simulators。

## 1. 安装坑 · 来源证据：Clone simulators

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Clone simulators
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/414 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Strict mode

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Strict mode
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/413 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：Poll AX readiness when snapshot_ui returns an empty hierarchy

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Poll AX readiness when snapshot_ui returns an empty hierarchy
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/408 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：Refactor: Extract VERSION_REGEX and validateVersion into a shared module

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Refactor: Extract VERSION_REGEX and validateVersion into a shared module
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/368 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安装坑 · 来源证据：Resolve JSON.stringify vs prettier conflict in generated src/version.ts

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Resolve JSON.stringify vs prettier conflict in generated src/version.ts
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/369 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 安装坑 · 来源证据：Warden weekly sweep

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Warden weekly sweep
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/436 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：[Bug]: Never gives Claude the full output

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Never gives Claude the full output
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/177 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 8. 安装坑 · 来源证据：[Bug]: suppressWarnings doesn't work

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: suppressWarnings doesn't work
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/447 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 9. 安装坑 · 来源证据：[Bug]: ui-automation element refs become unavailable after debugger-paused tap

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: ui-automation element refs become unavailable after debugger-paused tap
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/445 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 安装坑 · 来源证据：[Feature]: Compatibility with Claude Cowork

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Compatibility with Claude Cowork
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/356 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 11. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/getsentry/XcodeBuildMCP | host_targets=mcp_host, claude_code, claude, cursor

## 12. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/getsentry/XcodeBuildMCP | README/documentation is current enough for a first validation pass.

## 13. 运行坑 · 来源证据：Move simulatorPlatform out of sessionDefaults into an internal cache

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Move simulatorPlatform out of sessionDefaults into an internal cache
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/366 | 来源类型 github_issue 暴露的待验证使用条件。

## 14. 运行坑 · 来源证据：[Feature]: macOS debug support

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Feature]: macOS debug support
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/364 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 15. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/getsentry/XcodeBuildMCP | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/getsentry/XcodeBuildMCP | no_demo; severity=medium

## 17. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/getsentry/XcodeBuildMCP | no_demo; severity=medium

## 18. 安全/权限坑 · 来源证据：Restore configurable simulator OSLog subsystem filters

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Restore configurable simulator OSLog subsystem filters
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/409 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 安全/权限坑 · 来源证据：Security Advisory: Prompt Injection Risk via Build Output and Dependency Content

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Advisory: Prompt Injection Risk via Build Output and Dependency Content
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/291 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 20. 安全/权限坑 · 来源证据：[Bug]: Bundled AXe fails with Xcode 27 because SimulatorKit.framework moved to Contents/SharedFrameworks

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Bundled AXe fails with Xcode 27 because SimulatorKit.framework moved to Contents/SharedFrameworks
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/446 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 21. 安全/权限坑 · 来源证据：[Feature]: build-sim custom timeout

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: build-sim custom timeout
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/getsentry/XcodeBuildMCP/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。

## 22. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/getsentry/XcodeBuildMCP | issue_or_pr_quality=unknown

## 23. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/getsentry/XcodeBuildMCP | release_recency=unknown

<!-- canonical_name: getsentry/XcodeBuildMCP; human_manual_source: deepwiki_human_wiki -->