xcode-cloud-mcp

App Store Connect API を介して、Xcode Cloud のプロダクトを検出し、ワークフローを調査・編集し、ビルド実行を監視し、ビルドの問題、ログ、テスト概要、UI テストアーティファクトを取得するための最小限の MCP サーバー。

機能

ビルドの検索はワークフロースコープです。取得ツールは、直接の 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 を渡した場合でも、インラインの excerpt は上限に切り詰められ、過大な 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 時間より古いビルドディレクトリは自動的に削除されます

• 単一の buildRunId に対して、または選択した保持期間より古いすべてのディレクトリに対して、cleanup_saved_logs を直接呼び出すこともできます

プロンプト例

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

注記：

• environment には、App Store Connect が返す場合に、リポジトリ、xcodeVersion、macOsVersion が含まれます。

• actions には、アクションタイプ、スキーム、プラットフォーム、宛先、合格必須状態、および存在する場合はテストプランの詳細が含まれます。

• 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 がリクエストを拒否する場合は、Admin などより強力な API キーロールを使用してください

ローカル開発

依存関係をインストール：

npm install

テストを実行：

npm test

パッケージをビルド：

npm run build