Appcircle MCP Server

officiel

Serveur MCP officiel d'Appcircle

GitHub

Que pouvez-vous faire avec Appcircle MCP ?

  • Surveiller l'état des builds et les journaux — Utilisez get_build_status et get_build_logs pour vérifier les exécutions de pipeline et déboguer les échecs.
  • Déclencher ou annuler des builds — Utilisez trigger_build et cancel_build pour démarrer ou arrêter de véritables exécutions de build.
  • Générer des informations sur la santé CI/CD — Utilisez get_build_insights_report pour obtenir un aperçu agrégé de la santé, des tendances et une analyse des causes racines.
  • Gérer la distribution des tests — Utilisez get_distribution_profiles et send_app_version_to_testers pour envoyer des builds aux testeurs.
  • Inspecter les identités de signature — Utilisez get_certificates, get_keystores et get_provisioning_profiles pour examiner la configuration de signature.
  • Suivre la publication sur le store — Utilisez get_publish_profiles et get_publish_details pour surveiller les exécutions du flux de publication.

Documentation

Appcircle MCP Server

Serveur MCP pour Appcircle : expose les outils Build, Signing Identities, Testing Distribution, Enterprise App Store, Publish to Stores et Reporting à tout client compatible MCP (Claude Desktop, Cursor, VS Code, etc.). Le serveur MCP Appcircle agit comme pont entre les outils d'IA et Appcircle ; ainsi, les agents IA, assistants et chatbots peuvent accéder et interagir en toute sécurité avec les ressources Appcircle via des outils structurés, gouvernés et au niveau des tâches.

Cas d'utilisation

  • Intelligence CI/CD et flux de travail : surveillez les exécutions de pipelines, suivez l'état des versions et obtenez des informations sur vos flux de travail CI/CD mobiles.
  • Configuration et informations sur l'environnement : interrogez les configurations de build et la configuration de signature pour comprendre comment un projet est configuré et d'où peuvent provenir les problèmes.
  • Reporting et informations opérationnelles : générez des résumés de la stabilité CI, des problèmes récurrents, des performances des pipelines et de la santé globale de la CI/CD.

Modes d'exécution

Vous pouvez utiliser le serveur MCP de quatre manières :

ModeRésumé
1. Hôte distantConnectez-vous à https://mcp.appcircle.io. Aucune installation locale ; votre client envoie votre jeton Appcircle (par ex. Authorization: Bearer <token>) à chaque requête.
2. Local (stdio)Exécutez le serveur à partir des sources : clonez le dépôt, utilisez éventuellement un venv, puis exécutez appcircle-mcp (le transport par défaut est stdio). Nécessite Python et pip. Définissez APPCIRCLE_ACCESS_TOKEN dans l'environnement. Votre client MCP exécute le serveur comme sous-processus.
3. Local (streamable-http)Exécutez le serveur localement via HTTP : utilisez --transport streamable-http et éventuellement --host / --port (par ex. appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000). Les clients se connectent à cette URL et envoient leur jeton dans la requête.
4. Local (Docker)Exécutez l'image Docker officielle sur votre machine. Nécessite Docker. Utilisez le port par défaut de l'image ou remplacez-le avec --port ; consultez la documentation de l'image pour une utilisation précise.

La configuration détaillée des clients (Cursor, Claude, etc.) se trouve dans les guides d'installation dédiés ; cette section n'est qu'un résumé de haut niveau.

Installation

Guides de configuration spécifiques aux clients :

Configuration (Variables d'environnement)

VariableRequiseDescription
APPCIRCLE_ACCESS_TOKENOui (stdio uniquement)Jeton d'accès API Appcircle. Requis lors de l'utilisation du transport stdio. Pour streamable-http, chaque client envoie son propre jeton. Voir Obtention d'un jeton pour savoir comment en obtenir un.
APPCIRCLE_API_URLNonURL de base de l'API (par défaut : https://api.appcircle.io peut différer pour les utilisateurs self-hosted).
APPCIRCLE_MCP_ALLOWED_HOSTNon (streamable-http uniquement)Nom d'hôte public pour le serveur MCP (par ex. mcp.appcircle.io). Définissez ceci lors d'un déploiement derrière un proxy inverse afin que le serveur accepte l'en-tête Host des clients. Omettez pour localhost.
APPCIRCLE_MCP_PORTNon (streamable-http uniquement)Port de liaison pour le serveur HTTP (par défaut : 8000). Remplacé par --port s'il est fourni. Utile pour on-prem ou Docker lorsqu'un port spécifique est requis.
LOG_LEVELNonNiveau de journalisation, par ex. DEBUG, INFO (par défaut : INFO).
APPCIRCLE_EXCLUDED_TOOLSETSNonEnsembles d'outils à exclure, séparés par des virgules (par ex. build_module,report). Voir Ensembles d'outils ci-dessous.
AC_MCP_ENABLE_WRITE_TOOLSNonLes outils d'écriture/action (par ex. trigger_build, cancel_build) sont enregistrés par défaut. Définissez sur false/0/no/off pour vous désinscrire et ne pas les enregistrer du tout (pas seulement les désactiver au moment de l'appel).

