vision-squeezer

VisionSqueezer

画像がモデルに届く前に、ビジョン LLM のトークン予算に収まるようにします。コード、エージェント、パイプライン向けのライブラリ、CLI、MCP サーバーです。

できないこと。 VisionSqueezer は、チャットウィンドウ（Claude Code、Cursor、ChatGPT など）に貼り付けたり、ドラッグしたり、@ で添付したりした画像を縮小できません。クライアントはツールやフックが実行される前に画像を添付するため、全サイズ分の料金が発生します。

トークンを節約できる場合：

• コードからモデル API に送信する画像：Rust クレート、Python バインディング、CLI。
• エージェントがファイルから読み込む画像や、ツール経由で取得する画像（スクリーンショット、クローラー、ブラウザー自動化）：MCP サーバー、またはプロジェクト内のファイル向け Claude Code の画像読み取りフック。

対象となる具体的なケースについては、トークンを節約できる場合をご覧ください。

MCP サーバーは任意の MCP クライアント（Claude Code、Cursor、Codex、Gemini CLI など）で動作しますが、エージェントが渡した画像だけを認識します。

インストール

クライアントごとに1つのコマンド（推奨）

npx vision-squeezer install                       # asks for the client and scope
npx vision-squeezer install --client claude --scope user --yes
npx vision-squeezer install --client cursor --yes

各クライアントにはインストール方法が1つだけあり、インストーラーが選択します。

JSON ファイルは置き換えずにマージします。他のサーバーやフックは保持され、解析できないファイルには手を加えず、再実行時には独自のエントリを置き換えるため、重複して追加されることはありません。

スコープ（user、local、project）は、クライアントが複数のスコープに対応している場合にのみ尋ねられます。旧バージョンの --method は受け付けますが、無視されます。

以下の手動コマンドでは、簡潔にするため npx -y vision-squeezer を使用しています。vision-squeezer@<version> のようにバージョンを固定してください（インストーラーでは固定されます）。バージョンを指定しない npx は、新しいリリースが出た後も最初にキャッシュしたバージョンを使い続けます。

Claude Code

npx vision-squeezer install --client claude --scope user --yes

これは以下の2つのコマンドを実行します（最初に、以前の claude mcp add 登録と settings.json のフックを削除します）。手動で行う場合：

claude plugin marketplace add eralpozcan/vision-squeezer
claude plugin install vision-squeezer-mcp@vision-squeezer --scope user

MCP サーバー、スキル、フックを読み込むには、Claude Code を再起動するか、/reload-plugins を実行してください。スキルとフックなしで MCP サーバーだけを使いたい場合は、claude mcp add --scope user vision-squeezer -- npx -y vision-squeezer を実行してください。

Claude Desktop

npx vision-squeezer install --client claude-desktop --yes

または、claude_desktop_config.json に追加してください（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\\Claude\\）：

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

Cursor

npx vision-squeezer install --client cursor --yes

または、~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）に追加します：

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

code --add-mcp '{"name":"vision-squeezer","command":"npx","args":["-y","vision-squeezer"]}'

