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

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 di Chromium che corrisponde alla versione di Playwright fornita dal server axe MCP — attualmente 1.60.0. Fissa Playwright a quella versione in modo che un semplice npx playwright non risolva in una nuova release con una revisione di Chromium che il server non supporta:

npx playwright@1.60.0 install chromium

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

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@1.60.0 install-deps chromium

Puoi anche combinare entrambi i passaggi in un unico comando:

sudo npx playwright@1.60.0 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@1.60.0 install chromium

Come regola generale, rilancia questo comando — usando la versione di Playwright che la release attuale fornisce — ogni volta che aggiorni axe-mcp-server e il server segnala un disallineamento di 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 è scaduto a sessione in corso, riavvia la connessione del server MCP nel tuo client (ad esempio, riavviando Claude Code, attivando e disattivando il server nelle impostazioni MCP di Cursor, o cliccando direttamente il pulsante "Restart" di CodeLens sopra l'entrata del server axe MCP in mcp.json) per ottenere un nuovo 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