Définissez ces variables dans votre shell ou dans la configuration de votre client MCP.

Ensembles d'outils

Ensembles d'outils disponibles

Les ensembles d'outils suivants sont disponibles :

Ensemble d'outilsDescription
build_moduleProfils de build, configurations, workflows, commits et opérations de pipeline
signing_identitiesIdentités de signature et identifiants de bundle
testing_distributionProfils de distribution de test et détails de distribution
publish_to_storesProfils de publication et opérations de publication vers les magasins
enterprise_app_storeProfils de magasin d'applications d'entreprise et détails du magasin
reportReporting : historique des builds, distribution, signature, état de publication et rapports associés

Vous pouvez exclure un ou plusieurs ensembles d'outils afin que leurs outils ne soient pas enregistrés. Les exclusions peuvent être définies via les arguments CLI ou la variable d'environnement APPCIRCLE_EXCLUDED_TOOLSETS ; les deux sont fusionnés (union).

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

Exemple de configuration MCP (Cursor / Claude Desktop) avec exclusions :

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

Outils

Les outils sont exposés via MCP tools/list. La référence ci-dessous liste tous les outils par ensemble d'outils ; pour la forme des réponses et des exemples, voir docs/tool_contract.md.

Build

  • get_build_profiles - Obtenir les profils de build pour l'organisation actuelle (paginé). Filtrer éventuellement par nom de profil, plateforme, dernier état de build et source de dépôt. Trier éventuellement.

    • Niveau d'accès : lecture
    • page : Numéro de page (base 1). Par défaut : 1. (nombre, optionnel)
    • size : Taille de page (1-100). Par défaut : 25. Les valeurs supérieures à 100 sont plafonnées à 100. (nombre, optionnel)
    • search : Terme de recherche optionnel pour filtrer les profils (correspondance partielle insensible à la casse sur le nom du profil ; la recherche de l'API peut également correspondre à d'autres champs du profil). (chaîne, optionnel)
    • platform : Liste optionnelle de codes de plateforme pour filtrer. Valeurs autorisées : 1=iOS, 2=Android. (liste de nombres, optionnel)
    • last_build_status : Liste optionnelle de codes d'état de dernier build pour filtrer. Valeurs autorisées : 0=Succès, 1=Échec, 2=Annulé, 3=Délai dépassé, 90=En attente, 91=En cours. (liste de nombres, optionnel)
    • repository_source : Liste optionnelle de codes de source de dépôt pour filtrer. Valeurs autorisées : 1=GitHub, 2=Bitbucket, 3=GitLab, 4=Azure DevOps, 6=Dépôt public, 7=Dépôt privé, 8=SSH. (liste de nombres, optionnel)
    • sort : Code de champ de tri optionnel. Valeurs autorisées : 1=Nom du profil, 2=Date de création, 3=Date du dernier build. (nombre, optionnel)
    • sort_direction : Code de direction de tri optionnel. Valeurs autorisées : 1=ASC, 2=DESC. (nombre, optionnel)

  • get_build_profile_details - Obtenir un seul profil de build par ID, en incluant éventuellement ses configurations de build.

    • Niveau d'accès : lecture
    • profile_id : L'ID du profil de build (par ex. UUID). (chaîne, requis)
    • configurations : Si vrai, récupère également les configurations de build du profil. Par défaut : faux. (booléen, optionnel)

  • get_build_configuration_details - Obtenir une seule configuration de build par ID de profil et ID de configuration.

    • Niveau d'accès : lecture
    • profile_id : L'ID du profil de build (par ex. UUID). (chaîne, requis)
    • configuration_id : L'ID de la configuration de build (par ex. UUID). (chaîne, requis)

  • get_build_profile_workflows - Obtenir les workflows pour un profil de build par ID de profil.

    • Niveau d'accès : lecture
    • profile_id : L'ID du profil de build (par ex. UUID). (chaîne, requis)

  • get_workflow_detail - Obtenir un seul workflow par ID de profil de build et ID de workflow.

    • Niveau d'accès : lecture
    • profile_id : L'ID du profil de build (par ex. UUID). (chaîne, requis)
    • workflow_id : L'ID du workflow (par ex. UUID). (chaîne, requis)

  • get_commits_by_branch - Obtenir les commits pour une branche de build (paginé).

    • Niveau d'accès : lecture
    • branch_id : L'ID de la branche (par ex. UUID). (chaîne, requis)
    • page : Numéro de page (base 1). S'il est fourni avec la taille, active la pagination. Par défaut : 1. (nombre, optionnel)
    • size : Taille de page. Si fournie avec le numéro de page, active la pagination. Par défaut : 25, max 100. (nombre, optionnel)

  • get_commit_details - Obtenir un seul commit par ID de commit (UUID) ou par hash de commit (SHA git). Fournissez soit commit_id, soit commit_hash, pas les deux.

    • Niveau d'accès : lecture
    • commit_id : L'ID du commit (UUID). (chaîne, optionnel)
    • commit_hash : Le hash du commit (SHA git). (chaîne, optionnel)

  • get_last_commit - Obtenir le commit le plus récent sur une branche de build.

    • Niveau d'accès : lecture
    • branch_id : L'ID de la branche (par ex. UUID). (chaîne, requis)

  • get_build_status - Obtenir l'état d'un build (par ex. 0=Succès, 1=Échec, 2=Annulé, 3=Délai dépassé, 90=En attente, 91=En cours, 92=Finalisation, 99=Inconnu).

    • Niveau d'accès : lecture
    • commit_id : L'ID du commit (UUID). (chaîne, requis)
    • build_id : L'ID du build (UUID). (chaîne, requis)

  • get_build_logs - Obtenir les journaux d'un build, éventuellement limités à une seule étape. Par défaut, une vue tronquée en fin de fichier pour éviter de surcharger le contexte du modèle.

    • Niveau d'accès : lecture
    • commit_id : L'ID du commit (UUID). (chaîne, requis)
    • build_id : L'ID du build (UUID). (chaîne, requis)
    • step : Nom d'étape exact optionnel (insensible à la casse) pour limiter la sortie au bloc de journal d'une seule étape. (chaîne, optionnel)
    • full_log : Si vrai, renvoie le journal complet au lieu de la fin par défaut. Toujours plafonné à 256 Ko. Par défaut : faux. (booléen, optionnel)
    • tail_lines : Nombre de lignes à conserver depuis la fin lorsque full_log n'est pas utilisé. Par défaut : 200, max 1000. (nombre, optionnel)
    • grep : Filtre de sous-chaîne insensible à la casse appliqué aux lignes avant troncature. (chaîne, optionnel)

  • get_variable_groups - Obtenir tous les groupes de variables d'environnement de build pour l'organisation, y compris les variables de chaque groupe (clé, valeur, isSecret, isFile). Les valeurs secrètes sont déjà masquées par l'API.

    • Niveau d'accès : lecture
    • Ne prend aucun paramètre.

  • trigger_build - EFFET DE BORD : démarre une nouvelle exécution de build réelle (met en file d'attente un build réel, consommant des minutes/crédits de build) soit sur une branche (dernier commit synchronisé), soit pour un commit spécifique. Enregistré par défaut ; définissez AC_MCP_ENABLE_WRITE_TOOLS=false pour vous désinscrire.

    • Niveau d'accès : écriture
    • profile_id : L'ID du profil de build (par ex. UUID). Requis en mode branche (commit_id non fourni) ; inutilisé en mode commit. (chaîne, optionnel)
    • workflow_id : L'ID du workflow (par ex. UUID). Requis en mode branche. Optionnel en mode commit (utilise le dernier workflow utilisé/par défaut si omis). (chaîne, optionnel)
    • branch_name : Nom de branche optionnel (par ex. "main"). Mode branche uniquement ; revient à la branche par défaut du profil si omis. Ne doit pas être fourni avec commit_id. (chaîne, optionnel)
    • commit_id : L'ID propre du commit (pas son hash git) pour déclencher un build pour un commit spécifique au lieu du dernier sur une branche. Ne doit pas être fourni avec branch_name. (chaîne, optionnel)
    • configuration_id : ID de configuration de build optionnel (par ex. UUID) à utiliser à la place de la configuration par défaut. (chaîne, optionnel)

  • cancel_build - EFFET DE BORD : annule un build en file d'attente ou en cours (le travail réel en cours est arrêté ; ne peut pas être repris). Enregistré par défaut ; définissez AC_MCP_ENABLE_WRITE_TOOLS=false pour vous désinscrire.

    • Niveau d'accès : écriture
    • task_id : L'ID de tâche du build (le champ "taskId" renvoyé par trigger_build). (chaîne, requis)
Signing Identities

  • get_bundle_identifiers - Obtenir tous les identifiants de bundle pour l'organisation (identifiants de bundle d'applications iOS/macOS).

    • Niveau d'accès : lecture
    • Aucun paramètre.

  • get_certificates - Obtenir tous les certificats de signature pour l'organisation. Les champs sensibles (p12Password, p12Binary, metaData, thumbprint) sont omis.

    • Niveau d'accès : read
    • Aucun paramètre.

  • get_keystores - Obtenir tous les magasins de clés pour l'organisation (par ex. magasins de clés de signature Android). Les champs sensibles (password, aliasPassword, binary, checkSum, sha256FingerPrint) sont omis.

    • Niveau d'accès : read
    • Aucun paramètre.

  • get_provisioning_profiles - Obtenir les profils de provisionnement pour l'organisation (par ex. iOS/macOS). Les champs sensibles/volumineux (binary, metaData, certificateThumbPrints, provisionedDevices, connectApiKeyId) sont omis. Optionnellement, filtrer par identifiant d'application (bundle).

    • Niveau d'accès : read
    • app_id : Identifiant d'application (bundle) optionnel pour filtrer les profils de provisionnement (par ex. com.example.app). (string, optional)
