**server axe MCP**

Vue d'ensemble

Le serveur axe MCP est un serveur de protocole de contexte de modèle (MCP) qui intègre des tests d'accessibilité de niveau entreprise directement dans votre flux de travail de développement. Construit sur la plateforme axe de confiance, il permet aux développeurs de réaliser des analyses d'accessibilité complètes et de recevoir des conseils de remédiation experts sans quitter leur IDE.

Le serveur fournit deux capacités principales - analyze et remediate.

Les deux outils s'intègrent parfaitement avec les clients compatibles MCP (comme Claude Desktop, VS Code avec Copilot ou Cursor) et respectent les paramètres de configuration axe de votre organisation.

Obtenir l'accès

Le serveur Axe MCP est inclus dans le pack Axe DevTools pour Web .

Outils et capacités

L'outil analyze outil

L'outil analyze réalise une analyse d'accessibilité complète des pages Web en effectuant un balayage grâce à l'extension du navigateur axe DevTools dans un environnement de navigateur réel. Il fonctionne sans problème avec les URL de développement local (par exemple, localhost:3000) et les URL de production distantes.

Fonctionnalités

1. **Validation de la clé API** - Valide la clé API de l'utilisateur pour garantir un accès autorisé
2. Récupération de la configuration - Récupère la configuration axe spécifique à l'organisation de l'utilisateur, y compris :
   • Standard de test d'accessibilité (par ex. WCAG 2.2 AA)
   • Version de axe-core
   • Besoins de révision / meilleures pratiques
3. Analyse basée sur le navigateur - Lance une instance de navigateur en arrière-plan avec l’extension axe DevTools montée
4. Navigation de page - Navigue vers l'URL fournie par l'utilisateur dans leur invite à l'agent IA
5. Balayage d'accessibilité - Exécute une analyse complète de l'accessibilité sur la page rendue en utilisant l'extension du navigateur axe DevTools, garantissant que l'expérience utilisateur réelle est testée (pas seulement le HTML statique)
6. Livraison des résultats - Retourne des résultats d'analyse complète à l'agent dans un format structuré

**Tests réactifs**

L'outil analyze prend en charge des paramètres optionnels viewportWidth et viewportHeight , vous permettant de tester les pages à des dimensions spécifiques de la fenêtre d'affichage. Ceci est utile pour détecter les problèmes d'accessibilité qui n'apparaissent qu'à certaines tailles d'écran, comme les points d'arrêt pour mobile ou tablette.

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

Lorsque ces paramètres sont omis, le navigateur utilise la taille de fenêtre d'affichage par défaut.

Interactions du navigateur avant le balayage

L'outil analyze prend en charge un tableau before optionnel d'étapes d'interaction qui s'exécutent après le chargement de la page mais avant le balayage d'accessibilité. Cela débloque plusieurs scénarios de test réels :

• Pages protégées par connexion — renseigner les identifiants et soumettre avant de scanner la page post-connexion
• Bannières de cookies/de consentement — ignorer les bannières qui couvriraient ou obscurciraient autrement le contenu de la page
• Contenu dynamique — attendre que le contenu rendu côté client (modifications de route, DOM injecté tardivement) apparaisse avant de scanner

Les étapes s'exécutent dans l'ordre du tableau, dans le même contexte de navigateur que le scan, donc les cookies, localStorage, et tout changement de route déclenché par click ou fill persistent dans le scan.

L'outil before prend en charge jusqu'à 20 étapes. Chaque étape dispose de son propre délai d'attente de BROWSER_TIMEOUT_MS (par défaut 30000 ms); il n'y a pas de remplacement par étape.

Actions supportées

Exemple : Se connecter avant de scanner

Demandez à votre agent IA en langage naturel — l'agent traduit votre intention en appel d'outil :

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.

L'agent résout l'invite et appelle l'outil analyze avec une charge utile similaire à :

{
  "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" }
  ]
}

Principaux avantages

• **Tests dans un véritable navigateur** - Teste la page réellement rendue, pas seulement le code source, garantissant des résultats précis
• **Normes de l'organisation** - Respecte les paramètres de configuration axe de votre équipe pour des tests cohérents auprès de tous les utilisateurs
• **Couverture complète** - Utilise la plateforme axe leader du secteur
• **Tests réactifs** - Testez à des dimensions de fenêtre spécifiques pour détecter les problèmes d'accessibilité spécifiques aux points de rupture
• **Pages authentifiées et interactives** - Analysez les pages derrière une connexion, fermez les bannières de cookies ou attendez le contenu dynamique en utilisant before des actions

