Plugin para Claude Code

Descripción general

El plugin de accesibilidad Axe es el kit de herramientas de accesibilidad de Deque para agentes de codificación, instalado y ejecutado desde Claude Code. Su instalación realiza tres acciones a la vez:

• Registra el servidor. El plugin incluye una entrada lista para el servidor MCP, por lo que no necesitas escribir un .mcp.json manualmente.
• Enseña a Claude a usar las herramientas. Una habilidad en segundo plano se carga automáticamente en el trabajo de accesibilidad, por lo que Claude sigue el ciclo de analizar → remediar → verificar, agrupa remediate correctamente y asigna campos entre las herramientas sin adivinanzas.
• Añade tres comandos de barra para configurar, generar instrucciones a nivel de repositorio y ejecutar el ciclo completo de remediación en una página.

El plugin es de código abierto en github.com/dequelabs/axe-accessibility y está bajo la licencia MIT.

No es solo para Claude Code

Claude Code es donde se ejecuta el plugin, pero dos de sus comandos producen salidas para agentes y editores otros:

• /axe-accessibility:mcp-generate-instructions escribe el flujo de trabajo de analizar → remediar → verificar en .github/copilot-instructions.md, reglas de Cursor o AGENTS.md tan fácilmente como en CLAUDE.md. Cualquiera en el equipo que use Copilot o Cursor hereda el flujo de trabajo del repositorio, independientemente de si tienen el plugin o Claude Code instalado.
• /axe-accessibility:mcp-setup puede configurar el Servidor MCP de Axe para Cursor, VS Code con Copilot o Claude Desktop, no solo Claude Code.

Por lo tanto, es razonable instalar el plugin puramente como una herramienta de configuración y redacción de instrucciones para un repositorio cuyos colaboradores usan una mezcla de agentes.

Requisitos

Para instalar el plugin:

• Claude Code con soporte para plugins.

Para ejecutar escaneos — es decir, para usar las herramientas analyze, igt y remediate, ya sea desde Claude Code o desde otro cliente configurado por el plugin:

• Una suscripción Axe DevTools para Web que incluya acceso al Servidor MCP de Axe. Sin ella, las herramientas no podrán autenticarse.
• Un entorno de ejecución, dependiendo de qué distribución utilices:
  • npm (lo que incluye el plugin): Node.js 22.19.0 o posterior, más una instalación única de Chromium. Consulta Instalar Chromium — el servidor no descarga un navegador por ti, y omitir este paso es el fallo más común en la primera ejecución.
  • Docker: Docker instalado y en ejecución. Chromium se incluye dentro de la imagen.
• Para la autenticación OAuth 2.0: un versión LTS activa de Node.js, ya que la configuración llama npx @deque/axe-auth.

Solo el primero se aplica si estás instalando el plugin únicamente para ejecutar /axe-accessibility:mcp-generate-instructions — escribir archivos de instrucciones para agentes no requiere un entorno de ejecución ni una suscripción.

Instalación

Agrega el mercado de Deque e instala el plugin desde dentro de Claude Code:

/plugin marketplace add dequelabs/axe-accessibility
/plugin install axe-accessibility

El primer comando registra el repositorio dequelabs/axe-accessibility como un mercado de plugins (el repositorio también funciona como su propio mercado). El segundo instala el plugin desde allí. Solo necesitas agregar el mercado una vez; las instalaciones y actualizaciones posteriores pueden omitir ese paso.

Reinicia Claude Code cuando se te indique para que se cargue el servidor MCP.

Autenticación

La configuración del servidor incluido en el plugin es independiente de la autenticación: al iniciar, intenta generar un token de acceso OAuth y se asegura de que exactamente una credencial llegue al servidor: el token OAuth si has iniciado sesión, de lo contrario, tu AXE_API_KEY.

Elige el método que te convenga:

• clave API — crea una en el Portal de Cuentas Axe bajo Claves API → AGREGAR NUEVA CLAVE API, eligiendo el producto Servidor Axe MCP. Luego expórtala en tu terminal para que Claude Code pueda leerla:

  export AXE_API_KEY="your-api-key-here"

  Añade la línea a tu perfil de terminal (~/.bashrc, ~/.zshrc, etc.) para que persista. Nunca incluyas la clave en un archivo de tu repositorio.

