Riferimento alla Configurazione

Questa pagina documenta le variabili d'ambiente che il server axe MCP legge e le istruzioni personalizzate consigliate per il tuo agente AI. Queste si applicano sia alle distribuzioni Docker e npm. Per sapere dove inserire questi valori, consulta la tua 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 predefinito (https://axe.deque.com) è corretto per la maggior parte degli utenti — quelli sull'istanza SaaS condivisa di Deque negli USA. Se la tua organizzazione utilizza una delle seguenti, devi impostare AXE_SERVER_URL all'URL base della tua istanza:

• Una istanza SaaS regionale (EU, Australia, Francoforte, ecc.)
• Un cloud privato deployment
• Un' 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 in modo esplicito nel env blocco della configurazione del server MCP. Le 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 suo browser integrato — il server non si avvia se AXE_CHROME_PATH è impostato nella distribuzione Docker.

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

• Il valore deve essere un file binario eseguibile, non un .app pacchetto 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 convalida questo all'avvio e si arresta immediatamente con Unable to find specified chrome instance se non riesce.
• La versione stabile 137 e successive di Google Chrome marchiato non è supportata. Usa Chrome for Testing o un altro binario compatibile con Chromium.

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

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 radice del tuo progetto
• Cursor - Aggiungi alle "Regole Cursor" nelle impostazioni
• Claude Code - Aggiungi a un CLAUDE.md file nella radice del tuo progetto
• Claude Desktop - Aggiungi alle istruzioni personalizzate nelle impostazioni
• Altri client MCP - Consulta la documentazione del tuo client 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 - Sfrutti modelli di AI addestrati su decenni di dati di valutazione dell'accessibilità anziché su conoscenze generali di LLM
• Segua le migliori pratiche - Applica correzioni coerenti e conformi al WCAG invece di 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.