Snapstack

SnapStack 服务是一个持续运行的 Node 进程：它接收来自扩展程序的浏览器截图，将其存入磁盘，并通过 Streamable HTTP 提供给任何支持 MCP 的大模型客户端。它仅监听 127.0.0.1 — 任何内容都不会离开你的设备。

初次使用？ 完整的安装和使用指南请参阅扩展程序 README： snapstack-extension。本页面是技术参考。

架构

一个持续运行的进程同时为扩展程序（捕获）和 MCP 客户端提供服务，两者通过磁盘上的文件夹解耦。

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

• 捕获 — 扩展程序将截图编码为 WebP（PNG 作为回退格式），缩小尺寸后 POST 到此服务。
• 存储 — 每次捕获生成一个图像文件（.webp/.png）和一个对应的 .json 文件（包含 url、标题、时间戳、尺寸），命名为 NN <timestamp>：一个稳定的两位数编号（按捕获顺序分配；堆栈清空后从 01 重新开始），加上时间戳，存储在 ~/.snapstack/ 下。
• 检索 — get_screenshots 返回 JSON 清单（编号、绝对路径、尺寸、元数据 — 不含图像字节）；客户端按路径仅读取所需文件。删除是单独、明确的 clear_screenshots 步骤。检索不会删除内容。

要求

• Node.js ≥ 18（在 Node 20 上测试）。运行时不需要 git。
• 一个使用 HTTP（Streamable HTTP）或 stdio 传输方式的 MCP 兼容大模型客户端。
• 在浏览器中加载的 snapstack-extension。

安装和运行

在 Windows 上，请使用管理员终端，否则全局 npm 安装和计划任务注册可能会被拒绝。

该服务通过 npm 发布，在 macOS、Linux 和 Windows 上均可轻松安装：

1. 全局安装：npm i -g snapstack-server
2. 启用后台服务：snapstack enable

SnapStack 会在登录时自动启动，崩溃后自动重启，并在每次启动时自行更新。
若要查看其状态或是否有可用更新，只需在终端运行 snapstack。

可用命令：

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)

守护进程会在每次启动、重启或登录时自行更新；全局 CLI（snapstack 命令）则不会。 运行 snapstack update，即可一次性将两者更新到最新版本。

完整的端到端指南（推荐的安装方式、MCP 客户端注册、扩展程序）请参阅**扩展程序 README**。

MCP

SnapStack 在同一套磁盘存储上支持两种 MCP 传输方式——请选择客户端支持的方式：

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

HTTP /mcp 端点是无状态的（每个请求都会创建全新的服务和传输）；stdio 前端 （snapstack mcp）按需启动，并读取同一套 ~/.snapstack 存储。
无论使用哪种 MCP 前端，采集数据入口（/push）始终由运行中的服务处理。

已公开的工具

工具	描述
get_screenshots	将待处理的截图列为 JSON 清单（稳定编号、绝对路径、尺寸、元数据）——不包含图像字节，也不会删除截图。传入 numbers（例如 [1,3]）可仅列出指定截图。
clear_screenshots	删除截图。传入 numbers 可删除指定截图；省略则清空整个存储。存储清空后，编号会从 01 重新开始。
count_screenshots	统计待处理截图数量，不检索截图内容。

get_screenshots 和 count_screenshots 是只读工具；只有 clear_screenshots 会执行删除操作。

配置

环境变量（基础设施）

变量	默认值	用途
SNAPSTACK_DIR	~/.snapstack	存储文件夹。
SNAPSTACK_PORT	4123	监听端口（始终为 127.0.0.1）。

采集策略（浏览器间共享）

编码和采集设置由服务管理，并存储在 ~/.snapstack/config.json 中，因此只需 编辑一次，即可应用于所有运行该扩展的浏览器。设置可在扩展的选项页面中修改—— 而非通过环境变量修改；扩展会在每次采集前获取这些设置。

键	默认值	含义
format	webp	图像格式：webp、png 或 jpg。
quality	0.85	有损压缩质量（0–1；扩展 UI 会将其显示为百分比）。
maxWidth	1568	将宽于此值的截图缩小至该像素宽度（0 = 不调整大小）。
maxSlices	50	全页采集：拼接切片数的上限。

有两个端点用于处理该设置：GET /config 返回生效策略；POST /config 验证并替换策略（与所有采集路由一样，受主机和 CORS 限制）。该文件不是图像文件，因此清空存储时不会删除它；删除该文件即可恢复上述默认值。

故障排查

• **扩展中显示捕获服务未启动：**运行 snapstack start（或在前台运行 snapstack run）， 或使用 snapstack 检查自动启动状态。测试：curl http://127.0.0.1:4123/health。
• **端口已被占用（EADDRINUSE）：**将 SNAPSTACK_PORT 设置为其他值。
• 切换 Node 版本后出现 snapstack: command not found（nvm、fnm、volta、Laravel Herd、nvm-windows）：npm i -g 只会将 snapstack 命令安装到安装时所用 Node 版本的全局 bin 目录中，因此切换版本后该命令会消失。这是 npm 全局包的工作方式，并非 SnapStack 的 bug——后台服务不受影响，会继续捕获；只有 CLI 命令会消失。修复方法：在当前 Node 版本下重新运行 npm i -g snapstack-server（或切换回安装时使用的版本）。
• 客户端看不到工具：MCP 客户端启动之前必须先运行服务；请检查配置 （type: "http"，URL 是否正确）。直接测试：curl http://127.0.0.1:4123/count。
• 查看堆栈：ls ~/.snapstack（图像文件 + 易读的 .json 文件）。

支持

• 有问题或想法？ → GitHub 讨论区
• 发现 bug？ → 提交 issue

许可证

MIT — 请参阅 LICENSE。