Ferramenta de Análise Mobile
A ferramenta analyze_mobile examina a tela que está sendo exibida em um dispositivo móvel em busca de problemas de acessibilidade, usando as regras Axe DevTools Mobile. Funciona com um dispositivo Android ou emulador conectado, e com um simulador iOS iniciado ou um iPhone conectado via USB.
analyze_mobile requer uma assinatura Axe DevTools Mobile. Não faz parte dos Planos Gratuitos ou Premium, que cobrem a varredura da web.
O que Faz
- Autenticação - Valida sua credencial Axe DevTools Mobile: seja uma
AXE_MOBILE_API_KEYou um token de acesso OAuth 2.0 para uma conta com direito ao Axe DevTools Mobile - Configuração do Dispositivo - Usa
adb(Android) ouxcodebuild(iOS) em sua máquina para instalar e iniciar o servidor de escaneamento da Deque no dispositivo - Escaneamento de Acessibilidade - Examina a tela que está aberta no dispositivo, usando as regras padrão do Axe DevTools Mobile
- Entrega de Resultados - Retorna violações, verificações incompletas e aprovações, cada uma com detalhes suficientes de localização para que seu agente encontre a visualização no seu código-fonte
Requisitos
A ferramenta aparece no seu cliente MCP apenas quando todos os seguintes critérios forem verdadeiros:
- A distribuição npm. O escaneamento móvel dirige um dispositivo ou simulador conectado à sua máquina, ao qual um contêiner não pode acessar.
- Uma credencial Axe DevTools Mobile. Configure
AXE_MOBILE_API_KEYpara uma chave de API Axe DevTools Mobile do Portal de Contas Axe, ou entre com OAuth 2.0 usando uma conta com direito ao Axe DevTools Mobile. - Os pacotes do scanner, instalado junto ao servidor. Veja Configuração.
Cada plataforma também precisa de ferramentas na máquina que executa o servidor:
| Plataforma | Host | Necessidades |
|---|---|---|
| Android | macOS, Windows, Linux | Android SDK Platform-Tools, com adb no seu PATH. Um dispositivo com depuração USB ativada, ou um emulador rodando. |
| Simulador iOS | apenas macOS | Xcode (não apenas as Ferramentas de Linha de Comando), selecionado com xcode-select. Um simulador iniciado. |
| iPhone (físico) | apenas macOS | Xcode, um iPhone conectado por cabo USB com Modo Desenvolvedor ativado, e uma conta de desenvolvedor Apple para assinar o WebDriverAgent. Veja Escaneando um iPhone físico. |
Configuração
1. Adicione os pacotes do scanner ao seu comando de servidor
A distribuição npm executa o servidor com npx, portanto adicione os pacotes do scanner ao mesmo comando:
@deque/axe-appium3-uiautomator2-serverpara Android@deque/axe-appium3-webdriveragent-assetspara iOS
No macOS, instale ambos, mesmo que você escaneie apenas uma plataforma. No Windows e Linux, instale apenas o pacote Android. O servidor busca ambos na inicialização, e se algum estiver faltando, ele não oferece a ferramenta.
macOS, ambas as plataformas:
{
"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 e Linux, apenas Android:
"args": [
"-y",
"-p",
"axe-mcp-server",
"-p",
"@deque/axe-appium3-uiautomator2-server@^1.7.0",
"axe-mcp-server"
]O exemplo utiliza o formato .mcp.json de Claude Code. Coloque o mesmo args na configuração de seu próprio cliente; consulte o guia de configuração para Claude Code, Cursor ou VS Code com Copilot. Se faltar um pacote, o servidor o nomeia em seu log de inicialização.
2. Defina suas credenciais
Defina uma das seguintes opções:
- Chave de API: Defina
AXE_MOBILE_API_KEYpara um Chave de API do Axe DevTools Mobile do Portal da Conta Axe. - OAuth 2.0: Faça login uma vez com
npx @deque/axe-auth login, usando uma conta habilitada para Axe DevTools Mobile. Em seguida, execute o servidor sob@deque/axe-auth run: coloque os mesmos argumentosnpxdo passo 1 após o--, e não incluaAXE_MOBILE_API_KEY. Veja OAuth 2.0.
Se você também usar as ferramentas web com uma chave de API, configure AXE_API_KEY junto com AXE_MOBILE_API_KEY. Uma chave de API não pode ser combinada com AXE_ACCESS_TOKEN; veja Referência de Configuração.
3. Conecte um dispositivo
Verifique se o dispositivo está visível antes de fazer a varredura:
- Android: Execute
adb devices. Seu dispositivo ou emulador deve estar listado com o estadodevice. Um estado deunauthorizedsignifica que o dispositivo ainda não aceitou o aviso de depuração USB;offlinesignifica queadbnão pode alcançá-lo. - iOS: Execute
xcrun simctl list devices bootedpara ver os simuladores inicializados. Um iPhone físico deve aparecer na janela Dispositivos e Simuladores do Xcode.
4. Execute uma primeira varredura
Abra a tela que deseja escanear, então informe seu agente.
Android:
Scan the screen on my Android emulator for accessibility issuesiOS:
Scan the screen on my iPhone simulator for accessibility issuesPara iOS, seu agente envia o ID do bundle do aplicativo com a varredura. Ele pode consultá-lo em seu projeto Xcode, ou você pode nomeá-lo no comando.
A primeira varredura em iOS compila o WebDriverAgent, o que pode levar até 15 minutos. Varreduras posteriores no mesmo dispositivo são muito mais rápidas.
Parâmetros
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
platform |
Sim | "android" ou "ios" |
bundleId |
Sim (apenas iOS) | O ID do bundle do aplicativo na tela, como com.example.app |
udid |
Não (apenas iOS) | O UDID do simulador ou iPhone a ser escaneado. Quando omitido, o servidor usa o simulador inicializado, ou então o iPhone conectado. |
Escolha um dispositivo Android. Não há parâmetro de dispositivo para Android. Quando um dispositivo ou emulador está pronto, o servidor o escaneia. Quando vários estão prontos, defina ANDROID_SERIAL no ambiente do servidor para a lista serial que adb devices fornece para o que você quer.
Encontre o ID do bundle. É o PRODUCT_BUNDLE_IDENTIFIER em seu projeto Xcode, ou o Info.plist do aplicativo. Informe seu agente onde procurar, ou inclua o ID do bundle no seu comando.
Comande seu agente de IA em linguagem natural. O agente traduz sua intenção em uma chamada de ferramenta:
Scan the app on my iPhone simulator for accessibility issues. The bundle ID
is in ios/MyApp.xcodeproj.O agente resolve o comando e chama analyze_mobile com um payload similar a:
{
"platform": "ios",
"bundleId": "com.example.myapp"
}Resultados
A ferramenta retorna um summary da varredura e três listas de achados: violations, incomplete e passes.
Achados
Cada entrada em violations, incomplete e passes tem os seguintes campos:
| Campo | Descrição |
|---|---|
ruleId |
A regra do Axe DevTools Mobile, como ColorContrast |
summary |
Uma breve descrição da regra |
impact |
Critical, Serious, Moderate, ou Minor |
standard |
O padrão ao qual a regra se corresponde, como WCAG 2.1 |
successCriteria |
O critério de sucesso ao qual a regra se corresponde, como 1.4.3 |
identifier |
O identificador definido pelo desenvolvedor para a visualização: accessibilityIdentifier no iOS, ou o ID de recurso no Android, mostrado como #name, ou null quando a visualização não o possui |
viewPath |
O caminho da raiz da tela até a visualização, como uma lista de nomes de classes, com o identificador de cada visualização entre parênteses quando possui um, como Button(#login_button) |
bounds |
A posição da exibição na tela, como left, top, right, e bottom |
accessibleName |
O nome que a tecnologia assistiva anuncia para a exibição, ou null |
props |
Evidências específicas da regra, como as cores e a proporção medida em uma verificação de contraste, com campos que variam conforme a regra |
identifier e viewPath são como o seu agente encontra a exibição no seu código-fonte. Um identifier é a correspondência mais direta: procure por ele no projeto. Quando uma exibição não tem identificador, viewPath mostra onde ela está, pelo nome da classe e pelos ancestrais mais próximos que tenham um.
Regras
analyze_mobile executa as regras do Axe DevTools Mobile para cada plataforma:
analyze_mobile executa as regras padrão do Axe DevTools Mobile. Ainda não aplica a configuração de regra global móvel da sua organização.
Regras Avançadas e Testes Guiados Inteligentes são apenas para web e não são executados em varreduras móveis.
Escaneando um iPhone Físico
Um iPhone físico precisa de um pouco mais do que um simulador:
- Conecte-o com um cabo USB. Um telefone emparelhado com seu Mac via Wi-Fi não pode ser escaneado.
- Ative o Modo Desenvolvedor em Ajustes > Privacidade e Segurança > Modo Desenvolvedor, em seguida reinicie o telefone.
- Confie no Mac. Desbloqueie o telefone e toque em Confiar quando solicitado.
- Mantenha-o desbloqueado, com a tela ligada, durante a varredura.
- Assine o WebDriverAgent com sua conta de desenvolvedor Apple. O servidor não define uma identidade de assinatura para você. Abra
WebDriverAgent.xcodeprojno Xcode, escolha sua Equipe em Assinatura e Capacidades, e deixe o Xcode criar um perfil de provisionamento.
Quando a assinatura falha, a varredura retorna uma mensagem dizendo o que está faltando, como uma equipe de desenvolvimento ou um perfil de provisionamento.
Resolução de Problemas
Se analyze_mobile não aparecer no seu cliente, verifique Requisitos e o log de inicialização do servidor, que menciona qualquer pacote de scanner ausente. Reinicie a sessão MCP do seu cliente após alterar a configuração.
Para outros problemas, as mensagens de erro do servidor dizem qual é o problema. As que precisam de mais do que a mensagem:
| Mensagem | O que fazer |
|---|---|
AXE_MOBILE_API_KEY is not supported in the Docker distribution |
O servidor se recusa a iniciar no Docker com uma chave móvel. Mude para a distribuição npm. |
No Android device or emulator found, or the device is not ready |
Inicie um emulador ou conecte um dispositivo com depuração USB ativada e aceite o prompt no dispositivo. Verifique adb devices: o estado deve ser device, não unauthorized ou offline. |
More than one Android device is ready |
Defina ANDROID_SERIAL para o número de série do dispositivo a ser escaneado, ou desconecte os outros. |
The device named by ANDROID_SERIAL is not ready |
Compare ANDROID_SERIAL com a coluna da esquerda de adb devices. |
An iOS scan needs the bundleId of the app on screen |
Inclua o ID do pacote em seu prompt, ou diga ao seu agente onde encontrá-lo. |
xcodebuild not found |
Instale o Xcode pela App Store. Se ele já estiver instalado, selecione-o: sudo xcode-select -s /Applications/Xcode.app. Somente as Ferramentas de Linha de Comando não são suficientes. |
The iPhone is not connected by USB |
Um telefone emparelhado via Wi-Fi não pode ser escaneado. Conecte-o com um cabo USB. |
Code signing failed: … |
Assine o WebDriverAgent com sua conta de desenvolvedor Apple. Veja Escaneando um iPhone físico. |
The device has Developer Mode disabled / has not trusted this Mac / appears to be locked |
Siga os passos em Escaneando um iPhone físico. |
The on-device scan server did not start within …ms |
Aumente MOBILE_SERVER_READY_TIMEOUT_MS e tente novamente. |
This account does not have an active axe DevTools Mobile subscription |
Peça ao administrador da sua conta para adicionar uma assinatura do Axe DevTools Mobile, depois inicie uma nova sessão. |
This API key belongs to a different product |
Certifique-se de que AXE_MOBILE_API_KEY contenha uma chave do Axe DevTools Mobile e AXE_API_KEY contenha uma chave web, depois inicie uma nova sessão. |
`analyze` needs a web credential (ou remediate, igt) |
Somente AXE_MOBILE_API_KEY está configurado, o que não autoriza as ferramentas web. Adicione AXE_API_KEY, ou mude para OAuth e remova AXE_MOBILE_API_KEY, depois inicie uma nova sessão. |
Para qualquer outra falha, configure LOG_LEVEL=debug no ambiente do servidor. Para uma falha de construção do iOS, o log de depuração inclui a saída do próprio Xcode. Veja também a página geral de Resolução de Problemas.
Limitações
- Uma tela por chamada. A ferramenta analisa o que está na tela e não navega no aplicativo. Abra cada tela você mesmo, depois faça a análise.
- Uma análise de cada vez, por máquina. O servidor realiza uma análise móvel de cada vez, e as análises Android usam uma porta local fixa, portanto, execute apenas um servidor de análise móvel por máquina.
- Sem Regras Avançadas ou Testes Guiados Inteligentes. Ambos são exclusivos para a web.
- Sem captura de tela. Ao contrário de
analyze, a ferramenta não retorna uma imagem da tela. - Sem atualizações de progresso durante a primeira compilação iOS. A chamada permanece silenciosa até que o WebDriverAgent seja compilado e a análise termine.
- Sem remediação móvel. A ferramenta
remediateaceita apenas problemas na web.
