Plugin Claude Code

Vue d'ensemble

Le Plugin d'accessibilité Axe est la boîte à outils d'accessibilité de Deque pour les agents de codage, installée et exécutée depuis Claude Code. L'installer fait trois choses à la fois :

• Enregistre le serveur. Le plugin fournit une entrée de serveur MCP prête à l'emploi, vous évitant ainsi d'écrire à la main un .mcp.json.
• Apprend à Claude à utiliser les outils. Une compétence en arrière-plan se charge automatiquement sur le travail d'accessibilité, ce qui permet à Claude de suivre le cycle analyser → remédier → vérifier, de regrouper remediate correctement, et de mapper les champs entre les outils sans deviner.
• Ajoute trois commandes slash pour la configuration, la génération d'instructions d'agent au niveau du dépôt, et l'exécution du cycle complet de remédiation sur une page.

Le plugin est open source sur github.com/dequelabs/axe-accessibility et est sous licence MIT.

Ce n'est pas seulement pour Claude Code

Claude Code est l'endroit où le plugin fonctionne, mais deux de ses commandes produisent un résultat pour les agents et éditeurs d'autres :

• /axe-accessibility:mcp-generate-instructions écrit le flux de travail analyser → remédier → vérifier dans .github/copilot-instructions.md, les règles de Cursor, ou AGENTS.md aussi facilement que dans CLAUDE.md. Toute personne de l'équipe utilisant Copilot ou Cursor hérite du flux de travail depuis le dépôt, qu'elle ait ou non le plugin — ou Claude Code — installé.
• /axe-accessibility:mcp-setup peut configurer le serveur MCP Axe pour Curseur, VS Code avec Copilot, ou Claude Desktop, pas seulement Claude Code.

Il est donc raisonnable d'installer le plugin uniquement en tant qu'outil de configuration et de rédaction d'instructions pour un dépôt dont les contributeurs utilisent un mélange d'agents.

Exigences

Pour installer le plugin :

• Claude Code avec support de plugin.

Pour exécuter des analyses — c'est-à-dire, utiliser les outils analyze, igt, et remediate, que ce soit depuis Claude Code ou depuis un autre client configuré par le plugin :

• Un abonnement Axe DevTools pour le Web qui inclut l'accès au serveur MCP Axe. Sans cela, les outils échoueront à s'authentifier.
• Un runtime, depending on which distribution you use:
  • npm (ce que le plugin offre) : Node.js 22.19.0 ou plus récent, plus une installation unique de Chromium. Voir Installer Chromium — le serveur ne pas télécharge pas un navigateur pour vous, et ignorer cette étape est la cause d'échec la plus courante au premier démarrage.
  • Docker : Docker installé et en cours d'exécution. Chromium est inclus dans l'image.
• Pour l'authentification OAuth 2.0 : un version LTS active de Node.js, car la configuration appelle npx @deque/axe-auth.

Seule la première s'applique si vous installez le plugin uniquement pour exécuter /axe-accessibility:mcp-generate-instructions — rédiger des fichiers d'instruction d'agent ne nécessite ni runtime ni abonnement.

Installation

Ajoutez le marketplace de Deque et installez le plugin depuis Claude Code :

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

La première commande enregistre le dépôt dequelabs/axe-accessibility comme un marketplace de plugin (le dépôt sert également de marketplace). La deuxième installe le plugin depuis celui-ci. Vous n'avez besoin d'ajouter le marketplace qu'une seule fois — les installations et mises à jour ultérieures peuvent sauter cette étape.

Redémarrez Claude Code quand cela vous est demandé pour que le serveur MCP se charge.

Authentification

La configuration du serveur incluse dans le plugin est indépendant de l'authentification : au démarrage, il essaie de créer un jeton d'accès OAuth et s'assure qu'exactement un crédentiel atteint le serveur — le jeton OAuth si vous êtes connecté, sinon votre AXE_API_KEY.

Choisissez la méthode qui vous convient :

