Plugin Claude Code

Panoramica

Il plugin Axe Accessibility è il toolkit di accessibilità di Deque per agenti di codifica, installato ed eseguito da Claude Code. L'installazione esegue tre azioni contemporaneamente:

• Registra il server. Il plugin fornisce un'entrata server MCP già pronta, quindi non è necessario scrivere a mano un .mcp.json.
• Insegna a Claude come utilizzare gli strumenti. Una competenza di background si carica automaticamente in lavori sull'accessibilità, così Claude segue il ciclo analizza → rimediezione → verifica, raggruppa correttamente remediate e mappa i campi tra gli strumenti senza indovinare.
• Aggiunge tre comandi slash per la configurazione, generare istruzioni agent al livello del repository, ed eseguire l'intero ciclo di rimediezione su una pagina.

Il plugin è open source su github.com/dequelabs/axe-accessibility ed è concesso in licenza MIT.

Non è solo per Claude Code

Claude Code è dove il plugin viene eseguito, ma due dei suoi comandi producono output per agenti e editor altri:

• /axe-accessibility:mcp-generate-instructions scrive il flusso di lavoro analizza → rimediezione → verifica dentro .github/copilot-instructions.md, regole Cursor, o AGENTS.md così come dentro CLAUDE.md. Chiunque nel team utilizzi Copilot o Cursor eredita il flusso di lavoro dal repository, che abbia o meno installato il plugin — o Claude Code.
• /axe-accessibility:mcp-setup può configurare il Axe MCP Server per Cursor, VS Code con Copilot, o Claude Desktop, non solo Claude Code.

Quindi è ragionevole installare il plugin puramente come strumento di configurazione e scrittura istruzioni per un repository i cui contributori usano una varietà di agenti.

Requisiti

Per installare il plugin:

• Claude Code con supporto plugin.

Per eseguire le scansioni — ovvero, per utilizzare gli strumenti analyze, igt, e remediate, sia da Claude Code o da un altro client configurato dal plugin:

• Un abbonamento Axe DevTools per il Web che include l'accesso all'Axe MCP Server. Senza di esso, gli strumenti non riusciranno ad autenticarsi.
• Un runtime, a seconda di quale distribuzione utilizzi:
  • npm (cosa porta il plugin): Node.js 22.19.0 o successivo, più un'installazione una-tantum di Chromium. Vedi Installa Chromium — il server non non scarica un browser per te, e saltare questo passaggio è l'errore più comune al primo avvio.
  • Docker: Docker installato e funzionante. Chromium viene fornito all'interno dell'immagine.
• Per l'autenticazione OAuth 2.0: un rilascio LTS attivo di Node.js, poiché la configurazione chiama npx @deque/axe-auth.

Solo il primo si applica se stai installando il plugin unicamente per eseguire /axe-accessibility:mcp-generate-instructions — la scrittura di file di istruzioni per agenti non necessita né di un runtime né di un abbonamento.

Installazione

Aggiungi il marketplace di Deque e installa il plugin all'interno di Claude Code:

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

Il primo comando registra il repository dequelabs/axe-accessibility come un marketplace per plugin (il repository funge anche da marketplace). Il secondo installa il plugin da esso. Devi aggiungere il marketplace solo una volta — le installazioni e gli aggiornamenti successivi possono saltare questo passaggio.

Riavvia Claude Code quando richiesto in modo che il server MCP si carichi.

Autenticazione

La configurazione del server inclusa nel plugin è indipendente dall'autenticazione: al momento dell'avvio cerca di generare un token di accesso OAuth e si assicura che esattamente uno credenziale raggiunga il server — il token OAuth se sei connesso, altrimenti il tuo AXE_API_KEY.

Scegli il metodo che ti conviene:

• Chiave API — crea una nel Portale account Axe sotto Chiavi API → AGGIUNGI NUOVA CHIAVE API, scegliendo il prodotto Server Axe MCP. Poi esportala nella tua shell affinché Claude Code possa leggerla:

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

  Aggiungi la linea al profilo della tua shell (~/.bashrc, ~/.zshrc, ecc.) per conservarla. Non registrare mai la chiave in un file nel tuo repository.

