Risoluzione dei problemi

Questa pagina copre problemi comuni per entrambe le Docker che npm. I problemi che riguardano solo una distribuzione sono contrassegnati di conseguenza.

Il server non si avvia

• Assicurarsi che Docker sia in esecuzione (distribuzione Docker) o che Chromium sia installato (distribuzione npm — vedi installazione di Chromium)
• Verificare che le credenziali siano corrette: o il tuo AXE_API_KEY o il tuo AXE_ACCESS_TOKEN, ma non entrambi (il server fallisce all'avvio se entrambi sono impostati)
• Verificare di avere accesso al server axe MCP (contattare il supporto se necessario)

Timeout durante la scansione

• Aumentare BROWSER_TIMEOUT_MS per pagine complesse
• Assicurarsi che l'URL di destinazione sia accessibile dalla rete
• Controllare eventuali problemi di connettività di rete

Scansione del server di sviluppo locale fallisce con ERR_CONNECTION_REFUSED

Questo si applica alla distribuzione Docker — con la distribuzione npm il server funziona direttamente sul tuo host e può raggiungere normalmente i servizi localhost.

Se lo strumento analyze fallisce con un errore net::ERR_CONNECTION_REFUSED durante il tentativo di scansione di un server di sviluppo in esecuzione locale, è probabile che questo accada perché il server axe MCP gira all'interno di un container Docker e non può raggiungere servizi legati 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 flag --host impostato su 0.0.0.0 per farlo ascoltare 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

Le regole avanzate non sono state eseguite

Controlla prima il blocco advancedRules nella risposta analyze — il campo source nomina il motivo:

Altre cose da controllare:

• Il parametro advancedRules non è offerto dal tuo agente. Lo strumento analyze lo offre solo quando le Regole Avanzate sono disponibili per la tua organizzazione. Riavvia la connessione al server MCP affinché il tuo client rileggi l'elenco degli strumenti dopo che l'accesso cambia.
• AXE_ADVANCED_RULES non ha avuto effetto. Conferma che il server sia effettivamente avviato con esso (un errore di battitura interrompe l'avvio — vedi AXE_ADVANCED_RULES), e che un argomento per chiamata advancedRules non prenda il sopravvento.
• I risultati avanzati mancano da data. I risultati avanzati che sono degradati a necessitano revisione sono filtrati a meno che Predefinito Necessita di Revisione sia abilitato in Configurazione axe. Controlla l'array messages della risposta per un messaggio di degrado.
• Le scansioni scadono dopo l'abilitazione delle Regole Avanzate. Aggiungono circa 15-20 secondi per scansione. Aumenta BROWSER_TIMEOUT_MS.
• Le regole avanzate hanno smesso di funzionare a metà sessione. Se Deque rifiuta una scansione perché le Regole Avanzate non sono disponibili per la tua organizzazione, il server smette di tentarle per il resto di quel process. Riavvialo dopo un cambio di abbonamento.

Vedi Regole Avanzate per la referenza completa.

Problemi con Docker

• Assicurarsi che il daemon Docker sia in esecuzione
• Controllare i permessi di Docker
• Verificare la connettività di rete per i download delle immagini Docker
• Assicurarsi che Docker abbia abbastanza memoria eseguendo un docker system prune

Installazione di Chromium (npm)

Questa sezione si applica alla distribuzione npm. La distribuzione Docker include il proprio browser, quindi gli utenti Docker non hanno bisogno di installare Chromium e non sono influenzati dagli errori qui descritti.

Cosa significa l'errore

Il server axe MCP esegue scansioni di accessibilità utilizzando un browser reale attraverso Playwright. Con la distribuzione npm, quel browser — Chromium — deve essere installato sul tuo host. Se manca, o se la versione installata non corrisponde alla revisione di Chromium che la versione di Playwright fornita dal server si aspetta, il server fallisce all'avvio (o al primo scan) con un errore che indica che Chromium non può essere avviato.

Questo è previsto in una nuova installazione ed è semplice da risolvere.

Soluzione standard

Installa la revisione Chromium corrispondente alla versione Playwright che il server MCP axe fornisce. Playwright deve essere bloccato, quindi un semplice npx playwright non si risolve in una versione più recente con una revisione di Chromium che il server non supporta:

npx playwright@$(npm view axe-mcp-server dependencies.playwright) install chromium

Poi riavvia il server MCP (o il tuo client MCP) e riprova.

Se esegui un server più vecchio bloccato, sostituisci la sua versione — npm view axe-mcp-server@<version> dependencies.playwright — o prendi il blocco dal messaggio di errore. Al momento della scrittura, la versione del server 1.4.0 fornisce Playwright 1.61.1.

Su Windows cmd.exe, che non ha sostituzione $(...), esegui npm view axe-mcp-server dependencies.playwright separatamente e incolla la versione. PowerShell, Git Bash e WSL gestiscono i comandi come scritti.

Seguito Linux

Su Linux, Chromium dipende anche da un numero di librerie di sistema che potrebbero non essere presenti. Se il browser continua a non avviarsi dopo la correzione standard, installa quelle dipendenze:

sudo npx playwright@$(npm view axe-mcp-server dependencies.playwright) install-deps chromium

Puoi anche combinare entrambi i passaggi in un unico comando:

sudo npx playwright@$(npm view axe-mcp-server dependencies.playwright) install --with-deps chromium

Usa un browser che hai già

Se hai già un binario di Chrome/Chromium compatibile sul tuo host, puoi evitare completamente l'installazione di Playwright impostando la variabile d'ambiente AXE_CHROME_PATH a quel binario. Questa è spesso la soluzione più rapida quando il download di Playwright è bloccato (rete limitata, proxy) o quando l'installazione delle dipendenze di sistema non è un'opzione. Vedi AXE_CHROME_PATH per i requisiti — nota che Google Chrome stabile con marchio 137+ non è supportato e il valore deve essere un binario eseguibile piuttosto che un pacchetto .app.

Perché Chromium non è incluso

Playwright associa un revisione specifica di Chromium a ciascuna versione di Playwright, e quella revisione cambia nel tempo. Includere un binario del browser nel pacchetto npm aumenterebbe significativamente la dimensione, legherebbe il pacchetto al binario di una singola piattaforma e diventerebbe obsoleto non appena Playwright aggiornasse la sua revisione fissata. Installare Chromium tramite Playwright garantisce invece di ottenere esattamente la revisione che la tua versione installata si aspetta, per la tua piattaforma. (La distribuzione Docker può includere un browser perché l'immagine è costruita per un ambiente unico e noto.)

Re-esecuzione dopo un aggiornamento di axe-mcp-server

Aggiornare axe-mcp-server potrebbe portare a una versione più recente di Playwright, che può fissare un revisione più recente di Chromium diverso da quello attualmente installato. Quando ciò accade, potresti vedere nuovamente lo stesso errore di avvio dopo un aggiornamento. La soluzione è la stessa: rilancia l'installazione con la versione di Playwright fornita dal server aggiornato affinché Chromium sia compatibile:

npx playwright@$(npm view axe-mcp-server dependencies.playwright) install chromium

Poiché il blocco è derivato piuttosto che codificato, lo stesso comando resta corretto in occasione degli aggiornamenti. Rieseguilo ogni volta che aggiorni axe-mcp-server e il server segnala una discrepanza Chromium all'avvio.

Errori di autenticazione

Chiave API

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

OAuth

• Conferma che solo AXE_ACCESS_TOKEN sia impostato — se anche AXE_API_KEY è impostato, il server fallirà all'avvio
• Esegui npx @deque/axe-auth token nel tuo terminale per confermare di avere un token valido; se termina con un codice diverso da zero, ri-autenticati con npx @deque/axe-auth login
• Conferma che l'URL del server axe sia corretto
• Se il tuo token scade a metà sessione, la tua configurazione sta catturando un singolo token all'avvio. Avvia il server tramite @deque/axe-auth run invece, che aggiorna il token del server in esecuzione per te — vedi Mantenere una sessione lunga attiva
• Se axe-auth run segnala che l'aggiornamento del token non ha potuto raggiungere il server, la porta di aggiornamento non corrisponde: verifica che AXE_TOKEN_REFRESH_PORT e il nome di pubblicazione Docker -p 127.0.0.1:<port>:<port> siano la stessa porta, e che il container imposti AXE_TOKEN_REFRESH_HOST=0.0.0.0. Vedi Variabili di aggiornamento del token
• Vedi Autenticazione per tutti i passi di risoluzione dei problemi OAuth

Ottenere aiuto

Se incontri problemi non coperti in questa sezione di risoluzione dei problemi:

1. Controlla la console/silog dell'utente sviluppatore del tuo client MCP per messaggi di errore dettagliati (ad esempio, la Console Sviluppatore di VS Code, gli Strumenti per sviluppatori di Cursor o l'output di --debug di Claude Code)
2. Controlla i log del server — i log del container Docker, o i log del client MCP quando usi la distribuzione npm
3. Contatta il nostro team di supporto a helpdesk@deque.com con:
   • Il tuo client MCP e la sua versione
   • La tua versione di Docker (distribuzione Docker) o la versione di Node.js (distribuzione npm)
   • Messaggi di errore completi
   • Passaggi per riprodurre il problema