Claude Code Plugin

Visão Geral

O plugin de Acessibilidade Axe é o kit de ferramentas de acessibilidade da Deque para agentes de codificação, instalado e executado a partir de Claude Code. Sua instalação faz três coisas ao mesmo tempo:

• Registra o servidor. O plugin fornece uma entrada de servidor MCP pronta, para que você não precise escrever um .mcp.json à mão.
• Ensina Claude a usar as ferramentas. Uma habilidade em segundo plano é carregada automaticamente em trabalhos de acessibilidade, então Claude segue o loop analisar → remediar → verificar, agrupa remediate corretamente e mapeia campos entre as ferramentas sem adivinhar.
• Adiciona três comandos barra para configuração, geração de instruções de agente em nível de repositório e execução do ciclo completo de remediação em uma página.

O plugin é de código aberto em github.com/dequelabs/axe-accessibility e está licenciado sob MIT.

Não é apenas para o Claude Code

Claude Code é onde o plugin roda, mas dois dos seus comandos produzem resultados para agentes e editores outros:

• /axe-accessibility:mcp-generate-instructions escreve o fluxo de trabalho analisar → remediar → verificar em .github/copilot-instructions.md, regras do Cursor, ou AGENTS.md tão facilmente quanto em CLAUDE.md. Qualquer pessoa da equipe que usa Copilot ou Cursor herda o fluxo de trabalho do repositório, independentemente de ter ou não o plugin — ou o Claude Code — instalado.
• /axe-accessibility:mcp-setup pode configurar o Axe MCP Server para Cursor, VS Code com Copilot ou Claude Desktop, não apenas Claude Code.

Portanto, é razoável instalar o plugin apenas como uma ferramenta de configuração e autoria de instruções para um repositório cujos colaboradores usam uma mistura de agentes.

Requisitos

Para instalar o plugin:

• Claude Code com suporte a plugins.

Para executar verificações — isto é, usar as ferramentas analyze, igt e remediate, seja a partir do Claude Code ou de outro cliente configurado pelo plugin:

• Uma assinatura Axe DevTools para Web que inclui acesso ao Axe MCP Server. Sem ela, as ferramentas falharão na autenticação.
• Um ambiente de execução, dependendo de qual distribuição você usa:
  • npm (o que o plugin fornece): Node.js 22.19.0 ou superior, além de uma instalação única do Chromium. Veja Instalar Chromium — o servidor não baixa um navegador para você, e pular esta etapa é o erro mais comum na primeira execução.
  • Docker: Docker instalado e em execução. O Chromium é fornecido dentro da imagem.
• Para autenticação OAuth 2.0: um versão LTS ativa do Node.js, já que a configuração utiliza npx @deque/axe-auth.

Apenas o primeiro se aplica se você estiver instalando o plugin apenas para executar /axe-accessibility:mcp-generate-instructions — criar arquivos de instrução de agente não requer nem um ambiente de execução nem uma assinatura.

Instalação

Adicione o marketplace da Deque e instale o plugin de dentro do Claude Code:

/plugin marketplace add dequelabs/axe-accessibility
/plugin install axe-accessibility

O primeiro comando registra o repositório dequelabs/axe-accessibility como um marketplace de plugins (o repositório funciona como seu próprio marketplace). O segundo instala o plugin a partir dele. Você só precisa adicionar o marketplace uma vez — instalações e atualizações posteriores podem pular essa etapa.

Reinicie o Claude Code quando solicitado para que o servidor MCP seja carregado.

Autenticação

A configuração do servidor incluída no plugin é agnóstico de autenticação: na inicialização, ele tenta gerar um token de acesso OAuth e garante que exatamente uma credencial chegue ao servidor — o token OAuth, se você estiver logado, caso contrário, seu AXE_API_KEY.

Escolha o método que lhe convier:

• Chave API — crie uma no Portal de Conta Axe em Chaves API → ADICIONAR NOVA CHAVE API, escolhendo o produto Servidor Axe MCP. Depois, exporte-a no seu shell para que o Claude Code possa lê-la:

  export AXE_API_KEY="your-api-key-here"

  Adicione a linha ao perfil do seu shell (~/.bashrc, ~/.zshrc, etc.) para persistir. Nunca comite a chave em um arquivo no seu repositório.