Distribution de test

  • get_distribution_profiles - Obtenir les profils de distribution de test pour l'organisation actuelle (paginés). Optionnellement, filtrer par nom de profil, plateforme et type d'authentification. Optionnellement, trier.

    • Niveau d'accès : read
    • page : Numéro de page (base 1). Défaut : 1. (number, optional)
    • size : Taille de page (1-100). Défaut : 25, max 100. (number, optional)
    • search : Terme de recherche optionnel pour filtrer les profils (correspondance partielle insensible à la casse sur le nom du profil ; la recherche de l'API peut également correspondre à d'autres champs du profil). (string, optional)
    • platform : Liste optionnelle de codes de plateforme pour filtrer. Valeurs autorisées : 1=iOS, 2=Android. (list of numbers, optional)
    • authentication_type : Liste optionnelle de codes de type d'authentification pour filtrer. Valeurs autorisées : 1=None, 3=Static Login, 4=LDAP, 5=SSO. (list of numbers, optional)
    • sort : Code de champ de tri optionnel. Valeurs autorisées : 1=Nom du profil, 2=Date de création, 3=Date de dernier téléchargement. (number, optional)
    • sort_direction : Code de direction de tri optionnel. Valeurs autorisées : 1=ASC, 2=DESC. (number, optional)

  • get_distribution_profile_details - Obtenir un seul profil de distribution de test par identifiant (avec pagination optionnelle des versions d'application).

    • Niveau d'accès : read
    • profile_id : L'identifiant du profil de distribution (par ex. UUID). (string, required)
    • page : Numéro de page pour les versions d'application (base 1). Défaut : 1. (number, optional)
    • size : Taille de page pour les versions d'application (1-100). Défaut : 25, max 100. (number, optional)

  • get_testing_groups - Obtenir tous les groupes de distribution de test pour l'organisation, y compris les adresses e-mail des testeurs membres de chaque groupe et le type de groupe.

    • Niveau d'accès : read
    • Ne prend aucun paramètre.

  • update_app_version_release_notes - EFFET DE BORD : écrase les notes de version ("message") affichées aux testeurs pour une version d'application de distribution. Renvoie l'objet de version d'application mis à jour (exclut certThumbPrints). Enregistré par défaut ; définissez AC_MCP_ENABLE_WRITE_TOOLS=false pour vous désinscrire.

    • Niveau d'accès : write
    • profile_id : L'identifiant du profil de distribution (par ex. UUID). (string, required)
    • app_version_id : L'identifiant de la version d'application (par ex. UUID). (string, required)
    • message : Le texte des nouvelles notes de version. (string, required)

  • send_app_version_to_testers - EFFET DE BORD : envoie une notification réelle aux testeurs/à un groupe de test, en déclenchant une tâche de distribution pour une version d'application spécifique. Enregistré par défaut ; définissez AC_MCP_ENABLE_WRITE_TOOLS=false pour vous désinscrire.

    • Niveau d'accès : write
    • profile_id : L'identifiant du profil de distribution (par ex. UUID). (string, required)
    • app_version_id : L'identifiant de la version d'application (par ex. UUID). (string, required)
    • message : Le message de notification affiché aux testeurs. (string, required)
    • testers : Liste des testeurs à qui envoyer. Chaque entrée est soit une adresse e-mail de testeur, soit un identifiant de groupe de test (le champ "id" de get_testing_groups). (list of strings, required)
Publication dans les magasins

  • get_publish_profiles - Obtenir les profils de publication pour l'organisation actuelle pour un type de plateforme donné (paginés). Optionnellement, filtrer par statut de flux, marché cible, présence de binaire candidat à la publication, et statut de magasin. Optionnellement, trier.

    • Niveau d'accès : read
    • platform_type : Type de plateforme des profils de publication ("ios" ou "android"). (string, required)
    • page : Numéro de page (base 1). Défaut : 1. (number, optional)
    • size : Taille de page (1-100). Défaut : 25, max 100. (number, optional)
    • flow_status : Code de statut de flux optionnel pour filtrer (par ex. 0=Succès, 1=Échec, 91=En cours). (number, optional)
    • market_place_type : Liste optionnelle de codes de marché cible pour filtrer. Les valeurs autorisées dépendent de platform_type -- ios : 0=Non disponible, 1=App Store Connect, 4=Intune ; android : 0=Non disponible, 2=Google Play, 3=AppGallery, 4=Intune. (list of numbers, optional)
    • has_rc_binary : Filtre optionnel pour savoir si le profil a un binaire candidat à la publication. (boolean, optional)
    • store_status : Liste optionnelle de codes de statut de magasin pour filtrer. Les valeurs autorisées dépendent de platform_type (beaucoup plus de codes pour ios que pour android, par ex. ios : "IN_REVIEW", "READY_FOR_SALE", "REJECTED" ; android : "NOT_AVAILABLE", "DRAFT", "IN_PROGRESS", "HALTED", "COMPLETED"). (list of strings, optional)
    • sort : Code de champ de tri optionnel. Valeurs autorisées : 1=Nom du profil, 2=Date de création. (number, optional)
    • sort_direction : Code de direction de tri optionnel. Valeurs autorisées : 1=ASC, 2=DESC. (number, optional)

  • get_publish_profile_details - Obtenir un seul profil de publication par type de plateforme et identifiant (avec pagination optionnelle des versions d'application).

    • Niveau d'accès : read
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)
    • page : Numéro de page pour les versions d'application (base 1). Défaut : 1. (number, optional)
    • size : Taille de page pour les versions d'application (1-100). Défaut : 25, max 100. (number, optional)

  • get_app_version_metadata - Obtenir les métadonnées de fiche de magasin pour une seule version d'application (informations de revue d'application, localisations, informations de publication, informations de version d'application). appReviewInformation.demoPassword est exclu.

    • Niveau d'accès : read
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)
    • app_version_id : L'identifiant de la version d'application (par ex. UUID). (string, required)

  • get_metadata_locales - Obtenir les locales de métadonnées de magasin disponibles pour une seule version d'application (nom, code, localisé, isPrimary).

    • Niveau d'accès : read
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)
    • app_version_id : L'identifiant de la version d'application (par ex. UUID). (string, required)

  • get_intune_metadata - Obtenir les métadonnées d'application Microsoft Intune pour une seule version d'application (nom d'affichage, éditeur, identifiant de bundle, version, état de publication, types d'appareils applicables, catégories, etc.).

    • Niveau d'accès : read
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)
    • app_version_id : L'identifiant de la version d'application (par ex. UUID). (string, required)

  • get_publish_metadata_lock_status - Obtenir si les métadonnées de magasin d'un profil de publication sont verrouillées pour modification.

    • Niveau d'accès : read
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)

  • get_publish_details - Obtenir les détails de l'exécution du flux de publication pour une seule version d'application (statut, calendrier, étapes ordonnées avec historique d'exécution/artefacts/identifiants de ressources de journaux).

    • Niveau d'accès : read
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)
    • app_version_id : L'identifiant de la version d'application (par ex. UUID). (string, required)

  • get_publish_step_logs - Obtenir les journaux d'une exécution de flux de publication, optionnellement limités à une seule étape. Par défaut, une vue tronquée en fin de fichier est utilisée pour éviter de surcharger le contexte du modèle.

    • Niveau d'accès : read
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)
    • publish_id : L'identifiant de l'exécution du flux de publication (le champ "id" de get_publish_details). (string, required)
    • step_id : L'identifiant de l'étape (le champ "id" d'une étape de la liste des étapes de get_publish_details). (string, required)
    • step : Nom d'étape exact optionnel (insensible à la casse) pour limiter la sortie au bloc de journal d'une étape. (string, optional)
    • full_log : Si vrai, renvoyer l'intégralité du journal au lieu de la fin par défaut. Toujours limité à 256 Ko. Défaut : false. (boolean, optional)
    • tail_lines : Nombre de lignes à conserver depuis la fin lorsque full_log n'est pas utilisé. Défaut : 200, max 1000. (number, optional)
    • grep : Filtre de sous-chaîne insensible à la casse appliqué aux lignes avant troncature. (string, optional)

  • get_publish_flows - Obtenir les flux de publication configurés pour un profil de publication (nom, identifiant, document YAML complet du flux).

    • Niveau d'accès : read
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)

  • start_publish - EFFET DE BORD : démarre une exécution de flux de publication (ou la redémarre à partir d'une étape spécifique) -- véritable travail de publication (par ex. téléchargement sur l'App Store/Play Store/Intune). Enregistré par défaut ; définissez AC_MCP_ENABLE_WRITE_TOOLS=false pour vous désinscrire.

    • Niveau d'accès : write
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)
    • publish_id : L'identifiant de l'exécution du flux de publication (le champ "id" de get_publish_details). (string, required)
    • step_id : Identifiant d'étape optionnel pour démarrer à partir de cette étape au lieu du début du flux. (string, optional)
    • organization_pool_id : Identifiant de pool d'organisation optionnel (par ex. UUID) sur lequel exécuter. (string, optional)

  • stop_publish - EFFET DE BORD : annule une exécution de flux de publication en cours (le travail réel en cours est arrêté ; ne peut pas être repris). Enregistré par défaut ; définissez AC_MCP_ENABLE_WRITE_TOOLS=false pour vous désinscrire.

    • Niveau d'accès : write
    • platform_type : Type de plateforme ("ios" ou "android"). (string, required)
    • profile_id : L'identifiant du profil de publication (par ex. UUID). (string, required)
    • publish_id : L'identifiant de l'exécution du flux de publication (le champ "id" de get_publish_details). (string, required)
    • step_id : Identifiant d'étape optionnel. (string, optional)
    • organization_pool_id : Identifiant de pool d'organisation optionnel (par ex. UUID). (string, optional)
