项目定位与核心能力

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

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

资料来源：src/server/server.ts:1-40

系统级架构

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

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 设计讨论

概述与角色

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。

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)

概述与设计目标

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

错误时 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

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
3. **查阅落盘的 *.log 与 *-DocumentationSearch-*.json artifact**，它们保留了被裁剪掉的原始响应。资料来源：src/snapshot-tests/__fixtures__/cli/text/simulator/build--success.txt

See Also

• 工具清单与会话默认值：src/cli/commands/tools.ts 与 src/server/server.ts
• 模拟器管理与 UI 自动化输出示例：src/snapshot-tests/__fixtures__/cli/json/ui-automation/
• 项目发现工作流输出示例：src/snapshot-tests/__fixtures__/cli/json/project-discovery/

本页面聚焦 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)。

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，以缩小可被注入的输入面

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
• Build & Run on Simulator
• Tool Manifest Reference
• Security Best Practices

Pitfall Log / 踩坑日志

项目：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