Appcircle MCP Server

offiziell

Appcircle offizieller MCP-Server

GitHub

Was kann man mit Appcircle MCP machen?

  • Build-Profile auflisten und durchsuchen — Paginierte Build-Profile abrufen und nach Namen filtern mit get_build_profiles.
  • Build-Konfigurationen und Workflows überprüfen — Details für ein bestimmtes Build-Profil, dessen Konfigurationen und Workflows abrufen mit get_build_profile_details, get_build_configuration_details und get_workflow_detail.
  • Signing-Identitäten überprüfen — Zertifikate, Keystores, Provisioning-Profile und Bundle-Identifikatoren auflisten über get_certificates, get_keystores, get_provisioning_profiles und get_bundle_identifiers.
  • Test- und Enterprise-Distributionsstatus prüfen — Distributionsprofile und deren App-Versionen abrufen mit get_distribution_profiles und get_distribution_profile_details, oder Enterprise-Store-Profile über get_store_profiles überprüfen.
  • CI/CD-Health- und Build-Verlaufsberichte generieren — get_build_insights_report für aggregierte Trends und Ursachenanalyse verwenden, oder get_build_history_report für rohe Build-Datensätze.

Dokumentation

Appcircle MCP Server

MCP-Server für Appcircle: stellt Build-, Signierungsidentitäten-, Testverteilungs-, Enterprise-App-Store-, Store-Veröffentlichungs- und Berichtswerkzeuge 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 auf Appcircle-Ressourcen zugreifen und mit ihnen über strukturierte, kontrollierte und aufgabenbezogene Werkzeuge interagieren.

Anwendungsfälle

  • CI/CD- und Workflow-Intelligenz: Überwachen Sie Pipeline-Ausführungen, verfolgen Sie den Release-Status und erhalten Sie Einblicke in Ihre mobilen CI/CD-Workflows.
  • Konfigurations- und Umgebungseinblicke: Fragen Sie Build-Konfigurationen und Signierungseinstellungen ab, um zu verstehen, wie ein Projekt konfiguriert ist und wo Probleme ihren Ursprung haben könnten.
  • Berichts- und Betriebseinblicke: Erstellen Sie Zusammenfassungen zur CI-Stabilität, wiederkehrenden Problemen, Pipeline-Leistung und dem allgemeinen CI/CD-Zustand.

Ausführungsmodi

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

ModusZusammenfassung
1. Remote-HostVerbinden Sie sich mit https://mcp.appcircle.io. Keine lokale Installation; Ihr Client sendet bei jeder Anfrage Ihr Appcircle-Token (z. B. Authorization: Bearer <token>).
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; siehe die Image-Dokumentation für die genaue Verwendung.

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

Installation

Client-spezifische Einrichtungsanleitungen:

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 erhalten für Informationen zur Beschaffung.
APPCIRCLE_API_URLNeinAPI-Basis-URL (Standard: https://api.appcircle.io kann für selbst gehostete Benutzer abweichen).
APPCIRCLE_MCP_ALLOWED_HOSTNein (nur streamable-http)Öffentlicher Hostname für den MCP-Server (z. B. mcp.appcircle.io). Setzen Sie dies, wenn Sie hinter einem Reverse-Proxy bereitstellen, 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 von --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 auszuschließende Toolsets (z. B. build_module,report). Siehe Toolsets unten.

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_identitiesSignierungsidentitäten und Bundle-Identifikatoren
testing_distributionTestverteilungsprofile und Verteilungsdetails
publish_to_storesVeröffentlichungsprofile und Store-Veröffentlichungsoperationen
enterprise_app_storeEnterprise-App-Store-Profile und Store-Details
reportBerichterstattung: Build-Verlauf, Verteilung, Signierung, Veröffentlichungsstatus und zugehörige Berichte

Sie können ein oder mehrere Toolsets ausschließen, sodass deren Werkzeuge nicht registriert werden. Ausschlüsse können über CLI-Argumente oder die Umgebungsvariable APPCIRCLE_EXCLUDED_TOOLSETS 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"]
    }
  }
}

Werkzeuge

Werkzeuge werden über MCP tools/list bereitgestellt. Die folgende Referenz listet alle Werkzeuge nach Toolset auf; für Antwortstruktur und Beispiele siehe docs/tool_contract.md.

