web-bridge — Herramienta MCP para que los editores de IA manipulen cualquier página web estática

web-bridge es un servidor MCP (proceso único de Node, doble interfaz) que permite a los editores de IA ejecutar JavaScript, leer la consola y simular clics/entradas en páginas web estáticas que incluyen client.js. Es adecuado para la depuración local entre navegadores y múltiples pestañas, y también admite el despliegue en un servidor externo (--transport http, consulte «Despliegue remoto» más abajo).

   AI 编辑器                ┌───────────────────┐              浏览器页面
┌──────────────┐           │    MCP Server     │           ┌──────────────────┐
│  MCP Client  │           │  （Node 单进程）    │           │ <script src=     │
│              │ stdio 或   │ · 接口B: MCP       │  WebSocket │  :3210/client.js">│
│  AI 只到这里  │◄─────────►│   (stdio / http)  │◄──────────►│  client.js       │
└──────────────┘  Streamable│ · 接口A: WebSocket │  接口A     │  （eval 执行/     │
      HTTP(远程)           │ · HTTP /client.js │            │   console 捕获）  │
                           └───────────────────┘            └──────────────────┘

El editor de IA y el navegador no se conectan directamente: ambas conexiones terminan en el servidor MCP (server.js); la IA manipula la página indirectamente mediante llamadas a herramientas.

Inicio rápido

cd web-bridge
npm install          # 首次

1. Incluye el script en la página web estática (funciona con cualquier página y puerto; el origen cruzado está permitido):

<script src="http://127.0.0.1:3210/client.js"></script>

2. Configura el servicio MCP en el editor de IA: reemplaza <REPO>/server.js en mcp.json por la ruta absoluta de este repositorio y pégalo según el editor correspondiente más abajo. Cuando el editor inicia server.js, el servicio WebSocket (por defecto 127.0.0.1:3210) queda listo.

3. Dile a la IA: «Usa list_pages de web-bridge para ver qué páginas están conectadas, y luego eval_js para hacer clic en #btn y leer la consola».

Nota sobre el orden de inclusión: no importa si la página incluye primero el script; client.js se reconecta automáticamente (con retroceso 1s→2s→5s→10s) y, cuando el editor arranca, la página se vuelve a enganchar automáticamente. Página de estado del hub: http://127.0.0.1:3210/

Herramientas MCP

Regla de pageId: se puede omitir si solo hay una página conectada; si hay varias páginas y no se especifica, la herramienta devuelve un error y la lista de páginas, y la IA añadirá pageId y reintentará.

Integración con cada editor

Los siguientes ejemplos asumen que la ruta absoluta del repositorio es /path/to/web-bridge; reemplázala según sea necesario.

ZCode / Claude Code (.mcp.json en la raíz del proyecto, o claude mcp add):

{
  "mcpServers": {
    "web-bridge": {
      "command": "node",
      "args": ["/path/to/web-bridge/server.js"],
      "env": { "PORT": "3210" }
    }
  }
}

Cursor (.cursor/mcp.json): mismo formato.

Claude Desktop (claude_desktop_config.json): mismo formato.

Argumentos de línea de comandos: node server.js --port 3210 --host 127.0.0.1 --token <secret> (también puedes usar las variables de entorno PORT / HOST / TOKEN).

Despliegue remoto (servidor externo)

El modo stdio predeterminado requiere que el editor inicie el proceso localmente; al desplegar web-bridge en un servidor externo, usa el modo de transporte HTTP; el editor solo necesita poner una URL en la configuración de MCP:

1. Inícialo en el servidor (se recomienda gestionarlo con systemd / pm2; en una red pública es obligatorio activar el token):

node server.js --transport http --host 0.0.0.0 --port 3210 --token <secret>

2. Configuración del editor (Claude Code / Cursor / ZCode, etc., pégalo en la ubicación de configuración original):

{
  "mcpServers": {
    "web-bridge": {
      "type": "http",
      "url": "https://your-domain.com/mcp",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}

Cuando se conecta directamente (sin proxy inverso/TLS), la URL debe ser http://<服务器IP>:3210/mcp. Nota: Claude Desktop solo admite el modo stdio local, no admite URLs remotas.

3. Cambia el script del lado de la página para que apunte al servidor:

<script src="https://your-domain.com/client.js?token=<secret>"></script>

Notas:

• Las páginas HTTPS solo pueden conectarse a https/wss (limitación de contenido mixto). Se recomienda usar un proxy inverso como nginx / caddy para terminar TLS y reenviar al servicio; client.js detecta automáticamente X-Forwarded-Proto / X-Forwarded-Host al servirse y genera la dirección de conexión wss:// correcta, sin configuración adicional. Ejemplo de caddy (certificado automático):

your-domain.com {
  reverse_proxy 127.0.0.1:3210
}

• Con el token activado, el endpoint /mcp admite tres formas de autenticación: Authorization: Bearer <secret> (recomendado; rellena los headers en la configuración del editor), X-Web-Bridge-Token: <secret> y el parámetro de URL ?token=.

• El transporte HTTP es el protocolo oficial Streamable HTTP (modo stateless); cada solicitud se procesa de forma independiente, comparten el mismo hub y varios editores pueden conectarse simultáneamente.

• Para desplegar en una red pública es imprescindible: establecer --token, usar TLS y permitir solo los puertos necesarios en el cortafuegos.

Notas de seguridad

• Por defecto solo escucha en 127.0.0.1. Cualquier página web abierta en la máquina (incluidos los sitios de terceros que estés visitando) puede intentar conectarse al puerto local; en el modo sin token predeterminado, pueden recibir el código enviado por la IA y también falsificar resultados.

• En entornos de red no confiables, o si quieres permitir que dispositivos LAN como teléfonos se conecten (--host 0.0.0.0), asegúrate de activar --token: en ese caso, obtener client.js requiere ?token=<secret>, y el primer paquete WebSocket también verificará el token.

Protocolo de mensajes WebSocket (referencia interna)

Los mensajes WS entre el navegador y el servidor MCP son tramas de texto JSON; consulta esto al mantener lib/hub.mjs / client.js:

Convención de ejecución de eval (client.js): primero se envuelve como expresión async () => ( code ); si hay SyntaxError, se recurre al bloque de sentencias (se puede usar return); incluye $ / $$; el tiempo de espera lo mide el hub (30 s por defecto, máximo 120 s); el resultado se serializa de forma segura como vista previa de cadena (Error→stack, DOM→resumen outerHTML, marcas de referencias circulares, profundidad ≤ 6, ≤ 50k caracteres).

Desarrollo

• Pruebas: npm test (e2e de Node: inicia el proceso + simula la página + llama a las herramientas con transporte stdio/HTTP); npm run test:browser (cadena de navegador real con Playwright: Chromium carga test/test-page.html, verifica las 6 herramientas a través de WebSocket real; antes de la primera ejecución, haz npx playwright install chromium). La cadena de navegador real también se puede verificar manualmente abriendo la página de prueba.

• Dependencias: ws (WebSocket), @modelcontextprotocol/sdk (MCP), zod (validación de parámetros); dependencia de desarrollo @playwright/test. Node ≥ 18.