Magasin d'applications d'entreprise
  • get_store_profiles - Obtenir les profils de magasin d'applications d'entreprise pour l'organisation actuelle (paginés). Ne prend pas en charge la recherche, mais peut filtrer par plateforme, type de publication et visibilité. Optionnellement, trier.
    • Niveau d'accès : read
    • page : Numéro de page (base 1). Défaut : 1. (number, optional)
    • size : Taille de page (1-100). Défaut : 25, max 100. (number, optional)
    • platform_type : Liste optionnelle de codes de plateforme pour filtrer. Valeurs autorisées : 1=iOS, 2=Android. (list of numbers, optional)
    • publish_type : Liste optionnelle de codes de type de publication pour filtrer. Valeurs autorisées : 1=Publié en version bêta, 2=Publié en production. (list of numbers, optional)
    • visibility : Filtre optionnel pour savoir si le profil est publiquement listé (true=Listé, false=Non listé). (boolean, optional)
    • sort : Code de champ de tri optionnel. Valeurs autorisées : 1=Nom de l'application, 2=Date de création, 3=Nombre de téléchargements, 4=Date de réception du binaire. (number, optional)
    • sort_direction : Code de direction de tri optionnel. Valeurs autorisées : 1=ASC, 2=DESC. (number, optional)
  • get_store_profile_details - Obtient les détails d'un profil de magasin d'applications d'entreprise par ID (avec pagination facultative des versions d'applications).
    • Niveau d'accès : lecture
    • profile_id : L'ID du profil de magasin d'applications d'entreprise (ex. UUID). (chaîne, obligatoire)
    • page : Numéro de page pour les versions d'applications (base 1). Par défaut : 1. (nombre, facultatif)
    • size : Taille de page pour les versions d'applications (1-100). Par défaut : 25, max 100. (nombre, facultatif)
    • Le champ publishType de chaque version d'application est un entier : 0=Aucun, 1=Bêta, 2=En direct.
