Referência de Configuração

Esta página documenta as variáveis de ambiente que o Axe MCP Server lê e as instruções personalizadas recomendadas para o seu agente de IA. Elas se aplicam a ambos os distribuições Docker e npm. Para saber onde colocar esses valores, consulte seu guia de configuração do cliente.

Opções de Configuração

O Axe MCP Server suporta várias variáveis de ambiente para personalização:

AXE_SERVER_URL

O valor padrão (https://axe.deque.com) é correto para a maioria dos usuários — aqueles na instância SaaS compartilhada dos EUA da Deque. Se a sua organização usar qualquer uma das opções abaixo, você deve definir AXE_SERVER_URL para a URL base da sua instância:

• Uma instância regional de SaaS (UE, Austrália, Frankfurt, etc.)
• Um nuvem privada deployment
• Uma instalação on-premises

Se você não tiver certeza de qual instância sua organização usa, verifique a URL que você usa para fazer login no Portal de Contas Axe ou pergunte ao seu administrador.

Defina AXE_SERVER_URL explicitamente no bloco env da configuração do servidor MCP. Os guias de configuração do cliente incluem exemplos mostrando exatamente onde adicioná-lo.

AXE_CHROME_PATH

distribuição npm apenas. Isso não é suportado no Docker, que sempre usa seu navegador empacotado — o servidor falha ao iniciar se AXE_CHROME_PATH for configurado na distribuição Docker.

Por padrão, a distribuição npm usa a compilação Chromium que você instala através de Playwright. Defina AXE_CHROME_PATH para o caminho completo de um binário Chrome/Chromium existente para usar isso em vez e pular a instalação do Playwright.

• O valor deve ser um arquivo binário executável, não um pacote .app ou diretório. No macOS, por exemplo, aponte para o binário dentro do pacote: /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• O binário deve iniciar e responder a --version. O servidor valida isso na inicialização e falha rapidamente com Unable to find specified chrome instance se não conseguir.
• Google Chrome estável de marca 137 e superior não é suportado. Use Chrome para Testes ou outro binário compatível com Chromium.

As ferramentas analyze e igt também aceitam um argumento chromePath por chamada, que tem precedência sobre AXE_CHROME_PATH para essa chamada.

AXE_ADVANCED_RULES

Define o predefinição de confiança Regras Avançadas para cada varredura que este servidor executa, substituindo o padrão de configuração do Axe da sua organização — desde que seu administrador permita que os usuários alterem a configuração.

Os valores aceitos são "precise" (ou "90%"), "balanced" (ou "70%"), "thorough" (ou "50%") e "disabled". Os valores não são sensíveis a maiúsculas.

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

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

A ferramenta analyze também aceita um argumento advancedRules por chamada, que tem precedência sobre AXE_ADVANCED_RULES para essa chamada. Se o administrador bloquear a configuração, ambos são ignorados em favor do predefinido da organização. Veja Regras Avançadas para conhecer as regras completas de precedência e o bloco de resposta advancedRules.

AXE_SCREENSHOT_DIR

Define o diretório onde a ferramenta analyze grava capturas de tela quando uma chamada passa por screenshot.save sem um caminho explícito. Não tem efeito em chamadas que definem screenshot.saveTo, que sempre vence, e nenhum em chamadas que não salvam de forma alguma.

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

Os caminhos relativos são resolvidos em relação ao diretório de trabalho do servidor. O padrão é o diretório temporário do seu sistema operacional.

Variáveis de atualização do token

Estas se aplicam apenas a OAuth 2.0 e permitem que um servidor em execução aceite um token de acesso recentemente atualizado para que uma sessão que dure mais que seu token não precise ser reiniciada. O ouvinte está desativado por padrão e só inicia quando ambos AXE_TOKEN_REFRESH_PORT e AXE_TOKEN_REFRESH_SECRET estão configurados.

Normalmente você não define estas manualmente. @deque/axe-auth run supervisiona o servidor e as fornece para você — você escolhe uma porta, e ele gera o segredo.

Seu token de atualização nunca é enviado ao servidor — apenas tokens de acesso de curta duração atravessam, e o segredo compartilhado é o que protege o endpoint. Veja Mantendo uma sessão longa ativa para configurações completas de Docker e npm.

IGT_TIMEOUT_MS

Delimita uma execução de Teste Guiado Inteligente, medida desde o momento em que o teste começa até o momento em que seus resultados retornam. Aplica-se tanto às chamadas analyze que passam igtTools quanto ao descontinuado ferramenta de igt.

Um teste é movido por IA e trabalha através dos elementos interativos da página um de cada vez, portanto, executa-se legitimamente por muito mais tempo do que uma varredura. Seu padrão é dimensionado para isso, e é por isso que é muito maior que BROWSER_TIMEOUT_MS. Uma execução que excede seu orçamento falha com um erro nomeando o orçamento que estourou:

IGT timed out after 200000ms

Aumente IGT_TIMEOUT_MS quando uma página tiver elementos interativos suficientes para precisar de mais tempo. Aumentar BROWSER_TIMEOUT_MS não ajudará: cada tempo limite nesta página é seu próprio orçamento independente, e a varredura já havia terminado antes do teste começar.

{
  "env": {
    "IGT_TIMEOUT_MS": "400000"
  }
}

Variáveis de seleção faseada

Estas se aplicam a seleção faseada para o IGT de Elementos Interativos. A primeira chamada pausa a execução e mantém o navegador aberto até que seu agente faça a segunda chamada, assim esses valores limitam quanto tempo uma execução pausada espera e quantos navegadores podem permanecer abertos ao mesmo tempo.

Aumente SELECTION_SESSION_TTL_MS se você regularmente precisar de mais de três minutos para revisar uma longa lista de elementos. Ambos os valores devem ser inteiros positivos; caso contrário, o servidor se recusa a iniciar.

{
  "env": {
    "SELECTION_SESSION_TTL_MS": "600000"
  }
}

AXE_PAGE_LOAD_DELAY_MS

Ao contrário das variáveis acima, isso não é um tempo limite. É um atraso fixo que o servidor sempre espera após a conclusão da navegação, antes de executar qualquer ações de before e antes de fazer varreduras. Existe para páginas que continuam renderizando após o carregamento sem nada confiável para esperar. Cada varredura que este servidor executa paga o atraso na íntegra, então mantenha-o pequeno.

{
  "env": {
    "AXE_PAGE_LOAD_DELAY_MS": "2000"
  }
}

Prefira um etapa de waitFor no array de before da ferramenta de analyze onde você pode nomear um elemento que só existe após a página ter se estabilizado. waitFor continua no momento em que esse elemento aparece, sendo assim mais confiável e geralmente mais rápido do que um atraso geral.

Configurando Seu Agente de IA (Recomendado)

Para garantir que seu agente de codificação de IA usa corretamente as ferramentas do Axe MCP Server e segue as melhores práticas de acessibilidade, você pode fornecer instruções personalizadas. Essas instruções ajudam o agente a entender o fluxo de trabalho adequado para analisar e remediar problemas de acessibilidade.

Onde Adicionar Instruções

O método varia conforme o cliente:

• VS Code com GitHub Copilot - Adicione a .github/copilot-instructions.md na raiz do seu projeto
• Cursor - Adicione a "Cursor Rules" nas configurações
• Claude Code - Adicione a um arquivo CLAUDE.md na raiz do seu projeto
• Claude Desktop - Adicione às instruções personalizadas nas configurações
• Outros clientes MCP - Consulte a documentação do seu cliente para a configuração de instruções personalizadas

Exemplo de Instruções de Fluxo de Trabalho

Abaixo está um modelo recomendado que você pode adaptar para o seu 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

Por Que Isso Importa

Essas instruções garantem que seu agente:

• Use a expertise da Deque - Aproveita modelos de IA treinados em décadas de dados de avaliação de acessibilidade, em vez de um conhecimento geral de LLM
• Siga as melhores práticas - Aplica correções consistentes e compatíveis com WCAG em vez de soluções genéricas
• Verifica alterações - Sempre confirma se as correções realmente resolveram os problemas
• Evita falsa confiança - Não assume que sabe como corrigir problemas de acessibilidade sem orientação de especialistas

Embora opcionais, fornecer essas instruções melhora significativamente a qualidade e a confiabilidade das correções de acessibilidade em sua base de código.