axe MCP Server

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

Descripción general

El Servidor axe MCP es un servidor del Protocolo de Contexto de Modelo (MCP) que integra pruebas de accesibilidad de nivel empresarial directamente en su flujo de trabajo de desarrollo. Construido sobre la confiable plataforma axe, permite a los desarrolladores realizar escaneos de accesibilidad completos y recibir orientación experta en remediación sin salir de su IDE.

El servidor proporciona tres capacidades - analyze, remediate, y igt.

Estas herramientas se integran sin problemas con clientes compatibles con MCP (como Claude Desktop, VS Code con Copilot o Cursor) y respetan la configuración de axe de su organización.

Obteniendo acceso

El Servidor axe MCP está incluido en el paquete Axe DevTools para Web paquete. Una suscripción que habilita el acceso al servidor axe MCP se configura hablando con un representante de ventas de Deque.

Herramientas y capacidades

La analyze Herramienta

La analyze herramienta realiza un análisis de accesibilidad completo en páginas web ejecutando un escaneo a través de la extensión del navegador axe DevTools en un entorno de navegador real. Funciona perfectamente con URLs de desarrollo local (por ejemplo, localhost:3000) y URLs de producción remota.

Qué Hace

  1. Autenticación - Valida las credenciales del usuario (ya sea una clave API o un token de acceso OAuth 2.0) para asegurar el acceso autorizado
  2. Recuperación de configuración - Obtiene la configuración de axe específica de la organización del usuario, incluyendo:
    • Estándar de pruebas de accesibilidad (por ejemplo, WCAG 2.2 AA)
    • versión de axe-core
    • Necesita revisión / mejores prácticas
  3. Análisis basado en navegador - Inicia una instancia de navegador en segundo plano con la extensión axe DevTools montada
  4. Navegación de la página - Navega a la URL proporcionada por el usuario en su solicitud al agente de IA
  5. Escaneo de accesibilidad - Ejecuta un análisis de accesibilidad completo en la página renderizada usando la extensión del navegador axe DevTools, asegurando que se pruebe la experiencia real del usuario (no solo el HTML estático)
  6. Entrega de resultados - Devuelve resultados de análisis completos al agente en un formato estructurado

Pruebas de respuesta

La analyze herramienta admite parámetros opcionales viewportWidth y viewportHeight , lo que le permite probar páginas en dimensiones específicas de visualización. Esto es útil para detectar problemas de accesibilidad que solo aparecen en ciertos tamaños de pantalla, como puntos de ruptura de móviles o tablets.

Analyze http://localhost:3000 for accessibility issues at a mobile viewport of 375x812

Cuando se omiten estos parámetros, el navegador usa su tamaño de visualización predeterminado.

Escaneos Parciales de Página

Por defecto, la analyze herramienta escanea toda la página. Para delimitar el escaneo a una región específica, pase el selector parámetro opcional — útil para centrar la atención en un único componente o excluir partes ruidosas y no relacionadas de la página de los resultados.

  • Una única cadena de selector CSS apunta a un elemento en el marco superior:

    {
  "url": "http://localhost:3000",
  "selector": "#main"
}

  • Una matriz de selectores CSS atraviesa los límites de iframe o shadow-DOM — cada segmento selecciona el anfitrión para el siguiente. Use una matriz solo cuando el objetivo esté dentro de un iframe o raíz de sombra:

    {
  "url": "http://localhost:3000",
  "selector": ["iframe#checkout", "#payment-form"]
}

Una matriz admite hasta 10 segmentos. Si el selector no coincide con ningún elemento en la página, el escaneo devuelve un error. Cuando selector se omite, se escanea toda la página.

Solicite a su agente de IA en lenguaje natural — el agente traduce su intención en la llamada a la herramienta:

Scan only the #main region of http://localhost:3000 for accessibility issues

Interacciones del navegador antes del escaneo