• OAuth 2.0 — accedi una volta con la CLI di @deque/axe-auth:

  npx -y @deque/axe-auth login

  Questo apre un browser per il flusso PKCE e memorizza i token nel portachiavi del tuo OS, aggiornandoli automaticamente. Vedi Autenticazione per il flusso completo, la gestione delle sessioni e il supporto della piattaforma.

La configurazione inclusa gestisce questa regola per te, e deve lavorare più duramente rispetto a una configurazione Docker. Un container riceve solo le variabili passate con flag espliciti -e, ma la distribuzione npm eredita l'intero ambiente della tua shell — quindi una AXE_API_KEY esportata e una sessione OAuth attiva raggiungerebbero entrambe il server e lo fermerebbero dall'avviarsi. L'entry inclusa cancella prima qualsiasi AXE_ACCESS_TOKEN ereditata, poi, se può generare un nuovo token, elimina AXE_API_KEY prima di impostarlo. OAuth vince quando entrambi sono disponibili.

Distribuzioni private cloud e on-premises

La distribuzione npm eredita AXE_SERVER_URL dalla tua shell, quindi esportarla insieme alla tua credenziale è sufficiente:

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

Se utilizzi OAuth, fornisci anche lo stesso URL al momento dell'accesso: npx -y @deque/axe-auth login --server https://your-axe-instance.example.com. Se AXE_SERVER_URL non è impostato, il server predefinito è https://axe.deque.com (istanza SaaS condivisa di Deque negli Stati Uniti). Vedi Riferimento alla configurazione.

Verifica dell'installazione

1. Riavvia Claude Code.

2. Esegui /mcp e conferma che axe-mcp-server è elencato e connesso, con gli strumenti analyze, igt e remediate disponibili.

3. Esegui una scansione di prova su una pagina nota:

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

Una scansione di successo di una pagina reale restituisce un payload considerevole — decine di kilobyte sono normali, non un errore. Se il tuo client si lamenta che il risultato è troppo grande, limita la scansione con il parametro analyze di selector.

Se il server non si connette, conferma la versione di Node, che Chromium sia installato, e che sia impostata esattamente una credenziale, quindi vedi Risoluzione dei problemi.

Cosa è incluso

L'abilità mcp-usage

Non invocare mai direttamente questa abilità. Si carica automaticamente ogni volta che un compito riguarda l'accessibilità, la conformità a11y o WCAG, o la risoluzione di problemi di accessibilità nell'interfaccia utente web, e fornisce a Claude la conoscenza operativa che altrimenti deve essere scritta manualmente in un CLAUDE.md:

• Il flusso di lavoro. Analizza la pagina, correggi le violazioni, quindi riesamina per verificare che non ci siano violazioni prima di considerare il lavoro completato.
• Mappatura del campo. Come ogni problema da analyze si mappa sui parametri di remediate — la fonte più comune di errore quando un agente collega i due strumenti per congettura. Include le trappole: i problemi arrivano sotto l'array data della risposta, e il campo remediation di un problema è un oggetto di dati di controllo grezzi, non la stringa che vuole il parametro remediate.
• Batching. remediate richiede un array issues di 1–25 per chiamata, ciascuno con un id inventato dal chiamante. Una chiamata per scansione, non una per problema — una forma di chiamata per problema viene respinta immediatamente.
• Consapevolezza del credito. I crediti sono consumati per problema, non per chiamata, quindi il batching è il contratto piuttosto che uno sconto. Ripetere analyze per verificare non consuma nulla, quindi la verifica è economica.
• Quali risultati fidarsi. I problemi segnalati isAdvanced: true provengono da Regole Avanzate — AI e visione artificiale — e sono probabilistici, quindi richiedono conferma rispetto all'interfaccia reale. I risultati standard di axe-core (isAdvanced: false) sono deterministici e autorevoli.
• Test della tastiera. Quando ricorrere a igt e come la sua forma di problema differisce da quella di analyze.
• Sfumatura specifica della regola. Guida per regole che richiedono giudizio come image-alt, color-contrast, link-name/button-name e l'etichettatura dei moduli.

