convez.ai
PluginIntegração & APIsIntermediário
bgaze

SnapStack Server

bgaze/snapstack-server

Servidor MCP para capturar e servir screenshots do navegador a LLMs

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP local sempre ativo que recebe capturas de tela do navegador via extensão e as disponibiliza para qualquer cliente LLM compatível com MCP. Funciona 100% localmente na máquina (127.0.0.1), sem dados saindo do computador.

Instalação

$npx convez-ai bgaze/snapstack-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v1.2.3
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar capturas de tela em fluxos de AI vision com Claude
  • Automatizar análise de interfaces web com LLMs locais
  • Construir agentes que monitoram e reagem a mudanças visuais no navegador

Veredito

Solução técnica sólida para ponte visual entre navegador e LLMs via MCP. Excelente para workflows que precisam de contexto visual, com foco em privacidade (tudo local) e separação clara entre captura e leitura.

README

A tradução para o português deste README ainda está na fila.

The SnapStack server is a single always-on Node process: it receives browser captures from the extension, stacks them on disk, and serves them to any MCP-capable LLM client over Streamable HTTP. It listens only on 127.0.0.1 — nothing ever leaves your machine.

New here? The full install + usage guide lives in the extension README: snapstack-extension. This page is the technical reference.

Architecture

One always-on process serves both the extension (capture) and your MCP client, decoupled by a folder on disk.

[MV3 extension]  --POST /push (bytes) ┐
                                      ▼
                              [SnapStack server - 127.0.0.1:4123]   
                                 ├─ writes           →  stack on disk
                                 └─ MCP /mcp (HTTP)  ←  MCP client
  • Capture — the extension encodes the shot as WebP (PNG fallback), downscales it, and POSTs it here.
  • Stack — one image file (.webp/.png) plus a twin .json (url, title, timestamp, dimensions) per capture, named NN <timestamp>: a stable two-digit number (assigned in capture order, restarts at 01 when the stack empties) plus a timestamp, under ~/.snapstack/.
  • Retrieval — get_screenshots returns a JSON manifest (number, absolute path, dimensions, metadata — no image bytes); the client reads only the files it needs, by path. Deletion is a separate, explicit clear_screenshots step. Retrieval never deletes.

Requirements

  • Node.js ≥ 18 (tested on Node 20). No git needed at runtime.
  • An MCP-capable LLM client speaking the HTTP (Streamable HTTP) or stdio transport.
  • The snapstack-extension loaded in your browser.

Install & run

On Windows, use an Administrator terminal, otherwise the global npm install and the scheduled-task registration may get rejected.

The server ships on npm and installation is straightforward on macOS, Linux and Windows:

  1. Install globally: npm i -g snapstack-server
  2. Enable background service: snapstack enable

SnapStack auto-starts on login, restarts on crash, and updates itself on each launch.
To check its status or if an update is available, simply run snapstack in your terminal.

Available commands:

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)

The daemon self-updates on each (re)start/login; the global CLI (the snapstack command) does not. Run snapstack update to bring both to the latest in one go.

The full end-to-end walkthrough (idiomatic install paths, MCP client registration, the extension) is in the extension README.

MCP

SnapStack speaks two MCP transports over the same on-disk stack — pick whichever your client supports:

// 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"] }

The HTTP /mcp endpoint is stateless (a fresh server + transport per request); the stdio front-end (snapstack mcp) is spawned on demand and reads the same ~/.snapstack stack.
Capture intake (/push) always stays in the running server, independent of either MCP front-end.

Exposed tools

ToolDescription
get_screenshotsLists pending captures as a JSON manifest (stable number, absolute path, dimensions, metadata) — no image bytes, no deletion. Pass numbers (e.g. [1,3]) to list only those.
clear_screenshotsDeletes captures. Pass numbers to delete specific ones; omit to clear the whole stack. Numbering restarts at 01 once empty.
count_screenshotsNumber of pending captures, without retrieving them.

get_screenshots and count_screenshots are read-only; only clear_screenshots is destructive.

Configuration

Environment variables (infrastructure)

VariableDefaultPurpose
SNAPSTACK_DIR~/.snapstackStack folder.
SNAPSTACK_PORT4123Listening port (always on 127.0.0.1).

Capture policy (shared across your browsers)

The encoding/capture settings are owned by the server and stored in ~/.snapstack/config.json, so a single edit applies to every browser running the extension. They are edited from the extension's options page — not an environment variable — and fetched by the extension before each capture.

KeyDefaultMeaning
formatwebpImage format: webp, png or jpg.
quality0.85Lossy quality (0–1; the extension UI shows it as a percentage).
maxWidth1568Downscale captures wider than this to this width in px (0 = no resize).
maxSlices50Full-page capture: hard cap on stitched slices.

Two endpoints back it: GET /config returns the effective policy; POST /config validates and replaces it (host- + CORS-guarded like every capture route). The file is a non-image, so a stack clear never touches it; deleting it just restores the defaults above.

Troubleshooting

  • Capture server not started message in the extension: run snapstack start (or snapstack run in the foreground), or check the auto-start with snapstack. Test: curl http://127.0.0.1:4123/health.
  • Port already in use (EADDRINUSE): set SNAPSTACK_PORT to another value.
  • The client doesn't see the tools: the server must run before the MCP client starts; check the config (type: "http", correct URL). Direct test: curl http://127.0.0.1:4123/count.
  • Inspect the stack: ls ~/.snapstack (image files + human-readable .json).

Support

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados