OverlayQA MCP
Ejecuta auditorías de accesibilidad WCAG y de contraste de color en cualquier URL y archivo, y genera problemas de QA listos para desarrollo, directamente desde Claude Code, Cursor o Windsurf. Plan gratuito: 3 escaneos por día.
Documentación
OverlayQA MCP
OverlayQA MCP es un servidor del Protocolo de Contexto de Modelos que le brinda a tu agente de codificación con IA superpoderes de accesibilidad y control de calidad de diseño. Pídele a Claude Code, Cursor o Windsurf que audite cualquier URL en busca de problemas de WCAG y contraste de color, y luego lee, asigna, discute, etiqueta y resuelve problemas en tus proyectos de OverlayQA sin salir de tu 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.
Instalación
Un clic:
O agrégalo a la configuración MCP de tu editor manualmente:
Claude Code (.mcp.json en la raíz de tu proyecto) / Cursor (~/.cursor/mcp.json) / Windsurf (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] }
}
}
Cualquier cliente compatible con MCP funciona de la misma manera. En la primera ejecución, se abre una pestaña del navegador para conectar tu cuenta de OverlayQA (gratuita, sin tarjeta). El token se almacena en caché en ~/.overlayqa/auth.json durante 30 días.
Herramientas
Herramientas que tu agente puede llamar. Cada una está escrita para que el modelo elija la correcta a partir del lenguaje natural.
Auditoría
| Herramienta | Qué hace |
|---|---|
scan_accessibility | Ejecuta una auditoría WCAG (axe-core) en cualquier URL. Devuelve violaciones con severidad, criterios de éxito WCAG y una puntuación general. |
scan_contrast | Verifica las relaciones de contraste de color en una página. Devuelve los pares de elementos de primer plano/fondo que fallan. |
audit_tokens | Audita los tokens del sistema de diseño de una URL en vivo. Devuelve una puntuación de salud de tokens de 0 a 100 y hallazgos (tamaños de fuente inconsistentes, colores de texto, espaciado, familias de fuente, radios de borde) con severidad. Audita solo la página en vivo. |
Crear y gestionar problemas
| Herramienta | Qué hace |
|---|---|
scan_and_create_issues | Escanea una URL y crea automáticamente un problema por cada violación por encima de un umbral de severidad. |
create_issue | Registra un problema de control de calidad con título, severidad, tipo, descripción y asignado opcional. |
list_issues | Recorre los problemas filtrados por estado, severidad, tipo, etiquetas, asignado, creador o estado activo/finalizado/ignorado. |
update_issue | Edita los campos de problema proporcionados, asignación, estado ignorado o estado. Acepta un UUID o ID de visualización como OQ-12. |
create_project | Crea un proyecto para una URL de sitio. |
list_projects | Lista todos los proyectos de tu equipo. |
list_labels | Lee la biblioteca de etiquetas del espacio de trabajo, las etiquetas asignadas y tus permisos. |
create_label | Crea una etiqueta reutilizable del espacio de trabajo. |
set_issue_label | Aplica o elimina una etiqueta sin cambiar el texto del problema ni otras etiquetas. |
rename_label | Renombra una etiqueta del espacio de trabajo (propietario/admin). |
delete_label | Elimina una etiqueta del espacio de trabajo y sus asignaciones; conserva los problemas (propietario/admin). |
Próximamente
| Herramienta | Qué hace |
|---|---|
compare_visual | Compara una página en vivo con un marco de Figma. |
Lo que registra el servidor
Cada herramienta también acepta un argumento opcional context: una oración sobre por qué el agente la está llamando. OverlayQA registra esa oración, el nombre de la herramienta, tu cuenta, los IDs de proyecto y problema, conteos y puntuaciones, la URL en la que se ejecuta un escaneo y el nombre y versión de tu editor (del protocolo de enlace MCP) como análisis de producto. La oración está limitada y se le eliminan direcciones de correo electrónico y cadenas similares a credenciales antes de almacenarse. Nada más viaja: ni tu conversación, ni tu código, ni las respuestas de la herramienta. Detalles completos: overlayqa.com/privacy.
Ejemplos de indicaciones
- "Escanea example.com en busca de problemas de accesibilidad."
- "Verifica el contraste en nuestra página de precios y dime qué está fallando."
- "Escanea staging.acme.com y crea problemas para cualquier cosa crítica o alta."
- "Crea un problema de accesibilidad de alta severidad: el botón de inicio de sesión no tiene anillo de enfoque."
- "Lista los problemas críticos abiertos en el proyecto Acme Web."
- "Crea un proyecto para shop.acme.com y luego escanéalo."
Precios
| Escaneos | Crear problemas y proyectos | |
|---|---|---|
| Gratis | 3 / día, para siempre | — |
| Prueba de 14 días | 30 / día | sí |
| De pago | 10-30 / día según el plan, ilimitado en Pro | sí, con exportación a Linear / Jira / Asana / Notion |
Consulta overlayqa.com/pricing.
Preguntas frecuentes
¿Con qué editores funciona? Claude Code, Cursor, Windsurf y cualquier cliente compatible con MCP (habla MCP stdio estándar).
¿Es gratis? Sí para empezar: 3 escaneos de accesibilidad/contraste por día sin tarjeta. Una prueba de 14 días aumenta eso a 30 escaneos por día y desbloquea la creación de problemas y proyectos. Después de eso, crear problemas y proyectos requiere un plan de pago (Pro tiene escaneos ilimitados).
¿Qué escanea realmente? Cualquier URL pública. La accesibilidad usa axe-core mapeado a los criterios de éxito WCAG; el contraste verifica las relaciones de primer plano/fondo y devuelve los pares de elementos que fallan.
¿Necesito una cuenta? Sí, una cuenta gratuita de OverlayQA. En la primera ejecución, se abre una pestaña del navegador para conectarla; el token se almacena en caché localmente durante 30 días.
¿Funciona con la extensión de Chrome de OverlayQA? Sí. El servidor MCP y la extensión comparten los mismos proyectos y problemas, por lo que cualquier cosa que registres desde tu editor aparece en la extensión y en el panel, y viceversa.
¿Prefieres hacer clic a escribir? Conoce la extensión
El servidor MCP es una forma de acceder a OverlayQA. La extensión de Chrome es la otra: haz clic en cualquier elemento de una página en vivo y captura una captura de pantalla más el CSS, DOM y metadatos en un problema listo para desarrollo en segundos, y ejecuta auditorías de accesibilidad y sistema de diseño con IA directamente en la página. Mismos proyectos, mismos problemas, compartidos con este servidor.
Enlaces
- Sitio web: overlayqa.com
- Extensión de Chrome: Chrome Web Store
- Verificador de accesibilidad gratuito (sin cuenta): overlayqa.com/accessibility-checker
- Verificador de contraste de color gratuito (sin cuenta): overlayqa.com/color-contrast-checker
- Precios: overlayqa.com/pricing
- Protocolo de Contexto de Modelos: modelcontextprotocol.io
Licencia
MIT
Etiquetas de problemas personalizadas
Usa list_labels con un UUID de proyecto para ver las etiquetas de ese espacio de trabajo y tus permisos. create_label crea una etiqueta reutilizable; set_issue_label la aplica o elimina de un problema sin cambiar sus otras etiquetas ni su texto. Los propietarios y administradores del espacio de trabajo pueden usar rename_label y delete_label; la eliminación quita las asignaciones de la etiqueta, no sus problemas. list_issues acepta labelIds (coincidir con cualquiera), incluido unlabeled. Los informes compartidos conservan los nombres presentes al compartirlos.
La verificación local puede establecer OVERLAYQA_API_BASE y un OVERLAYQA_AUTH_FILE aislado; ninguno cambia el endpoint de producción predeterminado ni el inicio de sesión guardado normal.
Gestión de problemas en 0.3.0
Requiere la implementación de API de paridad de problemas correspondiente. Los escaneos existentes y las actualizaciones de estado siguen siendo compatibles con 0.2.0.
| Herramienta | Qué hace |
|---|---|
get_issue | Lee descripción, propiedad, etiquetas, estado ignorado, capturas de pantalla, elemento/CSS capturado y evidencia de viewport. |
list_issues | Filtra por uno o más estados, severidades o tipos; etiquetas; asignado (me, unassigned o ID de usuario); creador; y estado activo/finalizado/ignorado. Sigue hasMore con el siguiente page. |
list_project_members | Encuentra IDs de usuario de compañeros de equipo para asignación y menciones en el espacio de trabajo de un proyecto legible. |
create_issue | Elige un asignado, usa null para Sin asignar, u omítelo para asignarte a ti mismo. El tipo predeterminado es General. |
update_issue | Cambia cualquier título, descripción, severidad, tipo, estado, asignado o indicador de ignorado proporcionado. Los campos omitidos permanecen sin cambios. Ignorar nunca resuelve un problema. Establecer verificado registra un estado; no ejecuta un escaneo. |
move_issue | Mueve por UUID de problema estable a otro proyecto escribible en el mismo espacio de trabajo; conserva comentarios y evidencia. Lee el ID de visualización devuelto después. |
list_comments | Lee la discusión, audiencia, menciones y metadatos de archivos adjuntos. |
create_comment | Publica con internal explícito (solo equipo) o public (equipo y clientes), menciones y archivos PNG/JPG/PDF opcionales. |
update_comment / delete_comment | Edita o elimina tus propios comentarios nativos. Las ediciones conservan audiencia y archivos. |
get_comment_attachment | Lee un archivo de comentario nativo como nombre de archivo y bytes base64 bajo las reglas de acceso del problema. |
Para menciones, usa @[userId] en el texto e incluye el mismo ID en mentionedUserIds. La creación de comentarios requiere un UUID requestId: reutilízalo al reintentar esa misma presentación después de una respuesta perdida, para que un reintento no publique dos veces. Los archivos adjuntos son bytes base64 con nombre de archivo y tipo MIME, hasta diez archivos PNG/JPG/PDF y 10 MiB en total por comentario.
list_issues tiene como predeterminado todos los estados para compatibilidad. Usa state: "active" para problemas abiertos/en progreso que no estén ignorados. finished incluye problemas resueltos/verificados/cerrados que no estén ignorados; ignored selecciona el indicador de ignorado independiente. Todos los filtros proporcionados se intersecan. Las páginas comienzan en 1 y contienen hasta 100 problemas; una página filtrada vacía no es un resultado de proyecto completo a menos que hasMore sea falso.
Las herramientas de etiquetas enumeradas arriba están incluidas en esta versión. Los diseños guardados, enlaces de clientes, revisiones programadas y comparación visual de Figma permanecen fuera de esta versión de gestión de problemas.
Verificar antes de publicar
Ejecuta npm test y npm run build. El recorrido en vivo impulsa el cliente integrado sobre el protocolo stdio real contra una API local o producción usando cuentas de fixture designadas; crea y elimina sus propios proyectos y produce evidencia JSON y 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
Orden de publicación: implementa y verifica los endpoints del servidor, luego publica npm 0.3.0 y actualiza el registro MCP. Una compilación local o un aumento de versión no es una publicación.