{
  "servers": {
    "vision-squeezer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

{
  "servers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

npx vision-squeezer install --client windsurf --yes

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

gemini mcp add --scope user vision-squeezer -- npx -y vision-squeezer

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

codex mcp add vision-squeezer -- npx -y vision-squeezer

[mcp_servers.vision-squeezer]
command = "npx"
args = ["-y", "vision-squeezer"]

qwen mcp add vision-squeezer -- npx -y vision-squeezer

{
  "mcp": {
    "vision-squeezer": {
      "type": "local",
      "command": ["npx", "-y", "vision-squeezer"],
      "enabled": true
    }
  }
}

kimi mcp add vision-squeezer -- npx -y vision-squeezer

{
  "context_servers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

手動インストール（Rust バイナリ）

# From crates.io
cargo install vision-squeezer

# Or from source
git clone https://github.com/eralpozcan/vision-squeezer && cd vision-squeezer
make install   # builds → ~/.local/bin/

その後、上記の設定で npx の代わりにバイナリのパスを直接使用します：

{ "command": "vision-squeezer-mcp" }

ヒント： npx -y vision-squeezer --setup を実行すると、自動検出されたパスを含む設定例が表示されます。

CLI の使用方法

vision-squeezer path/to/image.jpg \
  --mode auto|ocr|standard \      # default: auto (= standard, keeps colour; ocr is opt-in)
  --format jpeg|webp|avif \       # default: jpeg
  --quality 85 \                  # output quality 1-100 (default: 75)
  --tile-size 256 \               # patch size in px (default: 512)
  --no-crop \                     # disable padding removal
  --smart-crop \                  # edge-energy crop (vs corner-tolerance)
  --auto-quality 0.95 \           # binary-search quality to hit SSIM target
  --bg-tolerance 25 \             # background detection 0-255 (default: 15)
  --model <provider-alias> \ # model-aware resizing; see the model catalog
  --max-tokens 1600 \            # token budget: downscale until the output fits (0 = off; MCP default 1600)
  --max-tiles 20 \                # hard cap on tile count (model-specific unit)
  --json \                        # machine-readable JSON output
  --dry-run                       # run pipeline, skip disk write

バッチモード

ファイルの代わりにディレクトリを渡します：

vision-squeezer ./screenshots --recursive --output-dir ./optimized
vision-squeezer ./screenshots --recursive --json > report.json

HTTP API（n8n、Make、Zapier）

vision-squeezer serve は小規模な HTTP サーバーを起動するため、任意のワークフローツールから、通常の HTTP リクエストで2つのステップの間に画像を圧縮できます。カスタムノードは不要です。

vision-squeezer serve                    # 127.0.0.1:8080
docker build -t vision-squeezer .        # or run it in a container
docker run -p 8080:8080 vision-squeezer

画像のバイトデータを POST /optimize の本文として送信します。オプションはクエリ文字列に指定します：

curl --data-binary @screenshot.png "http://localhost:8080/optimize?max_tokens=1600" -o out.jpg -D -
# X-Tokens-Before: 4674
# X-Tokens-After: 1584
# X-Input-Size: 2400x1670
# X-Output-Size: 1344x924

GET /health は ok を返します。本文が 25 MB を超えると 413 を返し、入力が不正な場合は理由を1行で示して 400 を返します。認証機能はありません。サーバーはデフォルトで 127.0.0.1 をリッスンし、Docker イメージはコンテナー内のすべてのインターフェースをリッスンするため、信頼できるネットワーク上でのみポートを公開してください。

n8n。 画像を取得するステップとビジョンモデルの間に HTTP Request ノードを配置します：

• Method を POST、URL を http://vision-squeezer:8080/optimize?max_tokens=1600 に設定します（同じ Docker ネットワーク上で両方を実行する場合はコンテナー名、それ以外の場合は localhost を使用します）。
• Send Body をオンにし、Body Content Type を n8n Binary File、Input Data Field Name を data に設定します。
• Options → Response → Response Format を File に設定すると、次のノードに最適化された画像がバイナリとして渡されます。Include Response Headers and Status をオンにすると、X-Tokens-* の値を読み取れます。

これらの設定は n8n のドキュメントに準拠していますが、n8n 自体ではまだテストされていません。

パイプライン

Input image
  → crop_padding               remove solid-color borders
  → calculate_optimal_dims     snap to tile boundary (always down)
  → [enforce_max_tokens]       token budget (MCP default 1600) / optional tile cap
  → resize_exact               Lanczos3
  → [binarize]                 OCR mode only: Otsu threshold
  → JPEG/WebP encode           configurable quality & format

🦀 Rustを選んだ理由

VisionSqueezerは、パフォーマンスが重要なミドルウェアです。妥協できない次の3つの理由から、Rustを選びました。

• 遅延を感じさせない： 画像処理がボトルネックになってはなりません。Rustなら、サイズ調整、クロップ、エンコードを数ミリ秒で実行でき、最適化レイヤーを開発者のワークフローから完全に見えないものにできます。
• 最小限のフットプリント： IDEのバックグラウンドで動作するMCP サーバーとして、VisionSqueezerは極めて軽量に設計されており、アイドル時のCPUとRAMの使用量はほぼゼロです。
• Wasm対応： RustはWebAssemblyを第一級でサポートしているため、同じ高性能な最適化をブラウザーやエッジ（Cloudflare Workers）にも適用できます。これにより、画像がネットワークに送信される前にクライアント側で圧縮できます。

ベンチマークのスナップショット

vision-squeezer <image> [flags] --dry-run --json を使い、data/ 内のサンプル画像で取得しました。目標はメガバイト数ではなく、トークン数を減らすことです。プロバイダーの課金はピクセル寸法に基づくため、ファイルサイズが影響するのはアップロードとレイテンシーだけです。予算を指定しない場合、パイプラインはグリッドに合わせてパディングを切り抜きますが、プロバイダーが大きすぎる画像をすでに自動縮小するため、大きな写真ではほとんど節約になりません。トークン予算（--max-tokens、MCP サーバーでのデフォルトは 1600）を指定することで、実際に節約できます。

ケーススタディ 1：標準画像（istanbul.jpg）

2400×1670、0.5 MB。

vision-squeezer data/istanbul.jpg --max-tokens 1600

Input:  2400×1670  (0.5 MB)
Output: 1344×924  (0.2 MB, JPG q75)
File:   67.5% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude 4.7+      4674     1584     3090 (66.1%)
GPT-6            2903     1462     1441 (49.6%)
GPT-4o           1105     1105        0 (0.0%)
GPT-5             910      910        0 (0.0%)
Gemini           3096     1032     2064 (66.7%)
────────────────────────────────────────────────────────────

ケーススタディ 2：1200 万画素の画像（istanbul2.jpg）

4096×3072、2.2 MB。

vision-squeezer data/istanbul2.jpg --max-tokens 1600

Input:  4096×3072  (2.2 MB)
Output: 1288×952  (0.3 MB, JPG q75)
File:   87.9% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude 4.7+      4661     1564     3097 (66.4%)
GPT-6            2942     1476     1466 (49.8%)
GPT-4o            765     1105        0 (0.0%)
GPT-5             630      910        0 (0.0%)
Gemini           6192     1032     5160 (83.3%)
────────────────────────────────────────────────────────────

数値の見方

• 予算が無効だと、トークン数はほとんど変わりません。 Claude 4.7+ は画像をすでに 4,784 トークンに制限しているため、元画像が 4,661 トークンでも、処理後に 4,698 トークンになることがあります。圧縮後のファイルは小さくなりますが、請求額は変わりません。
• --max-tokens 1600 は、構図、色、大きな文字を保ちながら、両方の写真で Claude のトークン数を約 66%、GPT-6 のトークン数を約 50%削減します。 最初に失われるのは細部（遠くの窓や小さな看板）です。
• 予算は対象モデルに基づいて計算されます。 モデルを指定しない場合は Claude が対象です。同じ 1600 を指定しても、--model gemini では Gemini の 768px タイルグリッドに合わせて処理され（1,032 トークン）、ファイルサイズの列もその結果に従います。
• コンテンツに応じて予算を選んでください。 1600 と 1000 では、Retina 解像度のコードのスクリーンショットに含まれる本文を読み取れる状態で保てましたが、600 では保てませんでした。上限を無効にするには、--max-tokens 0 を渡すか、CLI で省略してください。
• 色が失われることはありません。 auto モードは standard と同様に動作します。白黒出力になるのは、--mode ocr を明示的に指定した場合だけです。

現行モデルの妥当性チェック

MCP ツール：optimize_image

応答： 最適化された画像を含むMCPのimageブロックと、それに続く簡単なレポートのテキストブロックです。テキスト内で画像がbase64になることはありません。モデルはこれをテキストトークンとして読み取るため、置き換え対象の画像よりもコストが高くなります。

{
  "width": 1344,
  "height": 924,
  "output_path": "/tmp/vision-squeezer/shot-1a2b3c4d.jpg",
  "tokens_before": 4674,
  "tokens_after": 1584,
  "savings_report": {
    "tiles_before": 4674,
    "tiles_after": 1584,
    "tiles_saved": 3090,
    "token_reduction_pct": "66.1",
    "size_reduction_pct": "67.5"
  }
}

入力がimage_pathの場合、output_pathが設定されます。

トークンを節約できる場面

最適化の効果があるのは、小さくなった画像がモデルに届く場合だけです。実際には、次のようになります。

基準値が重要です。 Claude Code は送信前に大きな画像をすでに縮小します。今回のテストでは、2400×1670 のファイルは 1999×1392 としてモデルに届きました。このため、istanbul.jpg では、元のファイルと比較して測定した 66% ではなく、1600 トークンの予算によって約 56% 節約できます。

この README のトークン数は、各プロバイダーが公開しているルールに基づく推定値です。Claude については、Anthropic の count_tokens エンドポイント（claude-sonnet-5-5、画像トークンのみ）で確認しました。

実際の節約量は、Claude Code が送信する画像を基準にすると 3,603 → 1,587（−56%）、元画像を基準にすると 4,759 → 1,587（−67%）です。GPT と Gemini の推定値は、それぞれの API で確認していません。

「MCP ツールのみ」とは、エージェントが image_path を指定して optimize_image を呼び出す必要があるという意味です。AGENTS.md でエージェントにそうするよう伝えてください。Cursor、Gemini CLI、OpenCode 用のフックは、これらのクライアントが読み込みをワークスペース内に制限しているため、プロジェクト内の自己無視設定された .vision-squeezer/ フォルダーにコピーを保持します。

節約効果を得るには、スクリーンショットをプロジェクト内（たとえば screenshots/）に保存し、パスで参照してください。フックが書き換えるのはプロジェクト内のファイルだけです。フックは許可する判定を返すため、通常の Read なら確認を求められるファイルを開いてはいけません。

設定リファレンス

対応モデル

プラットフォームのサポート

ビルド済みの MCP バイナリは、Linux x86_64／ARM64、macOS Apple Silicon／Intel、Windows x86_64／ARM64 に対応しています。Python ホイールは、Linux x86_64／ARM64、macOS Apple Silicon／Intel、Windows x86_64 に対応しています。サポート対象外の Python アーキテクチャでは、pip install --no-binary vision-squeezer vision-squeezer を実行してソースからインストールできます。

高度な機能

永続化と分析

VisionSqueezer は、すべての最適化をローカルの ~/.vision-squeezer/stats.db に記録します。

vision-squeezer stats

── VisionSqueezer Analytics ────────────────────────────────
Total Optimizations: 42
Total Tokens Saved:  842,500
Total Bytes Saved:   156.40 MB
Estimated USD Saved: $2.11
────────────────────────────────────────────────────────────

シェルフックと Claude Code スキル

.zshrc ／ .bashrc に追加します。

eval "$(vision-squeezer setup-hook)"

これにより、次の 2 つが同時にインストールされます。

• squeeze エイリアス — 最適化と出力パスの取得を 1 ステップで実行します。

  img_path=$(squeeze data/logo.png --model gemini)
  

• Claude Code スキル — 初回実行時に ~/.claude/skills/ に自動で書き込まれます

利用可能なスキル

出力例：

/vision-stats
── VisionSqueezer Analytics ────────────────────────────────
Total Optimizations: 42
Total Tokens Saved:  842,500
Total Bytes Saved:   156.40 MB
Estimated USD Saved: $2.11
────────────────────────────────────────────────────────────

/vision-doctor
## VisionSqueezer Doctor
- [x] Binary found: /usr/local/bin/vision-squeezer
- [x] Installed version: 0.1.8
- [x] Latest version (npm): 0.1.8
- [x] Status: Up to date

マーケットプレイスからのインストール（setup-hook の代替）： ~/.claude/settings.json に追加します。

{
  "extraKnownMarketplaces": {
    "vision-squeezer": {
      "source": { "source": "github", "repo": "eralpozcan/vision-squeezer" }
    }
  }
}

次に、Claude Code で /plugins add vision-stats@vision-squeezer、/plugins add vision-doctor@vision-squeezer、または /plugins add vision-upgrade@vision-squeezer を実行します。

サンドボックスモード：「コードで考える」

画像が LLM に届く前に、アトミックな操作をローカルで実行します。画像の処理方法はエージェントが判断し、中間ステップでトークンを消費することはありません。

CLI：

vision-squeezer screenshot.png --ops '[{"op":"crop","x":10,"y":20,"width":500,"height":500},{"op":"binarize"}]'

MCP ツール — sandbox_execute：

対応する操作：crop、grayscale、binarize、resize、contrast、brightness。

クローラーとの統合

Playwright／Puppeteer を使ったスクレイピングパイプラインで、画像をその場で最適化できます。生のスクリーンショットによる API トークンの無駄はありません。

await page.route('**/*.{png,jpg}', async (route) => {
  const response = await route.fetch();
  const body = await response.body();
  const optimized = await squeeze(body); // pipe through vision-squeezer
  route.fulfill({ body: optimized });
});

コントリビューション

PR を歓迎します。セットアップとガイドラインについては、CONTRIBUTING.md を参照してください。 行動規範 に従ってください。

ライセンス

Elastic License 2.0 (ELv2) — 詳細は LICENSE を参照してください。