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 tanto às distribuições Docker e npm. Para saber onde colocar esses valores, consulte o 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 que utilizam a instância compartilhada de SaaS dos EUA da Deque. Se sua organização usar qualquer um dos seguintes, 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.)
• Uma 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 env bloco da configuração do seu 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 utiliza seu navegador incluído — o servidor falha ao iniciar se AXE_CHROME_PATH for definido na distribuição Docker.

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

• O valor deve ser um arquivo binário executável, não um .app pacote 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.

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

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 "Regras do Cursor" nas configurações
• Claude Code - Adicione a um CLAUDE.md arquivo na raiz do seu projeto
• Claude Desktop - Adicione a 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 - Utilize modelos de IA treinados com décadas de dados de avaliação de acessibilidade em vez de 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 que as correções realmente resolveram os problemas
• Evita falsa confiança - Não presume saber como corrigir problemas de acessibilidade sem orientação especializada

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