Appcircle MCP Server

offiziell

Appcircle offizieller MCP-Server

GitHub

Was kann man mit Appcircle MCP machen?

  • Build-Status und Logs überwachen – Verwenden Sie get_build_status und get_build_logs, um Pipeline-Läufe zu prüfen und Fehler zu debuggen.
  • Builds auslösen oder abbrechen – Verwenden Sie trigger_build und cancel_build, um echte Build-Läufe zu starten oder zu stoppen.
  • CI/CD-Health-Insights generieren – Verwenden Sie get_build_insights_report, um eine aggregierte Health-Übersicht, Trends und Ursachenanalyse zu erhalten.
  • Testverteilung verwalten – Verwenden Sie get_distribution_profiles und send_app_version_to_testers, um Builds an Tester zu senden.
  • Signierungsidentitäten prüfen – Verwenden Sie get_certificates, get_keystores und get_provisioning_profiles, um das Signierungs-Setup zu überprüfen.
  • Store-Veröffentlichung verfolgen – Verwenden Sie get_publish_profiles und get_publish_details, um Veröffentlichungsabläufe zu überwachen.

Dokumentation

Appcircle MCP Server

MCP-Server für Appcircle: stellt Build-, Signing-Identities-, Testing-Distribution-, Enterprise-App-Store-, Publish-to-Stores- und Reporting-Tools für jeden MCP-fähigen Client (Claude Desktop, Cursor, VS Code usw.) bereit. Der Appcircle MCP Server fungiert als Brücke zwischen KI-Tools und Appcircle; so können KI-Agenten, Assistenten und Chatbots sicher über strukturierte, gesteuerte und aufgabenbezogene Tools auf Appcircle-Ressourcen zugreifen und mit ihnen interagieren.

Anwendungsfälle

  • CI/CD- und Workflow-Intelligenz: Überwachen Sie Pipeline-Läufe, verfolgen Sie den Release-Status und erhalten Sie Einblicke in Ihre mobilen CI/CD-Workflows.
  • Konfigurations- und Umgebungseinblicke: Fragen Sie Build-Konfigurationen und Signing-Setups ab, um zu verstehen, wie ein Projekt konfiguriert ist und wo Probleme entstehen könnten.
  • Reporting- und Betriebseinblicke: Erstellen Sie Zusammenfassungen zur CI-Stabilität, zu wiederkehrenden Problemen, zur Pipeline-Leistung und zum allgemeinen CI/CD-Zustand.

Ausführungsmodi

Sie können den MCP-Server auf vier Arten verwenden:

ModusZusammenfassung
1. Remote-HostVerbinden Sie sich mit https://mcp.appcircle.io. Keine lokale Installation erforderlich; Ihr Client sendet Ihr Appcircle-Token (z. B. Authorization: Bearer <token>) bei jeder Anfrage.
2. Lokal (stdio)Führen Sie den Server aus dem Quellcode aus: Klonen Sie das Repository, verwenden Sie optional eine venv, und führen Sie dann appcircle-mcp aus (Standardtransport ist stdio). Erfordert Python und pip. Setzen Sie APPCIRCLE_ACCESS_TOKEN in der Umgebung. Ihr MCP-Client führt den Server als Unterprozess aus.
3. Lokal (streamable-http)Führen Sie den Server lokal über HTTP aus: Verwenden Sie --transport streamable-http und optional --host / --port (z. B. appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000). Clients verbinden sich mit dieser URL und senden ihr Token in der Anfrage.
4. Lokal (Docker)Führen Sie das offizielle Docker-Image auf Ihrem Rechner aus. Erfordert Docker. Verwenden Sie den Standardport des Images oder überschreiben Sie ihn mit --port; die genaue Verwendung finden Sie in der Image-Dokumentation.

Detaillierte Client-Konfigurationen (Cursor, Claude usw.) finden Sie in den dedizierten Installationsanleitungen; dieser Abschnitt ist nur eine allgemeine Übersicht.

Installation

Clientspezifische Setup-Anleitungen:

Konfiguration (Umgebungsvariablen)