• clé API — créez-en une dans le Axe Account Portal sous Clés API → AJOUTER UNE NOUVELLE CLÉ API, en choisissant le produit Serveur Axe MCP. Ensuite, exportez-la dans votre shell afin que Claude Code puisse la lire :

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

  Ajoutez la ligne à votre profil de shell (~/.bashrc, ~/.zshrc, etc.) pour la conserver. Ne jamais soumettre la clé dans un fichier de votre dépôt.

• OAuth 2.0 — connectez-vous une fois avec le CLI @deque/axe-auth :

  npx -y @deque/axe-auth login

  Cela ouvre un navigateur pour le flux PKCE et stocke les jetons dans le trousseau de clés de votre système d'exploitation, les rafraîchissant automatiquement. Voir Authentification pour le flux complet, la gestion de session et la prise en charge de la plateforme.

La configuration incluse gère cette règle pour vous et elle doit travailler plus fort qu'une configuration Docker ne le ferait. Un conteneur ne reçoit que les variables passées avec des drapeaux -e explicites, mais la distribution npm hérite de l'ensemble de votre environnement shell — ainsi, un AXE_API_KEY exporté et une session OAuth active atteindraient autrement le serveur et l'empêcheraient de démarrer. L'entrée incluse efface d'abord tout AXE_ACCESS_TOKEN hérité, puis, si elle peut créer un nouveau jeton, elle désactive AXE_API_KEY avant de le définir. OAuth l'emporte lorsque les deux sont disponibles.

Déploiements en cloud privé et sur site

La distribution npm hérite AXE_SERVER_URL de votre shell, donc l'exporter avec votre crédentiel suffit :

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

Si vous utilisez OAuth, passez également la même URL lors de la connexion : npx -y @deque/axe-auth login --server https://your-axe-instance.example.com. Si AXE_SERVER_URL est non défini, le serveur utilise par défaut https://axe.deque.com (l'instance SaaS partagée de Deque aux États-Unis). Voir Référence de configuration.

Vérification de l'installation

1. Redémarrez Claude Code.

2. Exécutez /mcp et confirmez que axe-mcp-server est répertorié et connecté, avec les outils analyze, igt et remediate disponibles.

3. Exécutez une analyse préliminaire sur une page connue :

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

Une analyse réussie d'une page réelle renvoie une charge utile importante — des dizaines de kilooctets sont normales, et non une erreur. Si votre client se plaint que le résultat est trop grand, délimitez l'analyse avec le paramètre selector de analyze.

Si le serveur ne se connecte pas, vérifiez votre version de Node, que Chromium est installé, et qu'exactement un crédentiel est défini, puis consultez Dépannage.

Ce qui est inclus

La compétence mcp-usage

Vous ne l'invoquez jamais directement. Elle se charge automatiquement chaque fois qu'une tâche implique l'accessibilité, la conformité a11y, WCAG, ou la correction des problèmes d'accessibilité dans l'interface utilisateur web, et elle donne à Claude les connaissances opérationnelles qui devraient autrement être écrites à la main dans un CLAUDE.md :

• Le flux de travail. Analyser la page, remédier aux violations, puis ré-analyser pour vérifier qu'il n'y a plus de violations avant de considérer le travail terminé.
• Cartographie des champs. Comment chaque problème de analyze se mappe sur les paramètres de remediate — la source d'erreur la plus courante lorsque qu'un agent connecte les deux outils par tâtonnement. Cela inclut les pièges : les problèmes arrivent sous le tableau data de la réponse, et le champ propre d'un problème remediation est un objet de données de vérification brutes, pas la chaîne que le paramètre remediate attend.
• Regroupement. remediate prend un tableau issues de 1 à 25 par appel, chacun avec un id inventé par l'appelant. Un appel par analyse, pas un par problème — une forme d'appel par problème est rejetée d'emblée.
• Sensibilisation aux crédits. Les crédits sont consommés par problème, et non par appel, donc le regroupement fait partie du contrat plutôt qu'une remise. Relancer analyze pour vérifier ne consomme rien, donc la vérification est peu coûteuse.
• Les résultats à considérer. Les problèmes signalés isAdvanced: true proviennent de Règles avancées — l'IA et la vision par ordinateur — et sont probabilistes, il est donc nécessaire de les confirmer avec l'interface utilisateur réelle. Les résultats standard d'axe-core (isAdvanced: false) sont déterministes et font autorité.
• Test de clavier. Quand s'adresser à igt, et comment la forme du problème diffère de celle de analyze.
• Nuances spécifiques aux règles. Conseils pour les règles nécessitant un jugement, telles que image-alt, color-contrast, link-name/button-name, et l'étiquetage des formulaires.

