xcode-cloud-mcp

Minimaler MCP-Server zum Entdecken von Xcode-Cloud-Produkten, zum Inspizieren und Bearbeiten von Workflows, zum Überwachen von Build-Läufen und zum Abrufen von Build-Problemen, Logs, Testzusammenfassungen und UI-Test-Artefakten über die App Store Connect API.

Funktionen

Die Build-Suche ist workflowbezogen. Abruf-Tools akzeptieren eine direkte buildRunId, oder eine workflowId plus buildNumber, oder eine workflowId plus buildSelector: "latest" | "latestFailing".

list_products und list_workflows paginieren automatisch durch alle Ergebnisse.

list_build_runs unterstützt status: "all" | "failed" | "succeeded" | "running" | "pending" und ein optionales limit, das standardmäßig 20 beträgt, sodass Agenten aktive Workflows abfragen können, ohne jeden Lauf lokal nachzubearbeiten oder die MCP-Antwortgröße aufzublähen.

Related MCP server: appstore-release-mcp

Anforderungen

• Node.js 20+

• App Store Connect API-Anmeldedaten mit Zugriff auf Xcode Cloud

Umgebungsvariablen

Primäre Namen:

• APPSTORE_CONNECT_API_KEY_ID

• APPSTORE_CONNECT_API_ISSUER_ID

• APPSTORE_CONNECT_API_KEY_CONTENT

Kompatibilitäts-Aliase:

• APP_STORE_KEY_ID

• APP_STORE_ISSUER_ID

• APP_STORE_PRIVATE_KEY

Der private Schlüssel kann als wörtlicher mehrzeiliger PEM-Inhalt oder als Zeichenfolge mit maskiertem \n übergeben werden.

Claude-Einrichtung

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-Einrichtung

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

Verfügbare Tools

• 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?)

Verhalten beim Log-Abruf

get_build_logs hält die MCP-Antwort absichtlich kompakt:

• Es lädt und extrahiert textähnliche Build-Log-Artefakte in ein temporäres lokales Verzeichnis.

• Es gibt savedLogsDirectory und savedLogs zurück, damit lokale Agenten die extrahierten Dateien mit rg, grep oder cat untersuchen können.

• Es gibt eine kompakte failedTests-Zusammenfassung, highlights und einen begrenzten excerpt zurück.

• Selbst wenn ein Aufrufer ein sehr großes maxCharacters übergibt, wird der Inline-Auszug begrenzt, um übermäßig große MCP-Antworten zu vermeiden.

Empfohlener Agenten-Workflow:

1. Rufe get_failed_tests oder get_build_logs auf.

2. Lies savedLogsDirectory.

3. Verwende rg in diesem Verzeichnis, um den genauen fehlgeschlagenen Test oder die Assertion zu untersuchen.

4. Falls nötig, rufe cleanup_saved_logs auf, wenn die Untersuchung abgeschlossen ist.

Temporäre Logs werden unter dem System-Temp-Verzeichnis in einem Pfad wie folgt geschrieben:

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

Auf macOS wird dies normalerweise zu einem Pfad unter /var/folders/.../T/ aufgelöst.

Bereinigungsrichtlinie:

• Jeder neue Aufruf für dieselbe buildRunId löscht und erstellt zuerst das build-spezifische temporäre Verzeichnis neu.

• Ältere Build-Verzeichnisse werden automatisch entfernt, wenn sie älter als 24 Stunden sind.

• Sie können cleanup_saved_logs auch direkt für eine buildRunId oder für alle Verzeichnisse aufrufen, die älter als ein gewähltes Aufbewahrungsfenster sind.

Beispiel-Prompts

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.

Verhalten der Workflow-Details

get_workflow_details gibt die Live-Workflow-Konfiguration zurück, die von App Store Connect bereitgestellt wird, gruppiert in:

• general

• environment

• startConditions

• actions

• postActions

Hinweise:

• environment enthält Repository, xcodeVersion und macOsVersion, wenn App Store Connect sie zurückgibt.

• actions enthält Aktionstyp, Schema, Plattform, Ziel, erforderlichen Bestehensstatus und Testplan-Details, falls vorhanden.

• postActions wird derzeit als leeres Array mit einem Hinweis zurückgegeben, da die App Store Connect-Workflow-Payload in der beobachteten API-Antwort keine separaten Post-Aktionen enthält.

Verhalten bei Workflow-Aktualisierungen

Die Workflow-Aktualisierungstools sind bewusst explizit:

• set_workflow_enabled schaltet nur isEnabled um.

• update_workflow_general ändert nur name, description und clean.

• update_workflow_start_conditions ändert nur die von dir übergebenen Startbedingungsobjekte.

• update_workflow_actions ersetzt das gesamte actions-Array, daher sollten Aufrufer zuerst den aktuellen Workflow abrufen und dann die endgültige gewünschte Aktionsliste senden.

Wichtige Einschränkung:

• Wenn der Workflow in Xcode Cloud Restrict Editing aktiviert hat, können Änderungen fehlschlagen, selbst wenn der App Store Connect-API-Schlüssel über App Manager-Zugriff verfügt.

• Damit MCP-Änderungen zuverlässig funktionieren, deaktiviere das Kontrollkästchen Restrict Editing für diesen Workflow, bevor du die Schreibwerkzeuge verwendest.

• Wenn Apple die Anfrage danach weiterhin ablehnt, verwende eine stärkere API-Schlüsselrolle wie Admin.

Lokale Entwicklung

Abhängigkeiten installieren:

npm install

Tests ausführen:

npm test

Paket erstellen:

npm run build