• OAuth 2.0 — faça login uma vez com o CLI @deque/axe-auth:

  npx -y @deque/axe-auth login

  Isso abre um navegador para o fluxo PKCE e armazena tokens no chaveiro do seu sistema operacional, atualizando-os automaticamente. Veja Autenticação para o fluxo completo, gerenciamento de sessões e suporte de plataforma.

A configuração incluída lida com essa regra para você, e ela deve trabalhar mais arduamente do que uma configuração Docker faria. Um contêiner só recebe as variáveis passadas com as flags explícitas -e, mas a distribuição npm herda todo o ambiente do seu shell — assim, um AXE_API_KEY exportado e uma sessão OAuth ativa chegariam de outra forma ao servidor e o impediriam de iniciar. A entrada incluída limpa qualquer AXE_ACCESS_TOKEN herdado primeiro, depois, se conseguir gerar um token novo, desconfigura AXE_API_KEY antes de configurá-lo. O OAuth vence quando ambos estão disponíveis.

Implantações em nuvem privada e no local

A distribuição npm herda AXE_SERVER_URL do seu shell, então exportá-lo junto com sua credencial é suficiente:

export AXE_SERVER_URL="https://your-axe-instance.example.com"

Se você usar OAuth, também passe a mesma URL ao fazer login: npx -y @deque/axe-auth login --server https://your-axe-instance.example.com. Se AXE_SERVER_URL não estiver configurado, o servidor padrão será https://axe.deque.com (instância SaaS compartilhada dos EUA da Deque). Veja Referência de Configuração.

Verificando a instalação

1. Reinicie o Claude Code.

2. Execute /mcp e confirme que axe-mcp-server está listado e conectado, com as ferramentas analyze, igt e remediate disponíveis.

3. Execute uma varredura de teste contra uma página conhecida:

   Analyze https://dequeuniversity.com/demo/mars for accessibility issues

Uma varredura bem-sucedida de uma página real retorna um payload considerável — dezenas de kilobytes é normal, não um erro. Se o seu cliente reclamar que o resultado é muito grande, delimite a varredura com o parâmetro selector de analyze.

Se o servidor não conectar, confirme a sua versão do Node, que o Chromium está instalado, e que exatamente uma credencial está configurada, depois veja Solução de Problemas.

O que está incluído

A habilidade mcp-usage

Você nunca invoca esta diretamente. Ela carrega automaticamente sempre que uma tarefa envolve acessibilidade, a11y, conformidade com WCAG ou correção de problemas de acessibilidade na interface web, e fornece a Claude o conhecimento operacional que de outra forma teria que ser escrito à mão em um CLAUDE.md:

• O fluxo de trabalho. Analise a página, remedie as violações, depois reanalise para verificar se não há violações antes de considerar o trabalho concluído.
• Mapeamento de campo. Como cada questão de analyze se mapeia nos parâmetros de remediate — a fonte mais comum de erro quando um agente conecta as duas ferramentas por tentativa e erro. Inclui as armadilhas: problemas chegam sob o array data da resposta, e o campo próprio de um problema remediation é um objeto de dados de verificação brutos, não a string que o parâmetro remediate quer.
• Agrupamento. remediate aceita um array issues de 1 a 25 por chamada, cada um com um id inventado pelo chamador. Uma chamada por varredura, não uma por problema — uma forma de chamada por problema é rejeitada imediatamente.
• Os Consciência de crédito. créditos são consumidos por problema, não por chamada, portanto, o agrupamento é o contrato em vez de um desconto. Reexecutar analyze para verificar não consome nada, por isso a verificação é barata.
• Quais achados confiar. Issues flagged isAdvanced: true come from Regras Avançadas — AI and computer vision — and are probabilistic, so they warrant confirmation against the real UI. Standard axe-core findings (isAdvanced: false) are deterministic and authoritative.
• Teste do teclado. When to reach for igt, and how its issue shape differs from analyze's.
• Nuances específicas da regra. Orientação para regras que exigem julgamento, como image-alt, color-contrast, link-name/button-name e rotulagem de formulários.

