**axe MCP Server**

Panoramica

Il Server axe MCP è un server Model Context Protocol (MCP) che integra il testing di accessibilità di livello enterprise direttamente nel tuo flusso di lavoro di sviluppo. Basato sulla consolidata piattaforma axe, consente agli sviluppatori di eseguire scansioni di accessibilità complete e ricevere guide di correzione esperta senza lasciare il loro IDE.

Il server fornisce due capacità principali - analyze e remediate.

Entrambi gli strumenti si integrano perfettamente con i client compatibili con MCP (come Claude Desktop, VS Code con Copilot o Cursor) e rispettano le impostazioni di configurazione axe della tua organizzazione.

Accesso

Il Server axe MCP è incluso nel bundle Axe DevTools per Web .

Strumenti e Capacità

Lo analyze Strumento

Lo analyze strumento esegue un'analisi completa dell'accessibilità delle pagine web effettuando una scansione tramite l'estensione del browser axe DevTools in un ambiente reale del browser. Funziona perfettamente con URL di sviluppo locale (es. localhost:3000) e URL di produzione remota.

Cosa Fa

1. Validazione della Chiave API - Valida la chiave API dell'utente per garantire l'accesso autorizzato
2. Recupero Configurazione - Recupera la configurazione specifica dell'organizzazione dell'utente Configurazione axe , includendo:
   • Standard di Testing dell'Accessibilità (es. WCAG 2.2 AA)
   • Versione axe-core
   • Necessità di revisione / buone pratiche
