OverlayQA MCP
Execute auditorias de acessibilidade WCAG e contraste de cores em qualquer URL e gere issues de QA prontas para desenvolvimento, direto do Claude Code, Cursor ou Windsurf. Plano gratuito: 3 varreduras/dia.
Documentação
OverlayQA MCP
OverlayQA MCP é um servidor Model Context Protocol que dá ao seu agente de codificação de IA superpoderes de acessibilidade e design-QA. Peça ao Claude Code, Cursor ou Windsurf para auditar qualquer URL em busca de problemas de WCAG e contraste de cores e, em seguida, leia, atribua, discuta, rotule e resolva problemas em seus projetos OverlayQA sem sair do seu editor.
You: Scan staging.acme.com for accessibility issues, then open issues for the criticals.
Agent: scan_accessibility → 7 violations (2 critical, 3 high), score 71/100.
scan_and_create_issues → created 2 issues in "Acme Web":
- Buttons missing accessible names (WCAG 4.1.2) — critical
- Insufficient text contrast on .cta (WCAG 1.4.3) — high
You: List the open criticals.
Agent: list_issues(status=open, severity=critical) → 2 issues.
Instalação
Um clique:
Ou adicione-o à configuração MCP do seu editor manualmente:
Claude Code (.mcp.json na raiz do seu projeto) / Cursor (~/.cursor/mcp.json) / Windsurf (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] }
}
}
Qualquer cliente compatível com MCP funciona da mesma forma. Na primeira execução, uma aba do navegador abre para conectar sua conta OverlayQA (grátis, sem cartão). O token fica em cache em ~/.overlayqa/auth.json por 30 dias.
Ferramentas
Ferramentas que seu agente pode chamar. Cada uma é escrita para que o modelo escolha a certa a partir da linguagem natural.
Auditoria
| Ferramenta | O que faz |
|---|---|
scan_accessibility | Executa uma auditoria WCAG (axe-core) em qualquer URL. Retorna violações com gravidade, critérios de sucesso WCAG e uma pontuação geral. |
scan_contrast | Verifica as taxas de contraste de cores em uma página. Retorna os pares de elementos primeiro plano/fundo com falha. |
audit_tokens | Audita os tokens de design-system de uma URL ativa. Retorna uma pontuação de saúde de tokens de 0 a 100 e descobertas (tamanhos de fonte inconsistentes, cores de texto, espaçamento, famílias de fonte, raios de borda) com gravidade. Audita apenas a página ativa. |
Registrar e gerenciar problemas
| Ferramenta | O que faz |
|---|---|
scan_and_create_issues | Escaneia uma URL e cria automaticamente um problema para cada violação acima de um limite de gravidade. |
create_issue | Registra um problema de QA com título, gravidade, tipo, descrição e responsável opcional. |
list_issues | Navega pelos problemas filtrados por status, gravidade, tipo, rótulos, responsável, criador ou estado ativo/concluído/ignorado. |
update_issue | Edita campos de problema fornecidos, atribuição, estado ignorado ou status. Aceita um UUID ou ID de exibição como OQ-12. |
create_project | Cria um projeto para uma URL de site. |
list_projects | Lista todos os projetos da sua equipe. |
list_labels | Lê a biblioteca de rótulos do workspace, rótulos atribuídos e suas permissões. |
create_label | Cria um rótulo de workspace reutilizável. |
set_issue_label | Aplica ou remove um rótulo sem alterar o texto do problema ou outros rótulos. |
rename_label | Renomeia um rótulo de workspace (proprietário/admin). |
delete_label | Exclui um rótulo de workspace e suas atribuições; mantém os problemas (proprietário/admin). |
Em breve
| Ferramenta | O que faz |
|---|---|
compare_visual | Compara uma página ativa com um frame do Figma. |
O que o servidor registra
Cada ferramenta também aceita um argumento opcional context: uma frase sobre por que o agente está chamando-a. OverlayQA registra essa frase, o nome da ferramenta, sua conta, IDs de projeto e problema, contagens e pontuações, a URL em que uma varredura é executada e o nome e versão do seu editor (do handshake MCP) como análise de produto. A frase é limitada e removida de endereços de e-mail e strings semelhantes a credenciais antes de ser armazenada. Nada mais trafega: nem sua conversa, nem seu código, nem as respostas da ferramenta. Detalhes completos: overlayqa.com/privacy.
Exemplos de prompts
- "Escaneie example.com em busca de problemas de acessibilidade."
- "Verifique o contraste na nossa página de preços e me diga o que está falhando."
- "Escaneie staging.acme.com e crie problemas para qualquer coisa crítica ou alta."
- "Crie um problema de acessibilidade de alta gravidade: o botão de login não tem anel de foco."
- "Liste os problemas críticos abertos no projeto Acme Web."
- "Crie um projeto para shop.acme.com e depois escaneie-o."
Preços
| Varreduras | Criar problemas e projetos | |
|---|---|---|
| Grátis | 3 / dia, para sempre | — |
| Teste de 14 dias | 30 / dia | sim |
| Pago | 10-30 / dia por plano, ilimitado no Pro | sim, com exportação para Linear / Jira / Asana / Notion |
Veja overlayqa.com/pricing.
FAQ
Com quais editores funciona? Claude Code, Cursor, Windsurf e qualquer cliente compatível com MCP (fala MCP stdio padrão).
É grátis? Sim, para começar: 3 varreduras de acessibilidade/contraste por dia sem cartão. Um teste de 14 dias aumenta para 30 varreduras por dia e desbloqueia a criação de problemas e projetos. Depois disso, criar problemas e projetos requer um plano pago (Pro tem varreduras ilimitadas).
O que ele realmente escaneia? Qualquer URL pública. Acessibilidade usa axe-core mapeado para critérios de sucesso WCAG; contraste verifica taxas primeiro plano/fundo e retorna os pares de elementos com falha.
Preciso de uma conta? Sim, uma conta OverlayQA gratuita. Na primeira execução, uma aba do navegador abre para conectá-la; o token fica em cache localmente por 30 dias.
Funciona com a extensão Chrome OverlayQA? Sim. O servidor MCP e a extensão compartilham os mesmos projetos e problemas, então qualquer coisa que você registrar do seu editor aparece na extensão e no painel, e vice-versa.
Prefere clicar a digitar? Conheça a extensão
O servidor MCP é uma forma de acessar OverlayQA. A extensão Chrome é a outra: clique em qualquer elemento de uma página ativa e ela captura uma captura de tela mais o CSS, DOM e metadados em um problema pronto para desenvolvimento em segundos, e executa auditorias de acessibilidade e design-system com IA diretamente na página. Mesmos projetos, mesmos problemas, compartilhados com este servidor.
Links
- Site: overlayqa.com
- Extensão Chrome: Chrome Web Store
- Verificador de acessibilidade gratuito (sem conta): overlayqa.com/accessibility-checker
- Verificador de contraste de cores gratuito (sem conta): overlayqa.com/color-contrast-checker
- Preços: overlayqa.com/pricing
- Model Context Protocol: modelcontextprotocol.io
Licença
MIT
Rótulos de problema personalizados
Use list_labels com um UUID de projeto para ver os rótulos desse workspace e suas permissões. create_label cria um rótulo reutilizável; set_issue_label aplica ou remove-o de um problema sem alterar seus outros rótulos ou texto. Proprietários e administradores do workspace podem usar rename_label e delete_label; a exclusão remove as atribuições do rótulo, não seus problemas. list_issues aceita labelIds (corresponder a qualquer), incluindo unlabeled. Relatórios compartilhados preservam os nomes presentes quando compartilhados.
A verificação local pode definir OVERLAYQA_API_BASE e um OVERLAYQA_AUTH_FILE isolado; nenhum altera o endpoint de produção padrão ou o login salvo normal.
Gerenciamento de problemas na 0.3.0
Requer a implantação de API de paridade de problemas correspondente. Varreduras existentes e atualizações de status permanecem compatíveis com 0.2.0.
| Ferramenta | O que faz |
|---|---|
get_issue | Lê descrição, propriedade, rótulos, estado ignorado, capturas de tela, elemento/CSS capturado e evidência de viewport. |
list_issues | Filtra por um ou mais status, gravidades ou tipos; rótulos; responsável (me, unassigned ou ID de usuário); criador; e estado ativo/concluído/ignorado. Siga hasMore com o próximo page. |
list_project_members | Encontra IDs de usuário de colegas de equipe para atribuição e menções no workspace de um projeto legível. |
create_issue | Escolha um responsável, use null para Não atribuído ou omita para atribuir a si mesmo. O tipo padrão é Geral. |
update_issue | Altera qualquer título, descrição, gravidade, tipo, status, responsável ou sinalizador ignorado fornecido. Campos omitidos permanecem inalterados. Ignorar nunca resolve um problema. Definir verificado registra um status; não executa uma varredura. |
move_issue | Move por UUID de problema estável para outro projeto gravável no mesmo workspace; retém comentários e evidências. Leia o ID de exibição retornado depois. |
list_comments | Lê a discussão, público, menções e metadados de anexos. |
create_comment | Publica com internal explícito (Somente equipe) ou public (Equipe e clientes) público, menções e arquivos PNG/JPG/PDF opcionais. |
update_comment / delete_comment | Edita ou exclui seus próprios comentários nativos. Edições preservam público e arquivos. |
get_comment_attachment | Lê um arquivo de comentário nativo como nome de arquivo e bytes base64 sob as regras de acesso do problema. |
Para menções, use @[userId] no texto e inclua o mesmo ID em mentionedUserIds. A criação de comentário requer um UUID requestId: reutilize-o ao tentar novamente o mesmo envio após uma resposta perdida, para que uma nova tentativa não publique duas vezes. Anexos são bytes base64 com nome de arquivo e tipo MIME, até dez arquivos PNG/JPG/PDF e 10 MiB no total por comentário.
list_issues padroniza para todos os estados por compatibilidade. Use state: "active" para problemas abertos/em andamento que não são ignorados. finished inclui problemas resolvidos/verificados/fechados que não são ignorados; ignored seleciona o sinalizador de ignorado independente. Todos os filtros fornecidos se cruzam. As páginas começam em 1 e contêm até 100 problemas; uma página filtrada vazia não é um resultado de projeto completo, a menos que hasMore seja falso.
As ferramentas de rótulo listadas acima estão incluídas neste lançamento. Designs salvos, links de clientes, revisões agendadas e comparação visual Figma permanecem fora deste lançamento de gerenciamento de problemas.
Verifique antes do lançamento
Execute npm test e npm run build. A jornada ao vivo dirige o cliente integrado sobre o protocolo stdio real contra uma API local ou produção usando contas de fixture designadas; ela cria e remove seus próprios projetos e produz evidências JSON e HTML.
MCP_PARITY_API=http://127.0.0.1:3241 MCP_SERVER_ENV=/path/to/server/.env npm run test:issues-live
MCP_PARITY_API=https://api.overlayqa.com npm run test:issues-live
Ordem de lançamento: implante e verifique os endpoints do servidor, depois publique npm 0.3.0 e atualize o registro MCP. Uma compilação local ou aumento de versão não é uma publicação.