Report

  • get_build_history_report - Obtient le rapport d'historique des builds, éventuellement filtré par plage de dates, profil de build et organisation. Paginé.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • build_profile_name : Filtre par nom de profil de build. (chaîne, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)

  • get_build_queue_waiting_report - Obtient le rapport d'attente de la file de builds, éventuellement filtré par plage de dates. Paginé. Remarque : sur ce point de terminaison, buildDuration signifie le temps d'attente dans la file en minutes, et non le temps d'exécution (contrairement à get_build_history_report).

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). Doit être <= date_fin si les deux sont fournies. (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)

  • get_build_activity_log - Obtient le journal d'activité des builds (changements de workflow/profil, versions CodePush, etc.), éventuellement filtré par plage de dates et d'autres paramètres. Paginé.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). Doit être <= date_fin si les deux sont fournies. (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)
    • platform : Filtre par type de plateforme (code entier, ex. 0=Android, 1=iOS). (nombre, facultatif)
    • email : Filtre par e-mail de l'utilisateur agissant. (chaîne, facultatif)
    • profile_name : Filtre par nom de profil de build. (chaîne, facultatif)
    • action : Filtre par code d'action d'activité (entier ; voir BUILD_ACTIVITY_ACTIONS dans la source de l'outil pour le mapping complet). (nombre, facultatif)

  • get_build_insights_report - Obtient un rapport d'analyse de builds calculé (instantané de santé + tendances, cause racine, santé des artefacts, qualité du workflow, temps de file d'attente et analyse de maturité) sur l'historique des builds, agrégé côté serveur. Contrairement à get_build_history_report, il récupère chaque page en interne et renvoie de petits résultats pré-agrégés plutôt que des enregistrements bruts.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ) pour la période actuelle. Par défaut : les 30 derniers jours. (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ) pour la période actuelle. (chaîne, facultatif)
    • sections : Liste facultative des sections à calculer : health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. Par défaut : les six. (tableau de chaînes, facultatif)
    • include_sub_orgs : Si true, conserve les enregistrements de builds inter-organisations dans les métriques dérivées de l'historique au lieu de filtrer sur la propre organisation du jeton. Par défaut : false. (booléen, facultatif)

  • get_distribution_app_version_report - Obtient le rapport d'utilisation quotidien pour les versions d'applications distribuées. Paginé ; prend en charge les filtres par profil, système d'exploitation, organisation.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • profile_name : Filtre par nom de profil de distribution. (chaîne, facultatif)
    • os : Filtre par système d'exploitation ("ios" ou "android"). (chaîne, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)

  • get_distribution_sent_report - Obtient le rapport d'utilisation quotidien pour le partage d'applications distribuées. Paginé ; prend en charge les filtres par profil, système d'exploitation, organisation.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • profile_name : Filtre par nom de profil de distribution. (chaîne, facultatif)
    • os : Filtre par système d'exploitation ("ios" ou "android"). (chaîne, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)

  • get_enterprise_app_store_app_usage_report - Obtient le rapport d'utilisation des applications pour le magasin d'applications d'entreprise. start_date et end_date sont obligatoires. Paginé.

    • Niveau d'accès : lecture
    • start_date : Date de début (AAAA-MM-JJ). (chaîne, obligatoire)
    • end_date : Date de fin (AAAA-MM-JJ). (chaîne, obligatoire)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • organization_id : Filtre facultatif par UUID d'organisation. (chaîne, facultatif)

  • get_publish_resign_report - Obtient le rapport de re-signature de publication, éventuellement filtré par plage de dates, nom d'application, organisation et statut. Paginé.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • app_name : Filtre par nom d'application. (chaîne, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)
    • status : Filtre par statut de re-signature (0=en attente, 1=en cours, 2=réussi, 3=échoué, 4=annulé, 5=délai dépassé). (nombre, facultatif)

  • get_publish_status_report - Obtient le rapport de statut de publication, éventuellement filtré par plage de dates, nom d'application, organisation et statut. Paginé.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • app_name : Filtre par nom d'application. (chaîne, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)
    • status : Filtre par statut de publication (ex. 0=Succès, 1=Échec, 91=En cours). (nombre, facultatif)

  • get_signing_report - Obtient le rapport de signature, éventuellement filtré par plage de dates, organisation, système d'exploitation et statut de build. Paginé.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)
    • os : Filtre par système d'exploitation ("ios" ou "android"). (chaîne, facultatif)
    • build_status : Filtre par statut de build (ex. 0=Succès, 1=Échec, 91=En cours). (nombre, facultatif)

  • get_signing_activity_log - Obtient le journal d'activité de signature (ex. avis d'expiration de certificat/profil de provisionnement/keystore), éventuellement filtré par plage de dates et d'autres paramètres. Paginé.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). Doit être <= date_fin si les deux sont fournies. (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)
    • platform : Filtre par plateforme (ex. "iOS", "Android"). (chaîne, facultatif)
    • email : Filtre par e-mail de l'utilisateur agissant. (chaîne, facultatif)
    • action : Filtre par code d'action d'activité (entier ; voir SIGNING_ACTIVITY_ACTIONS dans la source de l'outil pour le mapping complet). (nombre, facultatif)

  • get_publish_activity_log - Obtient le journal d'activité de publication (re-signature, événements de flux de publication, etc.), éventuellement filtré par plage de dates et d'autres paramètres. Paginé.

    • Niveau d'accès : lecture
    • start_date : Date de début facultative (AAAA-MM-JJ). Doit être <= date_fin si les deux sont fournies. (chaîne, facultatif)
    • end_date : Date de fin facultative (AAAA-MM-JJ). (chaîne, facultatif)
    • page : Numéro de page (par défaut : 1). (nombre, facultatif)
    • size : Éléments par page (1-100, par défaut : 50). (nombre, facultatif)
    • organization_id : Filtre par UUID d'organisation. (chaîne, facultatif)
    • platform : Filtre par plateforme (ex. "iOS", "Android"). (chaîne, facultatif)
    • email : Filtre par e-mail de l'utilisateur agissant. (chaîne, facultatif)
    • profile_name : Filtre par nom de profil de publication. (chaîne, facultatif)
    • action : Filtre par code d'action d'activité (entier ; voir PUBLISH_ACTIVITY_ACTIONS dans la source de l'outil pour le mapping complet). (nombre, facultatif)

Exécution du serveur

Depuis la racine du dépôt :

python -m src.server

Ou après pip install -e . :

appcircle-mcp

Le serveur s'exécute via stdio (ou SSE/HTTP selon la façon dont votre client le démarre).

Format de réponse

Chaque outil renvoie une enveloppe standard :

  • Succès : { "success": true, "data": <payload>, "meta": { ... } }
    data est le résultat de l'outil ; meta est facultatif (par ex. count, page, filters).
  • Erreur : { "success": false, "error": { "tool", "type", "message", "details" } }
    Même forme pour tous les outils afin que les clients puissent analyser les erreurs de manière cohérente.

Spécification complète : docs/tool_contract.md.

Tests

Installation avec les dépendances de développement :

pip install -e ".[dev]"

Tests unitaires (par défaut)

Utilisent une API simulée ; aucun APPCIRCLE_ACCESS_TOKEN n'est nécessaire. Le pytest par défaut exécute uniquement ceux-ci (voir testpaths dans pyproject.toml) :

pytest test/unit/ -v
  • Fichier unique : pytest test/unit/tools/build_module/test_get_build_profiles.py -v
  • Avec couverture : pytest test/unit/ --cov=src --cov-report=term-missing

Tests d'intégration

Appellent la vraie API Appcircle. Définissez APPCIRCLE_ACCESS_TOKEN dans l'environnement, puis exécutez :

pytest test/integration/ -v
  • Tous les tests d'intégration : pytest test/integration/ -v
  • Par outil : pytest test/integration/build_module/ -v, pytest test/integration/report/ -v, etc.
  • Par marqueur : pytest -m integration -v (en exécutant depuis la racine du dépôt ; inclut uniquement les tests d'intégration si les tests unitaires et d'intégration sont tous deux collectés)

Si APPCIRCLE_ACCESS_TOKEN n'est pas défini, les tests d'intégration sont ignorés (aucun échec).

Variables d'environnement facultatives pour les tests d'intégration (si la découverte échoue ou si les tests ont besoin d'IDs réels ; omettre pour ignorer ces tests) :

VariableDescription
APPCIRCLE_TEST_ORGANIZATION_IDUUID d'organisation. Utilisé par test_with_organization_id (rapport d'utilisation des applications du magasin d'applications d'entreprise).
APPCIRCLE_TEST_BRANCH_IDUUID de branche. Utilisé par get_commits_by_branch et les tests associés lorsqu'aucune branche ne peut être découverte à partir de l'API.
APPCIRCLE_TEST_COMMIT_IDUUID de commit. Utilisé par les tests get_commit_details lorsqu'aucun commit ne peut être découvert à partir de l'API.
Tests d'intégration d'écriture/action (trigger_build, cancel_build, etc.) sont marqués integration_write et sont optionnels en plus de APPCIRCLE_ACCESS_TOKEN — ils modifient des données réelles (déclenchent de vraies builds, etc.), donc ils ne s'exécutent jamais simplement à partir de pytest test/integration/ -v. Définissez APPCIRCLE_RUN_WRITE_INTEGRATION_TESTS=true (pointant APPCIRCLE_ACCESS_TOKEN vers une org de test dédiée, pas la production) pour les activer.

Sécurité

Ce projet dépend de packages open-source tiers listés dans pyproject.toml. Bien que nous épinglions les plages de versions des dépendances et fournissions un fichier de verrouillage (uv.lock) avec des hachages cryptographiques, ces packages sont maintenus indépendamment et fournis « tels quels ». Appcircle ne donne aucune garantie concernant la sécurité ou la fiabilité des dépendances tierces.

Nous recommandons d'auditer les packages installés avant utilisation :

uv run pip-audit