Referencia de Configuración

Esta página documenta las variables de entorno que lee el servidor axe MCP, y las instrucciones personalizadas recomendadas para tu agente de IA. Estas se aplican tanto a Docker y npm. Para saber dónde colocar estos valores, consulta tu guía de configuración del cliente.

Opciones de Configuración

El servidor axe MCP admite varias variables de entorno para la personalización:

AXE_SERVER_URL

El valor predeterminado (https://axe.deque.com) es correcto para la mayoría de los usuarios: aquellos en la instancia SaaS compartida de Deque en EE. UU. Si tu organización usa alguno de los siguientes, debes configurar AXE_SERVER_URL a la URL base de tu instancia:

• Un instancia de SaaS regional (UE, Australia, Fráncfort, etc.)
• Un cloud privado despliegue
• Una on-premises instalación

Si no está seguro de qué instancia usa su organización, verifique la URL que utiliza para iniciar sesión en el portal de cuentas axe, o pregunte a su administrador.

Configura AXE_SERVER_URL explícitamente en el bloque env de la configuración de tu servidor MCP. Los guías de configuración del cliente incluyen ejemplos que muestran exactamente dónde añadirlo.

AXE_CHROME_PATH

Solo distribución npm. Esto no es compatible con Docker, que siempre usa su navegador integrado — el servidor no se inicia si AXE_CHROME_PATH se configura en la distribución de Docker.

Por defecto, la distribución de npm usa la versión de Chromium que instalas a través de Playwright. Configura AXE_CHROME_PATH con la ruta completa de un binario existente de Chrome/Chromium para usar ese en su lugar y omitir la instalación de Playwright.

• El valor debe ser un archivo binario ejecutable, no un paquete o directorio .app. En macOS, por ejemplo, apunta al binario dentro del paquete: /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• El binario debe iniciarse y responder a --version. El servidor valida esto al iniciar y falla rápidamente con Unable to find specified chrome instance si no puede.
• Google Chrome de marca estable 137 y posteriores no es compatible. Usa Chrome para pruebas u otro binario compatible con Chromium.

Las herramientas analyze y igt también aceptan un argumento chromePath por llamada, que tiene prioridad sobre AXE_CHROME_PATH para esa llamada.

AXE_ADVANCED_RULES

Establece el preajuste de confianza Reglas avanzadas para cada escaneo que realiza este servidor, anulando la configuración predeterminada de axe de su organización, siempre que su administrador permita a los usuarios cambiar la configuración.

Los valores aceptados son "precise" (o "90%"), "balanced" (o "70%"), "thorough" (o "50%") y "disabled". Los valores no distinguen entre mayúsculas y minúsculas.

{
  "env": {
    "AXE_ADVANCED_RULES": "thorough"
  }
}

Invalid Advanced Rules value: "high". Expected one of: 'precise' (90%), 'balanced' (70%), 'thorough' (50%), 'disabled'.

La herramienta analyze también acepta un argumento advancedRules por llamada, que tiene prioridad sobre AXE_ADVANCED_RULES para esa llamada. Si su administrador ha bloqueado la configuración, ambos se ignoran en favor del preestablecido de la organización. Ver Reglas avanzadas para conocer las reglas de precedencia completas y el bloque de respuesta advancedRules.

AXE_SCREENSHOT_DIR

Establece el directorio en el que la herramienta analyze guarda capturas de pantalla cuando una llamada pasa screenshot.save sin un camino explícito. No tiene efecto en las llamadas que establecen screenshot.saveTo, que siempre prevalece, ni en las llamadas que no guardan en absoluto.

{
  "env": {
    "AXE_SCREENSHOT_DIR": "/Users/me/axe-screenshots"
  }
}

Las rutas relativas se resuelven en relación con el directorio de trabajo del servidor. El valor predeterminado es el directorio temporal de su sistema operativo.

Variables de actualización de token

Esto se aplica solo a OAuth 2.0, y permite que un servidor en ejecución acepte un token de acceso recién renovado para que una sesión que supera su token no necesite reinicio. El escucha está desactivado por defecto y solo comienza cuando se configuran AXE_TOKEN_REFRESH_PORT y AXE_TOKEN_REFRESH_SECRET.

Normalmente no configura estos de manera manual. @deque/axe-auth run supervisa el servidor y los proporciona por usted: usted elige un puerto, y él genera el secreto.

Su token de actualización nunca se envía al servidor; solo los tokens de acceso de corta duración lo hacen, y el secreto compartido es lo que protege el punto final. Ver Mantener viva una sesión larga para configuraciones completas de Docker y npm.

Configuración de su agente de IA (Recomendado)

Para asegurar que su agente de codificación de IA utiliza correctamente las herramientas del servidor axe MCP y sigue las mejores prácticas de accesibilidad, puede proporcionarle instrucciones personalizadas. Estas instrucciones ayudan al agente a entender el flujo de trabajo adecuado para analizar y remediar problemas de accesibilidad.

Dónde agregar las instrucciones

El método varía según el cliente:

• VS Code con GitHub Copilot - Añadir a .github/copilot-instructions.md en la raíz de tu proyecto
• Cursor - Añadir a "Reglas de Cursor" en configuración
• Claude Code - Añadir a un archivo CLAUDE.md en la raíz de tu proyecto
• Claude Desktop - Añadir a instrucciones personalizadas en configuración
• Otros clientes MCP - Consulta la documentación de tu cliente para la configuración de instrucciones personalizadas

Ejemplo de instrucciones de flujo de trabajo

A continuación se presenta una plantilla recomendada que puede adaptar para su agente:

# Accessibility Testing and Remediation Workflow

## MANDATORY WORKFLOW - DO NOT DEVIATE

When working with accessibility issues, you MUST follow this exact workflow:

### 1. Analysis Phase

When asked to analyze pages for accessibility issues, you MUST:

- Use the `analyze` tool to scan the page
- Do NOT manually identify accessibility issues
- Always provide the complete URL being analyzed

### 2. Authentication & Pre-Scan Setup

When the user's request involves credentials, form input, dismissing
overlays, or waiting for content before the scan, you MUST:

- Pass an ordered `before` array to the `analyze` tool using the
  `click`, `fill`, and `waitFor` actions
- Resolve any references to env vars, `.env*` files, or local
  configuration into literal strings BEFORE calling the tool — the
  server treats `value` as a literal and will not expand `${VAR}`,
  `$VAR`, or `{{VAR}}` syntax
- Use `fill` for secret values so the server's redaction protections
  apply; never embed secrets in a `selector`, which appears in logs
  and error messages
- ASK the user when the source of a credential or value is ambiguous;
  do NOT guess or fabricate values
- Use ONLY selectors the user provided; if a step needs a selector
  the user did not name, ASK rather than guess
- Use `waitFor` after any `click`/`fill` that triggers async UI
  (route changes, late-rendered content) to deterministically gate
  the next step or the scan — pick a selector that exists ONLY in
  the post-interaction state (e.g., a logout button or dashboard
  heading), never a generic one like `body` or `#app` that already
  exists beforehand

### 3. Remediation Phase

When asked to remediate or fix accessibility issues, you MUST:

- Collect ALL violations from the analysis and pass them to the
  `remediate` tool in a SINGLE batched call — do NOT call `remediate`
  once per issue
- Give each issue a unique `id` so each result can be correlated
  back to its input
- Provide the exact HTML element, rule ID, and issue description for
  every issue in the batch
- Review the remediation guidance before making any code changes
- Apply fixes based on the remediate tool's recommendations
- Do NOT manually fix accessibility issues without first using the remediate tool

### 4. Verification Phase

After applying fixes, you MUST:

- Re-run `analyze` to verify all issues are resolved
- Confirm zero violations before considering the task complete

## Required Workflow Example:

1. analyze → Find violations
2. remediate → Pass ALL violations in one batched call to get fix guidance
3. Apply recommended fixes to code
4. analyze → Verify fixes

## Enforcement

- NEVER skip the remediate tool when fixing accessibility issues
- ALWAYS use both analyze and remediate tools as specified
- This workflow ensures proper accessibility best practices and compliance

Por qué es importante

Estas instrucciones aseguran que su agente:

• Usa la experiencia de Deque - Aprovecha modelos de IA entrenados en décadas de datos de evaluación de accesibilidad en lugar de conocimiento general de LLM
• Sigue las mejores prácticas - Aplica arreglos consistentes, compatibles con WCAG, en lugar de soluciones genéricas
• Verifica los cambios - Siempre confirma que los arreglos realmente resolvieron los problemas
• Evita la falsa confianza - No asume que sabe cómo solucionar problemas de accesibilidad sin la orientación de expertos

Aunque es opcional, proporcionar estas instrucciones mejora significativamente la calidad y fiabilidad de las correcciones de accesibilidad en tu código.