Riferimento alla Configurazione

Questa pagina documenta le variabili d'ambiente che l'axe MCP Server legge e le istruzioni personalizzate raccomandate per il tuo agente AI. Queste si applicano a entrambi i Docker e npm. Per sapere dove posizionare questi valori, consulta il tuo guida alla configurazione del client.

Opzioni di Configurazione

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

AXE_SERVER_URL

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

• Un istanza SaaS regionale (EU, Australia, Francoforte, etc.)
• Un'installazione cloud privato
• Un'installazione installazione on-premises

Se non sei sicuro di quale istanza utilizza la tua organizzazione, controlla l'URL che usi per accedere al portale dell'account axe oppure chiedi al tuo amministratore.

Imposta AXE_SERVER_URL esplicitamente nel blocco env della configurazione del tuo server MCP. I guide di configurazione del client includono esempi che mostrano esattamente dove aggiungerlo.

AXE_CHROME_PATH

Solo distribuzione npm. Questo non è supportato in Docker, che utilizza sempre il browser integrato — il server non si avvia se AXE_CHROME_PATH è impostato sotto la distribuzione Docker.

Di default, la distribuzione npm usa la build di Chromium che installi tramite Playwright. Imposta AXE_CHROME_PATH al percorso completo di un binario esistente di Chrome/Chromium per usare quello invece e saltare l'installazione di Playwright.

• Il valore deve essere un file binario eseguibile, non un pacchetto .app o una directory. Su macOS, ad esempio, punta al binario all'interno del pacchetto: /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• Il binario deve avviarsi e rispondere a --version. Il server lo valida all'avvio e fallisce rapidamente con Unable to find specified chrome instance se non ci riesce.
• La versione stabile 137 e successive di Google Chrome marchiato non è supportata. Usa Chrome for Testing o un altro binario compatibile con Chromium.

Gli strumenti analyze e igt accettano anche un argomento chromePath per chiamata, che ha la precedenza su AXE_CHROME_PATH per quella chiamata.

AXE_ADVANCED_RULES

Imposta il preset di confidenza Regole avanzate per ogni scansione eseguita da questo server, sovrascrivendo la configurazione predefinita di axe della tua organizzazione — a condizione che l'amministratore consenta agli utenti di modificare l'impostazione.

I valori accettati sono "precise" (o "90%"), "balanced" (o "70%"), "thorough" (o "50%") e "disabled". I valori non dipendono dalla maiuscola o minuscola.

{
  "env": {
    "AXE_ADVANCED_RULES": "thorough"
  }
}

Invalid Advanced Rules value: "high". Expected one of: 'precise' (90%), 'balanced' (70%), 'thorough' (50%), 'disabled'.

Lo strumento analyze accetta anche un argomento advancedRules per ogni chiamata, che ha la precedenza su AXE_ADVANCED_RULES per quella chiamata. Se l'amministratore ha bloccato l'impostazione, entrambi vengono ignorati a favore del preset dell'organizzazione. Vedi Regole avanzate per le regole complete di precedenza e il blocco di risposta advancedRules.

AXE_SCREENSHOT_DIR

Imposta la directory in cui lo strumento analyze salva gli screenshot quando una chiamata passa screenshot.save senza un percorso esplicito. Non ha effetto sulle chiamate che impostano screenshot.saveTo, che vince sempre, né su quelle che non salvano affatto.

{
  "env": {
    "AXE_SCREENSHOT_DIR": "/Users/me/axe-screenshots"
  }
}

I percorsi relativi sono risolti rispetto alla directory di lavoro del server. L'impostazione predefinita è la directory temporanea del tuo sistema operativo.

Variabili di aggiornamento del token

Queste si applicano solo a OAuth 2.0 e consentono a un server in esecuzione di accettare un token di accesso appena aggiornato, in modo che una sessione che supera il suo token non debba essere riavviata. Il listener è disattivato per impostazione predefinita e si avvia solo quando entrambi AXE_TOKEN_REFRESH_PORT e AXE_TOKEN_REFRESH_SECRET sono impostati.

Di solito non le imposti manualmente. @deque/axe-auth run supervisiona il server e le fornisce per te — scegli una porta e genera il segreto.

Il tuo token di aggiornamento non viene mai inviato al server — solo i token di accesso a breve termine passano, e il segreto condiviso è ciò che protegge l'endpoint. Vedi Mantenere viva una lunga sessione per le configurazioni complete di Docker e npm.

Configurazione del tuo Agente AI (Consigliato)

Per garantire che il tuo agente di codifica AI utilizzi correttamente gli strumenti del server MCP di axe e segua le migliori pratiche di accessibilità, puoi fornirgli 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 root del tuo progetto
• Cursor - Aggiungi a "Regole del cursore" nelle impostazioni
• Claude Code - Aggiungi a un file CLAUDE.md nella root del tuo progetto
• Claude Desktop - Aggiungi alle istruzioni personalizzate nelle impostazioni
• Altri client MCP - Consulta la documentazione del tuo cliente per la configurazione delle istruzioni personalizzate

Esempio di Istruzioni per il Flusso di Lavoro

Di seguito è riportato un modello consigliato 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:

- Collect ALL violations from the analysis and pass them to the
  `remediate` tool in a SINGLE batched call — do NOT call `remediate`
  once per issue
- Give each issue a unique `id` so each result can be correlated
  back to its input
- Provide the exact HTML element, rule ID, and issue description for
  every issue in the batch
- 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. remediate → Pass ALL violations in one batched call to 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é Questo è Importante

Queste istruzioni garantiscono che il tuo agente:

• Usi l'esperienza di Deque - Sfrutta modelli AI addestrati su decenni di dati di valutazione dell'accessibilità invece che sulla conoscenza generale degli LLM
• Segua le migliori pratiche - Applica correzioni coerenti e conformi alle WCAG anziché soluzioni generiche
• Verifica le modifiche - Conferma sempre che le correzioni abbiano effettivamente risolto i problemi
• Evita false sicurezze - 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 codebase.