Sortie

L'outil renvoie une réponse JSON structurée contenant :

• Toutes les violations d'accessibilité trouvées
• Niveaux de gravité des violations (critique, grave, modéré, mineur)
• Sélecteurs d'éléments spécifiques et code source
• Identifiants et descriptions des règles

L'outil remediate outil

L'outil remediate outil prend tout problème d'accessibilité identifié par axe et génère des conseils de remédiation contextuels, alimentés par l'IA, que les agents de codage peuvent traduire en corrections de code réelles.

Fonctionnalités

1. **Validation de la clé API** - Valide la clé API de l'utilisateur pour garantir un accès autorisé
2. **Utilisation de crédits d'IA** - Chaque remediate appel consomme des crédits d'IA de l'allocation de votre organisation, permettant l'utilisation de modèles d'IA avancés formés sur l'expertise approfondie de Deque en matière d'accessibilité
3. **Remédiation générée par l'IA** - Crée une correction d'accessibilité de haute qualité et exploitable que les agents de codage peuvent interpréter et implémenter dans le code source

Sortie

L'outil renvoie des conseils de remédiation structurés qui incluent :

• Résumé de haut niveau de la correction requise
• Modifications de code spécifiques nécessaires (en format HTML)
• Raisonnement sur l'accessibilité et critères WCAG
• Contexte supplémentaire pour garantir une mise en œuvre correcte

Utilisation de crédits

L'outil remediate outil fait partie du Système de gestion des crédits d'IA. Chaque demande de remédiation consomme des crédits de l'allocation mensuelle de votre organisation. Les administrateurs peuvent surveiller l'utilisation des crédits via le portail de comptes axe.

Installation et configuration

Prérequis

