Appcircle MCP Server

officiel

Serveur MCP officiel d'Appcircle

GitHub

Que pouvez-vous faire avec Appcircle MCP ?

Lister et rechercher des profils de build — Récupérez les profils de build paginés et filtrez par nom avec get_build_profiles.
Inspecter les configurations de build et les workflows — Obtenez les détails d’un profil de build spécifique, de ses configurations et de ses workflows à l’aide de get_build_profile_details, get_build_configuration_details et get_workflow_detail.
Examiner les identités de signature — Listez les certificats, les keystores, les profils de provisionnement et les identifiants de bundle via get_certificates, get_keystores, get_provisioning_profiles et get_bundle_identifiers.
Vérifier l’état des tests et de la distribution en entreprise — Obtenez les profils de distribution et leurs versions d’application avec get_distribution_profiles et get_distribution_profile_details, ou inspectez les profils de store d’entreprise via get_store_profiles.
Générer des rapports sur l’état de santé CI/CD et l’historique des builds — Utilisez get_build_insights_report pour les tendances agrégées et l’analyse des causes racines, ou get_build_history_report pour les enregistrements bruts de builds.

Documentation

Serveur MCP Appcircle

Serveur MCP pour Appcircle : expose les outils de Build, Identités de signature, Distribution de test, App Store d'entreprise, Publication sur les stores et Rapports à tout client compatible MCP (Claude Desktop, Cursor, VS Code, etc.). Le serveur MCP Appcircle agit comme un pont entre les outils d'IA et Appcircle, permettant ainsi aux agents IA, assistants et chatbots d'accéder et d'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 Workflow : Surveiller les exécutions de pipeline, suivre l'état des releases et obtenir des informations sur vos workflows CI/CD mobiles.
Informations sur la configuration et l'environnement : Interroger les configurations de build et la configuration de signature pour comprendre comment un projet est configuré et d'où peuvent provenir les problèmes.
Rapports et informations opérationnelles : Générer des résumés de la stabilité CI, des problèmes récurrents, des performances des pipelines et de la santé globale CI/CD.

Modes d'exécution

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

Mode	Résumé
1. Hôte distant	Se connecter à 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écuter le serveur depuis les sources : cloner le dépôt, utiliser éventuellement un venv, puis exécuter `appcircle-mcp` (le transport par défaut est stdio). Nécessite Python et pip. Définir `APPCIRCLE_ACCESS_TOKEN` dans l'environnement. Votre client MCP exécute le serveur comme un sous-processus.
3. Local (streamable-http)	Exécuter le serveur localement via HTTP : utiliser `--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écuter l'image Docker officielle sur votre machine. Nécessite Docker. Utiliser le port par défaut de l'image ou le remplacer par `--port` ; consulter la documentation de l'image pour les détails d'utilisation.

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 au client :

Applications Claude - Guide d'installation pour Claude Desktop et Claude Code CLI.
Cursor IDE - Guide d'installation pour Cursor IDE.
Codex - Guide d'installation pour l'application Codex et Codex CLI.
Antigravity IDE - Guide d'installation pour Antigravity IDE.
VS Code (GitHub Copilot) - Guide d'installation pour VS Code avec GitHub Copilot.
Windsurf IDE - Guide d'installation pour Windsurf IDE.
Gemini CLI - Guide d'installation pour Gemini CLI.
GitHub Copilot CLI - Guide d'installation pour GitHub Copilot CLI.

Configuration (Variables d'environnement)

Variable	Requise	Description
`APPCIRCLE_ACCESS_TOKEN`	Oui (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_URL`	Non	URL de base de l'API (par défaut : `https://api.appcircle.io` peut différer pour les utilisateurs auto-hébergés).
`APPCIRCLE_MCP_ALLOWED_HOST`	Non (streamable-http uniquement)	Nom d'hôte public pour le serveur MCP (par ex. `mcp.appcircle.io`). À définir lors du déploiement derrière un proxy inverse afin que le serveur accepte l'en-tête `Host` des clients. Omettre pour localhost.
`APPCIRCLE_MCP_PORT`	Non (streamable-http uniquement)	Port d'écoute pour le serveur HTTP (par défaut : `8000`). Remplacé par `--port` s'il est fourni. Utile pour les installations sur site ou Docker lorsqu'un port spécifique est requis.
`LOG_LEVEL`	Non	Niveau de journalisation, par ex. `DEBUG`, `INFO` (par défaut : `INFO`).
`APPCIRCLE_EXCLUDED_TOOLSETS`	Non	Liste séparée par des virgules des jeux d'outils à exclure (par ex. `build_module,report`). Voir Jeux d'outils ci-dessous.