Dato che la competenza è sempre disponibile, le richieste in linguaggio semplice funzionano senza cerimonie:

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

Comandi

/axe-accessibility:mcp-setup

/axe-accessibility:mcp-setup [client]

Ti guida nel collegamento del Server Axe MCP, chiedendo delle decisioni anziché supporle. Facoltativamente, passa un client — claude-code, cursor, vscode o claude-desktop — per saltare quella domanda.

Il comando:

1. Chiede se vuoi npm o Docker distribuzione, quindi verifica quel runtime — la versione di Node e Chromium per npm, un demone in esecuzione per Docker.
2. Chiede se vuoi l'autenticazione Chiave API o OAuth 2.0, quindi guida attraverso la creazione di una chiave nel Portale Account o l'accesso al browser.
3. Scrive la configurazione corrispondente per il tuo client — fondendo qualsiasi configurazione MCP esistente invece di sovrascriverla. Per Claude Code sulla distribuzione npm, il server incluso nel plugin di solito rende questo passaggio non necessario.
4. Offre le impostazioni opzionali da sapere: AXE_SERVER_URL per il cloud privato, AXE_ADVANCED_RULES per un'impostazione predefinita di Regole Avanzate, e AXE_CHROME_PATH per riutilizzare un browser già esistente (solo npm).
5. Verifica la connessione ed esegue una scansione preliminare.

Utile anche se l'installazione del plugin registra già il server: eseguilo quando hai bisogno di configurare l'autenticazione per la prima volta, passare a Docker, puntare a un'istanza cloud privata, o configurare un editor diverso sulla stessa macchina. I frammenti di client che emette sono gli stessi documentati per VS Code con Copilot, Cursor e Claude Code — il comando semplicemente sceglie quello giusto e lo unisce alla configurazione esistente.

/axe-accessibility:mcp-generate-instructions

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

Scrive il flusso di lavoro obbligatorio analizza → rimedia → verifica nei file di istruzione dell'agente del tuo repository, così qualsiasi agente di codifica che lavora nel repo — non solo quello che ha il plugin installato — lo segue. Target:

Senza argomenti, il comando rileva quali di questi file esistono già e conferma il set con te prima di scrivere.

Ogni file riceve il contratto completo, non solo il ciclo: la regola di batching remediate, la mappatura dei campi, la distinzione di affidabilità deterministico-contro-avanzato, la sezione tastiera igt, e la nota sui crediti. I nomi degli strumenti sono adattati per target, poiché i client denominano gli strumenti MCP in modo diverso — ad esempio, Copilot si collega a mcp_axe-mcp-server_analyze, mentre Claude Code e Cursor risolvono nomi semplici.

I file esistenti sono fusi, non sovrascritti: se una sezione di flusso di lavoro sull'accessibilità è già presente, viene aggiornata sul posto, altrimenti la sezione viene aggiunta e il resto del file viene preservato. Il comando adatta anche le istruzioni al tuo repository dove possibile — ad esempio, riferendosi all'URL reale del dev-server del tuo progetto e al comando di avvio invece di un segnaposto.

/axe-accessibility:mcp-generate-instructions all

Generare all è la scelta usuale per un repository condiviso: una persona lo esegue una volta da Claude Code, commette i file, e ogni agente di collaboratore adotta il flusso di lavoro — Copilot da .github/copilot-instructions.md, Cursor da .cursor/rules/accessibility.mdc, e così via. Le istruzioni entrano in vigore solo per gli agenti che le leggono, e ogni collaboratore ha ancora bisogno che il Server Axe MCP sia collegato nel proprio client perché il flusso di lavoro funzioni effettivamente.

Questo è l'equivalente automatico del modello in Configurare il Tuo Agente AI.

/axe-accessibility:mcp-audit

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

