**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 tre funzionalità - analyze, remediate e igt.

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

Accesso

Axe MCP Server è incluso nel pacchetto bundle Axe DevTools per Web. Una sottoscrizione che abilita l'accesso all'axe MCP Server viene attivata contattando un rappresentante commerciale di Deque.

Strumenti e Capacità

Lo Strumento analyze

Lo strumento analyze esegue un'analisi completa dell'accessibilità sulle pagine web effettuando una scansione tramite l'estensione axe DevTools Browser in un ambiente browser reale. Funziona senza problemi sia con gli URL di sviluppo locale (ad es. localhost:3000) che con URL di produzione remota.

Cosa Fa

1. Autenticazione - Valida le credenziali dell'utente (ovvero una chiave API o un token di accesso OAuth 2.0) per garantire un accesso autorizzato
2. Recupero Configurazione - Recupera le impostazioni specifiche dell'organizzazione dell'utente Configurazione axe, inclusi:
   • 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 verso l'URL fornito dall'utente nel loro prompt all'agente AI
5. Scansione di Accessibilità - Esegue un'analisi completa dell'accessibilità sulla pagina pagina visualizzata utilizzando l'estensione axe DevTools Browser, garantendo che l'esperienza utente effettiva venga testata (non solo l'HTML statico)
6. Consegna dei Risultati - Restituisce i risultati dell'analisi completi all'agente in un formato strutturato

Test reattivo

Lo strumento analyze supporta parametri opzionali viewportWidth e viewportHeight, consentendo di testare le pagine a dimensioni specifiche del viewport. Questo è utile per rilevare problemi di accessibilità che compaiono solo a determinate dimensioni dello schermo, come i punti di interruzione per dispositivi mobili 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.

Scansioni Parziali della Pagina

Per impostazione predefinita, lo strumento analyze esegue la scansione dell'intera pagina. Per delimitare la scansione a una regione specifica, passa il parametro facoltativo selector — utile per concentrarsi su un singolo componente o escludere parti della pagina rumorose e non correlate dai risultati.

• Una singola stringa di selettore CSS individua un elemento nel frame superiore:

  {
    "url": "http://localhost:3000",
    "selector": "#main"
  }

• Un array di selettori CSS passa attraverso i limiti di iframe o shadow-DOM — ogni segmento seleziona l'host per il successivo. Usa un array solo quando l'obiettivo si trova all'interno di un iframe o di una radice shadow:

  {
    "url": "http://localhost:3000",
    "selector": ["iframe#checkout", "#payment-form"]
  }

Un array supporta fino a 10 segmenti. Se il selettore non corrisponde ad alcun elemento sulla pagina, la scansione restituisce un errore. Quando selector viene omesso, viene scansionata l'intera pagina.

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

Scan only the #main region of http://localhost:3000 for accessibility issues

Interazioni del Browser Prima della Scansione

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

• Pagine con accesso limitato — inserire le credenziali e sottomettere prima di scansionare la pagina post-login
• Banners sui cookie/consenso — chiudere i banner che altrimenti coprirebbero o oscurerebbero il contenuto della pagina
• Contenuto dinamico — attendere che il contenuto client-rendered (cambi di percorso, DOM iniettato in ritardo) appaia prima di effettuare la scansione

I passaggi vengono eseguiti in ordine di array, nello stesso contesto del browser come la scansione, così i cookie, localStorage e qualsiasi cambiamento di percorso attivato da click o fill persiste nella scansione.

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

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

Iniezione di cookie

Lo strumento analyze supporta un array opzionale cookies che imposta i cookie sul contesto del browser prima della navigazione — in modo che accompagnino la prima richiesta alla pagina. Questo è distinto da before azioni, che viene eseguito dopo navigazione e quindi non può influenzare come viene instradata la richiesta iniziale. Due usi comuni:

• Instradamento dell'ambiente — imposta un cookie selettore di staging o di branch di funzionalità che un livello edge o CDN legge per decidere quale versione del sito servire.
• Sessioni pre-autenticate — inietta un cookie di sessione valido in modo che la scansione inizi già autenticata, senza dover gestire un modulo di login attraverso before.

L'array cookies supporta fino a 20 cookie.

Campi del cookie

Esempio: Accesso a una pagina pre-autenticata

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

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

L'agente risolve il valore del cookie e chiama lo strumento analyze con un payload simile a:

{
  "url": "https://app.example.com",
  "cookies": [
    {
      "name": "session",
      "value": "<resolved-from-.env.local>",
      "domain": "app.example.com"
    }
  ]
}

Vantaggi principali

• Test del browser reale - Testa la pagina effettivamente renderizzata, non solo il codice sorgente, assicurando risultati accurati
• Standard dell'organizzazione - Rispetta le impostazioni di configurazione di axe del tuo team per test coerenti tra tutti gli utenti
• Copertura completa - Sfrutta la piattaforma axe leader del settore
• Test reattivo - Testa a dimensioni specifiche del viewport per identificare problemi di accessibilità specifici del punto di interruzione
• Scansioni Mirate - Limita una scansione a una regione specifica, iframe o shadow root con il parametro selector
• Pagine Autenticate e Interattive - Scansiona pagine dietro un login, rimuovi i banner dei cookie o attendi contenuti dinamici utilizzando le azioni before
• Cookie di Sessione e Ambiente - Arriva già autenticato, o indirizza a un ambiente specifico, iniettando cookie prima della navigazione con il parametro cookies

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 Strumento remediate

Lo strumento remediate prende uno o più problemi di accessibilità identificati dallo strumento analyze o igt e genera suggerimenti di rimedio contestualizzati e potenziati dall'AI che gli agenti di codifica possono tradurre in correzioni di codice effettive. I problemi vengono inviati in gruppo, quindi una singola chiamata può restituire correzioni per ogni violazione trovata su una pagina.

Cosa Fa

1. Autenticazione - Convalida le credenziali dell'utente — una chiave API o un token di accesso OAuth 2.0 — per garantire l'accesso autorizzato
2. Uso di Crediti AI - Ogni problema nel gruppo consuma crediti AI dall'allocazione della tua organizzazione, consentendo 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

Rimediazione del Batch

Lo strumento accetta un array issues. Invia tutti i problemi da un singolo analyze o igt eseguiti insieme in una chiamata piuttosto che chiamare lo strumento una volta per problema — un batch supporta tra 1 e 25 problemi.

Ogni problema ha i seguenti campi:

Invita il tuo agente AI in linguaggio naturale — assembla il batch dai risultati dell'analisi:

Analyze http://localhost:3000 and remediate every issue found

L'agente risolve il prompt e chiama lo strumento remediate con un payload simile a:

{
  "issues": [
    {
      "id": "color-contrast-0",
      "rule": "color-contrast",
      "elementHtml": "<span style=\"color: #aaa\">Sign up</span>",
      "remediation": "Increase the contrast ratio to at least 4.5:1",
      "pageUrl": "http://localhost:3000"
    },
    {
      "id": "image-alt-1",
      "rule": "image-alt",
      "elementHtml": "<img src=\"logo.png\">",
      "remediation": "Add alt text describing the image"
    }
  ]
}

Output

Lo strumento restituisce un array di risultati per problema, ciascuno associato al suo input tramite id. Un risultato è di una delle due forme:

• Successo — status: "ok", con un oggetto remediation contenente una descrizione generale, i passaggi di rimedio e una correzione di codice concreta
• Errore — status: "error", con un oggetto error (code e message) per un problema che non ha potuto essere risolto

{
  "data": [
    {
      "id": "color-contrast-0",
      "status": "ok",
      "remediation": {
        "general_description": "...",
        "remediation": "...",
        "code_fix": "<span style=\"color: #595959\">Sign up</span>"
      }
    },
    {
      "id": "image-alt-1",
      "status": "error",
      "error": { "code": "LLM_ERROR", "message": "..." }
    }
  ]
}

I risultati sono indipendenti: un fallimento in un problema non blocca le indicazioni per gli altri.

Utilizzo del Credito

Lo strumento remediate fa parte del Sistema di Gestione dei Crediti AI. Ogni problema in un batch consuma crediti dalla tua allocazione mensile. Gli amministratori possono monitorare l'uso dei crediti tramite il Portale account axe.

Lo Strumento igt

Lo strumento igt esegue il Test Intelligenti Guidati Automatizzati (IGT) di Deque su una pagina web dal tuo IDE. Mentre l'estensione del browser axe DevTools normalmente guida uno sviluppatore attraverso un IGT con prompt manuali, lo strumento igt esegue il test automaticamente e restituisce risultati strutturati su cui un agente di codifica può agire.

Oggi lo strumento supporta il IGT Tastiera, che valuta se gli elementi interattivi su una pagina possono essere raggiunti e operati usando solo la tastiera.

Cosa Fa

1. Autenticazione - Convalida le credenziali dell'utente — una chiave API o un token di accesso OAuth 2.0 — per garantire l'accesso autorizzato
2. Esecuzione Basata su Browser - Testa nella stessa istanza di Chromium con l'estensione axe DevTools montata che lo strumento analyze utilizza
3. Navigazione della Pagina - Naviga all'URL fornito dall'utente nel loro prompt all'agente AI
4. IGT Tastiera Automatizzato - Passa attraverso le schede della pagina mentre l'IA analizza ogni fermata, valutando l'ordine del focus e l'operabilità tramite tastiera—non è richiesto input manuale
5. Consegna dei Risultati - Ritorna i risultati strutturati all'agente

Uso

Lo strumento accetta un array url e un array igtTools che nominano quali IGT eseguire. Attualmente, l'IGT Tastiera è l'unico valore supportato:

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"]
}