Définissez-les dans votre shell ou dans la configuration de votre client MCP.

Jeux d'outils

Jeux d'outils disponibles

Les ensembles d'outils suivants sont disponibles :

Jeu d'outils	Description
`build_module`	Profils de build, configurations, workflows, commits et opérations de pipeline
`signing_identities`	Identités de signature et identifiants de bundle
`testing_distribution`	Profils de distribution de test et détails de distribution
`publish_to_stores`	Profils de publication et opérations de publication sur les stores
`enterprise_app_store`	Profils de store d'entreprise et détails du store
`report`	Rapports : historique de build, distribution, signature, statut de publication et rapports associés

Vous pouvez exclure un ou plusieurs jeux d'outils afin que leurs outils ne soient pas enregistrés. Les exclusions peuvent être définies via des 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 jeu 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.
- Niveau d'accès : lecture
- page : Numéro de page (basé sur 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 par nom (correspondance partielle insensible à la casse). (chaîne, 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 : false. (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 d'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 d'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 (basé sur 1). Si fourni avec la taille, active la pagination. Par défaut : 1. (nombre, optionnel)
- size : Taille de page. Si fourni avec la 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 (git SHA). Fournir 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 (git SHA). (chaîne, optionnel)

Identités de signature

get_bundle_identifiers - Obtenir tous les identifiants de bundle pour l'organisation (ID de bundle d'application 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 : lecture
- Aucun paramètre.
get_keystores - Obtenir tous les keystores pour l'organisation (par ex. keystores de signature Android). Les champs sensibles (password, aliasPassword, binary, checkSum, sha256FingerPrint) sont omis.
- Niveau d'accès : lecture
- 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. Filtrer éventuellement par ID d'application (bundle).
- Niveau d'accès : lecture
- app_id : ID d'application (bundle) optionnel pour filtrer les profils de provisionnement (par ex. com.example.app). (chaîne, optionnel)

Distribution de test

get_distribution_profiles - Obtenir les profils de distribution de test pour l'organisation actuelle (paginé). Filtrer éventuellement par nom de profil.
- Niveau d'accès : lecture
- page : Numéro de page (basé sur 1). Par défaut : 1. (nombre, optionnel)
- size : Taille de page (1-100). Par défaut : 25, max 100. (nombre, optionnel)
- search : Terme de recherche optionnel pour filtrer les profils par nom. (chaîne, optionnel)
get_distribution_profile_details - Obtenir un seul profil de distribution de test par ID (avec pagination optionnelle des versions d'application).
- Niveau d'accès : lecture
- profile_id : L'ID du profil de distribution (par ex. UUID). (chaîne, requis)
- page : Numéro de page pour les versions d'application (basé sur 1). Par défaut : 1. (nombre, optionnel)
- size : Taille de page pour les versions d'application (1-100). Par défaut : 25, max 100. (nombre, optionnel)

Publication sur les stores

get_publish_profiles - Obtenir les profils de publication pour l'organisation actuelle pour un type de plateforme donné (paginé). Filtrer éventuellement par statut de flux.
- Niveau d'accès : lecture
- platform_type : Type de plateforme des profils de publication ("ios" ou "android"). (chaîne, requis)
- page : Numéro de page (basé sur 1). Par défaut : 1. (nombre, optionnel)
- size : Taille de page (1-100). Par défaut : 25, max 100. (nombre, optionnel)
- flow_status : Code de statut de flux optionnel pour filtrer (par ex. 0=Succès, 1=Échec, 91=En cours). (nombre, optionnel)
get_publish_profile_details - Obtenir un seul profil de publication par type de plateforme et ID (avec pagination optionnelle des versions d'application).
- Niveau d'accès : lecture
- platform_type : Type de plateforme ("ios" ou "android"). (chaîne, requis)
- profile_id : L'ID du profil de publication (par ex. UUID). (chaîne, requis)
- page : Numéro de page pour les versions d'application (basé sur 1). Par défaut : 1. (nombre, optionnel)
- size : Taille de page pour les versions d'application (1-100). Par défaut : 25, max 100. (nombre, optionnel)

App Store d'entreprise

get_store_profiles - Obtenir les profils de store d'entreprise pour l'organisation actuelle (paginé).
- Niveau d'accès : lecture
- page : Numéro de page (basé sur 1). Par défaut : 1. (nombre, optionnel)
- size : Taille de page (1-100). Par défaut : 25, max 100. (nombre, optionnel)
get_store_profile_details - Obtenir un seul profil de store d'entreprise par ID (avec pagination optionnelle des versions d'application).
- Niveau d'accès : lecture
- profile_id : L'ID du profil de store d'entreprise (par ex. UUID). (chaîne, requis)
- page : Numéro de page pour les versions d'application (basé sur 1). Par défaut : 1. (nombre, optionnel)
- size : Taille de page pour les versions d'application (1-100). Par défaut : 25, max 100. (nombre, optionnel)

Rapport

- **get_build_history_report** - Obtenir le rapport d'historique des builds, filtré optionnellement par plage de dates, profil de build et organisation. Paginé. - **Niveau d'accès :** lecture - `start_date` : Date de début optionnelle (AAAA-MM-JJ). (chaîne, optionnel) - `end_date` : Date de fin optionnelle (AAAA-MM-JJ). (chaîne, optionnel) - `page` : Numéro de page (par défaut : 1). (nombre, optionnel) - `size` : Éléments par page (1-100, par défaut : 50). (nombre, optionnel) - `build_profile_name` : Filtrer par nom de profil de build. (chaîne, optionnel) - `organization_id` : Filtrer par UUID d'organisation. (chaîne, optionnel)

get_build_insights_report - Obtenir un rapport d'analyse des builds calculé (instantané de santé + tendances, cause racine, santé des artefacts, qualité du workflow, temps d'attente et évaluation de la maturité) sur l'historique des builds, agrégé côté serveur. Contrairement à get_build_history_report, celui-ci récupère chaque page en interne et renvoie de petits résultats pré-agrégés au lieu d'enregistrements bruts.
- Niveau d'accès : lecture
- start_date : Date de début optionnelle (AAAA-MM-JJ) pour la période actuelle. Par défaut : les 30 derniers jours. (chaîne, optionnel)
- end_date : Date de fin optionnelle (AAAA-MM-JJ) pour la période actuelle. (chaîne, optionnel)
- sections : Liste optionnelle des sections à calculer : health_snapshot, root_cause, artifact_health, workflow_quality, queue_time, maturity_assessment. Par défaut : les six. (tableau de chaînes, optionnel)
- include_sub_orgs : Si vrai, conserver les enregistrements de build 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 : faux. (booléen, optionnel)
get_distribution_app_version_report - Obtenir le rapport d'utilisation quotidienne pour les versions d'application distribuées. Paginé ; prend en charge les filtres par profil, OS, organisation.
- Niveau d'accès : lecture
- start_date : Date de début optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- end_date : Date de fin optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- page : Numéro de page (par défaut : 1). (nombre, optionnel)
- size : Éléments par page (1-100, par défaut : 50). (nombre, optionnel)
- profile_name : Filtrer par nom de profil de distribution. (chaîne, optionnel)
- os : Filtrer par OS ("ios" ou "android"). (chaîne, optionnel)
- organization_id : Filtrer par UUID d'organisation. (chaîne, optionnel)
get_distribution_sent_report - Obtenir le rapport d'utilisation quotidienne pour le partage d'application distribuée. Paginé ; prend en charge les filtres par profil, OS, organisation.
- Niveau d'accès : lecture
- start_date : Date de début optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- end_date : Date de fin optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- page : Numéro de page (par défaut : 1). (nombre, optionnel)
- size : Éléments par page (1-100, par défaut : 50). (nombre, optionnel)
- profile_name : Filtrer par nom de profil de distribution. (chaîne, optionnel)
- os : Filtrer par OS ("ios" ou "android"). (chaîne, optionnel)
- organization_id : Filtrer par UUID d'organisation. (chaîne, optionnel)
get_enterprise_app_store_app_usage_report - Obtenir le rapport d'utilisation d'application 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, optionnel)
- size : Éléments par page (1-100, par défaut : 50). (nombre, optionnel)
- organization_id : Filtre optionnel par UUID d'organisation. (chaîne, optionnel)
get_publish_resign_report - Obtenir le rapport de resignature de publication, filtré optionnellement par plage de dates, nom d'application, organisation et statut. Paginé.
- Niveau d'accès : lecture
- start_date : Date de début optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- end_date : Date de fin optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- page : Numéro de page (par défaut : 1). (nombre, optionnel)
- size : Éléments par page (1-100, par défaut : 50). (nombre, optionnel)
- app_name : Filtrer par nom d'application. (chaîne, optionnel)
- organization_id : Filtrer par UUID d'organisation. (chaîne, optionnel)
- status : Filtrer par statut de resignature (0=en attente, 1=en cours, 2=réussi, 3=échoué, 4=annulé, 5=expiré). (nombre, optionnel)
get_publish_status_report - Obtenir le rapport de statut de publication, filtré optionnellement par plage de dates, nom d'application, organisation et statut. Paginé.
- Niveau d'accès : lecture
- start_date : Date de début optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- end_date : Date de fin optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- page : Numéro de page (par défaut : 1). (nombre, optionnel)
- size : Éléments par page (1-100, par défaut : 50). (nombre, optionnel)
- app_name : Filtrer par nom d'application. (chaîne, optionnel)
- organization_id : Filtrer par UUID d'organisation. (chaîne, optionnel)
- status : Filtrer par statut de publication (par ex. 0=Succès, 1=Échec, 91=En cours). (nombre, optionnel)
get_signing_report - Obtenir le rapport de signature, filtré optionnellement par plage de dates, organisation, OS et statut de build. Paginé.
- Niveau d'accès : lecture
- start_date : Date de début optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- end_date : Date de fin optionnelle (AAAA-MM-JJ). (chaîne, optionnel)
- page : Numéro de page (par défaut : 1). (nombre, optionnel)
- size : Éléments par page (1-100, par défaut : 50). (nombre, optionnel)
- organization_id : Filtrer par UUID d'organisation. (chaîne, optionnel)
- os : Filtrer par OS ("ios" ou "android"). (chaîne, optionnel)
- build_status : Filtrer par statut de build (par ex. 0=Succès, 1=Échec, 91=En cours). (nombre, optionnel)

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 optionnel (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

Installer avec les dépendances de développement :

pip install -e ".[dev]"

Tests unitaires (par défaut)

Utilise une API simulée ; aucun APPCIRCLE_ACCESS_TOKEN nécessaire. Par défaut, pytest 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 véritable 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 (lors de l'exécution depuis la racine du dépôt ; inclut uniquement les tests d'intégration si les deux types, unitaires et d'intégration, sont collectés)

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

Variables d'environnement optionnelles pour les tests d'intégration (lorsque la découverte échoue ou que les tests nécessitent de vrais identifiants ; omettez-les pour ignorer ces tests) :

Variable	Description
`APPCIRCLE_TEST_ORGANIZATION_ID`	UUID de l'organisation. Utilisé par `test_with_organization_id` (rapport d'utilisation d'application du magasin d'applications d'entreprise).
`APPCIRCLE_TEST_BRANCH_ID`	UUID de la branche. Utilisé par get_commits_by_branch et les tests associés lorsqu'aucune branche ne peut être découverte depuis l'API.
`APPCIRCLE_TEST_COMMIT_ID`	UUID du commit. Utilisé par les tests get_commit_details lorsqu'aucun commit ne peut être découvert depuis l'API.

Sécurité

Ce projet dépend de paquets 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 paquets sont maintenus indépendamment et fournis « en l'état ». Appcircle ne donne aucune garantie concernant la sécurité ou la fiabilité des dépendances tierces.

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

uv run pip-audit