Referência de Configuração

Esta página documenta as variáveis de ambiente que o servidor axe MCP lê e as instruções personalizadas recomendadas para o seu agente de IA. Estas 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 servidor axe MCP 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 entrar 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 predefinido de confiança Regras Avançadas para cada análise que este servidor executa, substituindo o padrão de configuração do axe da sua organização — desde que o 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.

Configurando Seu Agente de IA (Recomendado)

Para garantir que seu agente de codificação de IA use corretamente as ferramentas do servidor MCP do axe e siga 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 corrigir 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.