• OAuth 2.0 — inicia sesión una vez con la CLI @deque/axe-auth:

  npx -y @deque/axe-auth login

  Esto abre un navegador para el flujo PKCE y almacena tokens en el llavero de tu sistema operativo, renovándolos automáticamente. Consulta Autenticación para el flujo completo, la gestión de sesiones y el soporte de plataforma.

La configuración incluida maneja esta regla por ti, y tiene que trabajar más que una configuración de Docker. Un contenedor solo recibe las variables pasadas con banderas -e explícitas, pero la distribución npm hereda todo el entorno de tu terminal — así que un AXE_API_KEY exportado y una sesión de OAuth activa de otro modo ambos llegarían al servidor e impedirían que comience. La entrada incluida limpia primero cualquier AXE_ACCESS_TOKEN heredado, luego, si puede generar un nuevo token, desactiva AXE_API_KEY antes de configurarlo. OAuth se impone cuando ambos están disponibles.

Implementaciones en nube privada y en instalaciones locales

La distribución npm hereda AXE_SERVER_URL de tu terminal, por lo que exportarla junto a tu credencial es suficiente:

export AXE_SERVER_URL="https://your-axe-instance.example.com"

Si usas OAuth, también pasa la misma URL al iniciar sesión: npx -y @deque/axe-auth login --server https://your-axe-instance.example.com. Si AXE_SERVER_URL no está establecido, el servidor predetermina a https://axe.deque.com (la instancia compartida de Deque en EE. UU.). Consulta Referencia de Configuración.

Verificación de la instalación

1. Reinicia Claude Code.

2. Ejecuta /mcp y confirma que axe-mcp-server esté listado y conectado, con las herramientas analyze, igt y remediate disponibles.

3. Realiza un escaneo sencillo en una página conocida:

   Analyze https://dequeuniversity.com/demo/mars for accessibility issues

Un escaneo exitoso de una página real devuelve un paquete grande: de decenas de kilobytes es normal, no un error. Si tu cliente se queja de que el resultado es demasiado grande, limita el escaneo con el parámetro selector de analyze.

Si el servidor no se conecta, confirma tu versión de Node, que Chromium esté instalado y que exactamente una credencial esté configurada, luego consulta Solución de problemas.

Qué está incluido

La habilidad mcp-usage

Nunca invocas esta directamente. Se carga automáticamente cada vez que una tarea involucra accesibilidad, conformidad a11y, WCAG, o solución de problemas de accesibilidad en la interfaz de usuario web, y le da a Claude el conocimiento operativo que de otro modo tendría que escribirse a mano en un CLAUDE.md:

• El flujo de trabajo. Analiza la página, remedia las violaciones, luego vuelve a analizar para verificar que no haya violaciones antes de considerar que el trabajo está hecho.
• Mapeo de campos. Cómo cada problema de analyze se corresponde con los parámetros de remediate — la fuente más común de error cuando un agente conecta las dos herramientas de forma tentativa. Incluye las trampas: los problemas llegan bajo el arreglo data de la respuesta, y el campo remediation de un problema es un objeto de datos de verificación en bruto, no la cadena que el parámetro remediate quiere.
• Agrupamiento. remediate toma un arreglo issues de 1–25 por llamada, cada uno con un id inventado por el llamante. Una llamada por escaneo, no una por problema — una forma de llamada por problema es rechazada de inmediato.
• Conciencia de crédito. Los créditos se consumen por problema, no por llamada, así que el agrupamiento es el contrato en lugar de un descuento. Volver a ejecutar analyze para verificar no consume nada, por lo que la verificación es barata.
• Cuáles hallazgos confiar. Los problemas señalados isAdvanced: true provienen de Reglas Avanzadas — IA y visión por computadora — y son probabilísticos, por lo que deben confirmarse con la interfaz de usuario real. Los hallazgos estándar de axe-core (isAdvanced: false) son determinísticos y autoritativos.
• Pruebas de teclado. Cuándo recurrir a igt, y cómo difiere la forma de su problema de la de analyze.
• Matiz específico de la regla. Orientación para reglas con alto juicio, como image-alt, color-contrast, link-name/button-name y etiquetado de formularios.