La analyze herramienta admite una matriz opcional de before pasos de interacción que se ejecutan después de que la página se carga pero antes del escaneo de accesibilidad. Esto desbloquea varios escenarios de prueba en el mundo real:

  • Páginas protegidas por inicio de sesión — complete las credenciales y envíe antes de escanear la página posterior al inicio de sesión
  • Banners de cookies/consentimiento — cierre los banners que de otro modo sobrepondrían o ocultarían el contenido de la página
  • Contenido dinámico — espere a que aparezca contenido renderizado por el cliente (cambios de ruta, DOM inyectado tardíamente) antes de escanear

Los pasos se ejecutan en el orden del array, en el mismo contexto del navegador que el escaneo, por lo que las cookies, localStorage, y cualquier cambio de ruta desencadenado por click o fill persisten en el escaneo.

La before array admite hasta 20 pasos. Cada paso tiene su propio tiempo de espera de BROWSER_TIMEOUT_MS (por defecto 30000 ms); no hay anulación por paso.

Acciones Soportadas
Acción Campos requeridos Campos opcionales Propósito
click selector Haga clic en el elemento que coincide con el CSS selector (por ejemplo, un botón de envío, un botón de "Cerrar" en un banner).
fill selector, value Rellene una entrada que coincida con selector con value. Úselo para credenciales, consultas de búsqueda o campos de formulario. Una cadena vacía borra la entrada.
waitFor selector state — uno de "visible" (por defecto), "attached", "hidden", "detached" Espere a que el elemento que coincide con selector alcance state. Úselo para controlar el siguiente paso o el escaneo en sí. Elija un selector que exista únicamente en el estado posterior a la interacción (por ejemplo, un botón de cerrar sesión o un encabezado de dashboard) — los selectores genéricos como body o #app ya existen antes de la interacción y se resuelven instantáneamente, por lo que no controlarán nada.
Ejemplo: Iniciar sesión antes de escanear

Solicite a su agente de IA en lenguaje natural — el agente traduce su intención en la llamada a la herramienta:

Analyze http://localhost:3000 for accessibility issues. Before running
the analysis, fill in the #username and #password fields with USERNAME
and PASSWORD from ./.env.local, click the button[type=submit] button,
and wait for #main-content to appear.

El agente resuelve la solicitud y llama a la analyze herramienta con una carga útil similar a:

