WebP Batch Converter

WebP Batch Converter

Um servidor Model Context Protocol (MCP) para conversão em lote de imagens para o formato WebP com suporte multiplataforma. Funciona perfeitamente com IDEs compatíveis com MCP, como o Cursor.

🌟 Recursos

• 🖼️ Conversão em lote de arquivos PNG, JPG e JPEG para WebP
• 🌍 Suporte multiplataforma (macOS, Linux, Windows)
• ⚡ Processamento multithread para conversões rápidas
• 🎛️ Opções flexíveis incluindo controle de qualidade, modo sem perdas e preservação de metadados
• 📊 Relatórios detalhados com tamanhos de arquivo e estatísticas de economia
• 🔧 Suporte a dois mecanismos - prefere o cwebp do Google, com fallback para Sharp
• 🎯 Integração MCP para uso em ambientes de desenvolvimento com IA

📦 Instalação

Instalação Global

npm install -g webp-batch-mcp

Desenvolvimento 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

Interface de Linha de Comando

node dist/cli.js [options]

Opções

• --src <dir> - Diretório de origem para verificação (padrão: diretório atual)
• --quality <0-100> - Configuração de qualidade WebP (padrão: 75)
• --lossless - Usar codificação sem perdas (recomendado para PNG)
• --overwrite - Substituir arquivos originais pelas versões WebP
• --threads <n> - Número de conversões simultâneas (padrão: número de CPUs)
• --preserve-meta - Preservar metadados EXIF e ICC
• --flat <dir> - Enviar todos os arquivos WebP para o diretório especificado

Exemplos

# 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

O servidor MCP expõe uma única ferramenta: convert_to_webp

Parâmetros da Ferramenta

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

⚙️ Como Adicionar Este Servidor no Cursor

1. Clone e compile o projeto:

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

2. Abra as Configurações do Cursor
3. Navegue até Recursos → MCP
4. Adicione uma nova configuração de servidor:

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

5. Reinicie o Cursor
6. A ferramenta convert_to_webp estará disponível em suas conversas com IA

🔧 Detalhes Técnicos

Estratégia de Conversão

1. Mecanismo Principal: Ferramenta cwebp do Google (incluída no libwebp-tools)

   • Desempenho mais rápido
   • Melhor compressão
   • Suporte completo a recursos

2. Mecanismo de Fallback: Sharp (Node.js)

   • Implementação pura em JavaScript
   • Sem dependências externas
   • Compatibilidade multiplataforma

Comportamento de Saída

• Padrão: Cria arquivos .webp junto aos originais
• Modo de substituição: Substitui os originais pelas versões WebP
• Modo plano: Envia todos os arquivos WebP para o diretório especificado
• Preservação de metadados: Mantém perfis EXIF e ICC quando solicitado

Desempenho

• Utiliza todos os núcleos da CPU por padrão
• Processa imagens simultaneamente usando p-limit
• Fornece feedback de progresso em tempo real
• Relata estatísticas detalhadas de conversão

🛠️ Desenvolvimento

Compilação

npm run build

Testes

npm test

Modo de Desenvolvimento

npm run dev

📊 Resultados de Testes

Verificado com imagens web reais:

• JPEG (35KB → 17KB): 51% de economia de espaço
• PNG (7,9KB → 2,8KB): 65% de economia de espaço
• Geral: 53% de compressão média

📋 Dependências

Tempo de Execução

• @modelcontextprotocol/sdk - Framework do servidor MCP
• sharp - Fallback de processamento de imagens
• chalk - Saída de terminal colorida
• commander - Análise de argumentos de CLI
• glob - Correspondência de padrões de arquivo
• p-limit - Controle de concorrência

Desenvolvimento

• typescript - Segurança de tipos
• tsup - Empacotador TypeScript rápido
• jest - Framework de testes

📄 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🤝 Contribuição

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Adicione testes para novas funcionalidades
4. Garanta que todos os testes passem
5. Envie um pull request

🆘 Suporte

Para problemas e solicitações de recursos, use o rastreador de problemas do GitHub.