Debido a que la habilidad siempre está disponible, las solicitudes en lenguaje sencillo funcionan sin ceremonia:

Make the checkout page at http://localhost:3000/checkout accessible

Comandos

/axe-accessibility:mcp-setup

/axe-accessibility:mcp-setup [client]

Lo guía a través de la conexión al servidor Axe MCP, preguntando sobre las decisiones en lugar de asumirlas. Opcionalmente, pase un cliente — claude-code, cursor, vscode o claude-desktop — para omitir esa pregunta.

El comando:

1. Pregunta si desea el npm o Docker distribución, y luego verifica ese entorno de ejecución — versión de Node y Chromium para npm, un demonio en ejecución para Docker.
2. Pregunta si desea clave API o OAuth 2.0 autenticación, luego guía a través de la creación de una clave en el Portal de Cuenta o la ejecución del inicio de sesión del navegador.
3. Escribe la configuración coincidente para su cliente — fusionando en cualquier configuración de MCP existente en lugar de sobrescribirla. Para Claude Code en la distribución npm, el servidor incluido en el complemento generalmente hace innecesario este paso.
4. Ofrece las configuraciones opcionales que vale la pena conocer: AXE_SERVER_URL para nube privada, AXE_ADVANCED_RULES para una regla predeterminada de Reglas Avanzadas, y AXE_CHROME_PATH para reutilizar un navegador que ya tenga (solo npm).
5. Verifica la conexión y realiza un escaneo rápido.

Útil, aunque la instalación del complemento ya registra el servidor: ejecútelo cuando necesite configurar la autenticación por primera vez, cambiar a Docker, apuntar a una instancia de nube privada o configurar un diferente editor en la misma máquina. Los fragmentos de cliente que emite son los mismos que están documentados para VS Code con Copilot, Cursor y Claude Code — el comando simplemente elige el correcto y lo fusiona en su configuración existente.

/axe-accessibility:mcp-generate-instructions

/axe-accessibility:mcp-generate-instructions [targets]

Escribe el flujo de trabajo obligatorio analizar → remediar → verificar en los archivos de instrucciones del agente de su repositorio, para que cualquiera agente de codificación que trabaje en el repositorio — no solo el que tiene el complemento instalado — lo siga. Objetivos:

Sin argumento, el comando detecta cuáles de estos archivos ya existen y confirma el conjunto con usted antes de escribir.

Cada archivo obtiene el contrato completo, no solo el bucle: la regla de agrupación remediate, el mapeo de campos, la distinción de confianza determinista versus avanzada, la sección de teclado igt y la nota de crédito. Los nombres de las herramientas se adaptan por objetivo, ya que los clientes nombran las herramientas de MCP de manera diferente — Copilot se vincula a mcp_axe-mcp-server_analyze, por ejemplo, mientras que Claude Code y Cursor resuelven nombres simples.

Los archivos existentes son fusionados, no sobrescritos: si ya existe una sección de flujo de trabajo de accesibilidad, se actualiza en su lugar, de lo contrario, la sección se agrega y el resto del archivo se conserva. El comando también adapta las instrucciones a su repositorio donde puede — por ejemplo, haciendo referencia a la URL y el comando de inicio reales de su proyecto en lugar de un marcador de posición.

/axe-accessibility:mcp-generate-instructions all

Generar all es la opción habitual para un repositorio compartido: una persona lo ejecuta una vez desde Claude Code, confirma los archivos, y el agente de cada colaborador recoge el flujo de trabajo — Copilot de .github/copilot-instructions.md, Cursor de .cursor/rules/accessibility.mdc, y así sucesivamente. Las instrucciones solo surten efecto para los agentes que las leen, y cada colaborador aún necesita tener el servidor Axe MCP conectado en su propio cliente para que el flujo de trabajo se ejecute realmente.

Este es el equivalente automatizado del modelo en Configurando tu Agente de IA.

/axe-accessibility:mcp-audit

/axe-accessibility:mcp-audit <url> [max-rounds]

