web-debug-mcp

web-debug-mcp es un servidor de depuración web local, nativo para agentes, para Codex y otros clientes MCP. Expone una pequeña superficie de herramientas que coordina una sesión de navegador, un depurador de JavaScript, evidencia de ejecución acotada y verificación de flujos reproducible.

El incremento actual admite objetivos de navegador independientes del framework, Chromium/CDP, Safari WebDriver con evidencia WebDriver BiDi, un puente de desarrollo de React inyectado automáticamente, un endpoint de grafo de módulos/HMR de Vite, y metadatos del servidor de desarrollo de Next.js con cola de registros del servidor acotada, compilación de rutas, búsqueda de Server Actions y evidencia de ejecución de solicitudes observadas. Los límites específicos del navegador siguen siendo explícitos. Esto mantiene el contexto específico del framework detrás de la misma fachada MCP en lugar de añadir catálogos de herramientas separados.

Qué incluye

• Detección de capacidades del proyecto sin iniciar un proceso.

• Modo de adjuntar a Chromium local mediante un endpoint CDP explícito.

• La adjunción remota explícita a CDP solo se admite con allowRemote: true; los objetivos se marcan como no aislados y nunca se descubren automáticamente.

• Modo de lanzamiento de Chromium local mediante una ruta de ejecutable explícita.

• Modo Safari WebDriver mediante safaridriver local o un endpoint WebDriver explícito, con eventos de consola BiDi y eventos de red cuando el Safari instalado los expone.

• Acciones de navegador de mismo origen: navegar, hacer clic, rellenar, esperar y recargar.

• Puntos de interrupción de JavaScript, control de pausa, marcos de llamada acotados y evaluación de solo lectura por defecto.

• Consola, metadatos de red, resumen DOM, captura de pantalla y evidencia del depurador en un paquete redactado.

• Árbol de componentes de React, valores de hooks, ubicaciones de origen, recuentos de renderizado, resúmenes de commits acotados, duraciones del perfilador, una vista de gráfico de llama plana y causas de renderizado inferidas cuando la compilación de desarrollo expone commits de React.

• Grafo de módulos/importadores de Vite, estado de HMR, diferencias de código transformado y resúmenes de source maps a través del plugin de desarrollo webDebugVitePlugin().

• Colas de registros de desarrollo de Next.js acotadas y redactadas cuando el registro permanece dentro de la raíz del proyecto detectada.

• Compilación de rutas de Next.js explícita y búsqueda de Server Actions mediante web_next_inspect, además de trazas de solicitudes de servidor normalizadas y evidencia de ejecución vinculada a solicitudes cuando el navegador envía una solicitud Next-Action.

• Línea de tiempo de reproducción acotada en capturas y búsqueda de marcos mediante web_replay_seek; restore: true reproduce solo acciones retenidas seguras y rechaza entradas de formulario sanitizadas.

• Escenarios de acción reproducibles con comprobaciones posteriores a la corrección simples.

• Un fixture vanilla determinista y una comprobación de arnés nativa del proyecto.

• Un fixture React/Vite en vivo, puente de React automático y prueba de humo de grafo de módulos/HMR.

• Un fixture Next.js App Router en vivo y prueba de humo del runtime /_next/mcp.

Related MCP server: Kaboom Browser AI Devtools MCP

Requisitos

• Node.js 20 o más reciente. Safari BiDi requiere Node 20.10+ con --experimental-websocket o Node 21+; los runtimes más antiguos mantienen las acciones de Safari WebDriver y el respaldo de red documentado, pero informan limitaciones de consola BiDi.

• Un navegador basado en Chromium al ejecutar una sesión en vivo.

• O bien una WEB_DEBUG_CHROME_EXECUTABLE_PATH explícita o un cdpEndpoint explícito proporcionado a web_session_start.

Comandos de desarrollo

npm install --no-audit --no-fund
npm test
npm run typecheck
npm run build
npm run harness:check
npm run smoke:live
npm run smoke:react-vite
npm run smoke:next
npm run smoke:safari

Ejecuta el fixture con npm run serve:fixture. El servidor se vincula a 127.0.0.1 y usa el puerto 4173 por defecto; establece WEB_DEBUG_FIXTURE_PORT para usar otro puerto.

Ejecuta npm run smoke:live después de establecer WEB_DEBUG_CHROME_EXECUTABLE_PATH cuando la ruta de Chrome de macOS por defecto no esté disponible. Inicia el fixture vanilla, establece un punto de interrupción en app.js, hace clic en el botón, captura una ruta de evidencia segura para pausa y limpia el navegador y los procesos del fixture que posee.

