Analizar Herramienta Móvil

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

La herramienta analyze_mobile escanea la pantalla que se muestra actualmente en un dispositivo móvil para detectar problemas de accesibilidad, utilizando las reglas de Axe DevTools Móvil. Funciona con un dispositivo Android conectado o un emulador, y con un simulador de iOS iniciado o un iPhone conectado por USB.

note

analyze_mobile necesita una suscripción Axe DevTools Móvil. No forma parte de los Planes Gratuitos o Premium, que cubren el escaneo web.

Qué Hace

  1. Autenticación - Valida tu credencial de Axe DevTools Móvil: ya sea una AXE_MOBILE_API_KEY o un token de acceso OAuth 2.0 para una cuenta con derecho a Axe DevTools Móvil
  2. Configuración del Dispositivo - Utiliza adb (Android) o xcodebuild (iOS) en tu máquina para instalar y empezar el servidor de escaneo de Deque en el dispositivo
  3. Escaneo de Accesibilidad - Escanea la pantalla que está abierta en el dispositivo, utilizando las reglas predeterminadas de Axe DevTools Móvil
  4. Entrega de Resultados - Devuelve violaciones, verificaciones incompletas y aprobaciones, cada una con suficiente detalle de ubicación para que tu agente pueda encontrar la vista en tu código fuente

Requisitos

La herramienta aparece en tu cliente MCP solo cuando todo lo siguiente es verdadero:

  • La distribución de npm. El escaneo móvil maneja un dispositivo o simulador conectado a tu máquina, al que un contenedor no puede acceder.
  • Una credencial de Axe DevTools Móvil. Configura AXE_MOBILE_API_KEY a una clave de API de Axe DevTools Móvil desde el Portal de Cuentas de Axe, o inicia sesión con OAuth 2.0 usando una cuenta con derecho a Axe DevTools Móvil.
  • Los paquetes de escaneo, instalados junto al servidor. Ver Configuración.

Cada plataforma también necesita herramientas en la máquina que ejecuta el servidor:

Plataforma Host Necesidades
Android macOS, Windows, Linux Android SDK Platform-Tools, con adb en tu PATH. Un dispositivo con depuración USB activada o un emulador en funcionamiento.
Simulador de iOS solo macOS Xcode (no solo las herramientas de línea de comandos), seleccionado con xcode-select. Un simulador iniciado.
iPhone (físico) solo macOS Xcode, un iPhone conectado por cable USB con el Modo de Desarrollador activado, y una cuenta de desarrollador de Apple para firmar WebDriverAgent. Ver Escaneo de un iPhone físico.

Configuración

1. Agrega los paquetes de escaneo a tu comando del servidor

La distribución de npm ejecuta el servidor con npx, así que añade los paquetes de escaneo al mismo comando:

  • @deque/axe-appium3-uiautomator2-server para Android
  • @deque/axe-appium3-webdriveragent-assets para iOS

En macOS, instala ambos, incluso si solo escaneas una plataforma. En Windows y Linux, instala solo el paquete de Android. El servidor busca ambos al iniciar, y si falta alguno no ofrece la herramienta.

macOS, ambas 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 y Linux, solo Android:

"args": [
  "-y",
  "-p",
  "axe-mcp-server",
  "-p",
  "@deque/axe-appium3-uiautomator2-server@^1.7.0",
  "axe-mcp-server"
]

El ejemplo utiliza el formato de .mcp.json de Claude Code. Pon el mismo args en la configuración de tu propio cliente; consulta la guía de configuración para Claude Code, Cursor o VS Code con Copilot. Si falta un paquete, el servidor lo nombra en su registro de inicio.

2. Configura tu credencial

Configura una de las siguientes:

  • Clave API: Configura AXE_MOBILE_API_KEY a un clave API de Axe DevTools Mobile desde el Portal de Cuentas de Axe.
  • OAuth 2.0: Inicia sesión una vez con npx @deque/axe-auth login, usando una cuenta con acceso a Axe DevTools Mobile. Luego ejecuta el servidor bajo @deque/axe-auth run: pon los mismos argumentos npx del paso 1 después del -- y omite AXE_MOBILE_API_KEY. Consulta OAuth 2.0.

Si también usas las herramientas web con una clave API, configura AXE_API_KEY junto con AXE_MOBILE_API_KEY. Una clave API no puede combinarse con AXE_ACCESS_TOKEN; consulta Referencia de configuración.

3. Conecta un dispositivo

