VisionSqueezer

VisionSqueezer

Middleware de optimización de imágenes nativo para LLM y servidor MCP. Reduce el consumo de tokens de los modelos de visión al preprocesar imágenes en formatos alineados a los límites de teselas, sin relleno.

Funciona con cualquier agente o editor que hable MCP: Claude, GPT, Gemini, Codex, o el tuyo propio.

Instalación

Interactiva (recomendada)

Elige por ti el cliente, el método y el ámbito:

npx vision-squeezer install

Pregunta por:

• CLI objetivo: Claude Code / Codex CLI / Qwen Code / OpenCode / Gemini CLI / Kimi CLI
• Método de instalación (solo Claude Code): plugin (incluye MCP + habilidades de stats/doctor/upgrade) o mcp-add (solo servidor)
• Ámbito de instalación (solo mcp-add): user (todos los proyectos, recomendado), local (solo este proyecto), project (compartir vía .mcp.json)

Los scripts de instalación pasan las opciones directamente:

npx vision-squeezer install --client claude --method plugin --yes
npx vision-squeezer install --client claude --method mcp-add --scope user --yes

Claude Code — marketplace de plugins (una línea, incluye habilidades)

/plugin marketplace add eralpozcan/vision-squeezer
/plugin install vision-squeezer-mcp@vision-squeezer

Instala el servidor MCP y las habilidades /vision-stats, /vision-doctor, /vision-upgrade como un único plugin de Claude Code. Reinicia las sesiones abiertas de Claude Code para que el servidor MCP se conecte.

Claude Code — mcp add (solo servidor)

# All projects on this machine (recommended)
claude mcp add --scope user vision-squeezer -- npx -y vision-squeezer

# This project only (Claude Code's default)
claude mcp add vision-squeezer -- npx -y vision-squeezer

# Share with the team via .mcp.json in the repo
claude mcp add --scope project vision-squeezer -- npx -y vision-squeezer

Claude Desktop

Añade a ~/.config/claude/claude_desktop_config.json:

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

Cursor

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

O añade a .cursor/mcp.json:

{
  "servers": {
    "vision-squeezer": {
      "type": "stdio",
      "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"]
    }
  }
}

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