Ejecuta npm run smoke:react-vite para iniciar el fixture de Vite, verificar la evidencia de componentes/estado de React, pausar en fixtures/react-vite/src/App.jsx y reproducir el flujo de pago enviado.

Para una aplicación de Vite, añade el plugin solo de desarrollo a vite.config.ts:

import { webDebugVitePlugin } from "web-debug-mcp/vite";

export default {
  plugins: [webDebugVitePlugin()],
};

El plugin sirve el endpoint local de grafo de módulos de solo lectura utilizado durante una sesión de depuración. No debe habilitarse en un servidor de producción.

Ejecuta npm run smoke:next para iniciar el fixture de Next.js App Router, consultar su endpoint integrado /_next/mcp, verificar metadatos de rutas/proyecto/compilación y una cola de registros de servidor acotada, y ejercitar el flujo del manejador de rutas del cliente.

Ejecuta npm run smoke:safari para ejercitar el fixture vanilla a través de Safari WebDriver. Habilita primero Safari Configuración → Desarrollador → Permitir automatización remota; Safari se ejecuta visiblemente, captura evidencia de consola BiDi e informa si la evidencia de red provino de BiDi o del respaldo acotado de Performance Resource Timing. El depurador de JavaScript de Safari sigue sin estar disponible a través de este adaptador.

Safari 27 y Safari Technology Preview 247 incluyen el servidor MCP oficial de Safari de Apple. Usa ese servidor oficial cuando sus herramientas nativas de DOM, red, consola y capturas de pantalla del navegador sean la superficie deseada; este repositorio no añade un catálogo MCP público duplicado de Safari. El adaptador WebDriver sigue siendo útil como la ruta de compatibilidad de fachada única del conjunto para versiones antiguas de Safari y para la orquestación compartida de sesiones/evidencia.

Ejecuta el servidor MCP con npm run dev durante el desarrollo o node dist/index.js después de npm run build. Los mensajes del protocolo MCP usan stdout; los diagnósticos deben permanecer en stderr.

Flujo de trabajo MCP

1. Llama a web_project_detect con la raíz del proyecto.

2. Llama a web_session_start con una URL de bucle local y una conexión de navegador o ejecutable explícito.

3. Usa web_browser_action y web_breakpoint_set para reproducir el problema.

4. Llama a web_issue_capture para obtener un paquete de evidencia acotado.

5. Para Next.js, llama a web_next_inspect para compilar una ruta o resolver un ID de Server Action.

6. Almacena un flujo con web_repro_record y ejecútalo más tarde con web_fix_verify.

7. Usa web_replay_seek para inspeccionar un marco capturado retenido; pasa restore: true solo cuando el marco contenga acciones seguras y no sensibles.

8. Llama a web_session_close cuando la sesión ya no sea necesaria.

El servidor no escribe en el proyecto durante una sesión normal. Las capturas de pantalla se almacenan en un directorio de artefactos temporal por sesión y se devuelven como rutas.

Valores predeterminados de seguridad

• Las URL del navegador son solo de bucle local a menos que allowRemote esté explícitamente habilitado.

• La navegación del navegador permanece en el origen de la sesión.

• La adjunción CDP externa se marca como no aislada.

• La consola, la red, las variables locales del depurador y los valores evaluados se redactan y acotan.

• Los cuerpos de respuesta sin procesar, las cookies, los valores de autorización y el almacenamiento del navegador no se recopilan por el adaptador principal.

• La evaluación rechaza efectos secundarios a menos que allowSideEffects sea explícitamente verdadero.

Límite actual

Este repositorio es una herramienta de desarrollo local, no un servicio alojado. No tiene despliegue de producción, flujo de trabajo de CI, control remoto de navegador no autenticado/auto-descubierto, ni paridad completa con el perfilador/gráfico de llama de React DevTools. Las duraciones de React y los detalles de causa de renderizado están acotados e inferidos del hook de DevTools; la procedencia de Vite y los source maps son resúmenes en lugar de un depurador de source maps completo; la evidencia de ejecución de Next se limita a metadatos de Server Actions vinculados a solicitudes, información de solicitudes y registros acotados; la paridad del depurador de Safari no está disponible y Safari 26 puede requerir el respaldo de red de Performance Resource Timing; la restauración de reproducción se limita a acciones retenidas seguras y no es un viaje en el tiempo del estado de la aplicación. La adjunción CDP remota explícita, las acciones/DOM/capturas de pantalla de Safari WebDriver, las advertencias de capacidad explícitas y la restauración de reproducción acotada están disponibles. Un host remoto externo aprobado y evidencia de certificación de arnés proporcionada por el llamador aún son necesarios para esas afirmaciones respectivas.