Référence de configuration

Cette page documente les variables d'environnement que le serveur axe MCP lit, ainsi que les instructions personnalisées recommandées pour votre agent IA. Celles-ci s'appliquent à la fois aux distributions Docker et npm. Pour savoir où placer ces valeurs, consultez votre guide de configuration client.

Options de configuration

Le serveur axe MCP prend en charge plusieurs variables d'environnement pour la personnalisation :

AXE_SERVER_URL

La valeur par défaut (https://axe.deque.com) est correcte pour la plupart des utilisateurs — ceux sur l'instance SaaS partagée des États-Unis de Deque. Si votre organisation utilise l'un des éléments suivants, vous devez définir AXE_SERVER_URL sur l'URL de base de votre instance :

• Un instance SaaS régionale (UE, Australie, Francfort, etc.)
• Un déploiement cloud privé
• Une installation installation sur site

Si vous ne savez pas quelle instance votre organisation utilise, vérifiez l'URL que vous utilisez pour vous connecter au portail de compte axe, ou demandez à votre administrateur.

Définissez AXE_SERVER_URL explicitement dans le bloc env de la configuration de votre serveur MCP. Les guides d'installation client incluent des exemples montrant exactement où l'ajouter.

AXE_CHROME_PATH

distribution npm uniquement. Cela n'est pas pris en charge dans Docker, qui utilise toujours son navigateur intégré — le serveur ne démarre pas si AXE_CHROME_PATH est défini sous la distribution Docker.

Par défaut, la distribution npm utilise la build de Chromium que vous installez via Playwright. Définissez AXE_CHROME_PATH sur le chemin complet d'un binaire Chrome/Chromium existant pour l'utiliser à la place et éviter l'installation de Playwright.

• La valeur doit être un fichier binaire exécutable, et non un package ou un répertoire .app. Sur macOS, par exemple, pointez vers le binaire à l'intérieur du package : /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• Le binaire doit se lancer et répondre à --version. Le serveur valide cela au démarrage et échoue rapidement avec Unable to find specified chrome instance s'il ne peut pas.
• Google Chrome stable 137 et ultérieur n'est pas pris en charge. Utilisez Chrome pour les tests ou un autre binaire compatible avec Chromium.

Les outils analyze et igt acceptent également un argument chromePath par appel, qui prend le pas sur AXE_CHROME_PATH pour cet appel.

AXE_ADVANCED_RULES

Définit le préréglage de confiance Règles avancées pour chaque analyse exécutée par ce serveur, en remplaçant la configuration par défaut d'axe de votre organisation — à condition que votre administrateur autorise les utilisateurs à modifier le paramètre.

Les valeurs acceptées sont "precise" (ou "90%"), "balanced" (ou "70%"), "thorough" (ou "50%"), et "disabled". Les valeurs ne sont pas sensibles à la casse.

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

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

L'outil analyze accepte également un argument advancedRules par appel, qui prend la priorité sur AXE_ADVANCED_RULES pour cet appel. Si votre administrateur a verrouillé le paramètre, les deux sont ignorés au profit du préréglage de l'organisation. Voir Règles avancées pour les règles complètes de priorité et le bloc de réponse advancedRules.

AXE_SCREENSHOT_DIR

Définit le répertoire dans lequel l'outil analyze écrit les captures d'écran lorsqu'un appel passe screenshot.save sans chemin explicite. Cela n'a aucun effet sur les appels qui définissent screenshot.saveTo, qui l'emporte toujours, ni sur les appels qui ne sauvegardent pas du tout.

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

Les chemins relatifs sont résolus par rapport au répertoire de travail du serveur. La valeur par défaut est le répertoire temporaire de votre système d'exploitation.

Variables de rafraîchissement du jeton

Cela s'applique uniquement à OAuth 2.0, et permet à un serveur en cours d'exécution d'accepter un jeton d'accès fraîchement rafraîchi pour qu'une session qui survit à son jeton n'ait pas besoin de redémarrage. L'écouteur est désactivé par défaut et ne démarre que lorsque les deux AXE_TOKEN_REFRESH_PORT et AXE_TOKEN_REFRESH_SECRET sont définis.

Vous ne configurez pas normalement ceux-ci manuellement. @deque/axe-auth run supervise le serveur et les fournit pour vous — vous choisissez un port, et il génère le secret.

Votre jeton de rafraîchissement n'est jamais envoyé au serveur — seuls les jetons d'accès de courte durée passent, et le secret partagé est ce qui protège le point de terminaison. Voir Maintenir une longue session active pour des configurations Docker et npm complètes.

Configurer votre agent IA (Recommandé)

Pour garantir que votre agent de codage IA utilise correctement les outils de serveur MCP d'axe et respecte les meilleures pratiques en matière d'accessibilité, vous pouvez lui fournir des instructions personnalisées. Ces instructions aident l'agent à comprendre le flux de travail approprié pour analyser et rectifier les problèmes d'accessibilité.

Où ajouter des instructions

La méthode varie selon le client :

• VS Code avec GitHub Copilot - Ajoutez à .github/copilot-instructions.md à la racine de votre projet
• Cursor - Ajoutez aux "Règles de curseur" dans les paramètres
• Claude Code - Ajoutez à un fichier CLAUDE.md à la racine de votre projet
• Claude Desktop - Ajoutez aux instructions personnalisées dans les paramètres
• Autres clients MCP - Consultez la documentation de votre client pour la configuration des instructions personnalisées

Exemple d'instructions de flux de travail

Ci-dessous un modèle recommandé que vous pouvez adapter pour votre agent :

# 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

Pourquoi c'est important

Ces instructions garantissent que votre agent :

• Utilise l'expertise de Deque - Exploite des modèles d'IA formés sur des décennies de données d'évaluation de l'accessibilité plutôt que sur des connaissances générales de LLM
• Suit les meilleures pratiques - Applique des correctifs conformes à la WCAG de manière cohérente plutôt que des solutions génériques
• Vérifie les changements - Confirme toujours que les correctifs ont effectivement résolu les problèmes
• Évite une confiance excessive - Ne suppose pas qu'il sait comment résoudre les problèmes d'accessibilité sans guidance experte

Bien que facultatives, ces instructions améliorent significativement la qualité et la fiabilité des corrections d'accessibilité dans votre base de code.