Ejecuta el bucle de remediación completo en una página y aplica las correcciones a su código fuente. Proporcione la URL completa, incluyendo el esquema y el puerto. Si lo omite, el comando intenta detectar un servidor de desarrollo en ejecución a partir de sus package.json scripts y puertos comunes, y confirma la URL con usted antes de escanear.

Cada ronda:

1. Analizar la URL y recopile los problemas.
2. Clasificar por bandera — los hallazgos isAdvanced se confirman con la interfaz de usuario real antes de efectuar cualquier cambio, los hallazgos isNeedsReview se presentan a usted en lugar de corregirse automáticamente cuando la llamada es una decisión de diseño, y los hallazgos isBestPractice nunca bloquean "limpio".
3. Remediar cada problema de la ronda en una llamada agrupada única (hasta 25 por llamada, divididos en lotes secuenciales más allá de eso).
4. Aplicar las directrices a su código fuente, correlacionando cada resultado de vuelta por id y verificando su estado, ya que un lote puede fallar parcialmente. Las correcciones de código sugeridas se adaptan al componente real en lugar de pegarse literalmente.
5. Reanalizar para verificar.

El bucle se detiene en cero infracciones o después de max-rounds (el valor predeterminado es 5). También se detiene antes si una ronda no logra avanzar — en ese punto, los problemas restantes generalmente necesitan una decisión de diseño, o son falsos positivos de reglas avanzadas, los cuales el comando informa como tal en lugar de contorsionar su código para alcanzar cero. El progreso se informa por ronda (por ejemplo, round 1: 7 → round 2: 2 → round 3: 0), y el comando resume los cambios de código que realizó para que pueda revisarlos antes de cometer.

/axe-accessibility:mcp-audit http://localhost:3000/checkout 3

Llegar a una página que no es una URL simple funciona como ocurre con la herramienta subyacente: describe un inicio de sesión o una interacción y los pasos se pasan como acciones de before; describe el enrutamiento del entorno o una sesión preautenticada y se pasan como cookies, que se aplican antes de la navegación. Mantén los secretos en un fill paso de value o en un value de cookie, nunca en un selector o en el nombre de una cookie.

Una vez que las violaciones automatizadas están limpias, el comando puede ejecutar un pase de teclado opcional con igt — el orden de enfoque, las trampas de enfoque y la visibilidad del enfoque son invisibles para un escaneo estático. Pídelo directamente si lo deseas en una página con menús, diálogos o widgets personalizados:

/axe-accessibility:mcp-audit http://localhost:3000 and run the keyboard test

Flujo de trabajo sugerido

1. /axe-accessibility:mcp-setup — conecta y autentica el servidor. Verifica con /mcp.
2. /axe-accessibility:mcp-generate-instructions all — incorpora el flujo de trabajo en el repositorio para que cada agente y compañero lo herede.
3. /axe-accessibility:mcp-audit http://localhost:3000 — limpia la deuda de accesibilidad ya presente en la página.
4. A partir de ahí, solo construye. La habilidad mcp-usage mantiene a Claude ejecutando el ciclo en los cambios de UI sin que se le pida.

Gestión del complemento

El comando /plugin de Claude Code gestiona el ciclo de vida del complemento:

/plugin                 # browse and manage installed plugins
/plugin update axe-accessibility
/plugin uninstall axe-accessibility

Desinstalar elimina la entrada del servidor MCP incluido junto con las habilidades y comandos. Cualquier archivo de instrucciones del agente creado por /axe-accessibility:mcp-generate-instructions permanece en tu repositorio — elimínalos tú mismo si ya no los deseas.

Páginas relacionadas

• Elegir una distribución — npm versus Docker, e instalando Chromium para npm
• Configuración en Claude Code — configurando el servidor a mano, sin el complemento
• Autenticación — clave API y OAuth 2.0 en su totalidad
• Referencia de Configuración — variables de entorno y plantillas de instrucciones del agente
• Reglas Avanzadas — preajustes, precedencia y qué significa el indicador isAdvanced
• Solución de problemas — conexión, Chromium, Docker y errores de autenticación
• Créditos de IA — cómo remediate y igt consumen créditos