Analyse Mobile Tool
De analyze_mobile tool scant het scherm dat momenteel op een mobiel apparaat wordt weergegeven op toegankelijkheidsproblemen, met gebruik van Axe DevTools Mobile regels. Het werkt met een verbonden Android-apparaat of emulator, en met een opgestarte iOS-simulator of een via USB verbonden iPhone.
analyze_mobile vereist een Axe DevTools Mobile abonnement. Het maakt geen deel uit van de Gratis of Premium abonnementen, die webscanning dekken.
Wat het doet
- Authenticatie - Valideert je Axe DevTools Mobile-referentie: ofwel een
AXE_MOBILE_API_KEYof een OAuth 2.0 toegangstoken voor een account met recht op Axe DevTools Mobile - Apparaatconfiguratie - Gebruikt
adb(Android) ofxcodebuild(iOS) op je machine om Deque's scanserver op het apparaat te installeren en te starten - Toegankelijkheidsscan - Scant het scherm dat openstaat op het apparaat, met gebruik van de standaard Axe DevTools Mobile-regels
- Resultaatlevering - Levert overtredingen, onvolledige controles en goedgekeurde checks, elk met voldoende locatiedetails zodat je agent de weergave in je broncode kan vinden
Vereisten
De tool verschijnt in je MCP-client alleen wanneer aan al de volgende voorwaarden is voldaan:
- De npm-distributie. Mobiele scanning bestuurt een apparaat of simulator verbonden met je machine, dat een container niet kan bereiken.
- Een Axe DevTools Mobile-referentie. Stel
AXE_MOBILE_API_KEYin op een Axe DevTools Mobile API-sleutel van het Axe Account Portal, of log in met OAuth 2.0 met een account met recht op Axe DevTools Mobile. - De scannerpakketten, geïnstalleerd naast de server. Zie Installatie.
Elke platform heeft ook tools nodig op de machine die de server uitvoert:
| Platform | Host | Benodigdheden |
|---|---|---|
| Android | macOS, Windows, Linux | Android SDK Platform-Tools, met adb op je PATH. Een apparaat met USB-debugging ingeschakeld, of een draaiende emulator. |
| iOS-simulator | alleen macOS | Xcode (niet alleen de Command Line Tools), geselecteerd met xcode-select. Een opgestarte simulator. |
| iPhone (fysiek) | alleen macOS | Xcode, een iPhone aangesloten via USB-kabel met Ontwikkelaarsmodus aan, en een Apple-ontwikkelaarsaccount om WebDriverAgent te ondertekenen. Zie Een fysieke iPhone scannen. |
Installatie
1. Voeg de scannerpakketten toe aan je servercommando
De npm-distributie start de server met npx, dus voeg de scannerpakketten toe aan hetzelfde commando:
@deque/axe-appium3-uiautomator2-servervoor Android@deque/axe-appium3-webdriveragent-assetsvoor iOS
Op macOS, installeer beide, zelfs als je slechts één platform scant. Op Windows en Linux, installeer alleen het Android-pakket. De server zoekt beide bij het opstarten, en als een van beide ontbreekt, biedt het de tool niet aan.
macOS, beide platforms:
{
"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 en Linux, alleen Android:
"args": [
"-y",
"-p",
"axe-mcp-server",
"-p",
"@deque/axe-appium3-uiautomator2-server@^1.7.0",
"axe-mcp-server"
]Het voorbeeld maakt gebruik van het formaat van Claude Code's .mcp.json. Plaats dezelfde args in de configuratie van uw eigen cliënt; zie de installatiewijzer voor Claude Code, Cursor of VS Code met Copilot. Als er een pakket ontbreekt, meldt de server dit in zijn opstartlogboeken.
2. Stel uw legitimatiebewijs in
Stel één van het volgende in:
- API-sleutel: Stel
AXE_MOBILE_API_KEYin op een Axe DevTools Mobile API-sleutel uit het Axe Account Portal. - OAuth 2.0: Meld u één keer aan met
npx @deque/axe-auth login, met een account dat recht heeft op Axe DevTools Mobile. Voer vervolgens de server uit onder@deque/axe-auth run: plaats dezelfdenpxargumenten van stap 1 na de--en laatAXE_MOBILE_API_KEYweg. Zie OAuth 2.0.
Als u ook de webtools gebruikt met een API-sleutel, stel dan AXE_API_KEY in naast AXE_MOBILE_API_KEY. Een API-sleutel kan niet worden gecombineerd met AXE_ACCESS_TOKEN; zie Configuratiereferentie.
3. Verbind een apparaat
Controleer of het apparaat zichtbaar is voordat u scant:
- Android: Voer
adb devicesuit. Uw apparaat of emulator moet worden weergegeven met de statusdevice. Een status vanunauthorizedbetekent dat het apparaat de USB-debuggingprompt nog niet heeft geaccepteerd;offlinebetekent datadbhet niet kan bereiken. - iOS: Voer
xcrun simctl list devices booteduit om opgestarte simulators te zien. Een fysieke iPhone zou moeten verschijnen in het Apparaten en Simulators-venster van Xcode.
4. Voer een eerste scan uit
Open het scherm dat u wilt scannen en instrueer vervolgens uw agent.
Android:
Scan the screen on my Android emulator for accessibility issuesiOS:
Scan the screen on my iPhone simulator for accessibility issuesVoor iOS stuurt uw agent de bundel-ID van de app mee met de scan. Deze kan opgezocht worden in uw Xcode-project, of u kunt deze benoemen in de prompt.
De eerste iOS-scan bouwt WebDriverAgent, wat tot 15 minuten kan duren. Latere scans op hetzelfde apparaat zijn veel sneller.
Parameters
| Parameter | Vereist | Beschrijving |
|---|---|---|
platform |
Ja | "android" of "ios" |
bundleId |
Ja (alleen iOS) | De bundel-ID van de app op het scherm, zoals com.example.app |
udid |
Nee (alleen iOS) | De UDID van de simulator of iPhone om te scannen. Als deze wordt weggelaten, gebruikt de server de opgestarte simulator of anders de aangesloten iPhone. |
Kies een Android-apparaat. Er is geen apparaatparameter voor Android. Wanneer één apparaat of emulator gereed is, scant de server het. Wanneer er meerdere klaar zijn, stel ANDROID_SERIAL in de omgeving van de server in op het serienummer dat adb devices oplijst voor degene die u wilt.
Vind de bundel-ID. Het is de PRODUCT_BUNDLE_IDENTIFIER in uw Xcode-project, of de Info.plist van de app. Vertel uw agent waar te kijken, of geef de bundel-ID op in uw prompt.
Geef uw AI-agent een opdracht in natuurlijke taal. De agent zet uw intentie om in de toolaanroep:
Scan the app on my iPhone simulator for accessibility issues. The bundle ID
is in ios/MyApp.xcodeproj.De agent verwerkt de prompt en roept analyze_mobile aan met een payload gelijk aan:
{
"platform": "ios",
"bundleId": "com.example.myapp"
}Resultaten
De tool retourneert een summary van de scan en drie lijsten met bevindingen: violations, incomplete en passes.
Bevindingen
Elk item in violations, incomplete en passes heeft de volgende velden:
| Veld | Beschrijving |
|---|---|
ruleId |
De Axe DevTools Mobile-regel, zoals ColorContrast |
summary |
Een korte beschrijving van de regel |
impact |
Critical, Serious, Moderate of Minor |
standard |
De standaard waarnaar de regel verwijst, zoals WCAG 2.1 |
successCriteria |
Het succescriterium waarnaar de regel verwijst, zoals 1.4.3 |
identifier |
De door de ontwikkelaar ingestelde ID van de weergave: accessibilityIdentifier op iOS, of de resource-ID op Android, getoond als #name, of null wanneer de weergave er geen heeft |
viewPath |
Het pad van de wortel van het scherm naar de weergave, als een lijst van klassenamen, met elke ID van de weergave tussen haakjes als het er een heeft, zoals Button(#login_button) |
bounds |
De positie van de weergave op het scherm, als left, top, right en bottom |
accessibleName |
De naam die assistieve technologie aankondigt voor de weergave, of null |
props |
Regelspecifiek bewijsmateriaal, zoals de kleuren en verhouding die een contrastcontrole heeft gemeten, met velden die per regel variëren |
identifier en viewPath zijn hoe je agent de weergave vindt in je broncode. Een identifier is de meest directe match: doorzoek het project ernaar. Als een weergave geen identificatie heeft, laat viewPath zien waar het zich bevindt, op basis van de naam van de klasse en de dichtstbijzijnde voorouders die er wel een hebben.
Regels
analyze_mobile voert de Axe DevTools Mobile-regels uit voor elk platform:
analyze_mobile voert de standaard Axe DevTools Mobile-regels uit. Het past de mobiele globale regelconfiguratie van je organisatie nog niet toe.
Geavanceerde Regels en Intelligent Guided Tests zijn uitsluitend voor het web en worden niet uitgevoerd in mobiele scans.
Een fysieke iPhone scannen
Een fysieke iPhone heeft iets meer nodig dan een simulator:
- Verbind hem met een USB-kabel. Een telefoon gekoppeld met je Mac via Wi-Fi kan niet worden gescand.
- Schakel de Ontwikkelaarsmodus in onder Instellingen > Privacy & Beveiliging > Ontwikkelaarsmodus, en herstart dan de telefoon.
- Vertrouw de Mac. Ontgrendel de telefoon en tik op Vertrouw wanneer daarom wordt gevraagd.
- Laat hem ontgrendeld, met het scherm aan, tijdens het scannen.
- Onderteken de WebDriverAgent met je Apple-ontwikkelaarsaccount. De server stelt geen ondertekeningsidentiteit voor je in. Open
WebDriverAgent.xcodeprojin Xcode, kies je Team onder Ondertekening & Mogelijkheden, en laat Xcode een provisioning profile aanmaken.
Wanneer het ondertekenen mislukt, geeft de scan een bericht met wat er ontbreekt, zoals een ontwikkelaarsteam of een provisioning profile.
Probleemoplossing
Als analyze_mobile niet verschijnt in je client, controleer Vereisten en het opstartlogboek van de server, dat elke ontbrekende scannerpakketnaam vermeldt. Herstart de MCP-sessie van je client nadat je de configuratie hebt gewijzigd.
Voor andere problemen, geven de foutmeldingen van de server aan wat er mis is. De fouten die meer nodig hebben dan het bericht:
| Bericht | Wat te doen |
|---|---|
AXE_MOBILE_API_KEY is not supported in the Docker distribution |
De server weigert te starten in Docker met een mobiele sleutel. Schakel over naar de npm-distributie. |
No Android device or emulator found, or the device is not ready |
Start een emulator, of verbind een apparaat met USB-debugging ingeschakeld en accepteer de prompt op het apparaat. Controleer adb devices: de status moet device zijn, niet unauthorized of offline. |
More than one Android device is ready |
Stel ANDROID_SERIAL in op het serienummer van het apparaat dat gescand moet worden, of ontkoppel de anderen. |
The device named by ANDROID_SERIAL is not ready |
Vergelijk ANDROID_SERIAL met de linker kolom van adb devices. |
An iOS scan needs the bundleId of the app on screen |
Voeg de bundel-ID toe aan je prompt, of laat je agent weten waar die te vinden is. |
xcodebuild not found |
Installeer Xcode vanuit de App Store. Als het geïnstalleerd is, selecteer het: sudo xcode-select -s /Applications/Xcode.app. De Command Line Tools alleen zijn niet voldoende. |
The iPhone is not connected by USB |
Een telefoon gekoppeld via Wi-Fi kan niet worden gescand. Verbind hem met een USB-kabel. |
Code signing failed: … |
Onderteken de WebDriverAgent met je Apple-ontwikkelaarsaccount. Zie Een fysieke iPhone scannen. |
The device has Developer Mode disabled / has not trusted this Mac / appears to be locked |
Volg de stappen in Een fysieke iPhone scannen. |
The on-device scan server did not start within …ms |
Verhoog MOBILE_SERVER_READY_TIMEOUT_MS en probeer het opnieuw. |
This account does not have an active axe DevTools Mobile subscription |
Vraag je accountbeheerder om een Axe DevTools Mobile-abonnement toe te voegen en begin dan een nieuwe sessie. |
This API key belongs to a different product |
Zorg ervoor dat AXE_MOBILE_API_KEY een Axe DevTools Mobile-sleutel heeft en AXE_API_KEY een websleutel, en start dan een nieuwe sessie. |
`analyze` needs a web credential (of remediate, igt) |
Alleen AXE_MOBILE_API_KEY is ingesteld, wat de webtools niet autoriseert. Voeg AXE_API_KEY toe, of schakel over naar OAuth en verwijder AXE_MOBILE_API_KEY, en start vervolgens een nieuwe sessie. |
Voor elke andere fout, stel LOG_LEVEL=debug in de omgeving van de server in. Voor een iOS-buildfout bevat het foutopsporingslogbestand de eigen output van Xcode. Zie ook de algemene Probleemoplossing-pagina.
Beperkingen
- Eén scherm per oproep. De tool scant wat er op het scherm staat en navigeert niet door de app. Open elk scherm zelf en scan het vervolgens.
- Eén scan tegelijk, per machine. De server voert één mobiele scan tegelijk uit, en Android-scans gebruiken een vaste lokale poort, daarom moet er per machine slechts één server voor mobieletelefoonscans draaien.
- Geen geavanceerde regels of intelligente begeleide tests. Beide zijn alleen voor het web.
- Geen screenshot. In tegenstelling tot
analyzegeeft de tool geen afbeelding van het scherm terug. - Geen voortgangsupdates tijdens de eerste iOS-build. De oproep blijft stil totdat WebDriverAgent is gebouwd en de scan is voltooid.
- Geen mobiele oplossingen. De
remediatetool accepteert alleen webproblemen.