Prompt del tuo agente AI in linguaggio naturale—l'agente trasforma la tua intenzione nella chiamata allo strumento:

Run the keyboard IGT on http://localhost:3000

Interazioni del Browser Prima del Test

Come lo strumento analyze, igt accetta un array opzionale before di passaggi di interazione che eseguono dopo il caricamento della pagina ma prima che il test guidato si avvii. Questo ti permette di eseguire un test guidato su pagine protette da login, chiudere banner dei cookie o aspettare che appaiano contenuti dinamici.

I passaggi vengono eseguiti nello stesso stesso contesto del browser del test (così i cookie, localStorage, e le modifiche del percorso persistono), usano le stesse azioni click, fill, e waitFor e sono limitati allo stesso 20 passaggi. Vedi Azioni supportate sotto lo strumento analyze per il riferimento completo, inclusa la gestione dei valori sensibili di fill.value e le regole dei selettori.

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"],
  "before": [
    { "action": "fill", "selector": "#username", "value": "<resolved-from-.env.local>" },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}

Output

Lo strumento restituisce una risposta JSON strutturata:

{
  "pageUrl": "http://localhost:3000",
  "data": {
    "keyboard": {
      "issues": [],
      "unanalyzedElements": [],
      "terminatedReason": "keyboard-trap"
    }
  }
}