3. Analisi Basata su Browser - Avvia un'istanza del browser in background con l'estensione axe DevTools montata
4. Navigazione della Pagina - Naviga all'URL fornito dall'utente nel loro prompt all'agente AI
5. Scansione di Accessibilità - Esegue un'analisi completa dell'accessibilità sulla pagina visualizzata utilizzando l'estensione del browser axe DevTools, garantendo che l'esperienza utente reale sia testata (non solo l'HTML statico)
6. Consegna dei Risultati - Restituisce i risultati dell'analisi completa all'agente in un formato strutturato

Test reattivo

Lo analyze strumento supporta opzionalmente viewportWidth e viewportHeight parametri, permettendoti di testare le pagine a dimensioni specifiche del viewport. Questo è utile per rilevare problemi di accessibilità che appaiono solo a certe dimensioni dello schermo, come i punti di interruzione di mobile o tablet.

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

Quando questi parametri vengono omessi, il browser utilizza la dimensione predefinita del viewport.

Interazioni del Browser Prima della Scansione

Lo analyze strumento supporta un'opzionale before array di passaggi di interazione che vengono eseguiti dopo il caricamento della pagina ma prima della scansione di accessibilità. Questo sblocca diversi scenari di test nel mondo reale:

• Pagine con accesso limitato — inserire le credenziali e inviare prima di eseguire la scansione della pagina post-login
• Banners sui cookie/consenso — chiudere i banner che altrimenti sovrapporrebbero o oscurerebbero il contenuto della pagina
• Contenuto dinamico — attendere che compaia il contenuto generato dal client (cambi di rotta, DOM iniettato tardivamente) prima di eseguire la scansione

I passaggi vengono eseguiti nell'ordine dell'array, nello stesso contesto del browser della scansione, quindi i cookie, localStorage, e qualsiasi cambiamento di rotta attivato da click o fill persistono nella scansione.

Lo before supporta fino a 20 passaggi. Ogni passaggio ha il proprio timeout di BROWSER_TIMEOUT_MS (predefinito 30000 ms); non c'è sovrascrizione per singolo passaggio.

Azioni supportate

Esempio: Effettuare il login prima della scansione

Chiedi al tuo agente AI in linguaggio naturale — l'agente traduce le tue intenzioni nella chiamata allo strumento:

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'agente risolve il prompt e chiama lo strumento analyze con un payload simile a:

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

Vantaggi principali

• Test del browser reale - Testa la pagina realmente renderizzata, non solo il codice sorgente, garantendo risultati accurati
• Standard dell'organizzazione - Rispetta le impostazioni di configurazione axe del tuo team per test coerenti su tutti gli utenti
• Copertura completa - Sfrutta la piattaforma axe leader del settore
• Test reattivo - Testa a specifiche dimensioni di viewport per individuare problemi di accessibilità specifici dei breakpoint
• Pagine Autenticate e Interattive - Scansiona pagine dietro un login, chiudi i banner dei cookie o attendi il caricamento di contenuti dinamici utilizzando before azioni

Output

Lo strumento restituisce una risposta JSON strutturata contenente:

• Tutte le violazioni dell'accessibilità riscontrate
• Livelli di gravità delle violazioni (critico, serio, moderato, minore)
• Selettori specifici degli elementi e codice sorgente
• ID delle regole e descrizioni

Lo remediate Strumento

Lo remediate strumento prende qualsiasi problema di accessibilità identificato da axe e genera indicazioni di rimedio consapevoli del contesto, basate sull'IA, che gli agenti di codifica possono tradurre in correzioni di codice effettive.

Cosa Fa

1. Validazione della Chiave API - Valida la chiave API dell'utente per garantire l'accesso autorizzato
2. Utilizzo dei Crediti AI - Ogni remediate chiamata consuma crediti AI dall'allocazione della tua organizzazione, permettendo l'uso di modelli AI avanzati addestrati sull'ampia esperienza di accessibilità di Deque
3. Correzioni Generate dall'IA - Crea correzioni di accessibilità di alta qualità e azionabili che gli agenti di codifica possono interpretare e implementare nel codice sorgente

Output

Lo strumento restituisce indicazioni di rimedio strutturate che includono:

• Riassunto di alto livello della correzione richiesta
• Specifici cambiamenti di codice necessari (in formato HTML)
• Motivazione dell'accessibilità e criteri WCAG
• Contesto aggiuntivo per garantire una corretta implementazione

Utilizzo del Credito

Lo remediate strumento fa parte del Sistema di Gestione dei Crediti AI. Ogni richiesta di rimedio consuma crediti dall'allocazione mensile della tua organizzazione. Gli amministratori possono monitorare l'uso dei crediti tramite il Portale dell'Account axe.

Installazione e Configurazione

Prerequisiti

• Docker installato e in esecuzione sul tuo sistema
• Agente AI configurato per il server MCP di axe (vedi Configurazione qui sotto per le istruzioni di configurazione specifiche per IDE)
• Un abbonamento che consente l'accesso al server MCP di axe parlando con un rappresentante commerciale di Deque

Passo 1: Configurare l'autenticazione

Il server MCP di axe supporta due metodi di autenticazione.

Opzione A: Chiave API

1. Accedi al Portale dell'Account axe
2. Naviga alla pagina Chiavi API
3. Fai clic su AGGIUNGI NUOVA CHIAVE API
4. Seleziona **axe MCP Server** come prodotto
5. Inserisci un nome descrittivo per la tua chiave API
6. Fai clic su **Salva**
7. Copia la chiave API generata per utilizzarla nel passaggio successivo

Opzione B: OAuth 2.0

L'opzione B è l'autenticazione OAuth 2.0 tramite la @deque/axe-auth CLI. Vedi Autenticazione OAuth 2.0 per le istruzioni di configurazione.

Passo 2: Scarica l’immagine Docker

All'inizio e ogni volta che viene rilasciata una versione aggiornata che desideri utilizzare, dovrai docker pull l'immagine di axe MCP Server:

docker pull dequesystems/axe-mcp-server:latest

Passo 3: Configurazione

Scegli il tuo IDE per istruzioni specifiche di configurazione:

• Configurazione in VS Code con Copilot
• Configurazione in Cursor
• Configurazione in Claude Code

Esempi di prompt

Garantire il richiamo degli strumenti attesi

In molti IDE, l'uso della seguente sintassi (prefisso "#") garantirà che gli strumenti di axe MCP Server vengano chiamati come previsto:

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

Analizzare un URL localhost per problemi di accessibilità:

Analyze http://localhost:3000 for accessibility issues

Analisi con correzione:

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

Analizzare una pagina dietro un login:

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.

Disattivare un banner di cookie prima della scansione:

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

Configurare il tuo agente AI (Consigliato)

Per garantire che il tuo agente di codifica AI utilizzi gli strumenti di axe MCP Server correttamente e segua le migliori pratiche di accessibilità, puoi fornire istruzioni personalizzate. Queste istruzioni aiutano l'agente a comprendere il flusso di lavoro corretto per analizzare e risolvere i problemi di accessibilità.

Dove aggiungere le istruzioni

Il metodo varia in base al client:

• **VS Code con GitHub Copilot** - Aggiungi a .github/copilot-instructions.md nella radice del tuo progetto
• Cursor - Aggiungi a "Cursor Rules" nelle impostazioni
• **Claude Code** - Aggiungi a un CLAUDE.md file nella radice del tuo progetto
• **Claude Desktop** - Aggiungi alle istruzioni personalizzate nelle impostazioni
• **Altri client MCP** - Consulta la documentazione del tuo client per la configurazione delle istruzioni personalizzate

Esempio di istruzioni di flusso di lavoro

Di seguito è riportato un modello raccomandato che puoi adattare per il tuo 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:

- 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

Perché è importante

Queste istruzioni garantiscono che il tuo agente:

• **Utilizza l'esperienza di Deque** - Sfrutta modelli di AI addestrati su decenni di dati di valutazione dell'accessibilità invece della conoscenza generica dei LLM
• **Segue le migliori pratiche** - Applica correzioni coerenti e conformi al WCAG piuttosto che soluzioni generiche
• **Verifica le modifiche** - Conferma sempre che le correzioni abbiano effettivamente risolto i problemi
• **Evita la falsa sicurezza** - Non presume di sapere come risolvere i problemi di accessibilità senza una guida esperta

Anche se opzionale, fornire queste istruzioni migliora significativamente la qualità e l'affidabilità delle correzioni di accessibilità nel tuo codice.

Opzioni di configurazione

Il server MCP di axe supporta diverse variabili d'ambiente per la personalizzazione:

AXE_SERVER_URL

Il valore predefinito (https://axe.deque.com) è corretto per la maggior parte degli utenti — quelli sull'istanza condivisa SaaS negli Stati Uniti di Deque. Se la tua organizzazione utilizza una delle seguenti, devi impostare AXE_SERVER_URL all'URL base della tua istanza:

• Un regionale (UE, Australia, Francoforte, ecc.)
• Un cloud privato installazione
• Un'installazione on-premises

Se non sei sicuro di quale istanza utilizzi la tua organizzazione, verifica l'URL che utilizzi per accedere al portale dell'account axe o chiedi al tuo amministratore.

Imposta AXE_SERVER_URL esplicitamente nel blocco env della configurazione del server MCP. Le guide di configurazione specifiche dell'IDE per VS Code con Copilot e Cursor includono esempi che mostrano esattamente dove aggiungerlo.

Risoluzione dei problemi

Problemi comuni

Il server non si avvia:

• Assicurati che Docker sia in esecuzione
• Verifica che la tua chiave API sia corretta
• Controlla che tu abbia accesso al server MCP di axe (contatta il supporto se necessario)

Timeout durante la scansione:

• Aumenta BROWSER_TIMEOUT_MS per pagine complesse
• Assicurati che l'URL di destinazione sia accessibile dalla tua rete
• Controlla eventuali problemi di connettività di rete

ERR_CONNECTION_REFUSED quando si analizza un server di sviluppo locale

Se lo analyze strumento fallisce con un net::ERR_CONNECTION_REFUSED errore mentre tenta di scansionare un server di sviluppo in esecuzione locale, è probabile che axe MCP Server funzioni all'interno di un container Docker e non possa raggiungere servizi vincolati solo a localhost (cioè, 127.0.0.1) sulla tua macchina host.

Esempio di errore:

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

Soluzione: Avvia il tuo server di sviluppo con il --host flag impostato su 0.0.0.0 in modo che ascolti su tutte le interfacce di rete, rendendolo raggiungibile dall'interno del container Docker:

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

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

Errori di autenticazione

Chiave API

• Verifica che la tua chiave API sia valida e non sia scaduta
• Assicurati che l'abbonamento al tuo axe Account Portal includa l'accesso a MCP Server
• Controlla che la chiave API sia stata creata per il prodotto "axe MCP Server"
• Conferma che solo AXE_API_KEY è impostato — se AXE_ACCESS_TOKEN è anche impostato, il server fallirà all'avvio
• Conferma che l'URL del server axe sia corretto — se la tua organizzazione utilizza un'istanza regionale, cloud privato o on-premises di axe, AXE_SERVER_URL deve essere impostato sull'URL di base della tua istanza. Vedi Opzioni di configurazione per i dettagli.

OAuth

• Conferma che solo AXE_ACCESS_TOKEN è impostato — se AXE_API_KEY è anche impostato, il server fallirà all'avvio
• Esegui npx @deque/axe-auth token nel terminale per confermare di avere un token valido; se esce con un codice diverso da zero, riautenticati con npx @deque/axe-auth login
• Conferma che l'URL del server axe sia corretto
• Se il tuo token è scaduto durante la sessione, riavvia la connessione al server MCP nel tuo IDE (ad esempio, riavviando Claude Code, disattivando e riattivando il server nelle impostazioni MCP di Cursor o cliccando il pulsante "Riavvia" di CodeLens di VS Code direttamente sopra l'entrata del server MCP di axe in mcp.json) per ottenere un nuovo token
• Consulta Autenticazione OAuth 2.0 per i passaggi completi di risoluzione dei problemi

Problemi legati a Docker:

• Assicurati che il demone Docker sia in esecuzione
• Controlla i permessi di Docker
• Verifica la connettività di rete per i download delle immagini Docker
• Assicurati che Docker abbia abbastanza memoria eseguendo un docker system prune

Ottenere aiuto

Se riscontri problemi non trattati in questa sezione di risoluzione problemi:

1. Controlla la Developer Console di VS Code per messaggi di errore dettagliati
2. Rivedi i log del container Docker per informazioni di debug aggiuntive
3. Contatta il nostro team di supporto a helpdesk@deque.com con:
   • La tua versione di VS Code
   • Versione di Docker
   • Messaggi di errore completi
   • Passaggi per riprodurre il problema

Supporto

Per domande, problemi o feedback riguardanti axe MCP Server:

• Supporto tecnico: helpdesk@deque.com
• Richieste generali: helpdesk@deque.com
• Domande relative alle vendite: sales@deque.com

FAQ Sicurezza & Privacy

Il server axe MCP memorizza o cattura il nostro codice sorgente?

No. Il server MCP axe non acquisisce né memorizza il tuo codice sorgente in alcun database o sistema di archiviazione persistente.

Quando lo analyze strumento viene eseguito, la risposta include il codice sorgente HTML degli elementi con problemi di accessibilità per contesto e scopi di debug. Tuttavia, questi dati:

• Vengono restituiti solo nella risposta API immediata al tuo agente AI
• Non vengono mai memorizzati nei database gestiti da Deque
• Rimangono all'interno del tuo ambiente di sviluppo locale
• Vengono scartati dopo il completamento dell'analisi

Per quanto tempo i risultati dei test MCP sono conservati nell'infrastruttura gestita da Deque?

Non lo sono. I risultati dei test MCP non sono memorizzati in alcun database o sistema di archiviazione gestito da Deque.

Lo analyze strumento:

• Viene eseguito interamente all'interno del container Docker sulla tua macchina
• Restituisce direttamente i risultati al tuo agente AI
• Non invia risultati di analisi ai server Deque

L'unica eccezione è quando si chiama lo remediate strumento, che può includere un minimo di dati sulle violazioni (vedere sotto) per generare indicazioni di correzione potenziate dall'AI.

Quali dati vengono inviati ai server Deque?

Solo quando si utilizza lo remediate strumento:

I seguenti dati sono inviati al punto finale di rimedio AI di Deque per generare indicazioni di correzione:

• ID Regola - La specifica regola di accessibilità che è stata violata
• HTML dell'elemento - Il markup HTML dell'elemento o degli elementi interessati
• Metadati del problema - Descrizione della violazione e guida di rimedio da axe-core

Questi dati sono utilizzati esclusivamente per generare indicazioni di rimedio e non sono memorizzati a lungo termine nei database di Deque.

Lo analyze strumento non invia alcun dato ai server Deque oltre alle richieste di validazione della chiave API.

Quale livello di accesso è necessario affinché l'agente AI funzioni?

L'agente AI (Claude, Copilot, Cursor, ecc.) ha bisogno di accesso a:

1. Comunicazione con il Server MCP - L'agente deve essere in grado di chiamare gli strumenti del server MCP tramite il Model Context Protocol

2. Dati di risposta degli strumenti - L'agente riceve:

   • Dati di violazione di accessibilità da analyze chiamate
   • Guida di rimedio da remediate chiamate
   • Questi dati sono necessari per l'agente per comprendere i problemi e generare correzioni al codice

3. Il tuo Codice (Opzionale) - Se desideri che l'agente applichi automaticamente le correzioni al codice, è necessario l'accesso ai file del tuo codice sorgente

• Questo è standard per gli assistenti di codifica AI negli IDE (VS Code, Cursor, ecc.)
• Non necessario se usi solo gli strumenti per analisi e guida (ad esempio, tramite l'app desktop Claude)

Il server MCP stesso ha bisogno di accesso a:

• URL che specifichi per i test (supporta sia locali che remoti)
• La tua chiave API axe (generata nel Portale Account axe; fornita tramite variabile d'ambiente)

Importante: Il server MCP viene eseguito localmente in un container Docker sulla tua macchina. Non richiede un ampio accesso al file system né privilegi elevati oltre a quelli richiesti da Docker.

Best Practices

• Sicurezza della chiave API - Memorizza la tua AXE_API_KEY come variabile d'ambiente, non nel codice
• Test Locale - Testa gli URL di sviluppo locali (localhost) o di staging per mantenere isolato il codice sensibile pre-produzione
• Isolamento della Rete - Il server MCP comunica solo con:
  • URL che richiedi esplicitamente di analizzare
  • Server Deque per la convalida della chiave API e la risoluzione (quando richiesto)
  • Il tuo agente AI locale attraverso il protocollo MCP
• Revisione Prima di Applicare - Revisiona sempre le modifiche al codice generate dall'AI prima di integrarle nel tuo codebase