Installare da Agora di Deque
Installare il server MCP di axe dal repository di artefatti Agora di Deque invece di npmjs.org o Docker Hub
Se la rete della vostra organizzazione limita l'accesso ai registri pubblici come npmjs.org e Docker Hub, potete ottenere il server MCP di axe da Agora. Entrambe le distribuzioni sono disponibili lì: i pacchetti npm e l'immagine Docker.
Agora è il repository di artefatti di Deque, ospitato su agora.dequecloud.com, dove Deque pubblica i pacchetti e le immagini che i suoi clienti installano. Si basa su Artifactory, quindi si comporta come qualsiasi altro registro npm o sorgente di artefatti che i vostri strumenti già comprendono, e la vostra organizzazione può farne un proxy dal proprio gestore di repository.
Questa guida copre specificamente il server MCP di axe. Per altri pacchetti di Axe DevTools, vedere Installare Axe DevTools per Web per Node.js da Agora di Deque.
Prerequisiti
- Credenziali di accesso ad Agora. Se non le avete, contattate il vostro rappresentante Deque o il servizio di supporto.
- Una distribuzione scelta — vedere Scegliere una Distribuzione.
- Per la distribuzione npm, Node.js versione 22.19.0 o successiva.
- Per la distribuzione Docker, Docker installato e in esecuzione.
Creare un Token d'Identità
Agora non autentica i download dei pacchetti con la password del vostro account. Invece, generate un Token d'Identità — una credenziale a lungo termine legata al vostro account — e usatelo come password ovunque queste istruzioni lo richiedano, incluse nel vostro .npmrc e nei comandi curl. Dovete crearlo solo una volta.
Il modo più semplice per creare un Token d'Identità è attraverso l'app web di Agora. Una volta effettuato l'accesso, createlo cliccando sul pulsante etichettato Benvenuto vostro-indirizzo-email nella barra superiore accanto al pulsante di aiuto.
I Token d'Identità scadono annualmente e possono essere visualizzati solo una volta, al momento della creazione. Conservatelo in un luogo sicuro.
Cosa Ospita Agora
Agora contiene gli stessi artefatti pubblicati nei registri pubblici, per le versioni stabili:
| Artefatto | Posizione in Agora |
|---|---|
axe-mcp-server (npm) |
devtools-npm repository npm |
@deque/axe-auth (npm) |
devtools-npm repository npm |
| Tar di immagini Docker | devtools-bin/axe-mcp-server/v<VERSION>/ |
Agora ospita i pacchetti propri di Deque — non è non uno specchio di npmjs.org. Il pacchetto axe-mcp-server dipende da playwright, e @deque/axe-auth dipende da alcuni pacchetti pubblici; quelle dipendenze si risolvono ancora da npmjs.org, o dal registro che il vostro gestore di pacchetti è configurato per utilizzare di default.
Se la vostra rete non può raggiungere npmjs.org in alcun modo, utilizzate Installazione tramite il tuo repository di artifact in modo che sia i pacchetti di Deque che le loro dipendenze pubbliche si risolvano tramite un registro che controllate.
Solo le versioni stabili sono pubblicate su Agora. Le build Canary (next) e le release candidate (rc) rimangono solo su npmjs.org.
Distribuzione npm
Aggiungere l'Autenticazione
Per accedere ai pacchetti Deque tramite npm o Yarn, aggiungete le informazioni di autenticazione di Agora al vostro file ~/.npmrc. Lo strumento Configurare l'Accesso ai pacchetti di Agora può generare questo contenuto per voi dalla vostra email di Agora e dal Token d'Identità. Altrimenti, generatelo con un comando curl:
curl -u "<your-email>" "https://agora.dequecloud.com/artifactory/api/npm/auth"Sostituite <your-email> con la vostra email di login ad Agora. curl richiede una password — incollate il Token d'Identità che avete creato sopra. Il comando restituisce:
_auth = <generated-auth-string>
always-auth = true
email = <your-email>Aprite il vostro ~/.npmrc per modificarlo e aggiungete il mapping del registro seguito dall'output del comando curl:
@deque:registry=https://agora.dequecloud.com/artifactory/api/npm/devtools-npm/
//agora.dequecloud.com/artifactory/api/npm/devtools-npm/:_auth=<generated-auth-string>
//agora.dequecloud.com/artifactory/api/npm/devtools-npm/:email=<your-email>
//agora.dequecloud.com/artifactory/api/npm/devtools-npm/:always-auth=trueSe non potete eseguire i comandi curl, generate la stringa di autenticazione manualmente facendo l'encoding base-64 di <your-email>:<your-identity-token>.
Non puntate la vostra impostazione registry= predefinita su Agora. Agora serve i pacchetti di Deque, non il più ampio ecosistema npm, quindi impostarlo come registro predefinito provoca il fallimento di installazioni non correlate.
Verifica del Vostro Accesso
Prima di installare qualsiasi cosa, confermate che le vostre credenziali funzionino e che il vostro account Agora possa vedere entrambi i pacchetti:
npm view @deque/axe-auth versions
npm view axe-mcp-server versions --registry=https://agora.dequecloud.com/artifactory/api/npm/devtools-npm/Ogni comando dovrebbe stampare un elenco di versioni pubblicate. Se uno dei due fallisce, vedere Risoluzione dei problemi sotto — risolverlo ora è più facile che diagnosticare nel mezzo di un'installazione.
Installazione di @deque/axe-auth
@deque/axe-auth — la CLI utilizzata per Autenticazione OAuth 2.0 — è un pacchetto con ambito, quindi la linea @deque:registry sopra è tutto ciò che serve. Ogni comando documentato axe-auth funziona senza modifiche, risolvendo da Agora anziché da npmjs.org:
npx @deque/axe-auth loginCiò significa anche che le configurazioni client MCP che avvolgono il server in npx -y @deque/axe-auth run non necessitano di modifiche.
Installazione di axe-mcp-server
axe-mcp-server è un pacchetto senza ambito, e npm può mappare i registri solo per ambito. Non esiste una linea .npmrc che possa instradare un singolo pacchetto senza ambito a Agora, quindi installalo invece dal suo tarball.
Scarica il tarball per la versione desiderata, sostituendo <version> con una versione rilasciata come 1.4.0 — vedi Note di rilascio. npm pack autentica con le credenziali già presenti nel tuo .npmrc, quindi non è necessario alcuno strumento di download separato o gestione di token:
npm pack axe-mcp-server@<version> --registry=https://agora.dequecloud.com/artifactory/api/npm/devtools-npm/Quindi installalo globalmente, il che aggiunge un comando axe-mcp-server sul tuo PATH:
npm install -g ./axe-mcp-server-<version>.tgzLa dipendenza playwright viene recuperata dal tuo registro predefinito durante questo secondo passaggio. Separare il download dall'installazione è ciò che mantiene funzionante quella risoluzione.
L'override --registry sopra è sicuro su npm pack perché quel comando recupera un singolo pacchetto e non risolve dipendenze. Non trasferirlo a npm install e non impostare npm_config_registry su Agora. Quelli si applicano all'intero albero delle dipendenze, quindi playwright viene richiesto anche da Agora e l'installazione fallisce con un errore 404.
Passare il flag tramite npx non funziona neanche. In una configurazione come "args": ["-y", "axe-mcp-server", "--registry=..."], tutto ciò che segue il nome del pacchetto viene inoltrato direttamente al server MCP di axe anziché a npx.
La distribuzione npm funziona su Node.js. Usa un release LTS attiva di Node.js — le versioni precedenti potrebbero non essere supportate.
Ricorda che anche la distribuzione npm ha bisogno di un browser Chromium. Vedi Installa Chromium, e nota che il comando lì trae la versione Playwright da npmjs.org. Per leggerla da Agora invece, aggiungi l'override del registro — npm view recupera un singolo pacchetto, quindi l'override è sicuro qui per lo stesso motivo che su npm pack:
npm view axe-mcp-server@<version> dependencies.playwright --registry=https://agora.dequecloud.com/artifactory/api/npm/devtools-npm/Configurazione del tuo client MCP
Poiché il server è installato globalmente piuttosto che recuperato su richiesta, chiama direttamente il comando installato invece di passare attraverso npx. Utilizzando VS Code con Copilot e una chiave API come esempio:
{
"servers": {
"axe-mcp-server": {
"command": "axe-mcp-server",
"args": [],
"env": {
"AXE_API_KEY": "your-api-key-here"
}
}
}
}Per OAuth 2.0, avvia il server tramite @deque/axe-auth run nello stesso modo in cui fanno le altre guide, sostituendo l'invocazione npx -y axe-mcp-server con il comando installato:
{
"servers": {
"axe-mcp-server": {
"command": "npx",
"args": ["-y", "@deque/axe-auth", "run", "--", "axe-mcp-server"],
"env": {
"AXE_TOKEN_REFRESH_PORT": "9223"
}
}
}
}Il rinnovo del token ha raggiunto il MCP Server ascia in v1.5.0. Installa la versione 1.5.0 o successiva per run avere un listener di refresh su cui inviare — una versione precedente si avvia, ma il suo token di accesso scade a metà sessione.
Imposta o AXE_API_KEY o AXE_ACCESS_TOKEN — non entrambi. Il server fallirà all'avvio se entrambe le variabili sono impostate.
Tutto il resto in guide di configurazione del client si applica come scritto — solo command e args differiscono. La stessa sostituzione funziona per Cursore e Claude Code.
Aggiornamento
Ripeti il download e l'installazione globale con il nuovo numero di versione. Controlla Note di rilascio per vedere cosa è disponibile.
Distribuzione Docker
Agora ospita l'immagine Docker come tars salvati, uno per architettura, a devtools-bin/axe-mcp-server/v<version>/.
Sostituisci <version> con una versione rilasciata come 1.4.0 e <arch> con l'architettura che corrisponde alla tua macchina — amd64 per Intel e AMD, arm64 per Apple silicon e ARM:
curl -u "<your-email>" \
-O "https://agora.dequecloud.com/artifactory/devtools-bin/axe-mcp-server/v<version>/axe-mcp-server-<version>-<arch>.tar"curl richiede una password — incolla il tuo Identity Token. Fornendolo invece in linea, come -u "<your-email>:<your-identity-token>", funziona anche ma lascia il token nella cronologia della tua shell.
Caricalo in Docker:
docker load -i axe-mcp-server-<version>-<arch>.tarL'immagine caricata è taggata con la sua versione, come dequesystems/axe-mcp-server:v<version> — non :latest. Riferisci quel tag nella configurazione del tuo client MCP, oppure taggala tu stesso:
docker tag dequesystems/axe-mcp-server:v<version> dequesystems/axe-mcp-server:latestCon l'immagine caricata, le configurazioni Docker in guide di configurazione del client funzionano senza modifiche. docker run utilizza l'immagine locale e non contatta Docker Hub.
Per aggiornare, scarica e carica il tar per la nuova versione.
Installazione tramite il tuo repository di artifact
Se la tua organizzazione gestisce già un repository di artifact come Artifactory o Nexus, fare da proxy a Agora attraverso di esso è solitamente l'opzione migliore. Gli sviluppatori non hanno quindi bisogno di credenziali Agora proprie, entrambi i pacchetti si risolvono normalmente, e — a differenza dell'approccio con tarball sopra — npx -y axe-mcp-server funziona come documentato ovunque:
Questa è la stessa connessione Agora utilizzata per gli altri pacchetti Axe DevTools, quindi si applicano le guide di configurazione esistenti — segui quella per il tuo gestore di repository, scegliendo il tipo di pacchetto npm e l'URL del registro npm https://agora.dequecloud.com/artifactory/api/npm/devtools-npm/:
Un'aggiunta specifica per il server axe MCP: poiché axe-mcp-server dipende da playwright, aggrega il repository remoto di Agora e il tuo esistente npmjs.org remoto in un unico repository virtuale, quindi indirizza registry= degli sviluppatori a quello. I pacchetti di Deque si risolvono quindi da Agora e le loro dipendenze pubbliche da npmjs.org attraverso un unico URL, e npx -y axe-mcp-server funziona esattamente come fa nei guide di configurazione del client.
Disponibilità delle versioni
Agora offre versioni stabili di entrambi i pacchetti npm, e il tag latest si risolve come ultima versione stabile, come su npmjs.org. I tag next e rc non sono disponibili; le build pre-rilascio rimangono disponibili solo da npmjs.org.
Se hai bisogno di una versione specifica, installala per versione esatta.
Risoluzione dei problemi
| Sintomo | Causa e soluzione |
|---|---|
401 Unauthorized da qualsiasi richiesta Agora |
La tua stringa di autenticazione è sbagliata o il tuo Identity Token è scaduto — durano un anno. Rigenera il token e la stringa di autenticazione. Se un token nuovo fallisce comunque, il tuo account Agora potrebbe non avere accesso al repository devtools-npm; contatta il tuo rappresentante Deque. |
404 Not Found per playwright o un'altra dipendenza |
Agora viene utilizzato per risolvere l'intero albero delle dipendenze. Rimuovi --registry dal tuo comando npm install e qualsiasi impostazione npm_config_registry, quindi installa dal pacchetto tarball come descritto sopra. |
TAR_BAD_ARCHIVE durante l'installazione del tarball |
Il file scaricato è una risposta di errore piuttosto che un pacchetto — ciò accade quando uno strumento di download salva il corpo di una richiesta fallita. Usa npm pack invece di scaricare il tarball tramite URL. |
| Il client MCP segnala che l'immagine Docker è mancante | Un tar caricato è etichettato con la sua versione, come dequesystems/axe-mcp-server:v1.4.0. Punta la tua configurazione verso quell'etichetta, oppure ri-etichetta l'immagine come :latest. |
Per problemi nell'esecuzione del server una volta installato, consulta la guida axe MCP Server Risoluzione dei problemi.
Passi successivi
- Imposta l'autenticazione — una chiave API o OAuth 2.0
- Configura il tuo client — VS Code con Copilot, Cursore, o Claude Code
Se hai difficoltà ad installare da Agora, contatta direttamente il tuo rappresentante Deque, chiedici tramite il nostro servizio di supporto, o mandaci un'email.