Esegue l'intero ciclo di rimedio su una pagina e applica le correzioni al tuo codice sorgente. Passa l'URL completo incluso schema e porta. Se lo ometti, il comando tenta di rilevare un server di sviluppo in esecuzione dai tuoi script package.json e porte comuni, e conferma l'URL con te prima di effettuare la scansione.

Ogni giro:

1. Analizzare l'URL e raccogli i problemi.
2. Triagare a seconda del flag — i risultati isAdvanced vengono confermati rispetto all'interfaccia reale prima che venga modificato qualcosa, i risultati isNeedsReview vengono presentati a te invece di essere corretti automaticamente quando la chiamata è una decisione di design e i risultati isBestPractice non bloccano mai "pulito".
3. Rimediare ogni problema del giro in una singola chiamata in batch (fino a 25 per chiamata, divisi in batch sequenziali oltre a ciò).
4. Applicare le indicazioni al tuo codice sorgente, correlando ogni risultato indietro per id e controllando il suo stato, poiché un batch può fallire parzialmente. Le correzioni al codice suggerite sono adattate al vero componente invece di essere incollate alla lettera.
5. Ri-analizzare per verificare.

Il ciclo si ferma a zero violazioni o dopo max-rounds (predefinito 5). Si ferma anche in anticipo se un giro non fa progressi — a quel punto i problemi rimanenti in genere necessitano di una decisione progettuale, o sono falsi positivi di regole avanzate, che il comando segnala come tali anziché contorcere il tuo codice per raggiungere zero. Il progresso è riportato per giro (ad esempio, round 1: 7 → round 2: 2 → round 3: 0), e il comando riassume le modifiche al codice che ha effettuato in modo che tu possa rivederle prima di confermare.

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

Raggiungere una pagina che non è un semplice URL funziona come per lo strumento sottostante: descrivi un accesso o un'interazione e i passaggi vengono trasmessi come azioni before; descrivi l'instradamento dell'ambiente o una sessione pre-autenticata e vengono trasmessi come cookies, da applicare prima della navigazione. Conserva i segreti in un passaggio fill del value o nel value di un cookie, mai in un selettore o nel nome di un cookie.

Una volta che le violazioni automatizzate sono pulite, il comando può eseguire un'passaggio tastiera opzionale con igt — l'ordine del focus, le trappole del focus e la visibilità del focus sono invisibili a una scansione statica. Richiedila direttamente se la vuoi su una pagina con menu, dialoghi o widget personalizzati:

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

Flusso di lavoro suggerito

1. /axe-accessibility:mcp-setup — connetti e autentica il server. Verifica con /mcp.
2. /axe-accessibility:mcp-generate-instructions all — integra il flusso di lavoro nel repository in modo che ogni agente e collega lo erediti.
3. /axe-accessibility:mcp-audit http://localhost:3000 — risolvi il debito di accessibilità già presente sulla pagina.
4. Da quel momento in poi, continua solo a costruire. L'abilità mcp-usage mantiene Claude in esecuzione nel ciclo dei cambiamenti dell'interfaccia utente senza essere chiesto.

Gestione del plugin

Il comando /plugin di Claude Code gestisce il ciclo di vita del plugin:

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

La disinstallazione rimuove la voce del server MCP integrato insieme alle abilità e ai comandi. Eventuali file di istruzione degli agenti scritti da /axe-accessibility:mcp-generate-instructions rimangono nel tuo repository — rimuovili tu stesso se non li desideri più.

Pagine correlate

• Scelta di una Distribuzione — npm contro Docker e installazione di Chromium per npm
• Configurazione in Claude Code — configurare il server manualmente, senza il plugin
• Autenticazione — chiave API e OAuth 2.0 nella loro interezza
• Riferimento alla configurazione — variabili d'ambiente e modelli di istruzione per agenti
• Regole Avanzate — preset, precedenza e cosa significa il flag isAdvanced
• Risoluzione dei problemi — connessione, Chromium, Docker ed errori di autenticazione
• Crediti AI — come remediate e igt consumano crediti