VariableErforderlichBeschreibung
APPCIRCLE_ACCESS_TOKENJa (nur stdio)Appcircle-API-Zugriffstoken. Erforderlich bei Verwendung des stdio-Transports. Bei streamable-http sendet jeder Client sein eigenes Token. Siehe Token abrufen für Informationen zum Erhalt eines Tokens.
APPCIRCLE_API_URLNeinAPI-Basis-URL (Standard: https://api.appcircle.io; kann für Self-Hosted-Benutzer abweichen).
APPCIRCLE_MCP_ALLOWED_HOSTNein (nur streamable-http)Öffentlicher Hostname für den MCP-Server (z. B. mcp.appcircle.io). Setzen Sie dies bei der Bereitstellung hinter einem Reverse-Proxy, damit der Server den Host-Header von Clients akzeptiert. Für localhost weglassen.
APPCIRCLE_MCP_PORTNein (nur streamable-http)Bind-Port für den HTTP-Server (Standard: 8000). Wird durch --port überschrieben, falls angegeben. Nützlich für On-Premises oder Docker, wenn ein bestimmter Port erforderlich ist.
LOG_LEVELNeinProtokollierungsstufe, z. B. DEBUG, INFO (Standard: INFO).
APPCIRCLE_EXCLUDED_TOOLSETSNeinKommagetrennte Toolsets, die ausgeschlossen werden sollen (z. B. build_module,report). Siehe Toolsets unten.
AC_MCP_ENABLE_WRITE_TOOLSNeinSchreib-/Aktions-Tools (z. B. trigger_build, cancel_build) werden standardmäßig registriert. Setzen Sie dies auf false/0/no/off, um sie abzuwählen und gar nicht erst zu registrieren (nicht nur zur Aufrufzeit zu deaktivieren).

Setzen Sie diese in Ihrer Shell oder in der Konfiguration Ihres MCP-Clients.

Toolsets

Verfügbare Toolsets

Die folgenden Tool-Sets sind verfügbar:

ToolsetBeschreibung
build_moduleBuild-Profile, Konfigurationen, Workflows, Commits und Pipeline-Operationen
signing_identitiesSigning-Identities und Bundle-Identifier
testing_distributionTesting-Distribution-Profile und Verteilungsdetails
publish_to_storesPublish-Profile und Store-Veröffentlichungsoperationen
enterprise_app_storeEnterprise-App-Store-Profile und Store-Details
reportReporting: Build-Verlauf, Distribution, Signing, Publish-Status und zugehörige Berichte

Sie können ein oder mehrere Toolsets ausschließen, sodass deren Tools nicht registriert werden. Ausschlüsse können über CLI-Argumente oder die APPCIRCLE_EXCLUDED_TOOLSETS-Umgebungsvariable festgelegt werden; beide werden zusammengeführt (Vereinigung).

  • CLI: --exclude toolset1 toolset2 oder --exclude-toolsets toolset1,toolset2
  • Env: APPCIRCLE_EXCLUDED_TOOLSETS=build_module,report

Beispiel-MCP-Konfiguration (Cursor / Claude Desktop) mit Ausschlüssen:

{
  "mcpServers": {
    "appcircle": {
      "command": "appcircle-mcp",
      "args": ["--exclude", "report"]
    }
  }
}

Tools

Tools werden über MCP tools/list bereitgestellt. Die folgende Referenz listet alle Tools nach Toolset auf; Antwortstruktur und Beispiele finden Sie unter docs/tool_contract.md.

Build

  • get_build_profiles – Build-Profile für die aktuelle Organisation abrufen (paginiert). Optional nach Profilname, Plattform, letztem Build-Status und Repository-Quelle filtern. Optional sortieren.

    • Zugriffsebene: read
    • page: Seitennummer (1-basiert). Standard: 1. (number, optional)
    • size: Seitengröße (1–100). Standard: 25. Werte über 100 werden auf 100 begrenzt. (number, optional)
    • search: Optionaler Suchbegriff zum Filtern von Profilen (case-insensitive partielle Übereinstimmung mit dem Profilnamen; die API-Suche kann auch andere Profilfelder abgleichen). (string, optional)
    • platform: Optionale Liste von Plattformcodes zum Filtern. Zulässige Werte: 1=iOS, 2=Android. (list of numbers, optional)
    • last_build_status: Optionale Liste von Statuscodes des letzten Builds zum Filtern. Zulässige Werte: 0=Success, 1=Failed, 2=Canceled, 3=Timeout, 90=Waiting, 91=Running. (list of numbers, optional)
    • repository_source: Optionale Liste von Repository-Quellcodes zum Filtern. Zulässige Werte: 1=GitHub, 2=Bitbucket, 3=GitLab, 4=Azure DevOps, 6=Public Repository, 7=Private Repository, 8=SSH. (list of numbers, optional)
    • sort: Optionaler Sortierfeldcode. Zulässige Werte: 1=Profile Name, 2=Create Date, 3=Last Build Date. (number, optional)
    • sort_direction: Optionaler Sortierrichtungscode. Zulässige Werte: 1=ASC, 2=DESC. (number, optional)

  • get_build_profile_details – Ein einzelnes Build-Profil anhand der ID abrufen, optional einschließlich seiner Build-Konfigurationen.

    • Zugriffsebene: read
    • profile_id: Die Build-Profil-ID (z. B. UUID). (string, required)
    • configurations: Wenn true, werden auch die Build-Konfigurationen des Profils abgerufen. Standard: false. (boolean, optional)

  • get_build_configuration_details – Eine einzelne Build-Konfiguration anhand von Profil-ID und Konfigurations-ID abrufen.

    • Zugriffsebene: read
    • profile_id: Die Build-Profil-ID (z. B. UUID). (string, required)
    • configuration_id: Die Build-Konfigurations-ID (z. B. UUID). (string, required)

  • get_build_profile_workflows – Workflows für ein Build-Profil anhand der Profil-ID abrufen.

    • Zugriffsebene: read
    • profile_id: Die Build-Profil-ID (z. B. UUID). (string, required)

  • get_workflow_detail – Einen einzelnen Workflow anhand von Build-Profil-ID und Workflow-ID abrufen.

    • Zugriffsebene: read
    • profile_id: Die Build-Profil-ID (z. B. UUID). (string, required)
    • workflow_id: Die Workflow-ID (z. B. UUID). (string, required)

  • get_commits_by_branch – Commits für einen Build-Zweig abrufen (paginiert).

    • Zugriffsebene: read
    • branch_id: Die Zweig-ID (z. B. UUID). (string, required)
    • page: Seitennummer (1-basiert). Wenn zusammen mit size angegeben, wird Paginierung aktiviert. Standard: 1. (number, optional)
    • size: Seitengröße. Wenn zusammen mit page angegeben, wird Paginierung aktiviert. Standard: 25, max. 100. (number, optional)

  • get_commit_details – Einen einzelnen Commit anhand der Commit-ID (UUID) oder des Commit-Hashs (git SHA) abrufen. Geben Sie entweder commit_id oder commit_hash an, nicht beides.

    • Zugriffsebene: read
    • commit_id: Die Commit-ID (UUID). (string, optional)
    • commit_hash: Der Commit-Hash (git SHA). (string, optional)

  • get_last_commit – Den neuesten Commit auf einem Build-Zweig abrufen.

    • Zugriffsebene: read
    • branch_id: Die Zweig-ID (z. B. UUID). (string, required)

  • get_build_status – Den Status eines Builds abrufen (z. B. 0=Success, 1=Failed, 2=Canceled, 3=Timeout, 90=Waiting, 91=Running, 92=Completing, 99=Unknown).

    • Zugriffsebene: read
    • commit_id: Die Commit-ID (UUID). (string, required)
    • build_id: Die Build-ID (UUID). (string, required)

  • get_build_logs – Die Protokolle für einen Build abrufen, optional auf einen einzelnen Schritt begrenzt. Standardmäßig wird eine am Ende abgeschnittene Ansicht zurückgegeben, um den Kontext des Modells nicht zu überfluten.

    • Zugriffsebene: read
    • commit_id: Die Commit-ID (UUID). (string, required)
    • build_id: Die Build-ID (UUID). (string, required)
    • step: Optionaler exakter Schrittname (case-insensitive), um die Ausgabe auf den Protokollblock eines Schritts zu begrenzen. (string, optional)
    • full_log: Wenn true, wird das gesamte Protokoll statt des Standard-Endabschnitts zurückgegeben. Weiterhin auf 256 KB begrenzt. Standard: false. (boolean, optional)
    • tail_lines: Anzahl der Zeilen, die vom Ende beibehalten werden, wenn full_log nicht verwendet wird. Standard: 200, max. 1000. (number, optional)
    • grep: Case-insensitiver Teilstring-Filter, der vor dem Abschneiden auf Zeilen angewendet wird. (string, optional)

  • get_variable_groups – Alle Build-Umgebungsvariablengruppen für die Organisation abrufen, einschließlich der Variablen jeder Gruppe (key, value, isSecret, isFile). Geheime Werte werden von der API bereits geschwärzt.

    • Zugriffsebene: read
    • Nimmt keine Parameter entgegen.

  • trigger_build – SEITENEFFEKT: startet einen neuen echten Build-Lauf (stellt einen tatsächlichen Build in die Warteschlange und verbraucht Build-Minuten/Guthaben) entweder auf einem Zweig (letzter synchronisierter Commit) oder für einen bestimmten Commit. Standardmäßig registriert; setzen Sie AC_MCP_ENABLE_WRITE_TOOLS=false, um abzuwählen.

    • Zugriffsebene: write
    • profile_id: Die Build-Profil-ID (z. B. UUID). Erforderlich im Zweigmodus (commit_id nicht angegeben); im Commit-Modus ungenutzt. (string, optional)
    • workflow_id: Die Workflow-ID (z. B. UUID). Erforderlich im Zweigmodus. Optional im Commit-Modus (verwendet den zuletzt verwendeten/Standard-Workflow, wenn weggelassen). (string, optional)
    • branch_name: Optionaler Zweigname (z. B. "main"). Nur Zweigmodus; fällt auf den Standardzweig des Profils zurück, wenn weggelassen. Darf nicht zusammen mit commit_id angegeben werden. (string, optional)
    • commit_id: Die eigene ID des Commits (nicht sein git-Hash), um einen Build für einen bestimmten Commit statt für den neuesten auf einem Zweig auszulösen. Darf nicht zusammen mit branch_name angegeben werden. (string, optional)
    • configuration_id: Optionale Build-Konfigurations-ID (z. B. UUID), die statt der Standardkonfiguration verwendet werden soll. (string, optional)

  • cancel_build – SEITENEFFEKT: bricht einen in der Warteschlange befindlichen oder laufenden Build ab (echte, laufende Arbeit wird gestoppt; kann nicht fortgesetzt werden). Standardmäßig registriert; setzen Sie AC_MCP_ENABLE_WRITE_TOOLS=false, um abzuwählen.

    • Zugriffsebene: write
    • task_id: Die Task-ID des Builds (das Feld "taskId", das von trigger_build zurückgegeben wird). (string, required)
Signing Identities

  • get_bundle_identifiers – Alle Bundle-Identifier für die Organisation abrufen (iOS/macOS-App-Bundle-IDs).

    • Zugriffsebene: read
    • Keine Parameter.

  • get_certificates – Alle Signierzertifikate für die Organisation abrufen. Sensible Felder (p12Password, p12Binary, metaData, thumbprint) werden ausgelassen.

    • Zugriffsebene: lesen
    • Keine Parameter.

  • get_keystores – Alle Keystores für die Organisation abrufen (z. B. Android-Signatur-Keystores). Sensible Felder (password, aliasPassword, binary, checkSum, sha256FingerPrint) werden ausgelassen.

    • Zugriffsebene: lesen
    • Keine Parameter.

  • get_provisioning_profiles – Bereitstellungsprofile für die Organisation abrufen (z. B. iOS/macOS). Sensible/große Felder (binary, metaData, certificateThumbPrints, provisionedDevices, connectApiKeyId) werden ausgelassen. Optional nach App- (Bundle-) ID filtern.

    • Zugriffsebene: lesen
    • app_id: Optionale App- (Bundle-) ID zum Filtern der Bereitstellungsprofile (z. B. com.example.app). (Zeichenkette, optional)
Testverteilung

  • get_distribution_profiles – Testverteilungsprofile für die aktuelle Organisation abrufen (paginiert). Optional nach Profilname, Plattform und Authentifizierungstyp filtern. Optional sortieren.

    • Zugriffsebene: lesen
    • page: Seitennummer (1-basiert). Standard: 1. (Zahl, optional)
    • size: Seitengröße (1-100). Standard: 25, max. 100. (Zahl, optional)
    • search: Optionaler Suchbegriff zum Filtern von Profilen (case-insensitive Teilabgleich auf Profilname; die API-Suche kann auch andere Profilfelder abgleichen). (Zeichenkette, optional)
    • platform: Optionale Liste von Plattformcodes zum Filtern. Zulässige Werte: 1=iOS, 2=Android. (Liste von Zahlen, optional)
    • authentication_type: Optionale Liste von Authentifizierungstyp-Codes zum Filtern. Zulässige Werte: 1=Keine, 3=Statischer Login, 4=LDAP, 5=SSO. (Liste von Zahlen, optional)
    • sort: Optionaler Sortierfeldcode. Zulässige Werte: 1=Profilname, 2=Erstellungsdatum, 3=Letztes Upload-Datum. (Zahl, optional)
    • sort_direction: Optionaler Sortierrichtungscode. Zulässige Werte: 1=ASC, 2=DESC. (Zahl, optional)

  • get_distribution_profile_details – Ein einzelnes Testverteilungsprofil anhand der ID abrufen (mit optionaler Paginierung der App-Versionen).

    • Zugriffsebene: lesen
    • profile_id: Die Verteilungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • page: Seitennummer für App-Versionen (1-basiert). Standard: 1. (Zahl, optional)
    • size: Seitengröße für App-Versionen (1-100). Standard: 25, max. 100. (Zahl, optional)

  • get_testing_groups – Alle Testverteilungsgruppen für die Organisation abrufen, einschließlich der E-Mail-Adressen der Mitglieder-Tester und des Gruppentyps.

    • Zugriffsebene: lesen
    • Nimmt keine Parameter entgegen.

  • update_app_version_release_notes – NEBENWIRKUNG: überschreibt die Release-Notizen („message“), die Testern angezeigt werden für eine Verteilungs-App-Version. Gibt das aktualisierte App-Versionsobjekt zurück (schließt certThumbPrints aus). Standardmäßig registriert; setzen Sie AC_MCP_ENABLE_WRITE_TOOLS=false, um abzulehnen.

    • Zugriffsebene: schreiben
    • profile_id: Die Verteilungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • app_version_id: Die App-Versions-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • message: Der neue Text der Release-Notizen. (Zeichenkette, erforderlich)

  • send_app_version_to_testers – NEBENWIRKUNG: sendet eine echte Benachrichtigung an Tester/eine Testgruppe und löst eine Verteilungsaufgabe für eine bestimmte App-Version aus. Standardmäßig registriert; setzen Sie AC_MCP_ENABLE_WRITE_TOOLS=false, um abzulehnen.

    • Zugriffsebene: schreiben
    • profile_id: Die Verteilungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • app_version_id: Die App-Versions-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • message: Die Benachrichtigungsnachricht, die Testern angezeigt wird. (Zeichenkette, erforderlich)
    • testers: Liste der Tester, an die gesendet werden soll. Jeder Eintrag ist entweder eine Tester-E-Mail-Adresse oder eine Testgruppen-ID (das „id“-Feld aus get_testing_groups). (Liste von Zeichenketten, erforderlich)
Veröffentlichen in Stores

  • get_publish_profiles – Veröffentlichungsprofile für die aktuelle Organisation für einen bestimmten Plattformtyp abrufen (paginiert). Optional nach Flow-Status, Ziel-Marketplace, Vorhandensein von Release-Kandidaten-Binaries und Store-Status filtern. Optional sortieren.

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp der Veröffentlichungsprofile („ios“ oder „android“). (Zeichenkette, erforderlich)
    • page: Seitennummer (1-basiert). Standard: 1. (Zahl, optional)
    • size: Seitengröße (1-100). Standard: 25, max. 100. (Zahl, optional)
    • flow_status: Optionaler Flow-Statuscode zum Filtern (z. B. 0=Erfolg, 1=Fehlgeschlagen, 91=Läuft). (Zahl, optional)
    • market_place_type: Optionale Liste von Ziel-Marketplace-Codes zum Filtern. Zulässige Werte hängen von platform_type ab – ios: 0=Nicht verfügbar, 1=App Store Connect, 4=Intune; android: 0=Nicht verfügbar, 2=Google Play, 3=AppGallery, 4=Intune. (Liste von Zahlen, optional)
    • has_rc_binary: Optionaler Filter, ob das Profil ein Release-Kandidaten-Binary hat. (Boolescher Wert, optional)
    • store_status: Optionale Liste von Store-Statuscodes zum Filtern. Zulässige Werte hängen von platform_type ab (bei ios deutlich mehr Codes als bei android, z. B. ios: „IN_REVIEW“, „READY_FOR_SALE“, „REJECTED“; android: „NOT_AVAILABLE“, „DRAFT“, „IN_PROGRESS“, „HALTED“, „COMPLETED“). (Liste von Zeichenketten, optional)
    • sort: Optionaler Sortierfeldcode. Zulässige Werte: 1=Profilname, 2=Erstellungsdatum. (Zahl, optional)
    • sort_direction: Optionaler Sortierrichtungscode. Zulässige Werte: 1=ASC, 2=DESC. (Zahl, optional)

  • get_publish_profile_details – Ein einzelnes Veröffentlichungsprofil anhand von Plattformtyp und ID abrufen (mit optionaler Paginierung der App-Versionen).

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • page: Seitennummer für App-Versionen (1-basiert). Standard: 1. (Zahl, optional)
    • size: Seitengröße für App-Versionen (1-100). Standard: 25, max. 100. (Zahl, optional)

  • get_app_version_metadata – Store-Listing-Metadaten für eine einzelne App-Version abrufen (App-Review-Informationen, Lokalisierungen, Release-Informationen, App-Versionsinformationen). appReviewInformation.demoPassword ist ausgeschlossen.

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • app_version_id: Die App-Versions-ID (z. B. UUID). (Zeichenkette, erforderlich)

  • get_metadata_locales – Die verfügbaren Store-Metadaten-Lokalisierungen für eine einzelne App-Version abrufen (Name, Code, lokalisiert, isPrimary).

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • app_version_id: Die App-Versions-ID (z. B. UUID). (Zeichenkette, erforderlich)

  • get_intune_metadata – Microsoft-Intune-App-Metadaten für eine einzelne App-Version abrufen (Anzeigename, Herausgeber, Bundle-ID, Version, Veröffentlichungsstatus, unterstützte Gerätetypen, Kategorien usw.).

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • app_version_id: Die App-Versions-ID (z. B. UUID). (Zeichenkette, erforderlich)

  • get_publish_metadata_lock_status – Abrufen, ob die Store-Metadaten eines Veröffentlichungsprofils für die Bearbeitung gesperrt sind.

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)

  • get_publish_details – Die Details des Veröffentlichungs-Flow-Laufs für eine einzelne App-Version abrufen (Status, Zeitplanung, geordnete Schritte mit Ausführungsverlauf/Artefakten/Log-Ressourcen-IDs).

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • app_version_id: Die App-Versions-ID (z. B. UUID). (Zeichenkette, erforderlich)

  • get_publish_step_logs – Die Logs für einen Veröffentlichungs-Flow-Lauf abrufen, optional auf einen einzelnen Schritt begrenzt. Standardmäßig wird eine am Ende abgeschnittene Ansicht verwendet, um den Kontext des Modells nicht zu überfluten.

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • publish_id: Die Veröffentlichungs-Flow-Lauf-ID (das „id“-Feld aus get_publish_details). (Zeichenkette, erforderlich)
    • step_id: Die Schritt-ID (das „id“-Feld eines Schritts aus der Schritte-Liste von get_publish_details). (Zeichenkette, erforderlich)
    • step: Optionaler exakter Schrittname (case-insensitive), um die Ausgabe auf den Log-Block eines Schritts zu begrenzen. (Zeichenkette, optional)
    • full_log: Wenn true, das gesamte Log statt des Standard-Endes zurückgeben. Weiterhin auf 256 KB begrenzt. Standard: false. (Boolescher Wert, optional)
    • tail_lines: Anzahl der Zeilen, die vom Ende beibehalten werden, wenn full_log nicht verwendet wird. Standard: 200, max. 1000. (Zahl, optional)
    • grep: Case-insensitive Teilstring-Filter, der vor dem Abschneiden auf Zeilen angewendet wird. (Zeichenkette, optional)

  • get_publish_flows – Die für ein Veröffentlichungsprofil konfigurierten Veröffentlichungs-Flows abrufen (Name, ID, vollständiges Flow-Dokument als YAML).

    • Zugriffsebene: lesen
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)

  • start_publish – NEBENWIRKUNG: startet einen Veröffentlichungs-Flow-Lauf (oder startet ihn ab einem bestimmten Schritt neu) – echte Veröffentlichungsarbeit (z. B. Hochladen in den App Store/Play Store/Intune). Standardmäßig registriert; setzen Sie AC_MCP_ENABLE_WRITE_TOOLS=false, um abzulehnen.

    • Zugriffsebene: schreiben
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • publish_id: Die Veröffentlichungs-Flow-Lauf-ID (das „id“-Feld aus get_publish_details). (Zeichenkette, erforderlich)
    • step_id: Optionale Schritt-ID, um ab diesem Schritt statt vom Anfang des Flows zu starten. (Zeichenkette, optional)
    • organization_pool_id: Optionale Organisations-Pool-ID (z. B. UUID), auf der ausgeführt werden soll. (Zeichenkette, optional)

  • stop_publish – NEBENWIRKUNG: bricht einen laufenden Veröffentlichungs-Flow-Lauf ab (echte, laufende Arbeit wird gestoppt; kann nicht fortgesetzt werden). Standardmäßig registriert; setzen Sie AC_MCP_ENABLE_WRITE_TOOLS=false, um abzulehnen.

    • Zugriffsebene: schreiben
    • platform_type: Plattformtyp („ios“ oder „android“). (Zeichenkette, erforderlich)
    • profile_id: Die Veröffentlichungsprofil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • publish_id: Die Veröffentlichungs-Flow-Lauf-ID (das „id“-Feld aus get_publish_details). (Zeichenkette, erforderlich)
    • step_id: Optionale Schritt-ID. (Zeichenkette, optional)
    • organization_pool_id: Optionale Organisations-Pool-ID (z. B. UUID). (Zeichenkette, optional)
