Snapstack

SnapStack サーバーは、常時稼働する単一の Node プロセスです。拡張機能からブラウザーのキャプチャを受け取り、ディスクに保存して、Streamable HTTP 経由で MCP 対応の任意の LLM クライアントに提供します。127.0.0.1 のみで待ち受けるため、データがマシンの外に送信されることはありません。

初めてお使いですか？ インストールから使い方までを網羅したガイドは、拡張機能の README にあります： snapstack-extension。このページは技術リファレンスです。

アーキテクチャ

1 つの常時稼働プロセスが拡張機能（キャプチャ）と 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）1 つと対応する .json（URL、タイトル、タイムスタンプ、寸法）1 つを保存します。ファイル名は NN <timestamp> です。安定した 2 桁の番号（キャプチャ順に割り当てられ、スタックが空になると 01 から再開）とタイムスタンプで構成され、~/.snapstack/ に保存されます。
• 取得 — get_screenshots は JSON マニフェスト（番号、絶対パス、寸法、メタデータ。画像データは含みません）を返し、クライアントはパスを指定して必要なファイルだけを読み取ります。削除は別途、明示的な clear_screenshots の手順で行います。取得によって削除されることはありません。

要件

• Node.js ≥ 18（Node 20 でテスト済み）。実行時に git は不要です。
• HTTP（Streamable HTTP）または stdio トランスポートを使用する MCP 対応 LLM クライアント。
• ブラウザーに読み込んだ 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 は同じディスク上のスタックで 2 種類の 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 スタックを読み取ります。
キャプチャの受け付け（/push）は、どちらの MCP フロントエンドとも独立して、常に稼働中のサーバーで処理されます。

公開されるツール

ツール	説明
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 に保存されます。そのため、1 回の編集で拡張機能を実行するすべてのブラウザーに適用されます。設定は拡張機能のオプションページから編集します。環境変数ではありません。拡張機能はキャプチャのたびに設定を取得します。

キー	デフォルト	意味
format	webp	画像形式：webp、png、jpg のいずれかです。
quality	0.85	非可逆圧縮の品質です（0～1。拡張機能の UI ではパーセンテージで表示されます）。
maxWidth	1568	この幅より広いキャプチャを、幅をこの値（px）にして縮小します（0 = サイズ変更なし）。
maxSlices	50	全ページキャプチャで結合するスライス数の上限です。

この設定は 2 つのエンドポイントを通じて利用します。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 は、インストール時にアクティブだった Node バージョンのグローバル bin にのみ snapstack コマンドを配置するため、バージョンを切り替えるとコマンドが見えなくなります。これは npm のグローバルパッケージの動作であり、SnapStack の不具合ではありません。バックグラウンドサービスには影響せず、キャプチャは継続されます。消えるのは CLI コマンドだけです。解決方法：現在の Node バージョンで npm i -g snapstack-server を再実行するか、インストール時に使用したバージョンに戻してください。
• クライアントにツールが表示されない場合： MCP クライアントの起動前にサーバーを実行しておく必要があります。設定（type: "http"、正しい URL）を確認してください。直接テストするには、curl http://127.0.0.1:4123/count を実行してください。
• スタックを確認する： ls ~/.snapstack（画像ファイルと、人が読める形式の .json）。

サポート

• 質問やアイデアがありますか？ → GitHub Discussions
• バグを見つけましたか？ → issue を作成する

ライセンス

MIT — LICENSE を参照してください。