xcode-cloud-mcp

极简 MCP 服务器，用于发现 Xcode Cloud 产品、检查和编辑工作流、监控构建运行，并通过 App Store Connect API 检索构建问题、日志、测试摘要和 UI 测试产物。

功能特性

构建查找以工作流为作用域。检索工具接受直接的 buildRunId，或 workflowId 加 buildNumber，或 workflowId 加 buildSelector: "latest" | "latestFailing"。

list_products 和 list_workflows 会自动对所有结果进行分页。

list_build_runs 支持 status: "all" | "failed" | "succeeded" | "running" | "pending" 以及可选的 limit（默认为 20），因此代理可以轮询活动工作流，而无需在本地对每次运行进行后处理或增大 MCP 响应大小。

Related MCP server: appstore-release-mcp

要求

• Node.js 20+

• 具有 Xcode Cloud 访问权限的 App Store Connect API 凭据

环境变量

主要名称：

• APPSTORE_CONNECT_API_KEY_ID

• APPSTORE_CONNECT_API_ISSUER_ID

• APPSTORE_CONNECT_API_KEY_CONTENT

兼容别名：

• APP_STORE_KEY_ID

• APP_STORE_ISSUER_ID

• APP_STORE_PRIVATE_KEY

私钥可以作为字面量多行 PEM 内容传递，也可以作为带有转义 \n 的字符串传递。

Claude 设置

claude mcp add xcode-cloud \
  --env APPSTORE_CONNECT_API_KEY_ID="$APPSTORE_CONNECT_API_KEY_ID" \
  --env APPSTORE_CONNECT_API_ISSUER_ID="$APPSTORE_CONNECT_API_ISSUER_ID" \
  --env APPSTORE_CONNECT_API_KEY_CONTENT="$APPSTORE_CONNECT_API_KEY_CONTENT" \
  -- npx -y @thatfactory/xcode-cloud-mcp

Codex 设置

codex mcp add xcode-cloud \
  --env APPSTORE_CONNECT_API_KEY_ID="$APPSTORE_CONNECT_API_KEY_ID" \
  --env APPSTORE_CONNECT_API_ISSUER_ID="$APPSTORE_CONNECT_API_ISSUER_ID" \
  --env APPSTORE_CONNECT_API_KEY_CONTENT="$APPSTORE_CONNECT_API_KEY_CONTENT" \
  -- npx -y @thatfactory/xcode-cloud-mcp

可用工具

• list_products()

• list_workflows(productId)

• get_workflow_details(workflowId)

• list_build_runs(workflowId, limit?, status?)

• set_workflow_enabled(workflowId, enabled)

• update_workflow_general(workflowId, name?, description?, clean?)

• update_workflow_start_conditions(workflowId, branchStartCondition?, manualBranchStartCondition?, pullRequestStartCondition?, manualPullRequestStartCondition?, scheduledStartCondition?, tagStartCondition?, manualTagStartCondition?)

• update_workflow_actions(workflowId, actions)

• get_build_issues(buildRunId? workflowId? buildNumber? buildSelector?)

• get_build_logs(buildRunId? workflowId? buildNumber? buildSelector?, maxCharacters?)

• materialize_build_logs(buildRunId? workflowId? buildNumber? buildSelector?)

• get_test_results(buildRunId? workflowId? buildNumber? buildSelector?)

• get_failed_tests(buildRunId? workflowId? buildNumber? buildSelector?)

• get_test_artifacts(buildRunId? workflowId? buildNumber? buildSelector?)

• cleanup_saved_logs(buildRunId?, maxAgeHours?)

日志检索行为

get_build_logs 有意保持 MCP 响应的紧凑性：

• 它将文本类构建日志产物下载并解压到本地临时目录

• 它返回 savedLogsDirectory 和 savedLogs，以便本地代理可以使用 rg、grep 或 cat 检查提取的文件

• 它返回紧凑的 failedTests 摘要、highlights 和受限的 excerpt

• 即使调用方传入非常大的 maxCharacters，内联摘录也会被限制，以避免过大的 MCP 响应

推荐的代理工作流：

1. 调用 get_failed_tests 或 get_build_logs。

2. 读取 savedLogsDirectory。

3. 在该目录中使用 rg 检查确切的失败测试或断言。

4. 如有需要，在调查完成后调用 cleanup_saved_logs。

临时日志写入系统临时目录下的路径，格式如下：

/tmp/xcode-cloud-mcp/build-logs/<buildRunId>

在 macOS 上，这通常解析为 /var/folders/.../T/ 下的路径。

清理策略：

• 每次对同一 buildRunId 的新调用都会先删除并重新创建该构建专属的临时目录

• 超过 24 小时的旧构建目录会自动清理

• 你也可以直接调用 cleanup_saved_logs 来清理单个 buildRunId，或清理所有超过所选保留期限的目录

示例提示词

Retrieve logs of the latest failing build for workflow abc123.

Retrieve logs of build 81, then inspect the returned savedLogsDirectory and grep for Expectation failed.

Get the failed tests for build 81, then open the saved logs directory and inspect the failing test in context.

Retrieve logs of build number 42 for workflow abc123.

Show me the latest failing UI test artifacts for workflow abc123.

List the workflows for product def456 and then summarize the latest build.

Show me the full workflow details for workflow abc123, including environment, start conditions, actions, and whether it is enabled.

Disable workflow abc123, remove the archive action, then restore the original action list after the experiment.

工作流详情行为

get_workflow_details 返回 App Store Connect 公开的实时工作流配置，分组为：

• general

• environment

• startConditions

• actions

• postActions

说明：

• 当 App Store Connect 返回时，environment 包含仓库、xcodeVersion 和 macOsVersion。

• actions 包含操作类型、scheme、平台、目标、必须通过状态以及测试计划详情（如果存在）。

• postActions 目前返回为空数组并附有说明，因为在观察到的 API 响应中，App Store Connect 工作流负载不公开单独的后置操作。

工作流更新行为

工作流更新工具刻意保持显式：

• set_workflow_enabled 仅切换 isEnabled

• update_workflow_general 仅更改 name、description 和 clean

• update_workflow_start_conditions 仅更改你传入的启动条件对象

• update_workflow_actions 替换完整的 actions 数组，因此调用方应首先获取当前工作流，然后发送最终所需的操作列表

重要限制：

• 如果工作流在 Xcode Cloud 中启用了 Restrict Editing（限制编辑），即使 App Store Connect API 密钥具有 App Manager 访问权限，编辑也可能失败

• 为使 MCP 编辑可靠工作，请在使用写入工具之前禁用该工作流的 Restrict Editing 复选框

• 如果 Apple 在此之后仍拒绝请求，请使用更强的 API 密钥角色，例如 Admin

本地开发

安装依赖：

npm install

运行测试：

npm test

构建包：

npm run build