SnapStack

El servidor SnapStack es un único proceso Node siempre activo: recibe capturas del navegador desde la extensión, las apila en disco y las sirve a cualquier cliente LLM compatible con MCP a través de HTTP Streamable. Solo escucha en 127.0.0.1 — nada sale jamás de tu máquina.

¿Nuevo aquí? La guía completa de instalación y uso está en el README de la extensión: snapstack-extension. Esta página es la referencia técnica.

Arquitectura

Un único proceso siempre activo sirve tanto a la extensión (captura) como a tu cliente MCP, desacoplados por una carpeta en disco.

[MV3 extension]  --POST /push (bytes) ┐
                                      ▼
                              [SnapStack server - 127.0.0.1:4123]   
                                 ├─ writes           →  stack on disk
                                 └─ MCP /mcp (HTTP)  ←  MCP client

• Captura — la extensión codifica la captura como WebP (con respaldo PNG), la reduce de escala y la envía aquí mediante POST.
• Pila — un archivo de imagen (.webp/.png) más un archivo .json gemelo (url, título, marca de tiempo, dimensiones) por captura, nombrado NN <timestamp>: un número estable de dos dígitos (asignado en orden de captura, se reinicia en 01 cuando la pila se vacía) más una marca de tiempo, bajo ~/.snapstack/.
• Recuperación — get_screenshots devuelve un manifiesto JSON (número, ruta absoluta, dimensiones, metadatos — sin bytes de imagen); el cliente lee solo los archivos que necesita, por ruta. La eliminación es un paso separado y explícito de clear_screenshots. La recuperación nunca elimina.

Requisitos

• Node.js ≥ 18 (probado en Node 20). No se necesita git en tiempo de ejecución.
• Un cliente LLM compatible con MCP que hable el transporte HTTP (Streamable HTTP) o stdio.
• La snapstack-extension cargada en tu navegador.

Instalación y ejecución

En Windows, usa una terminal de Administrador; de lo contrario, la instalación global de npm y el registro de la tarea programada pueden ser rechazados.

El servidor se distribuye en npm y la instalación es sencilla en macOS, Linux y Windows:

1. Instalar globalmente: npm i -g snapstack-server
2. Habilitar el servicio en segundo plano: snapstack enable

SnapStack se inicia automáticamente al iniciar sesión, se reinicia ante fallos y se actualiza solo en cada lanzamiento.
Para comprobar su estado o si hay una actualización disponible, simplemente ejecuta snapstack en tu terminal.

Comandos disponibles:

snapstack                            # status report: service + server health, update check
snapstack start | stop | restart     # control the running service (this session)
snapstack update                     # update the CLI (npm i -g) + restart the server on the latest
snapstack run                        # run the daemon in the foreground (no auto-start)

El daemon se autoactualiza en cada (re)inicio/inicio de sesión; el CLI global (el comando snapstack) no. Ejecuta snapstack update para llevar ambos a la última versión de una sola vez.

La guía completa de principio a fin (rutas de instalación idiomáticas, registro del cliente MCP, la extensión) está en el README de la extensión.

MCP

SnapStack habla dos transportes MCP sobre la misma pila en disco — elige el que admita tu cliente:

// HTTP (server already running) — register http://127.0.0.1:4123/mcp; copy deploy/mcp.json
{ "type": "http", "url": "http://127.0.0.1:4123/mcp" }

// stdio (the client spawns the process)
{ "command": "npx", "args": ["-y", "-p", "snapstack-server", "snapstack", "mcp"] }

El endpoint HTTP /mcp es sin estado (un servidor + transporte nuevos por solicitud); el front-end stdio (snapstack mcp) se genera bajo demanda y lee la misma pila ~/.snapstack.
La ingesta de capturas (/push) permanece siempre en el servidor en ejecución, independiente de cualquiera de los front-ends MCP.

Herramientas expuestas

Herramienta	Descripción
get_screenshots	Lista las capturas pendientes como un manifiesto JSON (número estable, ruta absoluta, dimensiones, metadatos) — sin bytes de imagen, sin eliminación. Pasa numbers (p. ej., [1,3]) para listar solo esas.
clear_screenshots	Elimina capturas. Pasa numbers para eliminar específicas; omítelo para limpiar toda la pila. La numeración se reinicia en 01 una vez vacía.
count_screenshots	Número de capturas pendientes, sin recuperarlas.

get_screenshots y count_screenshots son de solo lectura; solo clear_screenshots es destructiva.

Configuración

Variables de entorno (infraestructura)

Variable	Predeterminado	Propósito
SNAPSTACK_DIR	~/.snapstack	Carpeta de la pila.
SNAPSTACK_PORT	4123	Puerto de escucha (siempre en 127.0.0.1).

Política de captura (compartida entre tus navegadores)

La configuración de codificación/captura es propiedad del servidor y se almacena en ~/.snapstack/config.json, por lo que una sola edición se aplica a cada navegador que ejecute la extensión. Se editan desde la página de opciones de la extensión — no una variable de entorno — y la extensión las obtiene antes de cada captura.

Clave	Predeterminado	Significado
format	webp	Formato de imagen: webp, png o jpg.
quality	0.85	Calidad con pérdida (0–1; la interfaz de la extensión la muestra como porcentaje).
maxWidth	1568	Reduce las capturas más anchas que esto a este ancho en px (0 = sin redimensionar).
maxSlices	50	Captura de página completa: límite máximo de segmentos unidos.

Dos endpoints lo respaldan: GET /config devuelve la política efectiva; POST /config la valida y reemplaza (protegido por host + CORS como cada ruta de captura). El archivo no es una imagen, por lo que una limpieza de la pila nunca lo toca; eliminarlo solo restaura los valores predeterminados anteriores.

Solución de problemas

• Mensaje de servidor de captura no iniciado en la extensión: ejecuta snapstack start (o snapstack run en primer plano), o verifica el inicio automático con snapstack. Prueba: curl http://127.0.0.1:4123/health.
• Puerto ya en uso (EADDRINUSE): establece SNAPSTACK_PORT a otro valor.
• snapstack: command not found después de cambiar la versión de Node (nvm, fnm, volta, Laravel Herd, nvm-windows): npm i -g coloca el comando snapstack en el binario global de la versión de Node que estaba activa solo en el momento de la instalación, por lo que cambiar de versión lo oculta. Así funcionan los globales de npm, no es un error de SnapStack — el servicio en segundo plano no se ve afectado y sigue capturando; solo desaparece el comando CLI. Solución: vuelve a ejecutar npm i -g snapstack-server bajo la versión actual de Node (o vuelve a la usada en la instalación).
• El cliente no ve las herramientas: el servidor debe ejecutarse antes de que el cliente MCP se inicie; verifica la configuración (type: "http", URL correcta). Prueba directa: curl http://127.0.0.1:4123/count.
• Inspecciona la pila: ls ~/.snapstack (archivos de imagen + .json legible por humanos).

Soporte

• ¿Una pregunta o una idea? → Debates de GitHub
• ¿Encontraste un error? → abre un problema

Licencia

MIT — consulta LICENCIA.