{
  "url": "http://localhost:3000",
  "before": [
    {
      "action": "fill",
      "selector": "#username",
      "value": "<resolved-from-.env.local>"
    },
    {
      "action": "fill",
      "selector": "#password",
      "value": "<resolved-from-.env.local>"
    },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}
important

fill.value se trata como sensible. El servidor axe MCP nunca registra fill.value, nunca lo muestra en mensajes de error, y nunca lo envía a telemetría. Use fill para cualquier entrada proporcionada por el usuario o secreta (contraseñas, tokens de API, etc.) para que los secretos permanezcan redactados en todo el proceso — y nunca incruste valores sensibles en un selector, el cual aparecen en registros y mensajes de error.

note

El agente resuelve value, no el servidor. El servidor axe MCP trata value como una cadena literal — no lee archivos, expande variables de entorno, o interpreta sintaxis de marcador de posición como ${VAR}, $VAR, o {{VAR}}. Tu agente de IA (Claude, Copilot, Cursor, etc.) es responsable de resolver la intención del usuario en una cadena concreta antes de llamar a la herramienta.

En la práctica, esto significa:

  • Formula sugerencias naturalmente — "usa USUARIO/CONTRASEÑA de .env.local" funciona. El agente lee el archivo con sus propias herramientas del sistema de archivos y sustituye los valores.
  • No pegues sintaxis de marcador de posición — escribir value: "${USERNAME}" en una sugerencia hará que la cadena literal ${USERNAME} sea escrita en la entrada.
  • Sé explícito sobre fuentes ambiguas — si dices "usa mis credenciales guardadas" sin señalar al agente un archivo o variable de entorno, un agente bien educado preguntará en lugar de adivinar. Indícale dónde buscar.
caution

Algunos flujos de autenticación no están soportados. before acciones controlan la página a través de interacciones al estilo Playwright en una instancia de Chromium con Docker. Las siguientes están intencionalmente fuera del alcance:

  • Desafíos de Captcha (reCAPTCHA, hCaptcha, etc.)
  • Verificación de 2FA / TOTP / SMS códigos de verificación
  • Cadenas de redirección de SSO de terceros (por ejemplo, "Iniciar sesión con Google", páginas de inicio de sesión alojadas en Okta)

Cuando tu flujo de inicio de sesión real requiere cualquiera de los anteriores, escanea un punto de entrada alternativo:

  • Una cookie de sesión preautenticada integrada en un entorno de pruebas
  • Una token de sesión o URL de derivación que tu equipo utiliza para pruebas automatizadas
  • Una URL de prueba con autenticación deshabilitada para pruebas de accesibilidad

Beneficios clave

  • Pruebas en navegador real - Prueba la página realmente renderizada, no solo el código fuente, asegurando resultados precisos
  • Estándares de la organización - Respeta las configuraciones de axe de tu equipo para pruebas consistentes en todos los usuarios
  • Cobertura integral - Aprovecha la plataforma líder del sector axe
  • Pruebas de respuesta - Prueba en dimensiones específicas de la ventana gráfica para detectar problemas de accesibilidad específicos de los puntos de interrupción
  • Escaneos Dirigidos - Delimite un escaneo a una región específica, iframe o raíz de sombra con el selector parámetro
  • **Páginas Autenticadas e Interactivas** - Escanea páginas detrás de un inicio de sesión, descarta banners de cookies o espera contenido dinámico usando before acciones

Salida

La herramienta devuelve una respuesta JSON estructurada que contiene:

  • Todas las violaciones de accesibilidad encontradas
  • Niveles de severidad de las violaciones (crítico, serio, moderado, menor)
  • Selectores de elementos específicos y código fuente
  • IDs de reglas y descripciones

La remediate Herramienta

La remediate herramienta toma uno o más problemas de accesibilidad identificados por la analyze o igt herramienta y genera guías de remediación alimentadas por IA y conscientes del contexto, que los agentes de codificación pueden traducir en correcciones de código reales. Los problemas se envían como un lote, por lo que una sola llamada puede devolver soluciones para cada violación encontrada en una página.

Qué Hace

  1. Autenticación - Valida las credenciales del usuario—ya sea una clave API o un token de acceso OAuth 2.0—para garantizar el acceso autorizado
  2. Crédito de IA Uso - Cada problema en el lote consume créditos de IA de la asignación de su organización, permitiendo el uso de modelos avanzados de IA entrenados en la amplia experiencia de accesibilidad de Deque
  3. **Remediación Generada por IA** - Elabora correcciones de accesibilidad de alta calidad y accionables que los agentes de codificación pueden interpretar e implementar en el código fuente
note

Si los créditos de IA se agotan, la remediate herramienta ya no funcionará hasta que sus créditos se restauren (ya sea comprando más o al reiniciar su ciclo mensual). Sin embargo, la analyze herramienta seguirá funcionando.

Remediación por Lotes

La herramienta acepta una issues matriz. Envíe todos los problemas de una sola analyze o igt ejecución juntos en una llamada en lugar de llamar a la herramienta una vez por problema — un lote admite entre 1 y 25 problemas.

Cada problema tiene los siguientes campos:

Campo Requerido Descripción
id Sí Un identificador elegido por el llamante, único dentro del lote (por ejemplo, el ID de la regla más un contador: color-contrast-0). Usado solo para correlacionar cada resultado con su entrada.
rule Sí El ID de la regla axe del analyze/igt salida (por ejemplo, color-contrast, image-alt).
elementHtml Sí El fragmento HTML del elemento que infringe.
remediation Sí Una descripción de lo que está mal y lo que necesita corregirse, tomada del resumen del problema (enriquecida opcionalmente con su descripción, texto de ayuda o razonamiento de IA).
pageUrl No La URL de la página que se está remediando, del analyze respuesta.

Indique a su agente de IA en lenguaje natural — que ensamblará el lote a partir de los resultados del análisis:

Analyze http://localhost:3000 and remediate every issue found

El agente resuelve la solicitud y llama a la remediate herramienta con una carga útil similar a:

{
  "issues": [
    {
      "id": "color-contrast-0",
      "rule": "color-contrast",
      "elementHtml": "<span style=\"color: #aaa\">Sign up</span>",
      "remediation": "Increase the contrast ratio to at least 4.5:1",
      "pageUrl": "http://localhost:3000"
    },
    {
      "id": "image-alt-1",
      "rule": "image-alt",
      "elementHtml": "<img src=\"logo.png\">",
      "remediation": "Add alt text describing the image"
    }
  ]
}

Salida

La herramienta devuelve un array de resultados por problema, cada uno vinculado a su entrada por id. Un resultado tiene una de dos formas:

  • Éxito — status: "ok", con un remediation objeto que contiene una descripción general, los pasos de remediación y una corrección de código concreta
  • Error — status: "error", con un error objeto (code y message) para un problema que no pudo ser remediado
{
  "data": [
    {
      "id": "color-contrast-0",
      "status": "ok",
      "remediation": {
        "general_description": "...",
        "remediation": "...",
        "code_fix": "<span style=\"color: #595959\">Sign up</span>"
      }
    },
    {
      "id": "image-alt-1",
      "status": "error",
      "error": { "code": "LLM_ERROR", "message": "..." }
    }
  ]
}

Los resultados son independientes: un fallo en un problema no bloquea la orientación para los demás.

Uso de Créditos

La remediate herramienta es parte del Sistema de Gestión de Créditos de IA. Cada problema en un lote consume créditos de la asignación mensual de su organización. Los administradores pueden monitorear el uso de créditos a través del portal de cuentas de axe.

La igt Herramienta

La igt herramienta ejecuta las Pruebas Guiadas Inteligentes Automatizadas (IGTs) de Deque en una página web desde su IDE. Donde la extensión para navegadores de axe DevTools normalmente guía a un desarrollador a través de una IGT con mensajes manuales, la igt herramienta lleva a cabo la prueba automáticamente y devuelve resultados estructurados sobre los que un agente de codificación puede actuar.

Hoy la herramienta soporta la IGT de Teclado, que evalúa si los elementos interactivos en una página pueden ser alcanzados y operados utilizando solamente el teclado.

Qué Hace

  1. Autenticación - Valida las credenciales del usuario—ya sea una clave API o un token de acceso OAuth 2.0—para asegurar un acceso autorizado
  2. Ejecución Basada en Navegador - Pruebas en la misma instancia de Chromium con la extensión de axe DevTools montada que utiliza la analyze herramienta
  3. Navegación de la página - Navega a la URL proporcionada por el usuario en su solicitud al agente de IA
  4. IGT de Teclado Automatizada - Navega por la página mientras la IA analiza cada parada de tabulación, evaluando el orden de enfoque y la operatividad del teclado—no se requiere entrada manual
  5. Entrega de resultados - Devuelve los hallazgos estructurados al agente

Uso

La herramienta acepta un url y un igtTools array que nombra qué IGTs ejecutar. La IGT de Teclado es actualmente el único valor soportado:

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"]
}

