WebP Batch Converter

WebP Batch Converter

Un servidor de Model Context Protocol (MCP) para convertir imágenes por lotes al formato WebP con soporte multiplataforma. Funciona perfectamente con IDEs compatibles con MCP como Cursor.

🌟 Características

• 🖼️ Conversión por lotes de archivos PNG, JPG y JPEG a WebP
• 🌍 Soporte multiplataforma (macOS, Linux, Windows)
• ⚡ Procesamiento multihilo para conversiones rápidas
• 🎛️ Opciones flexibles que incluyen control de calidad, modo sin pérdida y preservación de metadatos
• 📊 Informes detallados con tamaños de archivo y estadísticas de ahorro
• 🔧 Soporte de doble motor: prefiere cwebp de Google, con respaldo en Sharp
• 🎯 Integración MCP para uso en entornos de desarrollo impulsados por IA

📦 Instalación

Instalación Global

npm install -g webp-batch-mcp

Desarrollo Local

git clone https://github.com/mhe8mah/webp-batch-mcp.git
cd webp-batch-mcp
npm install
npm run build

Docker

docker build -t webp-batch .
docker run -v /path/to/images:/data webp-batch

🚀 Uso

Interfaz de Línea de Comandos

node dist/cli.js [options]

Opciones

• --src <dir> - Directorio de origen para escanear (predeterminado: directorio actual)
• --quality <0-100> - Configuración de calidad WebP (predeterminado: 75)
• --lossless - Usar codificación sin pérdida (recomendado para PNG)
• --overwrite - Reemplazar archivos originales con versiones WebP
• --threads <n> - Número de conversiones concurrentes (predeterminado: número de CPU)
• --preserve-meta - Preservar metadatos EXIF e ICC
• --flat <dir> - Enviar todos los archivos WebP al directorio especificado

Ejemplos

# Convert all images in current directory
node dist/cli.js

# High quality conversion of specific directory
node dist/cli.js --src ./photos --quality 95 --preserve-meta

# Lossless conversion with overwrite
node dist/cli.js --src ./images --lossless --overwrite

# Batch process to output directory
node dist/cli.js --src ./input --flat ./output --threads 8

Servidor MCP

El servidor MCP expone una única herramienta: convert_to_webp

Parámetros de la Herramienta

{
  "src": "string",          // Source directory (default: ".")
  "quality": "number",      // Quality 0-100 (default: 75)
  "lossless": "boolean",    // Lossless mode (default: false)
  "overwrite": "boolean",   // Replace originals (default: false)
  "threads": "number",      // Concurrent threads (default: CPU count)
  "preserveMeta": "boolean", // Keep metadata (default: false)
  "flat": "string"          // Output directory (optional)
}

⚙️ Cómo Agregar Este Servidor en Cursor

1. Clona y compila el proyecto:

git clone https://github.com/mhe8mah/webp-batch-mcp.git
cd webp-batch-mcp
npm install
npm run build

2. Abre la Configuración de Cursor
3. Navega a Features → MCP
4. Agrega una nueva configuración de servidor:

{
  "mcpServers": {
    "webp-batch": {
      "command": "node",
      "args": ["/path/to/webp-batch-mcp/dist/server.js"]
    }
  }
}

5. Reinicia Cursor
6. La herramienta convert_to_webp estará disponible en tus conversaciones de IA

🔧 Detalles Técnicos

Estrategia de Conversión

1. Motor Principal: La herramienta cwebp de Google (incluida en libwebp-tools)

   • Rendimiento más rápido
   • Mejor compresión
   • Soporte completo de funciones

2. Motor de Respaldo: Sharp (Node.js)

   • Implementación pura en JavaScript
   • Sin dependencias externas
   • Compatibilidad multiplataforma

Comportamiento de Salida

• Predeterminado: Crea archivos .webp junto a los originales
• Modo sobrescritura: Reemplaza los originales con versiones WebP
• Modo plano: Envía todos los archivos WebP al directorio especificado
• Preservación de metadatos: Mantiene perfiles EXIF e ICC cuando se solicita

Rendimiento

• Utiliza todos los núcleos de CPU por defecto
• Procesa imágenes de forma concurrente usando p-limit
• Proporciona retroalimentación de progreso en tiempo real
• Reporta estadísticas detalladas de conversión

🛠️ Desarrollo

Compilación

npm run build

Pruebas

npm test

Modo de Desarrollo

npm run dev

📊 Resultados de Pruebas

Verificado con imágenes web reales:

• JPEG (35KB → 17KB): 51% de ahorro de espacio
• PNG (7.9KB → 2.8KB): 65% de ahorro de espacio
• General: 53% de compresión promedio

📋 Dependencias

Tiempo de Ejecución

• @modelcontextprotocol/sdk - Marco de trabajo del servidor MCP
• sharp - Respaldo de procesamiento de imágenes
• chalk - Salida de terminal con colores
• commander - Análisis de argumentos CLI
• glob - Coincidencia de patrones de archivos
• p-limit - Control de concurrencia

Desarrollo

• typescript - Seguridad de tipos
• tsup - Empaquetador rápido de TypeScript
• jest - Marco de trabajo de pruebas

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

🤝 Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad
3. Agrega pruebas para la nueva funcionalidad
4. Asegúrate de que todas las pruebas pasen
5. Envía una solicitud de extracción

🆘 Soporte

Para problemas y solicitudes de funciones, utiliza el rastreador de problemas de GitHub.