Como a habilidade está sempre disponível, os pedidos em linguagem simples funcionam sem cerimônia:

Make the checkout page at http://localhost:3000/checkout accessible

Comandos

/axe-accessibility:mcp-setup

/axe-accessibility:mcp-setup [client]

Guia você na conexão com o servidor Axe MCP, perguntando sobre as decisões em vez de assumi-las. Opcionalmente, passe um cliente — claude-code, cursor, vscode ou claude-desktop — para pular essa pergunta.

O comando:

1. Pergunta se você deseja o npm ou Docker distribuição, depois verifica aquele runtime — versão do Node e Chromium para npm, um daemon em execução para Docker.
2. Pergunta se você deseja autenticação Chave API ou OAuth 2.0, depois orienta a criação de uma chave no Portal da Conta ou a execução do login no navegador.
3. Escreve a configuração correspondente para o seu cliente — mesclando em qualquer configuração MCP existente em vez de substituí-la. Para o Claude Code na distribuição npm, o servidor incorporado do plugin geralmente torna esse passo desnecessário.
4. Oferece as configurações opcionais que vale a pena conhecer: AXE_SERVER_URL para nuvem privada, AXE_ADVANCED_RULES para um padrão de Regras Avançadas permanente, e AXE_CHROME_PATH para reutilizar um navegador que você já tem (apenas npm).
5. Verifica a conexão e executa uma varredura de fumaça.

Útil, mesmo que instalar o plugin já registre o servidor: execute-o quando precisar configurar a autenticação pela primeira vez, mudar para Docker, apontar para uma instância de nuvem privada, ou configurar um editor diferente na mesma máquina. Os snippets de cliente que ele emite são os mesmos documentados para VS Code com Copilot, Cursor e Claude Code — o comando apenas escolhe o correto e o mescla na sua configuração existente.

/axe-accessibility:mcp-generate-instructions

/axe-accessibility:mcp-generate-instructions [targets]

Escreve o fluxo de trabalho obrigatório de analisar → remediar → verificar nos arquivos de instruções do agente do seu repositório, para que qualquer agente de codificação trabalhando no repositório — não apenas aquele com o plugin instalado — o siga. Alvos:

Sem argumento, o comando detecta quais desses arquivos já existem e confirma isso com você antes de escrever.

Cada arquivo recebe o contrato completo, não apenas o loop: a regra de agrupamento remediate, o mapeamento de campo, a distinção de confiança entre determinístico e avançado, a seção igt do teclado e a nota de crédito. Os nomes das ferramentas são adaptados por alvo, já que os clientes compartimentam as ferramentas MCP de forma diferente — o Copilot se conecta a mcp_axe-mcp-server_analyze, por exemplo, enquanto o Claude Code e Cursor resolvem nomes simples.

Os arquivos existentes são mesclado, não substituído: se uma seção de fluxo de trabalho de acessibilidade já estiver presente, ela é atualizada no mesmo local, caso contrário, a seção é adicionada, e o restante do arquivo é preservado. O comando também adapta as instruções para o seu repositório onde possível — por exemplo, referenciando o verdadeiro URL do servidor de desenvolvimento do seu projeto e comando de início em vez de um espaço reservado.

/axe-accessibility:mcp-generate-instructions all

Gerar all é a escolha usual para um repositório compartilhado: uma pessoa executa uma vez a partir do Claude Code, comita os arquivos, e o agente de cada colaborador adota o fluxo de trabalho — Copilot de .github/copilot-instructions.md, Cursor de .cursor/rules/accessibility.mdc, e assim por diante. As instruções só têm efeito para agentes que as leem, e cada colaborador ainda precisa do servidor Axe MCP conectado em seu próprio cliente para que o fluxo de trabalho realmente funcione.

Este é o equivalente automatizado do modelo em Configurando Seu Agente de IA.