Indicá a tu agente de IA en lenguaje natural: el agente traduce tu intención en la llamada de la herramienta:

Run the keyboard IGT on http://localhost:3000

Interacciones con el Navegador Antes de las Pruebas

Al igual que la analyze herramienta, igt acepta un opcional before pasos de interacción que se ejecutan después de que la página se carga pero antes de que se active la prueba guiada. Esto le permite ejecutar una prueba guiada en páginas protegidas por inicio de sesión, descartar banners de cookies o esperar a que aparezca primero el contenido dinámico.

Los pasos se ejecutan en el mismo contexto del navegador como la prueba (por lo que cookies, localStorage, y los cambios de ruta persisten), utilizan el mismo click, fill, y waitFor acciones, y están limitados al mismo 20 pasos. Consulte Acciones Soportadas en la analyze herramienta para la referencia completa, incluyendo el manejo de valores sensibles de fill.value y las reglas de seleccionadores.

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"],
  "before": [
    { "action": "fill", "selector": "#username", "value": "<resolved-from-.env.local>" },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}

Salida

La herramienta devuelve una respuesta JSON estructurada:

{
  "pageUrl": "http://localhost:3000",
  "data": {
    "keyboard": {
      "issues": [],
      "unanalyzedElements": [],
      "terminatedReason": "keyboard-trap"
    }
  }
}
  • issues - Violaciones de accesibilidad del teclado encontradas durante la ejecución
  • unanalyzedElements - Paradas de tabulación que la IA no pudo analizar. Estas se reportan por separado de issues para que puedan revisarse manualmente, en lugar de ser informadas erróneamente como aprobadas o fallidas.
  • terminatedReason - Actualmente únicamente cuando la ejecución se interrumpió antes de que se analizara cada punto de tabulación. El valor actual es "keyboard-trap", lo que significa que la prueba encontró una trampa de teclado de la que no pudo escapar; los pasos restantes se detienen y los puntos de tabulación analizados hasta ese momento se devuelven en issues.

