SnapStack

Capture qualquer aba do navegador com um clique e envie para seu cliente MCP — 100% local, sem conta, sem telemetria.

Documentação

SnapStack demo — capture a browser tab, your AI reads the screenshots over MCP

O servidor SnapStack é um único processo Node sempre ativo: ele recebe capturas do navegador da extensão, as empilha em disco e as serve para qualquer cliente LLM compatível com MCP via HTTP Streamable. Ele escuta apenas em 127.0.0.1 — nada jamais sai da sua máquina.

Novo aqui? O guia completo de instalação + uso está no README da extensão: snapstack-extension. Esta página é a referência técnica.

Arquitetura

Um único processo sempre ativo atende tanto a extensão (captura) quanto seu cliente MCP, desacoplados por uma pasta em disco.

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

Captura — a extensão codifica a imagem como WebP (fallback para PNG), reduz a escala e a envia via POST para cá.
Pilha — um arquivo de imagem (.webp/.png) mais um .json gêmeo (url, título, timestamp, dimensões) por captura, nomeado NN <timestamp>: um número estável de dois dígitos (atribuído na ordem de captura, reinicia em 01 quando a pilha esvazia) mais um timestamp, em ~/.snapstack/.
Recuperação — get_screenshots retorna um manifesto JSON (número, caminho absoluto, dimensões, metadados — sem bytes de imagem); o cliente lê apenas os arquivos de que precisa, pelo caminho. A exclusão é uma etapa separada e explícita de clear_screenshots. A recuperação nunca exclui.

Requisitos

Node.js ≥ 18 (testado no Node 20). Nenhum git necessário em tempo de execução.
Um cliente LLM compatível com MCP que fale o transporte HTTP (Streamable HTTP) ou stdio.
A snapstack-extension carregada no seu navegador.

Instalação e execução

No Windows, use um terminal de Administrador, caso contrário a instalação global do npm e o registro da tarefa agendada podem ser rejeitados.

O servidor é distribuído via npm e a instalação é simples no macOS, Linux e Windows:

Instale globalmente: npm i -g snapstack-server
Habilite o serviço em segundo plano: snapstack enable

O SnapStack inicia automaticamente no login, reinicia em caso de falha e se atualiza a cada inicialização.
Para verificar o status ou se há uma atualização disponível, basta executar snapstack no seu terminal.

Comandos disponíveis:

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)

O daemon se atualiza automaticamente a cada (re)inicialização/login; a CLI global (o comando snapstack) não. Execute snapstack update para atualizar ambos de uma só vez.

O passo a passo completo de ponta a ponta (caminhos de instalação idiomáticos, registro do cliente MCP, a extensão) está no README da extensão.

MCP

O SnapStack fala dois transportes MCP sobre a mesma pilha em disco — escolha o que seu cliente suportar:

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

O endpoint HTTP /mcp é stateless (um servidor + transporte novos por requisição); o front-end stdio (snapstack mcp) é iniciado sob demanda e lê a mesma pilha ~/.snapstack.
A entrada de captura (/push) permanece sempre no servidor em execução, independente de qualquer front-end MCP.

Ferramentas expostas

Ferramenta	Descrição
`get_screenshots`	Lista capturas pendentes como um manifesto JSON (número estável, caminho absoluto, dimensões, metadados) — sem bytes de imagem, sem exclusão. Passe `numbers` (ex.: `[1,3]`) para listar apenas essas.
`clear_screenshots`	Exclui capturas. Passe `numbers` para excluir específicas; omita para limpar toda a pilha. A numeração reinicia em `01` quando vazia.
`count_screenshots`	Número de capturas pendentes, sem recuperá-las.

get_screenshots e count_screenshots são somente leitura; apenas clear_screenshots é destrutiva.

Configuração

Variáveis de ambiente (infraestrutura)

Variável	Padrão	Finalidade
`SNAPSTACK_DIR`	`~/.snapstack`	Pasta da pilha.
`SNAPSTACK_PORT`	`4123`	Porta de escuta (sempre em `127.0.0.1`).

Política de captura (compartilhada entre seus navegadores)

As configurações de codificação/captura são de propriedade do servidor e armazenadas em ~/.snapstack/config.json, então uma única edição se aplica a todos os navegadores que executam a extensão. Elas são editadas pela página de opções da extensão — não uma variável de ambiente — e buscadas pela extensão antes de cada captura.

Chave	Padrão	Significado
`format`	`webp`	Formato de imagem: `webp`, `png` ou `jpg`.
`quality`	`0.85`	Qualidade com perda (`0`–`1`; a interface da extensão mostra como porcentagem).
`maxWidth`	`1568`	Reduz a escala de capturas mais largas que isso para esta largura em px (`0` = sem redimensionamento).
`maxSlices`	`50`	Captura de página inteira: limite máximo de fatias costuradas.

Dois endpoints dão suporte a isso: GET /config retorna a política efetiva; POST /config valida e a substitui (protegido por host + CORS como toda rota de captura). O arquivo não é uma imagem, então uma limpeza da pilha nunca o toca; excluí-lo apenas restaura os padrões acima.

Solução de problemas

Mensagem de servidor de captura não iniciado na extensão: execute snapstack start (ou snapstack run em primeiro plano), ou verifique o início automático com snapstack. Teste: curl http://127.0.0.1:4123/health.
Porta já em uso (EADDRINUSE): defina SNAPSTACK_PORT para outro valor.
snapstack: command not found após trocar a versão do Node (nvm, fnm, volta, Laravel Herd, nvm-windows): npm i -g coloca o comando snapstack apenas no binário global da versão do Node que estava ativa na instalação, então trocar de versão o esconde. É assim que os globais do npm funcionam, não é um bug do SnapStack — o serviço em segundo plano não é afetado e continua capturando; apenas o comando CLI desaparece. Correção: execute novamente npm i -g snapstack-server sob a versão atual do Node (ou volte para a usada na instalação).
O cliente não vê as ferramentas: o servidor deve estar em execução antes de o cliente MCP iniciar; verifique a configuração (type: "http", URL correta). Teste direto: curl http://127.0.0.1:4123/count.
Inspecione a pilha: ls ~/.snapstack (arquivos de imagem + .json legível por humanos).

Suporte

Uma pergunta ou ideia? → Discussões no GitHub
Encontrou um bug? → abra uma issue

Licença

MIT — veja LICENSE.