easy-ui-mcp

Un servidor MCP (Model Context Protocol) dockerizado para pruebas de UI locales. Expone herramientas de automatización de navegador basadas en Playwright a través de HTTP/SSE para que un agente de IA (como Claude Code) pueda guiar flujos de UI web paso a paso y recibir un informe JSON + HTML con capturas de pantalla, sin LLM en el servidor y sin necesidad de escribir scripts de prueba.

Inicio rápido

docker compose up -d --build
curl http://localhost:8765/health
# {"status":"ok"}

Conecta Claude Code:

claude mcp add --transport http easy-ui-mcp http://localhost:8765/mcp

Después pide a Claude Code que navegue a una página y haga una captura de pantalla: llamará a las herramientas que aparecen más abajo y te informará del resultado.

¿Usar esto desde otro repositorio? El registro de MCP es por proyecto: ejecuta también claude mcp add desde la raíz de ese repositorio (el contenedor anterior solo necesita ejecutarse una vez y se comparte entre repositorios). Consulta AGENTS.md → Uso de easy-ui-mcp desde otro repositorio para conocer todos los pasos necesarios.

Related MCP server: Playwright MCP Server

Redes

El contenedor se ejecuta con network_mode: host en docker-compose.yml (no con un puerto publicado en una red bridge). Esto es obligatorio, no opcional: el navegador que Playwright controla dentro de este contenedor necesita acceder a localhost:<port> en tu máquina host, donde se está ejecutando realmente el servidor de desarrollo de la aplicación objetivo (el repositorio que estás probando). Una red bridge por defecto le da al contenedor su propio espacio de nombres de red aislado, sin ninguna ruta de vuelta al host: las URL objetivo como http://localhost:8766 se quedarán colgadas o fallarán con ERR_CONNECTION_REFUSED, y http://<host-LAN-IP>:8766 simplemente agotará el tiempo de espera, incluso si el servidor objetivo está escuchando y es accesible mediante curl desde el shell del host.

Si haces un fork o vuelves a desplegar este contenedor en algún lugar donde network_mode: host no esté disponible (p. ej., Docker Desktop en macOS/Windows, donde la compatibilidad con la red host es limitada o inexistente), usa host.docker.internal como nombre de host objetivo en lugar de localhost al llamar a ui_navigate, y añade a docker-compose.yml extra_hosts: ["host.docker.internal:host-gateway"] como alternativa a network_mode: host.

Herramientas

ui_start_session, ui_end_session, ui_step, ui_navigate, ui_click, ui_fill, ui_assert, ui_check, ui_wait_for, ui_get_page_state, ui_take_screenshot, además de un envoltorio REST en POST /api/run-test para clientes que no usan MCP.

Etiqueta tus pasos

ui_step(label) agrupa todo lo que le sigue bajo un encabezado en lenguaje natural, hasta el siguiente ui_step. La etiqueta es la única declaración de intención del informe escrita por quien llama. El servidor usa plantillas deterministas como «Opened …», «Clicked …» y «Filled …» para las acciones individuales (no se ejecuta ningún LLM dentro del contenedor), por lo que una sesión sin etiquetas sigue mostrando descripciones de acciones legibles bajo un único grupo implícito.

ui_start_session  target: "Account Access toggle smoke"
ui_step           label:  "Open the Settings page"
ui_navigate       ...
ui_wait_for       ...
ui_step           label:  "Turn Manual Invoice access on"
ui_click          ...
ui_assert         ...
ui_end_session

Las sesiones sin llamadas a ui_step también se muestran correctamente, bajo un único grupo implícito.

Verificar vs. esperar: elige la opción correcta

Una sesión se marca como failed si falla cualquier acción dura, así que cómo verifiques decide si el informe dice la verdad.

No llames nunca a ui_assert en un bucle de reintentos para esperar algo: el primer resultado falso hace fallar la ejecución de forma permanente aunque la aplicación esté bien. Para eso está ui_wait_for.

Tanto para ui_check como para ui_wait_for, una condición que no puede ejecutarse (no hay ninguna página abierta o la expresión lanza una excepción) es siempre un fallo duro: eso es un error del arnés de pruebas, no una observación.

Las capturas de pantalla automáticas en caso de fallo tienen un presupuesto por sesión (FAILURE_SCREENSHOT_BUDGET, 3 por defecto). El contenido de capturas de pantalla idénticas solo se incrusta una vez en el informe HTML.

Qué muestra el informe

Una caja de veredicto (estado, objetivo, recuentos de pasos/acciones/fallos, duración), después la ejecución como pasos etiquetados con el resultado de cada paso y el tiempo transcurrido, luego cualquier problema del navegador y, por último, el registro de acciones en bruto plegado tras un elemento desplegable.

Los errores de consola, los errores de página no capturados y los fallos de solicitud a nivel de red se capturan automáticamente y se enumeran en Problemas del navegador: un flujo que pasa mientras la consola lanza errores es un falso verde que merece la pena ver. Las respuestas de error HTTP como 404 o 500 no activan el evento requestfailed de Playwright y no se enumeran automáticamente. Los problemas capturados son informativos y nunca cambian el veredicto. Se conservan hasta 50 por sesión; a partir de ahí, el informe indica que el resto se descartaron.

Consulta AGENTS.md para conocer la arquitectura y la guía completa de conexión MCP, y HARNESS.md para la referencia de la API REST. Los procedimientos de despliegue y reversión están en RUNBOOK.md.

Alcance (v1)

Solo web (Chromium), solo local, sin soporte móvil por ahora. Consulta PRD.md para conocer la intención completa del producto y PROJECT_SPEC.md para las decisiones de arquitectura.