Uso de Créditos

La igt herramienta es una función impulsada por IA y es parte de la Sistema de Gestión de Créditos de IA. Cada ejecución consume créditos de IA de la asignación mensual de su organización. Los administradores pueden monitorear el uso de créditos a través del Portal de Cuentas de axe.

note

Si los créditos de IA se agotan, la igt herramienta ya no funcionará hasta que sus créditos se restauren (ya sea comprando más o al reiniciar su ciclo mensual). Sin embargo, la analyze herramienta seguirá funcionando.

Empezando

Configurar el Servidor MCP de axe implica tres elecciones independientes:

  1. Elige una distribución — Docker o npm
  2. Configura la autenticación — una clave API o OAuth 2.0
  3. Configura tu cliente — VS Code con Copilot, Cursor, o Claude Code

Para las variables de entorno e instrucciones recomendadas para agentes de IA, vea el Referencia de Configuración. Si algo sale mal, consulte Solución de Problemas.

Ejemplos de Indicaciones

Asegurando que se llamen las herramientas esperadas

En muchos entornos de desarrollo, usar la siguiente sintaxis (con el prefijo "#") garantizará que se llamen las herramientas del servidor axe MCP como se espera:

#analyze the http://localhost:3033/ web page for accessibility issues and #remediate any violations found

Analizar una URL de localhost para problemas de accesibilidad:

Analyze http://localhost:3000 for accessibility issues

Análisis con remediación:

Analyze https://example.com for accessibility issues and fix any issues found

Analizar una página detrás de un inicio de sesión:

Analyze http://localhost:3000 for accessibility issues. Before running the
analysis, fill in the #username and #password fields with USERNAME and
PASSWORD from ./.env.local, click the button[type=submit] button, and
wait for #main-content to appear.

Cerrar una banner de cookies antes de escanear:

Analyze https://example.com for accessibility issues, but first click the
#cookie-dismiss button to dismiss the cookie consent banner.

Soporte

Para preguntas, problemas o comentarios relativos al axe MCP Server:

Preguntas frecuentes sobre Seguridad y Privacidad

¿El axe MCP Server captura o almacena nuestro código fuente?

No. El servidor axe MCP no captura ni almacena su código fuente en ninguna base de datos o almacenamiento persistente.

Cuando la analyze herramienta se ejecuta, la respuesta incluye el código fuente HTML de los elementos con problemas de accesibilidad para proporcionar contexto y propósitos de depuración. Sin embargo, estos datos:

  • Solo se devuelven en la respuesta inmediata de la API a su agente de IA
  • Nunca se almacenan en bases de datos gestionadas por Deque
  • Permanecen dentro de su entorno de desarrollo local
  • Se descartan después de que se complete el análisis