Unternehmens-App-Store
  • get_store_profiles – Unternehmens-App-Store-Profile für die aktuelle Organisation abrufen (paginiert). Unterstützt keine Suche, kann aber nach Plattform, Veröffentlichungstyp und Sichtbarkeit filtern. Optional sortieren.
    • Zugriffsebene: lesen
    • page: Seitennummer (1-basiert). Standard: 1. (Zahl, optional)
    • size: Seitengröße (1-100). Standard: 25, max. 100. (Zahl, optional)
    • platform_type: Optionale Liste von Plattformcodes zum Filtern. Zulässige Werte: 1=iOS, 2=Android. (Liste von Zahlen, optional)
    • publish_type: Optionale Liste von Veröffentlichungstyp-Codes zum Filtern. Zulässige Werte: 1=Veröffentlicht in Beta, 2=Veröffentlicht in Live. (Liste von Zahlen, optional)
    • visibility: Optionaler Filter, ob das Profil öffentlich gelistet ist (true=Gelistet, false=Nicht gelistet). (Boolescher Wert, optional)
    • sort: Optionaler Sortierfeldcode. Zulässige Werte: 1=App-Name, 2=Erstellungsdatum, 3=Download-Anzahl, 4=Binärempfangsdatum. (Zahl, optional)
    • sort_direction: Optionaler Sortierrichtungscode. Zulässige Werte: 1=ASC, 2=DESC. (Zahl, optional)
  • get_store_profile_details - Ein einzelnes Enterprise-App-Store-Profil anhand der ID abrufen (mit optionaler Paginierung der App-Versionen).
    • Zugriffsebene: read
    • profile_id: Die ID des Enterprise-App-Store-Profils (z. B. UUID). (string, erforderlich)
    • page: Seitennummer für App-Versionen (1-basiert). Standard: 1. (number, optional)
    • size: Seitengröße für App-Versionen (1-100). Standard: 25, max. 100. (number, optional)
    • Das publishType-Feld jeder App-Version ist ein int: 0=Keine, 1=Beta, 2=Live.