• Docker installé et fonctionnant sur votre système
• Agent AI configuré pour le serveur axe MCP (voir Configuration ci-dessous pour les instructions de configuration spécifiques à l'IDE)
• Un abonnement permettant l'accès au serveur axe MCP en contactant un représentant commercial de Deque

Étape 1 : Configurer l'authentification

Le serveur axe MCP prend en charge deux méthodes d'authentification.

Option A : Clé API

1. Connectez-vous au portail de comptes axe
2. Accédez à la page Clés API
3. Cliquez sur **AJOUTER UNE NOUVELLE CLÉ API**
4. Sélectionnez **server axe MCP** en tant que produit
5. Entrez un nom descriptif pour votre clé API
6. Cliquez sur **Enregistrer**
7. Copiez la clé API générée pour l'utiliser dans l'étape suivante

Option B : OAuth 2.0

L'option B est l'authentification OAuth 2.0 via le @deque/axe-auth CLI. Voir Authentification OAuth 2.0 pour les instructions de configuration.

Étape 2 : Extraire l'image Docker

Initialement et chaque fois qu'une version mise à jour est publiée que vous souhaitez utiliser, vous devrez docker pull l'image du server axe MCP :

docker pull dequesystems/axe-mcp-server:latest

Étape 3 : Configuration

Choisissez votre IDE pour des instructions d'installation spécifiques :

• Installation dans VS Code avec Copilot
• Installation dans Cursor
• Installation dans Claude Code

Exemples d'invites

Assurer l'appel des outils attendus

Dans de nombreux IDE, utiliser la syntaxe suivante (préfixe "#") garantira que les outils du server axe MCP sont appelés comme prévu :

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

Analyser une URL localhost pour les problèmes d'accessibilité :

Analyze http://localhost:3000 for accessibility issues

Analyse avec remédiation :

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

Analyser une page derrière une connexion :

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.

Ignorer une bannière de cookies avant de scanner :

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

Configurer votre agent IA (recommandé)

Pour garantir que votre agent de codage IA utilise correctement les outils du server axe MCP et suive les meilleures pratiques d'accessibilité, vous pouvez lui fournir des instructions personnalisées. Ces instructions aident l'agent à comprendre le flux de travail approprié pour analyser et remédier aux problèmes d'accessibilité.

Où ajouter des instructions

La méthode varie selon le client :

• **VS Code avec GitHub Copilot** - Ajouter à .github/copilot-instructions.md à la racine de votre projet
• Cursor - Ajouter aux "Règles de Cursor" dans les paramètres
• **Claude Code** - Ajouter à un fichier CLAUDE.md dans la racine de votre projet
• **Claude Desktop** - Ajouter 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:

- First use `remediate` tool for EACH violation found
- Provide the exact HTML element, rule ID, and issue description
- 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. For each violation: remediate → 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 cela importe-t-il

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 des LLM
• **Suit les meilleures pratiques** - Applique des corrections cohérentes et conformes aux normes WCAG plutôt que des solutions génériques
• **Vérifie les changements** - Confirme toujours que les correctifs ont réellement résolu les problèmes
• **Évite la fausse confiance** - Ne présume pas savoir comment résoudre les problèmes d'accessibilité sans conseils d'experts

Bien qu'optionnelles, ces instructions améliorent considérablement la qualité et la fiabilité des corrections d'accessibilité dans votre code.

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 qui utilisent l'instance commune US SaaS 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 régionale SaaS (UE, Australie, Francfort, etc.)
• Un cloud privé déploiement
• Une installation sur site installation

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éfinir AXE_SERVER_URL explicitement dans le env bloc de la configuration de votre serveur MCP. Les guides de configuration spécifiques à l'IDE pour VS Code avec Copilot et Cursor incluent des exemples montrant exactement où l'ajouter.

Dépannage

Problèmes courants

Le serveur ne démarre pas :

• Assurez-vous que Docker est en cours d'exécution
• Vérifiez que votre clé API est correcte
• Vérifiez que vous avez accès au serveur axe MCP (contactez le support si nécessaire)

Dépassements de temps d'analyse :

• Augmenter BROWSER_TIMEOUT_MS pour les pages complexes
• Assurez-vous que l'URL cible est accessible depuis votre réseau
• Vérifiez les problèmes de connectivité réseau

ERR_CONNECTION_REFUSED lors de l'analyse d'un serveur de développement local

Si l' analyze outil échoue avec une net::ERR_CONNECTION_REFUSED erreur lors de la tentative de scan d'un serveur de développement local, c'est probablement parce que axe MCP Server s'exécute à l'intérieur d'un conteneur Docker et ne peut pas atteindre les services liés uniquement à localhost (c'est-à-dire, 127.0.0.1) sur votre machine hôte.

Exemple d'erreur :

net::ERR_CONNECTION_REFUSED at http://192.168.65.2:5173/

Solution : Démarrez votre serveur de développement avec l'option --host configurée sur 0.0.0.0 afin qu'il écoute sur toutes les interfaces réseau, le rendant accessible depuis le conteneur Docker :

# Vite
npm run dev -- --host=0.0.0.0

# Webpack (webpack-dev-server)
npm run dev -- --host=0.0.0.0

Erreurs d'authentification

Clé API

• Vérifiez que votre clé API est valide et n'a pas expiré
• Assurez-vous que votre abonnement axe Account Portal inclut l'accès à MCP Server
• Vérifiez que la clé API a été créée pour le produit « axe MCP Server »
• Confirmez que seul AXE_API_KEY est défini — si AXE_ACCESS_TOKEN est également défini, le serveur échouera au démarrage
• Confirmez que l'URL de votre serveur axe est correcte — si votre organisation utilise une instance axe régionale, privée ou sur site, AXE_SERVER_URL doit être définie sur l'URL de base de votre instance. Voir Options de configuration pour plus de détails.

OAuth

• Confirmez que seul AXE_ACCESS_TOKEN est défini — si AXE_API_KEY est également défini, le serveur échouera au démarrage
• Exécutez npx @deque/axe-auth token dans votre terminal pour confirmer que vous avez un jeton valide ; s'il se termine avec un code différent de zéro, réauthentifiez-vous avec npx @deque/axe-auth login
• Confirmez que l'URL de votre serveur axe est correcte
• Si votre jeton a expiré en cours de session, redémarrez la connexion du serveur MCP dans votre IDE (par exemple, redémarrer Claude Code, basculer le serveur marche/arrêt dans les paramètres MCP de Cursor, ou cliquer sur le bouton "Redémarrer" de CodeLens de VS Code directement au-dessus de l'entrée du serveur axe MCP dans mcp.json) pour obtenir un nouveau jeton
• Voir Authentification OAuth 2.0 pour les étapes complètes de dépannage

Problèmes liés à Docker :

• Assurez-vous que le démon Docker fonctionne
• Vérifiez les permissions Docker
• Vérifiez la connectivité réseau pour les téléchargements d'images Docker
• Assurez-vous que Docker dispose de suffisamment de mémoire en exécutant une docker system prune

Obtenir de l'aide

Si vous rencontrez des problèmes non couverts dans cette section de dépannage :

1. Vérifiez la console développeur de VS Code pour des messages d'erreur détaillés
2. Consultez les journaux des conteneurs Docker pour obtenir des informations supplémentaires de débogage
3. Contactez notre équipe de support à helpdesk@deque.com avec :
   • Votre version de VS Code
   • Version de Docker
   • Messages d'erreur complets
   • Étapes pour reproduire le problème

Support

Pour des questions, problèmes, ou retours concernant le serveur axe MCP :

• Support technique: helpdesk@deque.com
• Demandes générales: helpdesk@deque.com
• Questions de vente: sales@deque.com

FAQ Sécurité et confidentialité

Le serveur axe MCP capture-t-il ou stocke-t-il notre code source ?

Non. Le serveur axe MCP ne capture ni ne stocke votre code source dans une base de données ou un stockage persistant.

Lorsque l'outil analyze s'exécute, la réponse inclut le code source HTML des éléments avec des problèmes d'accessibilité pour le contexte et le débogage. Cependant, ces données :

• Ne sont renvoyées que dans la réponse immédiate de l'API à votre agent IA
• Ne sont jamais conservées dans les bases de données gérées par Deque
• Restent dans votre environnement de développement local
• Sont supprimées après la fin de l'analyse

Combien de temps les résultats des tests MCP résident-ils sur l'infrastructure gérée par Deque ?

Ils ne résident pas. Les résultats des tests MCP ne sont pas conservés dans une base de données ou un système de stockage géré par Deque.

L'outil analyze :

• S'exécute entièrement dans le conteneur Docker sur votre machine
• Retourne les résultats directement à votre agent IA
• N'envoie pas les résultats d'analyse aux serveurs Deque

La seule exception est lorsque vous appelez l'outil remediate , qui peut inclure des métadonnées minimales de violation (voir ci-dessous) pour générer des conseils de correction alimentés par l'IA.

Quelles données sont envoyées aux serveurs Deque ?

Seulement en utilisant l'outil remediate :

Les données suivantes sont envoyées au point de terminaison de remédiation IA de Deque pour générer des conseils de correction :

• Identifiant de règle - La règle d'accessibilité spécifique qui a été violée
• HTML de l'élément - Le balisage HTML de l'élément(s) affecté(s)
• Métadonnées des problèmes - Description de la violation et orientation de correction de axe-core

Ces données sont utilisées exclusivement pour générer des conseils de correction et ne sont pas stockées à long terme dans les bases de données de Deque.

L'outil analyze ne transmet aucune donnée aux serveurs Deque au-delà des demandes de validation de la clé API.

Quel niveau d'accès l'agent IA doit-il avoir pour fonctionner ?

L'agent IA (Claude, Copilot, Cursor, etc.) doit avoir accès à :

1. Communication du serveur MCP - L'agent doit pouvoir appeler les outils du serveur MCP via le Model Context Protocol

2. Données de réponse de l'outil - L'agent reçoit :

   • Données de violation d'accessibilité depuis les appels analyze Appels
   • Guides de remédiation depuis les appels remediate Appels
   • Ces données sont nécessaires à l'agent pour comprendre les problèmes et générer des corrections de code

3. Votre code source (optionnel) - Si vous voulez que l'agent applique automatiquement des corrections de code, il doit avoir accès à vos fichiers de code source

• Ceci est standard pour les assistants de codage IA dans les IDE (VS Code, Cursor, etc.)
• Pas nécessaire si vous utilisez uniquement les outils pour l'analyse et les conseils (par exemple, via l'application Claude pour ordinateur)

Le serveur MCP lui-même doit avoir accès à :

• Les URL que vous spécifiez pour le test (prend en charge à la fois local et distant)
• Votre clé API axe (générée dans le portail de compte axe ; fournie via une variable d'environnement)

Important : Le serveur MCP fonctionne localement dans un conteneur Docker sur votre machine. Il ne nécessite pas d'accès étendu au système de fichiers ni de privilèges élevés au-delà de ce que Docker requiert.

Meilleures pratiques

• Sécurité des clés API - Stockez votre AXE_API_KEY comme une variable d'environnement, pas dans le code
• Tests locaux - Testez les URLs de développement local (localhost) ou de pré-production pour garder le code sensible isolé
• Isolement du réseau - Le serveur MCP ne communique qu'avec :
  • les URLs que vous demandez explicitement d'analyser
  • les serveurs Deque pour la validation des clés API et la remédiation (lorsqu'ils sont appelés)
  • votre agent IA local via le protocole MCP
• Revoir avant d'appliquer - Vérifiez toujours les modifications de code générées par l'IA avant de les valider dans votre code source