/axe-accessibility:mcp-audit

/axe-accessibility:mcp-audit <url> [max-rounds]

Executa o ciclo completo de remediação em uma página e aplica as correções ao seu código-fonte. Passe o URL completo incluindo esquema e porta. Se você omitir, o comando tenta detectar um servidor dev em execução a partir dos seus scripts package.json e portas comuns, e confirma o URL com você antes de escanear.

Cada rodada:

1. Analisar o URL e coletar os problemas.
2. Triajar por bandeira — os achados isAdvanced são confirmados contra a interface real antes que qualquer coisa seja alterada, os achados isNeedsReview são apresentados a você em vez de corrigidos automaticamente quando a chamada é uma decisão de design, e os achados isBestPractice nunca bloqueiam "limpo".
3. Remediar cada problema da rodada em uma chamada agrupada única (até 25 por chamada, dividido em lotes sequenciais além disso).
4. Aplicar as orientações ao seu código-fonte, correlacionando cada resultado pelo id e verificando seu status, uma vez que um lote pode falhar parcialmente. As correções de código sugeridas são adaptadas ao componente real em vez de coladas literalmente.
5. Re-analisar para verificar.

O loop para em zero violações ou após max-rounds (padrão 5). Também para prematuramente se uma rodada não fizer progresso — nesse ponto, os problemas restantes geralmente precisam de uma decisão de design, ou são falsos positivos de regra avançada, que o comando relata como tal em vez de contorcer seu código para atingir zero. O progresso é relatado por rodada (por exemplo, round 1: 7 → round 2: 2 → round 3: 0), e o comando resume as mudanças de código que realizou para que você possa revisá-las antes de confirmar.

/axe-accessibility:mcp-audit http://localhost:3000/checkout 3

Reaching a page that isn't a plain URL works the way it does for the underlying tool: describe a login or interaction and the steps are passed through as before ações; describe environment routing or a pre-authenticated session and they're passed as cookies, which apply before navigation. Keep secrets in a fill step's value or a cookie's value, never in a selector or a cookie name.

Uma vez que as violações automatizadas estão limpas, o comando pode executar uma passe de teclado opcional com igt — a ordem de foco, armadilhas de foco, e visibilidade de foco são invisíveis para um escaneamento estático. Solicite diretamente se desejar em uma página com menus, diálogos ou widgets personalizados:

/axe-accessibility:mcp-audit http://localhost:3000 and run the keyboard test

Fluxo de trabalho sugerido

1. /axe-accessibility:mcp-setup — conecte e autentique o servidor. Verifique com /mcp.
2. /axe-accessibility:mcp-generate-instructions all — integre o fluxo de trabalho no repositório para que todos os agentes e colegas de equipe o herdem.
3. /axe-accessibility:mcp-audit http://localhost:3000 — limpe a dívida de acessibilidade já presente na página.
4. A partir daí, apenas construa. A habilidade mcp-usage mantém Claude rodando o ciclo em mudanças de IU sem ser solicitado.

Gerenciando o plugin

O comando /plugin de Claude Code gerencia o ciclo de vida do plugin:

/plugin                 # browse and manage installed plugins
/plugin update axe-accessibility
/plugin uninstall axe-accessibility

Desinstalar remove a entrada do servidor MCP empacotada junto com as habilidades e comandos. Qualquer arquivo de instrução de agente escrito por /axe-accessibility:mcp-generate-instructions permanece no seu repositório — remova-os você mesmo se não quiser mais eles.

Páginas relacionadas

• Escolhendo uma Distribuição — npm versus Docker, e instalando Chromium para npm
• Configuração no Claude Code — configurando o servidor manualmente, sem o plugin
• Autenticação — chave de API e OAuth 2.0 na íntegra
• Referência de Configuração — variáveis de ambiente e modelos de instrução de agente
• Regras Avançadas — predefinições, precedência e o que o sinalizador isAdvanced significa
• Solução de Problemas — conexão, Chromium, Docker, e erros de autenticação
• Créditos de IA — como remediate e igt consomem créditos