¿Cuánto tiempo permanecen los resultados de las pruebas MCP en la infraestructura gestionada por Deque?

No lo hacen. Los resultados de las pruebas MCP no se almacenan en ninguna base de datos o sistema de almacenamiento gestionado por Deque.

La analyze herramienta:

  • Funciona completamente en su máquina: en un contenedor Docker, o como un proceso local de Node.js con la distribución npm
  • Devuelve los resultados directamente a su agente de IA
  • No envía los resultados del análisis a los servidores de Deque

La única excepción es cuando se llama a la remediate herramienta, que puede incluir metadatos mínimos de violación (ver más abajo) para generar orientación de corrección potenciada por IA.

¿Qué datos se envían a los servidores de Deque?

Solo al usar la remediate herramienta:

Los siguientes datos se envían al punto de acceso de remediación de IA de Deque para generar orientación de corrección:

  • ID de regla - La regla de accesibilidad específica que fue violada
  • HTML del elemento - El marcado HTML del(los) elemento(s) afectado(s)
  • Metadatos del problema - Descripción de la violación y guía de remediación de axe-core

Estos datos se utilizan exclusivamente para generar orientación de remediación y no se almacenan a largo plazo en las bases de datos de Deque.

La analyze herramienta no envía ningún dato a los servidores de Deque más allá de las solicitudes de autenticación (validando su clave API o el token de acceso OAuth 2.0).

¿Qué nivel de acceso necesita el agente de IA para funcionar?

El agente de IA (Claude, Copilot, Cursor, etc.) necesita acceso a:

  1. Comunicación del servidor MCP - El agente debe poder llamar a las herramientas del servidor MCP a través del Model Context Protocol

  2. Datos de respuesta de herramientas - El agente recibe:

    • Datos de violación de accesibilidad de analyze llamadas
    • Guía de remediación de remediate llamadas
    • Estos datos son necesarios para que el agente entienda los problemas y genere correcciones de código

  3. Su base de código (opcional) - Si desea que el agente aplique automáticamente correcciones de código, necesita acceso a sus archivos de código fuente

  • Esto es estándar para los asistentes de codificación de IA en IDEs (VS Code, Cursor, etc.)
  • No se requiere si solo está utilizando las herramientas para análisis y orientación (por ejemplo, a través de la aplicación de escritorio Claude)

El propio servidor MCP necesita acceso a:

  • URLs que especifique para las pruebas (admite tanto locales como remotos)
  • Sus credenciales de axe: ya sea una clave API (generada en el Portal de Cuentas de axe) o un token de acceso OAuth 2.0 (obtenido a través de @deque/axe-auth); proporcionadas a través de una variable de entorno

Importante: El servidor MCP se ejecuta localmente en su máquina: en un contenedor Docker, o como un proceso de Node.js con la distribución npm. No requiere acceso amplio al sistema de archivos ni privilegios elevados.

Mejores prácticas

  • Seguridad de las Credenciales - Almacene su AXE_API_KEY o AXE_ACCESS_TOKEN como una variable de entorno, no en el código. Con OAuth 2.0, @deque/axe-auth mantiene los tokens en el llavero de su sistema operativo e inyecta un token de acceso nuevo al iniciar, por lo que no es necesario almacenar un secreto de larga duración en su configuración
  • Pruebas locales - Pruebe las URL de desarrollo local (localhost) o de etapas para mantener aislado el código sensible previo a la producción
  • Aislamiento de red - El servidor MCP solo se comunica con:
    • URLs que solicite explícitamente analizar
    • Servidores Deque para autenticación (validación de clave API o token OAuth 2.0) y remediación (cuando se solicita)
    • Su agente de IA local a través del protocolo MCP
  • Revise antes de aplicar - Siempre revise los cambios de código generados por IA antes de confirmarlos en su base de código

Is this page helpful?

Help us improve this page

Still need help?