Analyser l’outil mobile
L’outil analyze_mobile analyse l’écran actuellement affiché sur un appareil mobile pour détecter des problèmes d’accessibilité, en utilisant les règles Axe DevTools Mobile. Il fonctionne avec un appareil Android ou un émulateur connecté, et avec un simulateur iOS démarré ou un iPhone connecté par USB.
analyze_mobile nécessite un abonnement Axe DevTools Mobile. Il ne fait pas partie des Plans Gratuits ou Premium, qui couvrent l’analyse web.
Ce qu’il fait
- Authentification - Valide votre identifiant Axe DevTools Mobile : soit un
AXE_MOBILE_API_KEYsoit un jeton d’accès OAuth 2.0 pour un compte disposant d’Axe DevTools Mobile - Configuration de l’appareil - Utilise
adb(Android) ouxcodebuild(iOS) sur votre machine pour installer et démarrer le serveur d’analyse de Deque sur l’appareil - Analyse de l’accessibilité - Analyse l’écran qui est ouvert sur l’appareil, en utilisant les règles par défaut d’Axe DevTools Mobile
- Livraison des résultats - Retourne les violations, les vérifications incomplètes et les réussites, chacune avec suffisamment de détails de localisation pour que votre agent puisse trouver la vue dans votre code source
Exigences
L’outil apparaît dans votre client MCP uniquement lorsque toutes les conditions suivantes sont vraies :
- La distribution npm. Le balayage mobile entraîne un appareil ou un simulateur connecté à votre machine, qu’un conteneur ne peut pas atteindre.
- Un identifiant Axe DevTools Mobile. Configurez
AXE_MOBILE_API_KEYà une clé API Axe DevTools Mobile depuis le portail de compte Axe, ou connectez-vous avec OAuth 2.0 en utilisant un compte disposant d’Axe DevTools Mobile. - Les packages de scanner, installé aux côtés du serveur. Voir Installation.
Chaque plateforme a également besoin d’outils sur la machine qui exécute le serveur :
| Plateforme | Hôte | Besoins |
|---|---|---|
| Android | macOS, Windows, Linux | Android SDK Platform-Tools, avec adb sur votre PATH. Un appareil avec le débogage USB activé, ou un émulateur en cours d’exécution. |
| Simulateur iOS | macOS uniquement | Xcode (pas seulement les outils de ligne de commande), sélectionné avec xcode-select. Un simulateur démarré. |
| iPhone (physique) | macOS uniquement | Xcode, un iPhone connecté par câble USB avec le mode développeur activé, et un compte développeur Apple pour signer WebDriverAgent. Voir Analyser un iPhone physique. |
Installation
1. Ajoutez les packages du scanner à votre commande de serveur
La distribution npm exécute le serveur avec npx, donc ajoutez les packages du scanner à la même commande :
@deque/axe-appium3-uiautomator2-serverpour Android@deque/axe-appium3-webdriveragent-assetspour iOS
Sur macOS, installez les deux, même si vous n’analysez qu’une seule plateforme. Sur Windows et Linux, n’installez que le package Android. Le serveur recherche les deux au démarrage, et s’il en manque un, il n’offre pas l’outil.
macOS, les deux plateformes :
{
"mcpServers": {
"axe-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"-p",
"axe-mcp-server",
"-p",
"@deque/axe-appium3-uiautomator2-server@^1.7.0",
"-p",
"@deque/axe-appium3-webdriveragent-assets@^1.7.0",
"axe-mcp-server"
],
"env": {
"AXE_MOBILE_API_KEY": "${AXE_MOBILE_API_KEY}"
}
}
}
}Windows et Linux, Android uniquement :
"args": [
"-y",
"-p",
"axe-mcp-server",
"-p",
"@deque/axe-appium3-uiautomator2-server@^1.7.0",
"axe-mcp-server"
]L'exemple utilise le format .mcp.json de Claude Code. Mettez le même args dans la configuration de votre propre client ; consultez le guide d'installation pour Claude Code, Curseur, ou VS Code avec Copilot. Si un package manque, le serveur le nomme dans son journal de démarrage.
2. Définir vos identifiants
Définissez un des éléments suivants :
- Clé API : Définissez
AXE_MOBILE_API_KEYà partir d'un Clé API Axe DevTools Mobile du portail de compte Axe. - OAuth 2.0 : Connectez-vous une fois avec
npx @deque/axe-auth login, en utilisant un compte ayant accès à Axe DevTools Mobile. Ensuite, exécutez le serveur sous@deque/axe-auth run: mettez les mêmes argumentsnpxde l'étape 1 après le--, et laissez de côtéAXE_MOBILE_API_KEY. Voir OAuth 2.0.
Si vous utilisez également les outils web avec une clé API, définissez AXE_API_KEY en plus de AXE_MOBILE_API_KEY. Une clé API ne peut pas être combinée avec AXE_ACCESS_TOKEN ; voir Référence de configuration.
3. Connecter un appareil
Vérifiez que l'appareil est visible avant de le scanner :
- Android : Exécutez
adb devices. Votre appareil ou émulateur doit être répertorié avec l'étatdevice. Un état deunauthorizedsignifie que l'appareil n'a pas encore accepté l'invite de débogage USB ;offlinesignifie queadbne peut pas l'atteindre. - iOS : Exécutez
xcrun simctl list devices bootedpour voir les simulateurs démarrés. Un iPhone physique devrait apparaître dans la fenêtre Appareils et simulateurs de Xcode.
4. Effectuer un premier scan
Ouvrez l'écran que vous souhaitez scanner, puis informez votre agent.
Android :
Scan the screen on my Android emulator for accessibility issuesiOS :
Scan the screen on my iPhone simulator for accessibility issuesPour iOS, votre agent envoie l'ID de bundle de l'application avec le scan. Il peut le trouver dans votre projet Xcode, ou vous pouvez le nommer dans l'invite.
Le premier scan iOS construit WebDriverAgent, ce qui peut prendre jusqu'à 15 minutes. Les scans suivants sur le même appareil sont beaucoup plus rapides.
Paramètres
| Paramètre | Obligatoire | Description |
|---|---|---|
platform |
Oui | "android" ou "ios" |
bundleId |
Oui (iOS seulement) | L'ID de bundle de l'application à l'écran, tel que com.example.app |
udid |
Non (iOS seulement) | L'UDID du simulateur ou de l'iPhone à scanner. S'il est omis, le serveur utilise le simulateur démarré, ou bien l'iPhone connecté. |
Choisissez un appareil Android. Il n'y a pas de paramètre d'appareil pour Android. Lorsqu'un appareil ou un émulateur est prêt, le serveur le scanne. Lorsqu'il y en a plusieurs de prêts, définissez ANDROID_SERIAL dans l'environnement du serveur sur le adb devices de série pour celui que vous souhaitez.
Trouvez l'ID de bundle. C'est le PRODUCT_BUNDLE_IDENTIFIER dans votre projet Xcode, ou le Info.plist de l'application. Dites à votre agent où chercher, ou incluez l'ID de bundle dans votre invite.
Invitez votre agent AI en langage naturel. L'agent traduit votre intention en appel d'outil :
Scan the app on my iPhone simulator for accessibility issues. The bundle ID
is in ios/MyApp.xcodeproj.L'agent résout l'invite et appelle analyze_mobile avec un chargement utile similaire à :
{
"platform": "ios",
"bundleId": "com.example.myapp"
}Résultats
L'outil renvoie un summary du scan et trois listes de résultats : violations, incomplete, et passes.
Résultats
Chaque entrée dans violations, incomplete, et passes possède les champs suivants :
| Champ | Description |
|---|---|
ruleId |
La règle Axe DevTools Mobile, telle que ColorContrast |
summary |
Une brève description de la règle |
impact |
Critical, Serious, Moderate, ou Minor |
standard |
La norme à laquelle la règle correspond, telle que WCAG 2.1 |
successCriteria |
Le critère de succès auquel la règle correspond, tel que 1.4.3 |
identifier |
L'identifiant défini par le développeur de la vue : accessibilityIdentifier sur iOS, ou l'ID de ressource sur Android, affiché sous forme de #name, ou null lorsque la vue n'en a pas |
viewPath |
Le chemin depuis la racine de l'écran jusqu'à la vue, sous forme de liste de noms de classe, avec l'identifiant de chaque vue entre parenthèses quand elle en a un, tel que Button(#login_button) |
bounds |
La position de la vue à l'écran, comme left, top, right et bottom |
accessibleName |
Le nom annoncé par la technologie d'assistance pour la vue, ou null |
props |
Preuves spécifiques à la règle, telles que les couleurs et le ratio mesurés par une vérification de contraste, avec des champs qui varient selon la règle |
identifier et viewPath sont comment votre agent trouve la vue dans votre code source. Un identifier est la correspondance la plus directe : recherchez-le dans le projet. Lorsqu'une vue n'a pas d'identifiant, viewPath montre où elle se situe, par nom de classe et par les ancêtres les plus proches qui en ont un.
Règles
analyze_mobile exécute les règles Axe DevTools Mobile pour chaque plateforme :
analyze_mobile exécute les règles par défaut d'Axe DevTools Mobile. Cela n'applique pas encore configuration des règles globales mobile de votre organisation.
Les Règles avancées et les tests guidés intelligents sont uniquement pour le web et ne s'exécutent pas dans les scans mobiles.
Scanner un iPhone physique
Un iPhone physique nécessite un peu plus qu'un simulateur :
- Connectez-le avec un câble USB. Un téléphone appairé avec votre Mac via Wi-Fi ne peut pas être scanné.
- Activez le mode développeur sous Réglages > Confidentialité & Sécurité > Mode développeur, puis redémarrez le téléphone.
- Faites confiance au Mac. Déverrouillez le téléphone et appuyez sur Faire confiance lorsqu'il le demande.
- Gardez-le déverrouillé, avec l'écran allumé, lors du scan.
- Signez WebDriverAgent avec votre compte de développeur Apple. Le serveur ne définit pas d'identité de signature pour vous. Ouvrez
WebDriverAgent.xcodeprojdans Xcode, choisissez votre Équipe sous Signature & Capabilités, et laissez Xcode créer un profil de provisioning.
Lorsque la signature échoue, le scan renvoie un message indiquant ce qui manque, tel qu'une équipe de développement ou un profil de provisioning.
Dépannage
Si analyze_mobile n'apparaît pas dans votre client, vérifiez Exigences et le journal de démarrage du serveur, qui nomme tout paquet de scanner manquant. Redémarrez la session MCP de votre client après avoir modifié la configuration.
Pour d'autres problèmes, les messages d'erreur du serveur indiquent ce qui ne va pas. Ceux qui nécessitent plus que le message :
| Message | Que faire |
|---|---|
AXE_MOBILE_API_KEY is not supported in the Docker distribution |
Le serveur refuse de démarrer dans Docker avec une clé mobile. Passez à la distribution npm. |
No Android device or emulator found, or the device is not ready |
Démarrez un émulateur, ou connectez un appareil avec le débogage USB activé et acceptez l'invite sur l'appareil. Vérifiez adb devices : l'état doit être device, pas unauthorized ou offline. |
More than one Android device is ready |
Réglez ANDROID_SERIAL sur le numéro de série de l'appareil à scanner, ou déconnectez les autres. |
The device named by ANDROID_SERIAL is not ready |
Comparez ANDROID_SERIAL avec la colonne de gauche de adb devices. |
An iOS scan needs the bundleId of the app on screen |
Incluez l'identifiant du bundle dans votre prompt, ou indiquez à votre agent où le trouver. |
xcodebuild not found |
Installez Xcode depuis l'App Store. S'il est installé, sélectionnez-le : sudo xcode-select -s /Applications/Xcode.app. Les outils en ligne de commande seuls ne suffisent pas. |
The iPhone is not connected by USB |
Un téléphone appairé via Wi-Fi ne peut pas être scanné. Connectez-le avec un câble USB. |
Code signing failed: … |
Signez WebDriverAgent avec votre compte de développeur Apple. Voir Analyser un iPhone physique. |
The device has Developer Mode disabled / has not trusted this Mac / appears to be locked |
Suivez les étapes dans Analyser un iPhone physique. |
The on-device scan server did not start within …ms |
Augmentez MOBILE_SERVER_READY_TIMEOUT_MS et réessayez. |
This account does not have an active axe DevTools Mobile subscription |
Demandez à l'administrateur de votre compte d'ajouter un abonnement Axe DevTools Mobile, puis démarrez une nouvelle session. |
This API key belongs to a different product |
Assurez-vous que AXE_MOBILE_API_KEY possède une clé Axe DevTools Mobile et que AXE_API_KEY possède une clé web, puis démarrez une nouvelle session. |
`analyze` needs a web credential (ou remediate, igt) |
Seul AXE_MOBILE_API_KEY est configuré, ce qui n'autorise pas les outils web. Ajoutez AXE_API_KEY, ou passez à OAuth et retirez AXE_MOBILE_API_KEY, puis démarrez une nouvelle session. |
Pour toute autre défaillance, définissez LOG_LEVEL=debug dans l'environnement du serveur. Pour une défaillance de build iOS, le journal de débogage inclut la sortie propre à Xcode. Voir également la page générale Dépannage.
Limitations
- Un écran par appel. L'outil scanne ce qui est à l'écran et ne navigue pas dans l'application. Ouvrez chaque écran vous-même, puis scannez-le.
- Un scan à la fois, par machine. Le serveur exécute un scan mobile à la fois, et les scans Android utilisent un port local fixe. Utilisez donc un seul serveur de scan mobile par machine.
- Pas de règles avancées ou de tests guidés intelligents. Les deux sont réservés au web uniquement.
- Pas de capture d'écran. Contrairement à
analyze, l'outil ne renvoie pas d'image de l'écran. - Pas de mises à jour de progression pendant la première construction iOS. L'appel reste silencieux jusqu'à ce que WebDriverAgent soit construit et que le scan soit terminé.
- Pas de remédiation mobile. L'outil
remediateaccepte uniquement les problèmes web.