Verifica que el dispositivo sea visible antes de escanear:

  • Android: Ejecuta adb devices. Tu dispositivo o emulador debe aparecer en la lista con el estado device. Un estado de unauthorized significa que el dispositivo aún no ha aceptado el aviso de depuración USB; offline significa que adb no puede alcanzarlo.
  • iOS: Ejecuta xcrun simctl list devices booted para ver simuladores iniciados. Un iPhone físico debería aparecer en la ventana Dispositivos y simuladores de Xcode.

4. Realiza un primer escaneo

Abre la pantalla que deseas escanear y luego avisa a tu agente.

Android:

Scan the screen on my Android emulator for accessibility issues

iOS:

Scan the screen on my iPhone simulator for accessibility issues

Para iOS, tu agente envía el ID del paquete de la aplicación con el escaneo. Puede buscarlo en tu proyecto de Xcode, o puedes nombrarlo en el aviso.

tip

El primer escaneo de iOS construye WebDriverAgent, lo que puede tardar hasta 15 minutos. Escaneos posteriores en el mismo dispositivo son mucho más rápidos.

Parámetros

Parámetro Requerido Descripción
platform Sí "android" o "ios"
bundleId Sí (solo iOS) El ID del paquete de la aplicación en la pantalla, como com.example.app
udid No (solo iOS) El UDID del simulador o iPhone para escanear. Cuando se omite, el servidor utiliza el simulador iniciado o el iPhone conectado.

Elige un dispositivo Android. No hay un parámetro de dispositivo para Android. Cuando un dispositivo o emulador está listo, el servidor lo escanea. Cuando varios están listos, configura ANDROID_SERIAL en el entorno del servidor con el serial que adb devices lista para el que deseas.

Encuentra el ID del paquete. Es el PRODUCT_BUNDLE_IDENTIFIER en tu proyecto de Xcode, o el Info.plist de la aplicación. Indica a tu agente dónde buscar, o incluye el ID del paquete en tu aviso.

Indica a tu agente de IA en lenguaje natural. El agente traduce tu intención en la llamada a la herramienta:

Scan the app on my iPhone simulator for accessibility issues. The bundle ID
is in ios/MyApp.xcodeproj.

El agente resuelve el aviso y llama a analyze_mobile con una carga similar a:

{
  "platform": "ios",
  "bundleId": "com.example.myapp"
}

Resultados

La herramienta devuelve un summary del escaneo y tres listas de hallazgos: violations, incomplete y passes.

Hallazgos

Cada entrada en violations, incomplete y passes tiene estos campos:

