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 fornece três capacidades - analyze, remediate e igt.

Essas 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 axe da sua organização.

Obtendo Acesso

O Axe MCP Server está incluído no pacote Axe DevTools para Web. Uma assinatura que permite o acesso ao axe MCP Server é configurada conversando com um representante de vendas da Deque.

Ferramentas e Capacidades

A Ferramenta analyze

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 tanto com URLs de desenvolvimento locais (por exemplo, localhost:3000) quanto com 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 - Busca as configurações Configuração axe específicas 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 a URL fornecida pelo usuário na 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 real do usuário seja testada (não apenas HTML estático)
6. Entrega de Resultados - Retorna os resultados da análise abrangente de volta ao agente em um formato estruturado

Teste Responsivo

A ferramenta analyze suporta parâmetros opcionais viewportWidth e viewportHeight, permitindo testar páginas em dimensões específicas de viewport. Isso é útil para detectar problemas de acessibilidade que aparecem apenas em certos tamanhos de tela, como pontos de interrupção para 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.

Scans de Página Parciais

Por padrão, a ferramenta analyze escaneia a página inteira. Para delimitar a varredura a uma região específica, passe o parâmetro opcional selector — útil para focar em um único componente ou excluir partes barulhentas e não relacionadas da página nos resultados.

• Uma única string de seletor CSS aponta para um elemento no quadro de topo:

  {
    "url": "http://localhost:3000",
    "selector": "#main"
  }

• Um array de seletores CSS atravessa limites de iframe ou shadow-DOM — cada segmento seleciona o host para o próximo. Use uma matriz apenas quando o alvo viver dentro de um iframe ou raiz shadow:

  {
    "url": "http://localhost:3000",
    "selector": ["iframe#checkout", "#payment-form"]
  }

Uma matriz suporta até 10 segmentos. Se o seletor não corresponder a nenhum elemento na página, a varredura retorna um erro. Quando selector é omitido, a página inteira é escaneada.

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

Scan only the #main region of http://localhost:3000 for accessibility issues

Interações do Navegador Antes da Varredura

A ferramenta analyze suporta uma matriz before opcional de etapas de interação que executam após o carregamento da página mas antes da varredura de acessibilidade. Isso desbloqueia vários 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 sobrepõem ou obscurecem 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 do array, no mesmo contexto do navegador da varredura, para que cookies, localStorage, e quaisquer mudanças de rota desencadeadas por click ou fill persistam na varredura.

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

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 solicitação e chama a ferramenta analyze com um pacote 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" }
  ]
}

Injeção de Cookie

A ferramenta analyze suporta uma matriz cookies opcional que define cookies no contexto do navegador antes da navegação — então eles acompanham a primeira solicitação à página. Isso é distinto de before ações, que executa depois navegação e, portanto, não pode influenciar como a solicitação inicial é roteada. Dois usos comuns:

• Roteamento de ambiente — definir um cookie de seletor de ramificação de estágio ou funcionalidade que uma camada de borda ou CDN lê para decidir qual versão do site servir.
• Sessões pré-autenticadas — injete um cookie de sessão válido para que a varredura comece já logada, sem precisar passar por um formulário de login através de before.

A matriz cookies suporta até 20 cookies.

Campos de Cookie

Exemplo: Acessando uma página pré-autenticada

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

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

O agente resolve o valor do cookie e chama a ferramenta analyze com uma carga útil semelhante a:

{
  "url": "https://app.example.com",
  "cookies": [
    {
      "name": "session",
      "value": "<resolved-from-.env.local>",
      "domain": "app.example.com"
    }
  ]
}

Principais Benefícios

• Testes em Navegador Real - Testa a página renderizada real, não apenas o código-fonte, garantindo resultados precisos
• Padrões da Organização - Respeita as configurações de configuração do seu time no axe para testes consistentes entre todos os usuários
• Cobertura Abrangente - Aproveita a plataforma axe que lidera a indústria
• Teste Responsivo - Teste em dimensões específicas de viewport para capturar problemas de acessibilidade específicos de breakpoint
• Scans Direcionados - Delimite uma varredura para uma região específica, iframe ou raiz de sombra com o parâmetro selector
• **Páginas Autenticadas e Interativas** - Escaneie páginas após login, dispense banners de cookies ou aguarde por conteúdo dinâmico usando ações before
• Cookies de Sessão & Ambiente - Acesse já autenticado ou direcione para um ambiente específico, injetando cookies antes da navegação com o parâmetro cookies

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