Build

  • get_build_profiles – Build-Profile für die aktuelle Organisation abrufen (paginiert). Optional nach Profilnamen filtern.

    • Zugriffsebene: lesen
    • page: Seitennummer (1-basiert). Standard: 1. (Zahl, optional)
    • size: Seitengröße (1-100). Standard: 25. Werte über 100 werden auf 100 begrenzt. (Zahl, optional)
    • search: Optionaler Suchbegriff zum Filtern von Profilen nach Namen (Groß-/Kleinschreibung ignorierende Teilübereinstimmung). (Zeichenkette, optional)

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

    • Zugriffsebene: lesen
    • profile_id: Die Build-Profil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • configurations: Wenn true, werden auch die Build-Konfigurationen des Profils abgerufen. Standard: false. (boolesch, optional)

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

    • Zugriffsebene: lesen
    • profile_id: Die Build-Profil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • configuration_id: Die Build-Konfigurations-ID (z. B. UUID). (Zeichenkette, erforderlich)

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

    • Zugriffsebene: lesen
    • profile_id: Die Build-Profil-ID (z. B. UUID). (Zeichenkette, erforderlich)

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

    • Zugriffsebene: lesen
    • profile_id: Die Build-Profil-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • workflow_id: Die Workflow-ID (z. B. UUID). (Zeichenkette, erforderlich)

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

    • Zugriffsebene: lesen
    • branch_id: Die Branch-ID (z. B. UUID). (Zeichenkette, erforderlich)
    • page: Seitennummer (1-basiert). Wenn zusammen mit size angegeben, wird Paginierung aktiviert. Standard: 1. (Zahl, optional)
    • size: Seitengröße. Wenn zusammen mit page angegeben, wird Paginierung aktiviert. Standard: 25, max. 100. (Zahl, optional)

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

    • Zugriffsebene: lesen
    • commit_id: Die Commit-ID (UUID). (Zeichenkette, optional)
    • commit_hash: Der Commit-Hash (git SHA). (Zeichenkette, optional)
Signing Identities

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

    • Zugriffsebene: lesen
    • Keine Parameter.

  • get_certificates – Alle Signierungszertifikate 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-Signierungs-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 von Bereitstellungsprofilen (z. B. com.example.app). (Zeichenkette, optional)
Testing Distribution

  • get_distribution_profiles – Testverteilungsprofile für die aktuelle Organisation abrufen (paginiert). Optional nach Profilnamen filtern.

    • 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 nach Namen. (Zeichenkette, 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)
Publish to Stores

  • get_publish_profiles – Veröffentlichungsprofile für die aktuelle Organisation für einen bestimmten Plattformtyp abrufen (paginiert). Optional nach Flow-Status filtern.

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

  • 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)
Enterprise App Store

  • get_store_profiles – Enterprise-App-Store-Profile für die aktuelle Organisation abrufen (paginiert).

    • Zugriffsebene: lesen
    • page: Seitennummer (1-basiert). Standard: 1. (Zahl, optional)
    • size: Seitengröße (1-100). Standard: 25, max. 100. (Zahl, optional)

  • get_store_profile_details – Ein einzelnes Enterprise-App-Store-Profil anhand der ID abrufen (mit optionaler Paginierung der App-Versionen).

    • Zugriffsebene: lesen
    • profile_id: Die Enterprise-App-Store-Profil-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)