Instalación manual (binario 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/

Luego usa la ruta del binario directamente en cualquier configuración anterior en lugar de npx:

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

Consejo: Ejecuta npx -y vision-squeezer --setup para imprimir configuraciones listas con rutas auto-detectadas.

Uso desde CLI

vision-squeezer path/to/image.jpg \
  --mode auto|ocr|standard \      # default: auto (detects text/grayscale)
  --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 claude|gpt4o|gpt5|gemini|llama|qwen|deepseek \ # model-aware resizing
  --max-tiles 20 \                # hard cap on tile count
  --json \                        # machine-readable JSON output
  --dry-run                       # run pipeline, skip disk write

Modo por lotes

Pasa un directorio en lugar de un archivo:

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

Pipeline

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

🦀 ¿Por qué Rust?

VisionSqueezer es un middleware crítico en rendimiento. Elegimos Rust por tres razones innegociables:

• Latencia invisible: El procesamiento de imágenes nunca debería ser el cuello de botella. Rust garantiza que el ajuste, el recorte y la codificación ocurran en milisegundos, haciendo que la capa de optimización sea realmente invisible para el flujo de trabajo del desarrollador.
• Huella mínima: Como servidor MCP que se ejecuta en segundo plano en tu IDE, VisionSqueezer está diseñado para ser ultraligero, consumiendo casi cero CPU y RAM cuando está inactivo.
• Listo para Wasm: El soporte de primera clase de Rust para WebAssembly nos permite llevar la misma optimización de alto rendimiento al navegador y al Edge (Cloudflare Workers), permitiendo el exprimido del lado del cliente antes de que la imagen siquiera llegue a la red.

Caso de Estudio 1: Imagen Estándar (istanbul.jpg)

Para demostrar el impacto en imágenes estándar, aquí está la ejecución sobre una imagen de 2400×1670 (4 MP, 0.5 MB) en los tres escenarios:

Ejemplo 1: Optimización Agnóstica (Predeterminada)

Cuando no se especifica un modelo objetivo, Squeezer reduce el tamaño del archivo y optimiza matemáticamente los límites para que sean generalmente eficientes en todos los modelos.

vision-squeezer data/istanbul.jpg

Input:  2400×1670  (0.5 MB)
Output: 2048×1536  (0.3 MB, JPG q75)
File:   28.6% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude           5344     4194     1150 (21.5%)
GPT-4o           1105      765      340 (30.8%)
GPT-5            1536     1536        0 (0.0%)
Gemini           3096     1548     1548 (50.0%)
────────────────────────────────────────────────────────────

vision-squeezer data/istanbul.jpg --model gpt4o

Input:  2400×1670  (0.5 MB)
Output: 2399×1200  (0.3 MB, JPG q75)
File:   33.6% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude           5344     3838     1506 (28.2%)
GPT-4o           1105     1105        0 (0.0%)
GPT-5            1536     1536        0 (0.0%)
Gemini           3096     2064     1032 (33.3%)
────────────────────────────────────────────────────────────

vision-squeezer data/istanbul.jpg --model claude

Input:  2400×1670  (0.5 MB)
Output: 2304×1536  (0.4 MB, JPG q75)
File:   21.3% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude           5344     4718      626 (11.7%)
GPT-4o           1105     1105        0 (0.0%)
GPT-5            1536     1536        0 (0.0%)
Gemini           3096     1548     1548 (50.0%)
────────────────────────────────────────────────────────────

Caso de Estudio 2: Imagen de Alta Resolución de 12 Megapíxeles (istanbul2.jpg)

Para demostrar el impacto en imágenes masivas, aquí está la ejecución sobre una imagen de 4096×3072 (12 MP, 2.2 MB) en los tres escenarios:

Ejemplo 1: Optimización Agnóstica

vision-squeezer data/istanbul2.jpg

Input:  4096×3072  (2.2 MB)
Output: 3584×2560  (1.3 MB, JPG q75)
File:   39.6% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude          16777    12233     4544 (27.1%)
GPT-4o            765     1105        0 (0.0%)
GPT-5            1536     1536        0 (0.0%)
Gemini           6192     5160     1032 (16.7%)
────────────────────────────────────────────────────────────

(Observa la Anomalía de Relación de Aspecto de OpenAI: Squeezer eliminó el letterboxing pesado (relleno) de esta imagen. Al eliminar el relleno, la imagen se volvió "más ancha". Como la API de OpenAI fuerza el nuevo lado corto a 768px, la relación de aspecto ancha empujó el lado largo a una tercera columna de la cuadrícula de teselas. Este es un caso límite fascinante donde recortar relleno matemáticamente AUMENTA tu costo de tokens en GPT-4o. Si usas específicamente --model gpt4o en esta imagen, Squeezer detectará esta paradoja y usará una restricción de cuadrícula diferente).

vision-squeezer data/istanbul2.jpg --model gpt4o

Input:  4096×3072  (2.2 MB)
Output: 4095×2048  (1.2 MB, JPG q75)
File:   43.2% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude          16777    11182     5595 (33.3%)
GPT-4o            765     1105        0 (0.0%)
GPT-5            1536     1536        0 (0.0%)
Gemini           6192     4644     1548 (25.0%)
────────────────────────────────────────────────────────────

vision-squeezer data/istanbul2.jpg --model claude

Input:  4096×3072  (2.2 MB)
Output: 3840×2816  (1.5 MB, JPG q75)
File:   31.5% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude          16777    14417     2360 (14.1%)
GPT-4o            765     1105        0 (0.0%)
GPT-5            1536     1536        0 (0.0%)
Gemini           6192     5160     1032 (16.7%)
────────────────────────────────────────────────────────────

Benchmark / Ahorros

Consumo real de tokens antes y después de vision-squeezer (usando fotos y capturas de pantalla estándar sin --max-tiles). Los cálculos usan las fórmulas de facturación actualizadas de 2026.

(Nota: Los límites altos de GPT-5 hacen que rara vez requiera optimización por mosaicos a menos que la imagen supere los 6000px, pero vision-squeezer igualmente recortará el relleno y comprimirá drásticamente el tamaño del archivo).

Herramienta MCP: optimize_image

Respuesta:

{
  "optimized_base64": "...",
  "savings_report": {
    "tiles_before": 48,
    "tiles_after": 35,
    "tiles_saved": 13,
    "token_reduction_pct": "27.1",
    "size_reduction_pct": "58.9"
  }
}

Referencia de configuración

Modelos compatibles

Funciones avanzadas

Persistencia y analítica

VisionSqueezer registra cada optimización localmente en ~/.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
────────────────────────────────────────────────────────────

Hook de shell y habilidades de Claude Code

Añade a .zshrc / .bashrc:

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

Esto instala dos cosas a la vez:

• Alias squeeze — optimiza y captura la ruta de salida en un solo paso:

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

• Habilidades de Claude Code — escritas en ~/.claude/skills/ automáticamente en la primera ejecución

Habilidades disponibles

Ejemplo de salida:

/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

Instalación desde el marketplace (alternativa a setup-hook): Añade a ~/.claude/settings.json:

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

Luego ejecuta /plugins add vision-stats@vision-squeezer, /plugins add vision-doctor@vision-squeezer, o /plugins add vision-upgrade@vision-squeezer en Claude Code.

Modo sandbox: «Pensar en código»

Ejecuta operaciones atómicas localmente antes de que la imagen llegue a un LLM. El agente decide cómo procesar la imagen; tú pagas cero tokens por los pasos intermedios.

CLI:

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

Herramienta MCP — sandbox_execute:

Operaciones soportadas: crop, grayscale, binarize, resize, contrast, brightness.

Integración con crawler

Optimiza imágenes sobre la marcha en cualquier pipeline de scraping con Playwright/Puppeteer — cero desperdicio de tokens de API en capturas de pantalla sin procesar.

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 });
});

Contribuciones

Se aceptan PRs. Consulta CONTRIBUTING.md para la configuración y las pautas. Por favor sigue nuestro Código de conducta.

Licencia

Elastic License 2.0 (ELv2) — Consulta LICENSE para más detalles.