A ferramenta remediate aceita um ou mais problemas de acessibilidade identificados pela ferramenta analyze ou igt e gera orientações de remediação, com consciência de contexto e com suporte de IA, que agentes de codificação podem traduzir em correções de código reais. Os problemas são enviados em lote, permitindo que uma única chamada retorne correções para todas as violações encontradas em uma página.

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 acesso autorizado
2. Uso de Crédito de IA - Cada problema no lote consome créditos de IA da alocação da sua organização, permitindo o uso de modelos de IA avançados treinados na extensa expertise em acessibilidade da Deque
3. Remediação Gerada por IA - Cria correções de acessibilidade de alta qualidade e aplicáveis que agentes de codificação podem interpretar e implementar no código-fonte

Remediação em Lote

A ferramenta aceita uma matriz issues. Envie todas os problemas de uma única execução analyze ou igt juntos em uma única chamada, em vez de chamar a ferramenta uma vez por problema — um lote suporta entre 1 e 25 problemas.

Cada questão possui os seguintes campos:

Instrua seu agente de IA em linguagem natural — ele monta o lote a partir dos resultados da análise:

Analyze http://localhost:3000 and remediate every issue found

O agente resolve o prompt e chama a ferramenta remediate com uma carga útil semelhante a:

{
  "issues": [
    {
      "id": "color-contrast-0",
      "rule": "color-contrast",
      "elementHtml": "<span style=\"color: #aaa\">Sign up</span>",
      "remediation": "Increase the contrast ratio to at least 4.5:1",
      "pageUrl": "http://localhost:3000"
    },
    {
      "id": "image-alt-1",
      "rule": "image-alt",
      "elementHtml": "<img src=\"logo.png\">",
      "remediation": "Add alt text describing the image"
    }
  ]
}

Saída

A ferramenta retorna um array de resultados por problema, cada um relacionado ao seu input por id. Um resultado tem um de dois formatos:

• Sucesso — status: "ok", com um objeto remediation contendo uma descrição geral, as etapas de remediação e uma correção de código concreta
• Erro — status: "error", com um objeto error (code e message) para um problema que não pôde ser remediado

{
  "data": [
    {
      "id": "color-contrast-0",
      "status": "ok",
      "remediation": {
        "general_description": "...",
        "remediation": "...",
        "code_fix": "<span style=\"color: #595959\">Sign up</span>"
      }
    },
    {
      "id": "image-alt-1",
      "status": "error",
      "error": { "code": "LLM_ERROR", "message": "..." }
    }
  ]
}

Os resultados são independentes: uma falha em um problema não bloqueia a orientação para os outros.

Uso de Créditos

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

A Ferramenta igt

A ferramenta igt executa o Tests Inteligentes Guiados Automatizados (IGTs) da Deque contra uma página da web a partir do seu IDE. Enquanto a Extensão do Navegador axe DevTools normalmente guia um desenvolvedor por um IGT com prompts manuais, a ferramenta igt executa o teste automaticamente e retorna resultados estruturados que um agente de codificação pode atuar.

Atualmente, a ferramenta suporta o IGT de Teclado, que avalia se os elementos interativos de uma página podem ser acessados e operados usando apenas o teclado.

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 acesso autorizado
2. Execução Baseada em Navegador - Testa na mesma instância do Chromium com a extensão axe DevTools montada que a ferramenta analyze usa
3. Navegação em Página - Navega para o URL fornecido pelo usuário em seu prompt para o agente de IA
4. IGT de Teclado Automatizado - Navega pelas abas da página enquanto a IA analisa cada ponto de parada, avaliando a ordem de foco e a operabilidade do teclado — sem necessidade de entrada manual
5. Entrega de Resultados - Retorna achados estruturados de volta para o agente

Uso

A ferramenta aceita um url e um array igtTools que nomeia quais IGTs executar. O IGT de Teclado é atualmente o único valor suportado:

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"]
}

Instrua seu agente IA em linguagem natural — o agente traduz sua intenção em uma chamada de ferramenta:

Run the keyboard IGT on http://localhost:3000

Interações no Navegador Antes do Teste

Assim como a ferramenta analyze, igt aceita um array before opcional de etapas de interação que são executadas após o carregamento da página mas antes que o teste guiado seja iniciado. Isso permite que você realize um teste guiado em páginas protegidas por login, descarte banners de cookies ou aguarde que o conteúdo dinâmico apareça primeiro.

As etapas são executadas no mesmo contexto do navegador como o teste (assim cookies, localStorage e alterações de rota permanecem), usando as mesmas ações de click, fill e waitFor, e são limitadas pelo mesmo 20 etapas. Consulte Ações Suportadas na ferramenta analyze para a referência completa, incluindo o tratamento de valores sensíveis de fill.value e as regras de seletores.

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

Saída

A ferramenta retorna uma resposta JSON estruturada:

{
  "pageUrl": "http://localhost:3000",
  "data": {
    "keyboard": {
      "issues": [],
      "unanalyzedElements": [],
      "terminatedReason": "keyboard-trap"
    }
  }
}

• issues - Violações de acessibilidade do teclado encontradas durante a execução
• unanalyzedElements - Paradas de tabulação que a IA não conseguiu analisar. Essas são relatadas separadamente de issues para que possam ser revisadas manualmente, em vez de serem relatadas incorretamente como aprovadas ou falhas.
• terminatedReason - Apresenta somente quando a execução foi interrompida antes que cada ponto de parada fosse analisado. O valor atual é "keyboard-trap", significando que o teste encontrou uma armadilha de teclado da qual não pôde escapar; as etapas restantes são interrompidas e as paradas de tabulação analisadas até aquele ponto são retornadas em issues.

Uso de Créditos

A ferramenta igt é um recurso alimentado por IA e faz parte do Sistema de Gerenciamento de Créditos de IA. Cada execução consome créditos de IA da alocação mensal da sua organização. Os administradores podem monitorar o uso de créditos através do Portal da Conta axe.

Primeiros Passos

Configurar o servidor axe MCP envolve três escolhas independentes:

1. Escolher uma distribuição — Docker ou npm
2. Configurar autenticação — uma chave de API ou OAuth 2.0
3. Configurar seu cliente — VS Code com Copilot, Cursor ou **Claude Code**

Para variáveis de ambiente e instruções recomendadas para o agente de IA, consulte o Referência de Configuração. Se algo der errado, veja o Solução de Problemas.

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.

Digitalize uma página com um cookie de sessão injetado:

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

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 Servidor MCP do axe não captura ou armazena seu código-fonte em nenhum banco de dados ou armazenamento persistente.

Quando a ferramenta analyze é executada, a resposta inclui o código-fonte HTML dos elementos com problemas de acessibilidade para fins de contexto e 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 armazenados em nenhum banco de dados ou sistema de armazenamento gerenciado pela Deque.

A ferramenta analyze:

• Executa inteiramente na sua máquina — em um contêiner Docker, ou como um processo Node.js local com a distribuição npm
• 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 ferramenta remediate, 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 ao utilizar a ferramenta remediate:

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 ferramenta analyze não envia nenhum dado 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 de Modelo

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

   • Dados de violação de acessibilidade de chamadas analyze
   • Orientação de remediação de chamadas remediate
   • 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 ter 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: ou uma chave de API (gerada no Portal da Conta axe) ou um token de acesso OAuth 2.0 (obtido via @deque/axe-auth); fornecido via variável de ambiente

Importante: O servidor MCP é executado localmente na sua máquina — em um contêiner Docker, ou como um processo Node.js com a distribuição npm. Ele não requer amplo acesso ao sistema de arquivos ou privilégios elevados.

Melhores Práticas

• Segurança de Credenciais - Armazene seu AXE_API_KEY ou AXE_ACCESS_TOKEN como uma variável de ambiente, não no código. Com o OAuth 2.0, @deque/axe-auth mantém tokens em seu chaveiro do sistema operacional e injeta um token de acesso novo na inicialização, portanto, nenhum segredo de longa duração precisa estar em sua configuração
• **Teste Local** - Teste URLs de desenvolvimento local (localhost) ou de preparação 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 submetê-las ao seu código-fonte