• issues - Violazioni dell'accessibilità tramite tastiera trovate durante l'esecuzione
• unanalyzedElements - Fermate tab che l'IA non ha potuto analizzare. Queste sono riportate separatamente da issues in modo che possano essere riviste manualmente, piuttosto che essere erroneamente riportate come passate o fallite.
• terminatedReason - Presenta solo quando l'esecuzione è stata interrotta prima che ogni fermata fosse analizzata. Il valore attuale è "keyboard-trap", il che significa che il test ha incontrato una trappola della tastiera da cui non poteva uscire; i passaggi rimanenti sono interrotti e le fermate tab analizzate fino a quel punto vengono restituite in issues.

Utilizzo del Credito

Lo strumento igt è una funzionalità potenziata dall'IA e fa parte di Sistema di Gestione dei Crediti AI. Ogni esecuzione consuma crediti IA dall'allocazione mensile della tua organizzazione. Gli amministratori possono monitorare l'uso dei crediti tramite il Portale Account axe.

Introduzione

Configurare il server axe MCP comporta tre scelte indipendenti:

1. Scegli una distribuzione — Docker o npm
2. Imposta l'autenticazione — una chiave API o OAuth 2.0
3. Configura il tuo client — VS Code con Copilot, Cursor, o **Claude Code**

Per le variabili d'ambiente e le istruzioni raccomandate per gli agenti IA, vedi Riferimento di Configurazione. Se qualcosa va storto, vedi Risoluzione dei problemi.

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.

Scansiona una pagina con un cookie di sessione iniettato:

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

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 axe MCP non cattura né memorizza il tuo codice sorgente in alcun database o archivio persistente.

Quando lo strumento analyze viene eseguito, la risposta include il codice sorgente HTML degli elementi problematici per il 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. risultati dei test MCP non sono memorizzati in alcun database o sistema di archiviazione gestito da Deque.

Lo strumento analyze:

• Funziona interamente sulla tua macchina — in un contenitore Docker, o come processo locale Node.js con la distribuzione npm
• Restituisce direttamente i risultati al tuo agente AI
• Non invia risultati di analisi ai server Deque

L'unica eccezione è quando chiami lo strumento remediate, che può includere metadati minimali sulle violazioni (vedi sotto) per generare guide di correzione potenziate dall'IA.

Quali dati vengono inviati ai server Deque?

Solo quando si utilizza lo strumento remediate:

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(i) interessato(i)
• Metadati del problema - Descrizione della violazione e guida alla correzione 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 strumento analyze non invia alcun dato ai server Deque oltre alle richieste di autenticazione (convalida la tua chiave API o il token di accesso OAuth 2.0).

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 Protocollo di Contesto del Modello

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

   • Dati sulle violazioni dell'accessibilità dalle chiamate analyze
   • Guida alla correzione dalle chiamate remediate
   • Questi dati sono necessari per l'agente per comprendere i problemi e generare correzioni al codice

3. Il tuo Codice (Opzionale) - Se si desidera che l'agente applichi automaticamente le correzioni di codice, deve avere 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)
• Le tue credenziali axe: o una chiave API (generata nel Portale Account axe) o un token di accesso OAuth 2.0 (ottenuto tramite @deque/axe-auth); fornito tramite variabile d'ambiente

Importante: Il server MCP funziona localmente sulla tua macchina - in un contenitore Docker, o come un processo Node.js con la distribuzione npm. Non richiede un ampio accesso al file system o privilegi elevati.

Best Practices

• Sicurezza delle Credenziali - Memorizza il tuo AXE_API_KEY o AXE_ACCESS_TOKEN come variabile d'ambiente, non nel codice. Con OAuth 2.0, @deque/axe-auth conserva i token nella tua chiave di sistema operativo e inietta un nuovo token di accesso all'avvio, quindi non è necessario che un segreto a lungo termine risieda nella tua configurazione
• Test Locale - Testa URL di sviluppo locale (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 l'autenticazione (convalida della chiave API o del token OAuth 2.0) e rimedio (quando chiamato)
  • Il tuo agente AI locale attraverso il protocollo MCP
• Revisione Prima di Applicare - Rivedi sempre le modifiche al codice generate dall'IA prima di integrarle nel tuo codice sorgente