Étant donné que la compétence est toujours disponible, les demandes en langage clair fonctionnent sans cérémonie :

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

Commandes

/axe-accessibility:mcp-setup

/axe-accessibility:mcp-setup [client]

Vous guide pour connecter le serveur Axe MCP, posant des questions sur les décisions plutôt que de les supposer. Vous pouvez éventuellement transmettre un client — claude-code, cursor, vscode, ou claude-desktop — pour éviter cette question.

La commande :

1. Demande si vous voulez npm ou Docker distribution, puis vérifie cet environnement d'exécution — version de Node et Chromium pour npm, un daemon en cours d'exécution pour Docker.
2. Demande si vous voulez clé API ou OAuth 2.0 authentification, puis guide la création d'une clé dans le portail de compte ou l'exécution de la connexion du navigateur.
3. Écrit la configuration correspondante pour votre client — en fusionnant dans toute configuration MCP existante au lieu de l'écraser. Pour Claude Code sur la distribution npm, le serveur inclus avec le plugin rend généralement cette étape inutile.
4. Propose les paramètres optionnels à connaître : AXE_SERVER_URL pour le cloud privé, AXE_ADVANCED_RULES pour une règle avancée par défaut, et AXE_CHROME_PATH pour réutiliser un navigateur que vous avez déjà (npm uniquement).
5. Vérifie la connexion et exécute un balayage rapide.

Utile même si installer le plugin enregistre déjà le serveur : exécutez-le lorsque vous avez besoin de configurer l'authentification pour la première fois, de passer à Docker, de pointer vers une instance de cloud privé, ou de configurer un éditeur différent sur la même machine. Les extraits de code client qu'il émet sont les mêmes que ceux documentés pour VS Code avec Copilot, Curseur, et Claude Code — la commande choisit simplement le bon et le fusionne dans votre configuration existante.

/axe-accessibility:mcp-generate-instructions

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

Écrit le workflow obligatoire analyser → remédier → vérifier dans les fichiers d'instructions de l'agent de votre référentiel, afin que tout l'agent de codage qui travaille dans le repo — pas seulement celui qui a installé le plugin — le suive. Cibles :

Sans argument, la commande détecte lesquels de ces fichiers existent déjà et confirme l'ensemble avec vous avant d'écrire.

Chaque fichier contient le contrat complet, pas seulement la boucle : la règle de regroupement remediate, le mapping des champs, la distinction de confiance déterministe-versus-avancée, la section igt du clavier, et la mention de crédit. Les noms des outils sont adaptés à la cible, car les clients définissent les outils MCP différemment — par exemple, Copilot se lie à mcp_axe-mcp-server_analyze, alors que Claude Code et Cursor résolvent des noms simples.

Les fichiers existants sont fusionnés, pas écrasés : si une section de workflow d'accessibilité est déjà présente, elle est mise à jour sur place, sinon la section est ajoutée et le reste du fichier est préservé. La commande adapte également les instructions à votre référentiel où elle le peut — par exemple, en faisant référence à l'URL réelle du serveur de développement de votre projet et à la commande de démarrage plutôt qu'à un espace réservé.

/axe-accessibility:mcp-generate-instructions all

Générer all est le choix habituel pour un référentiel partagé : une personne l'exécute une fois à partir de Claude Code, s'engage les fichiers, et chaque agent des contributeurs adopte le workflow — Copilot depuis .github/copilot-instructions.md, Cursor depuis .cursor/rules/accessibility.mdc, et ainsi de suite. Les instructions ne prennent effet que pour les agents qui les lisent, et chaque contributeur doit toujours avoir le Axe MCP Server connecté dans son propre client pour que le workflow se déroule réellement.

