Servidor axe MCP

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 Ferramenta analyze Ferramenta

A ferramenta 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. Validação da Chave API - Valida a chave API do usuário para garantir 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 ferramenta 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.

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

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. Validação de Chave da API - Valida a chave da API do usuário para garantir acesso autorizado
2. Uso de Créditos de IA - 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: Gerar 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

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

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. 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

### 3. 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 sua chave de API está correta
• 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:

• 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“
• Se sua organização usa uma instância axe regional, nuvem privada ou local, confirme que AXE_SERVER_URL está definido para a URL base da sua instância — sem isso, o servidor tentará autenticar contra https://axe.deque.com e falhará. Veja Opções de Configuração para mais detalhes.

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 validação de chave de API.

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)
• Sua chave API do axe (gerada no Portal de Conta axe; fornecida 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 da Chave de API** - Armazene sua AXE_API_KEY como uma variável de ambiente, não no código
• **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 validação e remediação da chave de API (quando solicitado)
  • 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