Campo Descripción
ruleId La regla de Axe DevTools Mobile, como ColorContrast
summary Una breve descripción de la regla
impact Critical, Serious, Moderate o Minor
standard El estándar al que mapea la regla, como WCAG 2.1
successCriteria El criterio de éxito al que mapea la regla, como 1.4.3
identifier El identificador establecido por el desarrollador de la vista: accessibilityIdentifier en iOS, o el ID de recurso en Android, mostrado como #name, o null cuando la vista no tiene ninguno
viewPath La ruta desde la raíz de la pantalla hasta la vista, como una lista de nombres de clase, con el identificador de cada vista entre paréntesis cuando tiene uno, tal como Button(#login_button)
bounds La posición de la vista en la pantalla, como left, top, right y bottom
accessibleName El nombre que la tecnología de asistencia anuncia para la vista, o null
props Evidencia específica de la regla, como los colores y la proporción medida en una verificación de contraste, con campos que varían según la regla

identifier y viewPath son cómo tu agente encuentra la vista en tu código fuente. Un identifier es la coincidencia más directa: búscalo en el proyecto. Cuando una vista no tiene identificador, viewPath muestra dónde se ubica, por nombre de clase y por los ancestros más cercanos que sí tienen uno.

Reglas

analyze_mobile ejecuta las reglas de Axe DevTools Mobile para cada plataforma:

analyze_mobile ejecuta las reglas predeterminadas de Axe DevTools Mobile. Aún no aplica la configuración global de reglas móvil de tu organización.

Las Reglas Avanzadas y las Pruebas Guiadas Intelligentes son solo para web y no se ejecutan en escaneos móviles.

Escanear un iPhone Físico

Un iPhone físico necesita un poco más que un simulador:

  • Conéctalo con un cable USB. Un teléfono emparejado con tu Mac por Wi-Fi no puede ser escaneado.
  • Activa el Modo Desarrollador bajo Configuración > Privacidad y Seguridad > Modo Desarrollador, luego reinicia el teléfono.
  • Confía en el Mac. Desbloquea el teléfono y toca Confiar cuando lo pida.
  • Mantenlo desbloqueado, con la pantalla encendida, mientras escaneas.
  • Firma WebDriverAgent con tu cuenta de desarrollador de Apple. El servidor no establece una identidad de firma para ti. Abre WebDriverAgent.xcodeproj en Xcode, elige tu Equipo bajo Firma y Capacidades y permite que Xcode cree un perfil de aprovisionamiento.

Cuando la firma falla, el escaneo devuelve un mensaje que dice qué falta, como un equipo de desarrollo o un perfil de aprovisionamiento.

Solución de problemas

Si analyze_mobile no aparece en tu cliente, revisa Requisitos y el registro de inicio del servidor, que nombra cualquier paquete de escáner faltante. Reinicia la sesión MCP de tu cliente después de cambiar la configuración.

Para otros problemas, los mensajes de error del servidor indican qué está mal. Los que necesitan más que el mensaje:

Mensaje Qué hacer
AXE_MOBILE_API_KEY is not supported in the Docker distribution El servidor se niega a iniciarse en Docker con una clave móvil. Cambia a la distribución npm.
No Android device or emulator found, or the device is not ready Inicia un emulador, o conecta un dispositivo con depuración USB activada y acepta el aviso en el dispositivo. Verifica adb devices: el estado debería ser device, no unauthorized o offline.
More than one Android device is ready Configura ANDROID_SERIAL al número de serie del dispositivo para escanear, o desconecta los otros.
The device named by ANDROID_SERIAL is not ready Compara ANDROID_SERIAL con la columna izquierda de adb devices.
An iOS scan needs the bundleId of the app on screen Incluye el ID del paquete en tu aviso, o dile a tu agente dónde encontrarlo.
xcodebuild not found Instala Xcode desde la App Store. Si está instalado, selecciónalo: sudo xcode-select -s /Applications/Xcode.app. Las herramientas de línea de comandos por sí solas no son suficientes.
The iPhone is not connected by USB Un teléfono emparejado por Wi-Fi no puede ser escaneado. Conéctalo con un cable USB.
Code signing failed: … Firma WebDriverAgent con tu cuenta de desarrollador de Apple. Ver Escaneo de un iPhone físico.
The device has Developer Mode disabled / has not trusted this Mac / appears to be locked Sigue los pasos en Escaneo de un iPhone físico.
The on-device scan server did not start within …ms Aumenta MOBILE_SERVER_READY_TIMEOUT_MS y prueba de nuevo.
This account does not have an active axe DevTools Mobile subscription Pide a tu administrador de cuenta que agregue una suscripción de Axe DevTools Mobile, luego inicia una nueva sesión.
This API key belongs to a different product Asegúrate de que AXE_MOBILE_API_KEY tenga una clave de Axe DevTools Mobile y AXE_API_KEY tenga una clave web, luego inicia una nueva sesión.
`analyze` needs a web credential (o remediate, igt) Solo AXE_MOBILE_API_KEY está configurado, lo que no autoriza las herramientas web. Agrega AXE_API_KEY, o cambia a OAuth y elimina AXE_MOBILE_API_KEY, luego inicia una nueva sesión.

Para cualquier otro fallo, configura LOG_LEVEL=debug en el entorno del servidor. Para un fallo de compilación de iOS, el registro de depuración incluye la propia salida de Xcode. Consulta también la página general Solución de problemas.

Limitaciones

  • Una pantalla por llamada. La herramienta escanea lo que está en pantalla y no navega por la aplicación. Abre cada pantalla tú mismo y luego escanéala.
  • Un escaneo a la vez, por máquina. El servidor ejecuta un escaneo móvil a la vez, y los escaneos de Android utilizan un puerto local fijo, por lo que ejecuta solo un servidor de escaneo móvil por máquina.
  • Sin Reglas Avanzadas o Pruebas Guiadas Inteligentes. Ambos son solo para la web.
  • Sin captura de pantalla. A diferencia de analyze, la herramienta no devuelve una imagen de la pantalla.
  • Sin actualizaciones de progreso durante la primera compilación de iOS. La llamada permanece en silencio hasta que WebDriverAgent se construya y el escaneo termine.
  • Sin corrección móvil. La herramienta remediate solo acepta problemas web.