Servidor MCP do axe

Visão Geral

O servidor axe MCP é um servidor do Model Context Protocol (MCP) que integra testes de acessibilidade de nível empresarial diretamente em seu fluxo de trabalho de desenvolvimento. Construído na confiável plataforma axe, permite que os desenvolvedores realizem varreduras abrangentes de acessibilidade e recebam orientações de remediação especializada sem sair do seu IDE.

O servidor oferece duas funcionalidades principais - analyze e remediate.

Ambas as ferramentas se integram perfeitamente com clientes compatíveis com MCP (como Claude Desktop, VS Code com Copilot, ou Cursor) e respeitam as configurações de Configuração axe da sua organização.

Obtendo Acesso

O servidor axe MCP está incluído no pacote Axe DevTools para Web .

Ferramentas e Capacidades

A analyze Ferramenta

A analyze realiza uma análise abrangente de acessibilidade em páginas da web executando uma varredura através da extensão de navegador axe DevTools em um ambiente de navegador real. Funciona perfeitamente com URLs de desenvolvimento local (por exemplo, localhost:3000) e URLs de produção remota.

O Que Ela Faz

1. Autenticação - Valida as credenciais do usuário (seja uma chave de API ou um token de acesso OAuth 2.0) para garantir o acesso autorizado
2. Recuperação de Configuração - Obtém a Configuração axe específica da organização do usuário, incluindo:
   • Padrão de Teste de Acessibilidade (por exemplo, WCAG 2.2 AA)
   • versão do axe-core
   • Necessidades de revisão / melhores práticas
3. Análise Baseada em Navegador - Inicia uma instância de navegador em segundo plano com a extensão axe DevTools instalada
4. Navegação em Página - Navega para o URL fornecido pelo usuário em sua solicitação ao agente de IA
5. Varredura de Acessibilidade - Executa uma análise completa de acessibilidade na página renderizada usando a extensão de navegador axe DevTools, garantindo que a experiência do usuário real seja testada (não apenas o HTML estático)
6. Entrega de Resultados - Retorna resultados de análise abrangentes ao agente em um formato estruturado

Teste Responsivo

A analyze oferece suporte a parâmetros opcionais de viewportWidth e viewportHeight , permitindo testar páginas em dimensões específicas de visualização. Isso é útil para identificar problemas de acessibilidade que só aparecem em determinados tamanhos de tela, como em pontos de interrupção de dispositivos móveis ou tablets.

Analyze http://localhost:3000 for accessibility issues at a mobile viewport of 375x812

Quando esses parâmetros são omitidos, o navegador usa seu tamanho padrão de visualização.

Interações do Navegador Antes da Varredura

A analyze ferramenta suporta uma opcional before matriz de etapas de interação que são executadas após o carregamento da página mas antes da varredura de acessibilidade. Isso desbloqueia diversos cenários de teste do mundo real:

• Páginas com login restrito — preencher credenciais e enviar antes de escanear a página pós-login
• Banners de cookies/consentimento — descartar banners que de outra forma sobreporiam ou obscureceriam o conteúdo da página
• Conteúdo dinâmico — esperar que o conteúdo renderizado pelo cliente (mudanças de rota, DOM injetado tardiamente) apareça antes da varredura

As etapas são executadas na ordem da matriz, no mesmo contexto do navegador da varredura, então cookies, localStorage, e quaisquer mudanças de rota acionadas por click ou fill persistem na varredura.

A before matriz suporta até 20 etapas. Cada etapa tem seu próprio limite de tempo de BROWSER_TIMEOUT_MS (padrão 30000 ms); não há substituição por etapa.

Ações Suportadas

Exemplo: Fazendo login antes da varredura

Instruir seu agente de IA em linguagem natural — o agente traduz sua intenção na chamada da ferramenta:

Analyze http://localhost:3000 for accessibility issues. Before running
the analysis, fill in the #username and #password fields with USERNAME
and PASSWORD from ./.env.local, click the button[type=submit] button,
and wait for #main-content to appear.

O agente resolve a instrução e chama a analyze ferramenta com um payload semelhante a:

{
  "url": "http://localhost:3000",
  "before": [
    { "action": "fill", "selector": "#username", "value": "<resolved-from-.env.local>" },
    { "action": "fill", "selector": "#password", "value": "<resolved-from-.env.local>" },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}

Principais Benefícios

• Testes em Navegador Real - Testa a página renderizada de fato, não apenas o código-fonte, garantindo resultados precisos
• Padrões da Organização - Respeita as configurações de Configuração axe da sua equipe para testes consistentes entre todos os usuários
• Cobertura Abrangente - Aproveita a plataforma axe líder do setor
• Teste Responsivo - Teste em dimensões específicas de visualização para identificar problemas de acessibilidade em pontos de ruptura
• **Páginas Autenticadas e Interativas** - Escaneie páginas após login, feche banners de cookies ou espere por conteúdo dinâmico usando before ações

Saída

A ferramenta retorna uma resposta JSON estruturada contendo:

• Todas as violações de acessibilidade encontradas
• Níveis de gravidade das violações (crítico, sério, moderado, leve)
• Seletores de elementos específicos e código fonte
• IDs e descrições de regras

A remediate Ferramenta

A remediate ferramenta toma qualquer problema de acessibilidade identificado pelo axe e gera orientações de remediação baseadas em IA e sensíveis ao contexto, que agentes de codificação podem traduzir em correções de código reais.

O Que Ela Faz

1. Autenticação - Valida as credenciais do usuário—seja uma chave de API ou um token de acesso OAuth 2.0 (veja Configurar Autenticação)—para garantir o acesso autorizado
2. Crédito de IA Uso - Cada remediate chamada consome créditos de IA da alocação da sua organização, permitindo o uso de modelos avançados de IA treinados na vasta expertise em acessibilidade da Deque
3. Remediação Gerada por IA - Cria uma correção de acessibilidade de alta qualidade e prática que agentes de codificação podem interpretar e implementar no código fonte

Saída

A ferramenta retorna orientações de remediação estruturadas que incluem:

• Resumo de alto nível da correção necessária
• Alterações de código específicas necessárias (em formato HTML)
• Raciocínio de acessibilidade e critérios WCAG
• Contexto adicional para garantir a implementação adequada

Uso de Créditos

A remediate ferramenta faz parte do Sistema de Gerenciamento de Créditos de IA. Cada solicitação de remediação consome créditos da alocação mensal da sua organização. Os administradores podem monitorar o uso de créditos através do Portal de Contas axe.

Instalação e Configuração

Pré-requisitos

• Docker instalado e em execução no seu sistema
• Agente de IA configurado para o servidor MCP do axe (consulte Configuração abaixo para instruções de configuração específicas do IDE)
• Uma assinatura que permite acesso ao servidor MCP do axe conversando com um representante de vendas da Deque

Passo 1: Configurar a Autenticação

O servidor axe MCP suporta dois métodos de autenticação.

Opção A: Chave da API

1. Faça login no Portal de Contas axe
2. Navegue até a página de Chaves da API
3. Clique em ADICIONAR NOVA CHAVE DA API
4. Selecione Servidor MCP do axe como o produto
5. Insira um nome descritivo para a sua chave de API
6. Clique em **Salvar**
7. Copie a chave de API gerada para usar na próxima etapa

Opção B: OAuth 2.0

A Opção B é a autenticação OAuth 2.0 via @deque/axe-auth CLI. Veja Autenticação OAuth 2.0 para instruções de configuração.

Etapa 2: Baixar a Imagem Docker

Inicialmente e sempre que uma versão atualizada for lançada que você deseja utilizar, será necessário docker pull a imagem do servidor axe MCP:

docker pull dequesystems/axe-mcp-server:latest

Etapa 3: Configuração

Escolha seu IDE para instruções específicas de configuração:

• Configuração no VS Code com Copilot
• Configuração no Cursor
• Configuração no Claude Code

Exemplos de Comandos

Garantindo que ferramentas esperadas sejam chamadas

Em muitos IDEs, usar a seguinte sintaxe ("#" como prefixo) garantirá que as ferramentas do servidor axe MCP sejam chamadas conforme esperado:

#analyze the http://localhost:3033/ web page for accessibility issues and #remediate any violations found

Analisar uma URL localhost em busca de problemas de acessibilidade:

Analyze http://localhost:3000 for accessibility issues

Análise com remediação:

Analyze https://example.com for accessibility issues and fix any issues found

Analise uma página após o login:

Analyze http://localhost:3000 for accessibility issues. Before running the
analysis, fill in the #username and #password fields with USERNAME and
PASSWORD from ./.env.local, click the button[type=submit] button, and
wait for #main-content to appear.

Feche um banner de cookies antes de escanear:

Analyze https://example.com for accessibility issues, but first click the
#cookie-dismiss button to dismiss the cookie consent banner.

Configurando Seu Agente de IA (Recomendado)

Para garantir que seu agente de codificação de IA use corretamente as ferramentas do servidor axe MCP 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 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 no diretório raiz do seu projeto
• Cursor - Adicione a "Regras do Cursor" nas configurações
• **Claude Code** - Adicione a um CLAUDE.md arquivo no diretório 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 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:

- First use `remediate` tool for EACH violation found
- Provide the exact HTML element, rule ID, and issue description
- 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. For each violation: remediate → 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 É Importante

Essas instruções garantem que seu agente:

• **Utilize a experiência da Deque** - Aproveite modelos de IA treinados em décadas de dados de avaliação de acessibilidade em vez de conhecimento geral de LLM
• **Siga as melhores práticas** - Aplique correções consistentes e compatíveis com WCAG em vez de soluções genéricas
• **Verifique as alterações** - Sempre confirme que as correções realmente resolveram os problemas
• **Evite confiança falsa** - Não presuma que sabe como corrigir problemas de acessibilidade sem orientação especializada

Embora seja opcional, fornecer essas instruções melhora significativamente a qualidade e a confiabilidade das correções de acessibilidade em seu código.

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 compartilhada dos EUA SaaS da Deque. Se sua organização usar qualquer um dos seguintes, deve definir AXE_SERVER_URL para a URL base da sua instância:

• Uma instância regional SaaS (UE, Austrália, Frankfurt, etc.)
• Uma nuvem privada implementação
• Uma instalação local instalação

Se não souber qual instância sua organização utiliza, verifique a URL que você usa para acessar o Portal da Conta axe ou pergunte ao seu administrador.

Defina AXE_SERVER_URL explicitamente no env bloco da configuração do servidor MCP. Os guias de configuração específicos para IDE para VS Code com Copilot e Cursor incluem exemplos mostrando exatamente onde adicioná-lo.

Solução de Problemas

Problemas Comuns

Servidor não inicia:

• Certifique-se de que o Docker está funcionando
• Verifique se suas credenciais estão corretas: seja sua AXE_API_KEY ou sua AXE_ACCESS_TOKEN, mas não ambas (o servidor falha ao iniciar se ambas estiverem configuradas)
• Verifique se você tem acesso ao servidor axe MCP (contate o suporte se necessário)

Timeouts de escaneamento:

• Aumente BROWSER_TIMEOUT_MS para páginas complexas
• Certifique-se de que a URL de destino seja acessível a partir da sua rede
• Verifique problemas de conectividade de rede

ERR_CONNECTION_REFUSED ao analisar um servidor de desenvolvimento local

Se a analyze ferramenta falhar com um net::ERR_CONNECTION_REFUSED erro ao tentar escanear um servidor de desenvolvimento em execução localmente, isso provavelmente ocorre porque o axe MCP Server é executado dentro de um container Docker e não pode acessar serviços vinculados apenas a localhost (ou seja, 127.0.0.1) na sua máquina host.

Exemplo de erro:

net::ERR_CONNECTION_REFUSED at http://192.168.65.2:5173/

Solução: Inicie seu servidor de desenvolvimento com o --host definido para 0.0.0.0 para que ele escute em todas as interfaces de rede, tornando-o acessível de dentro do container Docker:

# Vite
npm run dev -- --host=0.0.0.0

# Webpack (webpack-dev-server)
npm run dev -- --host=0.0.0.0

Erros de Autenticação

Chave da API

• Verifique se sua chave de API é válida e não expirou
• Certifique-se de que sua assinatura do Portal de Conta axe inclua acesso ao MCP Server
• Verifique se a chave de API foi criada para o produto „axe MCP Server“
• Confirme que apenas AXE_API_KEY está definida — se AXE_ACCESS_TOKEN também estiver definida, o servidor falhará na inicialização
• Confirme que o URL do seu servidor axe está correto — se sua organização usa uma instância regional, privada na nuvem ou local do axe, AXE_SERVER_URL deve estar definida para o URL base da sua instância. Veja Opções de Configuração para mais detalhes.

OAuth

• Confirme que apenas AXE_ACCESS_TOKEN está definida — se AXE_API_KEY também estiver definida, o servidor falhará na inicialização
• Execute npx @deque/axe-auth token no seu terminal para confirmar que você tem um token válido; se sair com um código diferente de zero, reautentique-se com npx @deque/axe-auth login
• Confirme que o URL do seu servidor axe está correto
• Se o seu token expirou durante a sessão, reinicie a conexão do servidor MCP no seu IDE (por exemplo, reiniciando o Claude Code, alternando o servidor em Configurações do MCP do Cursor ou clicando no botão "Reiniciar" do CodeLens do VS Code diretamente acima da entrada do servidor axe MCP em mcp.json) para obter um novo token
• Veja Autenticação OAuth 2.0 para etapas completas de resolução de problemas

Problemas relacionados ao Docker:

• Certifique-se de que o daemon do Docker está em execução
• Verifique as permissões do Docker
• Verifique a conectividade de rede para downloads de imagens do Docker
• Garanta que o Docker tenha memória suficiente executando um docker system prune

Obtenha Ajuda

Se você encontrar problemas não abordados nesta seção de solução de problemas:

1. Verifique o Console do Desenvolvedor do VS Code para mensagens de erro detalhadas
2. Revise os logs do container Docker para informações adicionais de depuração
3. Entre em contato com nossa equipe de suporte em helpdesk@deque.com com:
   • Sua versão do VS Code
   • Versão do Docker
   • Mensagens de erro completas
   • Passos para reproduzir o problema

Suporte

Para perguntas, problemas ou feedback sobre o axe MCP Server:

• Suporte Técnico: helpdesk@deque.com
• Dúvidas Gerais: helpdesk@deque.com
• Perguntas de Vendas: sales@deque.com

FAQ de Segurança e Privacidade

O axe MCP Server captura ou armazena nosso código-fonte?

Não. O axe MCP Server não captura ou armazena seu código-fonte em qualquer banco de dados ou armazenamento persistente.

Quando o analyze a ferramenta é executada, a resposta inclui o código-fonte HTML dos elementos com problemas de acessibilidade para contexto e propósitos de depuração. No entanto, esses dados:

• São retornados apenas na resposta imediata da API para o seu agente de IA
• Nunca são persistidos em bancos de dados geridos pela Deque
• Permanecem dentro do seu ambiente de desenvolvimento local
• São descartados após a conclusão da análise

Por quanto tempo os resultados dos testes MCP permanecem na infraestrutura gerida pela Deque?

Eles não permanecem. Os resultados dos testes MCP não são persistidos em nenhum banco de dados ou sistema de armazenamento gerido pela Deque.

A analyze ferramenta:

• É executada inteiramente dentro do contêiner Docker na sua máquina
• Retorna os resultados diretamente para o seu agente de IA
• Não envia resultados de análise para os servidores da Deque

A única exceção é quando você chama a remediate ferramenta, que pode incluir metadados mínimos de violação (veja abaixo) para gerar orientações de correção alimentadas por IA.

Quais dados são enviados para os servidores da Deque?

Apenas quando usa a remediate ferramenta:

Os seguintes dados são enviados para o endpoint de remediação de IA da Deque para gerar orientações de correção:

• ID da Regra - A regra específica de acessibilidade que foi violada
• HTML do Elemento - A marcação HTML do(s) elemento(s) afetado(s)
• Metadados do Problema - Descrição da violação e orientação de remediação do axe-core

Esses dados são usados exclusivamente para gerar orientações de remediação e não são armazenados a longo prazo nos bancos de dados da Deque.

A analyze ferramenta não envia quaisquer dados para os servidores da Deque além das solicitações de autenticação (validando sua chave de API ou token de acesso OAuth 2.0).

Qual é o nível de acesso necessário ao agente de IA para funcionar?

O agente de IA (Claude, Copilot, Cursor, etc.) precisa de acesso a:

1. Comunicação com o Servidor MCP - O agente deve ser capaz de chamar as ferramentas do servidor MCP através do Protocolo de Contexto do Modelo

2. Dados de Resposta da Ferramenta - O agente recebe:

   • Dados de violação de acessibilidade a partir de analyze chamadas
   • Orientação de remediação a partir de remediate chamadas
   • Esses dados são necessários para o agente entender os problemas e gerar correções de código

3. Seu Código-fonte (Opcional) - Se você deseja que o agente aplique automaticamente correções de código, ele precisa de acesso aos seus arquivos de código-fonte

• Isso é padrão para assistentes de codificação de IA em IDEs (VS Code, Cursor, etc.)
• Não é necessário se você estiver usando as ferramentas apenas para análise e orientação (por exemplo, via aplicativo Claude Desktop)

O próprio servidor MCP precisa de acesso a:

• URLs que você especifica para teste (suporta tanto locais quanto remotos)
• Suas credenciais axe: seja uma chave de API (gerada no Portal da Conta axe) ou um token de acesso OAuth 2.0 (obtido via @deque/axe-auth); fornecidas via variável de ambiente

Importante: O servidor MCP é executado localmente em um contêiner Docker na sua máquina. Ele não requer amplo acesso ao sistema de arquivos ou privilégios elevados além do que o Docker requer.

Melhores Práticas

• Segurança de Credenciais - Armazene sua AXE_API_KEY ou AXE_ACCESS_TOKEN como uma variável de ambiente, não no código. Com OAuth 2.0, @deque/axe-auth mantém os tokens no chaveiro do seu SO e injeta um novo token de acesso na inicialização, de modo que nenhum segredo de longa duração precisa estar na sua configuração
• **Teste Local** - Teste URLs de desenvolvimento local (localhost) ou de estágio para manter o código sensível de pré-produção isolado
• **Isolamento de Rede** - O servidor MCP só se comunica com:
  • URLs que você solicita explicitamente para analisar
  • Servidores Deque para autenticação (validação de chave de API ou token OAuth 2.0) e remediação (quando chamado)
  • Seu agente de IA local através do protocolo MCP
• **Revisão Antes de Aplicar** - Sempre revise as alterações de código geradas por IA antes de confirmá-las no seu repositório