C'est l'équivalent automatisé du modèle dans Configurer votre agent AI.

/axe-accessibility:mcp-audit

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

Exécute le cycle complet de remédiation sur une page et applique les corrections à votre code source. Passez l'URL complète, y compris le schéma et le port. Si vous l'omettez, la commande essaie de détecter un serveur de développement en cours d'exécution à partir de vos scripts package.json et des ports courants, et confirme l'URL avec vous avant de procéder à l'analyse.

Chaque cycle :

1. Analyser l'URL et collecter les problèmes.
2. Triage par drapeau — les résultats isAdvanced sont confirmés contre l'interface utilisateur réelle avant qu'un changement ne soit effectué, les résultats isNeedsReview vous sont présentés plutôt que d'être corrigés automatiquement lorsque l'appel est une décision de conception, et les résultats isBestPractice ne bloquent jamais « propre ».
3. Corriger chaque problème du cycle dans un appel groupé unique (jusqu'à 25 par appel, répartis en lots séquentiels au-delà).
4. Appliquer les directives à votre code source, corrélant chaque résultat par id et vérifiant son statut, car un lot peut échouer partiellement. Les corrections de code suggérées sont adaptées au composant réel plutôt que collées telles quelles.
5. Ré-analyser pour vérifier.

La boucle s'arrête à zéro violation ou après max-rounds (par défaut 5). Elle s'arrête également prématurément si un cycle ne fait aucun progrès — à ce stade, les problèmes restants nécessitent généralement une décision de conception ou sont des faux positifs de règles avancées, que la commande signale comme tels plutôt que de contorsionner votre code pour atteindre zéro. Le progrès est rapporté par cycle (par exemple, round 1: 7 → round 2: 2 → round 3: 0), et la commande résume les modifications de code qu'elle a effectuées pour que vous puissiez les examiner avant de les valider.

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

Atteindre une page qui n'est pas une simple URL fonctionne comme pour l'outil sous-jacent : décrivez une connexion ou une interaction et les étapes sont transmises sous forme de Actions before ; décrivez le routage d'environnement ou une session pré-authentifiée et elles sont transmises sous forme de cookies, ce qui s'applique avant la navigation. Gardez les secrets dans une fill étape de value ou une value de cookie, jamais dans un sélecteur ou un nom de cookie.

Une fois que les violations automatisées sont nettoyées, la commande peut exécuter un Passe clavier optionnel avec igt — l'ordre de focus, les pièges de focus et la visibilité du focus sont invisibles pour une analyse statique. Demandez-le directement si vous le souhaitez sur une page avec des menus, des dialogues ou des widgets personnalisés :

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

Flux de travail suggéré

1. /axe-accessibility:mcp-setup — connectez et authentifiez le serveur. Vérifiez avec /mcp.
2. /axe-accessibility:mcp-generate-instructions all — intégrez le flux de travail dans le dépôt pour que chaque agent et coéquipier en hérite.
3. /axe-accessibility:mcp-audit http://localhost:3000 — nettoyez la dette d'accessibilité déjà présente sur la page.
4. À partir de là, continuez simplement à construire. La compétence mcp-usage garde Claude en train de boucler sur les changements UI sans qu'on le demande.

Gestion du plugin

La commande /plugin de Claude Code gère le cycle de vie du plugin :

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

La désinstallation supprime l'entrée du serveur MCP groupé avec les compétences et les commandes. Tous les fichiers d'instruction d'agent écrits par /axe-accessibility:mcp-generate-instructions restent dans votre dépôt — supprimez-les vous-même si vous n'en voulez plus.

Pages connexes

• Choisir une distribution — npm versus Docker, et installation de Chromium pour npm
• Configuration dans Claude Code — configuration manuelle du serveur, sans le plugin
• Authentification — clé API et OAuth 2.0 en entier
• Référence de configuration — variables d'environnement et modèles d'instruction d'agent
• Règles avancées — préréglages, préséance, et ce que signifie le drapeau isAdvanced
• Dépannage — erreurs de connexion, Chromium, Docker et authentification
• Crédits AI — comment remediate et igt consomment des crédits