webshot-mcp

Dale ojos a tu agente — sin darle un navegador ni tu red. Un servidor MCP con dos herramientas, screenshot y page_text, que se conecta a un Chrome que ya tengas en ejecución (a través de CDP) y captura páginas completas o elementos individuales. Nunca se inicia ni descarga ningún navegador; los objetivos de red privada están bloqueados por una política de URL consciente de SSRF.

Por qué existe esto

Dos lecciones de ejecutar bucles de verificación visual → corrección con agentes de codificación:

1. Iniciar un navegador por cada captura de pantalla es la forma lenta y poco fiable. Un Chromium sin cabeza persistente (sidecar de Docker, servicio de CI, tu Chrome de escritorio con --remote-debugging-port) es cálido, compartido y fiable. La pieza que falta es un cliente disciplinado: conectar a través de CDP, abrir un contexto nuevo por captura, cerrar solo lo que abriste, nunca matar el navegador compartido. Esa disciplina es este repositorio.

2. Una herramienta de captura de pantalla dentro de tu red es un proxy SSRF con cámara. Un agente al que se le pueda convencer de "capturar http://169.254.169.254/…" o http://redis.internal:6379/ fotografiará felizmente tu punto final de metadatos en la nube. Por lo tanto, la política de URL bloquea loopback, RFC-1918, link-local, CGNAT y objetivos v6-local — incluidos nombres de host que resuelven a ellos — a menos que permitas explícitamente el nombre de host. Los servidores de desarrollo locales son la excepción legítima, y los nombras uno por uno.

Inicio rápido

npm install
npm test        # URL-policy test suite — no browser needed
npm run demo    # policy walkthrough + a real screenshot if a CDP Chrome is reachable

Obtén un Chrome con CDP habilitado (cualquiera de estos):

# your installed Chrome, headless
chrome --headless --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 about:blank

# or a Docker sidecar you keep running
docker run -d -p 127.0.0.1:9222:9222 chromedp/headless-shell

Conéctalo a Claude Code:

claude mcp add webshot \
  -e WEBSHOT_CDP_URL=http://127.0.0.1:9222 \
  -e WEBSHOT_ALLOW_HOSTS=localhost,127.0.0.1 \
  -- npx tsx src/server.ts

Luego pídele al agente cosas como "captura la sección hero de localhost:5173 — solo .hero — y dime qué está mal": selector recorta a un solo elemento, lo que mantiene la atención del agente (y tus tokens) en la parte en discusión en lugar de una página de 4,000 píxeles.

Herramientas

Notas de diseño

• Contexto nuevo por captura, navegador compartido de por vida. Los contextos son baratos y están aislados (cookies, caché, viewport); el navegador es caro y compartido. browser.close() en una conexión CDP se desconecta sin matar el navegador remoto — el servidor puede reiniciarse todo el día sin tocar Chrome.

• Se verifica el DNS, se documenta el rebinding. Los nombres de host que no son IP se resuelven y cada dirección devuelta se vuelve a verificar contra los rangos privados. Un servidor DNS malicioso que responda de manera diferente en la segunda resolución del propio navegador (rebinding clásico) está fuera del alcance de una herramienta de captura de pantalla — se anota aquí en lugar de ignorarse.

• deviceScaleFactor: 2 — capturas retina, porque los agentes (y los humanos) leen mal el texto borroso en las capturas de pantalla más a menudo de lo que crees.

• La política es de fallo cerrado y comprobable. evaluateUrl es una función pura con toda la tabla de amenazas en su archivo de prueba; el servidor nunca llama al navegador antes de que la política diga que sí.

Pila tecnológica

TypeScript · @modelcontextprotocol/sdk (stdio) · playwright-core (solo cliente CDP — sin navegadores incluidos) · zod · vitest.

Licencia

MIT © Brandon Ta