Report - **get_build_history_report** – Build-Verlaufsbericht abrufen, optional gefiltert nach Datumsbereich, Build-Profil und Organisation. Paginiert. - **Zugriffsebene:** Lesen - `start_date`: Optionales Startdatum (JJJJ-MM-TT). (String, optional) - `end_date`: Optionales Enddatum (JJJJ-MM-TT). (String, optional) - `page`: Seitennummer (Standard: 1). (Zahl, optional) - `size`: Einträge pro Seite (1-100, Standard: 50). (Zahl, optional) - `build_profile_name`: Nach Build-Profilnamen filtern. (String, optional) - `organization_id`: Nach Organisations-UUID filtern. (String, optional)

  • get_build_insights_report – Einen berechneten Build-Insights-Bericht (Health Snapshot & Trends, Root Cause, Artifact Health, Workflow Quality, Queue Time und Maturity Assessment-Analyse) über den Build-Verlauf abrufen, serverseitig aggregiert. Im Gegensatz zu get_build_history_report ruft dieser intern jede Seite ab und liefert kleine, voraggregierte Ergebnisse anstelle von Rohdatensätzen.

    • Zugriffsebene: Lesen
    • 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 von Strings, optional)
    • include_sub_orgs: Wenn true, organisationsübergreifende Build-Datensätze in verlaufsbasierten 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: Lesen
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (String, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (String, optional)
    • page: Seitennummer (Standard: 1). (Zahl, optional)
    • size: Einträge pro Seite (1-100, Standard: 50). (Zahl, 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 das Teilen verteilter Apps abrufen. Paginiert; unterstützt Filter nach Profil, Betriebssystem, Organisation.

    • Zugriffsebene: Lesen
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (String, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (String, optional)
    • page: Seitennummer (Standard: 1). (Zahl, optional)
    • size: Einträge pro Seite (1-100, Standard: 50). (Zahl, 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: Lesen
    • start_date: Startdatum (JJJJ-MM-TT). (String, erforderlich)
    • end_date: Enddatum (JJJJ-MM-TT). (String, erforderlich)
    • page: Seitennummer (Standard: 1). (Zahl, optional)
    • size: Einträge pro Seite (1-100, Standard: 50). (Zahl, optional)
    • organization_id: Optionaler Filter nach Organisations-UUID. (String, optional)

  • get_publish_resign_report – Veröffentlichungs-Resign-Bericht abrufen, optional gefiltert nach Datumsbereich, App-Name, Organisation und Status. Paginiert.

    • Zugriffsebene: Lesen
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (String, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (String, optional)
    • page: Seitennummer (Standard: 1). (Zahl, optional)
    • size: Einträge pro Seite (1-100, Standard: 50). (Zahl, optional)
    • app_name: Nach App-Namen filtern. (String, optional)
    • organization_id: Nach Organisations-UUID filtern. (String, optional)
    • status: Nach Resign-Status filtern (0=Wartend, 1=In Bearbeitung, 2=Erfolgreich, 3=Fehlgeschlagen, 4=Abgebrochen, 5=Zeitüberschreitung). (Zahl, optional)

  • get_publish_status_report – Veröffentlichungsstatus-Bericht abrufen, optional gefiltert nach Datumsbereich, App-Name, Organisation und Status. Paginiert.

    • Zugriffsebene: Lesen
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (String, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (String, optional)
    • page: Seitennummer (Standard: 1). (Zahl, optional)
    • size: Einträge pro Seite (1-100, Standard: 50). (Zahl, optional)
    • app_name: Nach App-Namen filtern. (String, optional)
    • organization_id: Nach Organisations-UUID filtern. (String, optional)
    • status: Nach Veröffentlichungsstatus filtern (z. B. 0=Erfolg, 1=Fehlgeschlagen, 91=Läuft). (Zahl, optional)

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

    • Zugriffsebene: Lesen
    • start_date: Optionales Startdatum (JJJJ-MM-TT). (String, optional)
    • end_date: Optionales Enddatum (JJJJ-MM-TT). (String, optional)
    • page: Seitennummer (Standard: 1). (Zahl, optional)
    • size: Einträge pro Seite (1-100, Standard: 50). (Zahl, 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). (Zahl, optional)

Server ausführen

Vom Repo-Stammverzeichnis aus:

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 Werkzeug liefert einen Standard-Umschlag:

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

Vollständige Spezifikation: docs/tool_contract.md.

Testen

Mit Entwicklungsabhängigkeiten installieren:

pip install -e ".[dev]"

Unit-Tests (Standard)

Verwendet eine gemockte 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 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 Werkzeug: pytest test/integration/build_module/ -v, pytest test/integration/report/ -v usw.
  • Nach Markierung: pytest -m integration -v (bei Ausführung vom Repo-Stammverzeichnis; schließt nur Integrationstests ein, wenn sowohl Unit- als auch Integrationstests gesammelt werden)

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

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. Wird von test_with_organization_id (Enterprise App Store App-Nutzungsbericht) verwendet.
APPCIRCLE_TEST_BRANCH_IDBranch-UUID. Wird von get_commits_by_branch und zugehörigen Tests verwendet, wenn kein Branch über die API ermittelt werden kann.
APPCIRCLE_TEST_COMMIT_IDCommit-UUID. Wird von get_commit_details-Tests verwendet, wenn kein Commit über die API ermittelt werden kann.

Sicherheit

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

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

uv run pip-audit