Bericht

  • get_build_history_report - Build-Verlaufsbericht abrufen, optional gefiltert nach Datumsbereich, Build-Profil und Organisation. Paginiert.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • build_profile_name: Nach Build-Profilnamen filtern. (string, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)

  • get_build_queue_waiting_report - Wartezeitbericht der Build-Warteschlange abrufen, optional gefiltert nach Datumsbereich. Paginiert. Hinweis: Bei diesem Endpunkt bedeutet buildDuration die Wartezeit in Minuten, nicht die Ausführungszeit (anders als bei get_build_history_report).

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). Muss <= end_date sein, wenn beide angegeben sind. (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)

  • get_build_activity_log - Build-Aktivitätsprotokoll abrufen (Workflow-/Profiländerungen, CodePush-Releases usw.), optional gefiltert nach Datumsbereich und anderen Parametern. Paginiert.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). Muss <= end_date sein, wenn beide angegeben sind. (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)
    • platform: Nach Plattformtyp filtern (Integer-Code, z. B. 0=Android, 1=iOS). (number, optional)
    • email: Nach E-Mail des ausführenden Benutzers filtern. (string, optional)
    • profile_name: Nach Build-Profilnamen filtern. (string, optional)
    • action: Nach Aktivitätsaktionscode filtern (Integer; siehe BUILD_ACTIVITY_ACTIONS in der Tool-Quelle für die vollständige Zuordnung). (number, optional)

  • get_build_insights_report - Einen berechneten Build-Insights-Bericht abrufen (Health-Snapshot + Trends, Root Cause, Artefakt-Gesundheit, Workflow-Qualität, Wartezeit und Reifegrad-Analyse) über den Build-Verlauf, serverseitig aggregiert. Im Gegensatz zu get_build_history_report ruft dieser jede Seite intern ab und gibt kleine voraggregierte Ergebnisse anstelle von Rohdatensätzen zurück.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT) für den aktuellen Zeitraum. Standard: letzte 30 Tage. (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT) für den aktuellen Zeitraum. (string, optional)
    • sections: Optionale Liste der zu berechnenden Abschnitte: health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. Standard: alle sechs. (array of strings, optional)
    • include_sub_orgs: Wenn true, werden organisationsübergreifende Build-Datensätze in den aus dem Verlauf abgeleiteten Metriken beibehalten, anstatt auf die eigene Organisation des Tokens zu filtern. Standard: false. (boolean, optional)

  • get_distribution_app_version_report - Täglichen Nutzungsbericht für verteilte App-Versionen abrufen. Paginiert; unterstützt Filter nach Profil, Betriebssystem, Organisation.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • profile_name: Nach Verteilungsprofilnamen filtern. (string, optional)
    • os: Nach Betriebssystem filtern ("ios" oder "android"). (string, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)

  • get_distribution_sent_report - Täglichen Nutzungsbericht für verteilte App-Freigaben abrufen. Paginiert; unterstützt Filter nach Profil, Betriebssystem, Organisation.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • profile_name: Nach Verteilungsprofilnamen filtern. (string, optional)
    • os: Nach Betriebssystem filtern ("ios" oder "android"). (string, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)

  • get_enterprise_app_store_app_usage_report - App-Nutzungsbericht für den Enterprise-App-Store abrufen. start_date und end_date sind erforderlich. Paginiert.

    • Zugriffsebene: read
    • start_date: Startdatum (JJJJ-MM-TT). (string, erforderlich)
    • end_date: Enddatum (JJJJ-MM-TT). (string, erforderlich)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • organization_id: Optionaler Filter nach Organisations-UUID. (string, optional)

  • get_publish_resign_report - Publish-Resign-Bericht abrufen, optional gefiltert nach Datumsbereich, App-Name, Organisation und Status. Paginiert.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • app_name: Nach App-Name filtern. (string, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)
    • status: Nach Resign-Status filtern (0=wartend, 1=verarbeitend, 2=erfolgreich, 3=fehlgeschlagen, 4=abgebrochen, 5=Zeitüberschreitung). (number, optional)

  • get_publish_status_report - Publish-Statusbericht abrufen, optional gefiltert nach Datumsbereich, App-Name, Organisation und Status. Paginiert.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • app_name: Nach App-Name filtern. (string, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)
    • status: Nach Publish-Status filtern (z. B. 0=Erfolg, 1=Fehlgeschlagen, 91=Läuft). (number, optional)

  • get_signing_report - Signierungsbericht abrufen, optional gefiltert nach Datumsbereich, Organisation, Betriebssystem und Build-Status. Paginiert.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)
    • os: Nach Betriebssystem filtern ("ios" oder "android"). (string, optional)
    • build_status: Nach Build-Status filtern (z. B. 0=Erfolg, 1=Fehlgeschlagen, 91=Läuft). (number, optional)

  • get_signing_activity_log - Signierungs-Aktivitätsprotokoll abrufen (z. B. Hinweise zum Ablauf von Zertifikaten/Provisioning-Profilen/Keystores), optional gefiltert nach Datumsbereich und anderen Parametern. Paginiert.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). Muss <= end_date sein, wenn beide angegeben sind. (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)
    • platform: Nach Plattform filtern (z. B. "iOS", "Android"). (string, optional)
    • email: Nach E-Mail des ausführenden Benutzers filtern. (string, optional)
    • action: Nach Aktivitätsaktionscode filtern (Integer; siehe SIGNING_ACTIVITY_ACTIONS in der Tool-Quelle für die vollständige Zuordnung). (number, optional)

  • get_publish_activity_log - Publish-Aktivitätsprotokoll abrufen (Re-Sign, Publish-Flow-Ereignisse usw.), optional gefiltert nach Datumsbereich und anderen Parametern. Paginiert.

    • Zugriffsebene: read
    • start_date: Optionales Startdatum (JJJJ-MM-TT). Muss <= end_date sein, wenn beide angegeben sind. (string, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (string, optional)
    • page: Seitennummer (Standard: 1). (number, optional)
    • size: Elemente pro Seite (1-100, Standard: 50). (number, optional)
    • organization_id: Nach Organisations-UUID filtern. (string, optional)
    • platform: Nach Plattform filtern (z. B. "iOS", "Android"). (string, optional)
    • email: Nach E-Mail des ausführenden Benutzers filtern. (string, optional)
    • profile_name: Nach Publish-Profilnamen filtern. (string, optional)
    • action: Nach Aktivitätsaktionscode filtern (Integer; siehe PUBLISH_ACTIVITY_ACTIONS in der Tool-Quelle für die vollständige Zuordnung). (number, optional)

Server ausführen

Aus dem Repository-Stammverzeichnis:

python -m src.server

Oder nach pip install -e .:

appcircle-mcp

Der Server läuft über stdio (oder SSE/HTTP, je nachdem, wie Ihr Client ihn startet).

Antwortformat

Jedes Tool gibt einen Standard-Umschlag zurück:

  • Erfolg: { "success": true, "data": <payload>, "meta": { ... } }
    data ist das Tool-Ergebnis; meta ist optional (z. B. count, page, filters).
  • Fehler: { "success": false, "error": { "tool", "type", "message", "details" } }
    Gleiche Struktur für alle Tools, damit Clients Fehler konsistent parsen können.

Vollständige Spezifikation: docs/tool_contract.md.

Testen

Mit Entwicklungsabhängigkeiten installieren:

pip install -e ".[dev]"

Unit-Tests (Standard)

Verwenden Sie eine simulierte API; kein APPCIRCLE_ACCESS_TOKEN erforderlich. Standardmäßig führt pytest nur diese aus (siehe testpaths in pyproject.toml):

pytest test/unit/ -v
  • Einzelne Datei: pytest test/unit/tools/build_module/test_get_build_profiles.py -v
  • Mit Abdeckung: pytest test/unit/ --cov=src --cov-report=term-missing

Integrationstests

Rufen Sie die echte Appcircle-API auf. Setzen Sie APPCIRCLE_ACCESS_TOKEN in der Umgebung und führen Sie dann aus:

pytest test/integration/ -v
  • Alle Integrationstests: pytest test/integration/ -v
  • Nach Tool: pytest test/integration/build_module/ -v, pytest test/integration/report/ -v, usw.
  • Nach Marker: pytest -m integration -v (wenn aus dem Repository-Stammverzeichnis ausgeführt; enthält nur Integrationstests, wenn sowohl Unit- als auch Integrationstests gesammelt werden)

Wenn APPCIRCLE_ACCESS_TOKEN nicht gesetzt ist, werden Integrationstests übersprungen (kein Fehler).

Optionale Umgebungsvariablen für Integrationstests (wenn die Erkennung fehlschlägt oder Tests echte IDs benötigen; weglassen, um diese Tests zu überspringen):

VariableBeschreibung
APPCIRCLE_TEST_ORGANIZATION_IDOrganisations-UUID. Verwendet von test_with_organization_id (Enterprise-App-Store-App-Nutzungsbericht).
APPCIRCLE_TEST_BRANCH_IDBranch-UUID. Verwendet von get_commits_by_branch und zugehörigen Tests, wenn kein Branch aus der API ermittelt werden kann.
APPCIRCLE_TEST_COMMIT_IDCommit-UUID. Verwendet von get_commit_details-Tests, wenn kein Commit aus der API ermittelt werden kann.
Schreib-/Aktions-Integrationstests (trigger_build, cancel_build, usw.) sind als integration_write markiert und sind optional zusätzlich zu APPCIRCLE_ACCESS_TOKEN — sie verändern echte Daten (lösen echte Builds aus, usw.), daher laufen sie nie nur über pytest test/integration/ -v. Setzen Sie APPCIRCLE_RUN_WRITE_INTEGRATION_TESTS=true (das APPCIRCLE_ACCESS_TOKEN auf eine dedizierte Test-Organisation zeigt, nicht auf Produktion), um sie zu aktivieren.

Sicherheit

Dieses Projekt hängt von Drittanbieter-Open-Source-Paketen ab, die in pyproject.toml aufgeführt sind. Obwohl wir Versionsbereiche der Abhängigkeiten festlegen und eine Sperrdatei (uv.lock) mit kryptografischen Hashes mitliefern, werden diese Pakete unabhängig gepflegt und "wie besehen" bereitgestellt. Appcircle gibt keinerlei Garantien hinsichtlich der Sicherheit oder Zuverlässigkeit von Drittanbieter-Abhängigkeiten.

Wir empfehlen, installierte Pakete vor der Verwendung zu prüfen:

uv run pip-audit