@justmpm/image-tools

MCP Server para conversao e analise de imagens usando sharp. Processamento nativo em Node.js -- sem Python, sem dependencias externas.

Descricao

Este servidor MCP (Model Context Protocol) permite converter imagens entre formatos (WebP, JPEG, PNG, AVIF) com controle fino de qualidade e resize, alem de analisar metadados de imagens sem converte-las. Substitui o script Python convert_to_webp.py com muito mais funcionalidades.

Por que usar?

• Conversao multi-formato -- PNG, JPEG, WebP, AVIF, BMP, TIFF, GIF de entrada
• Controle fino de qualidade -- Ajuste de 1 a 100 baseado no contexto
• Resize integrado -- maxWidth/maxHeight com proporcao automatica
• Analise sem conversao -- Inspecione metadados antes de decidir
• Batch resiliente -- Erros individuais nao interrompem o processamento
• Zero dependencia de Python -- Tudo nativo em Node.js com sharp
• Sem variaveis de ambiente -- Funciona direto, sem API keys

Instalacao

npx (sem instalar, recomendado)

No seu config MCP (Claude Desktop, OpenCode, Cursor, etc.):

{
  "mcpServers": {
    "image-tools": {
      "command": "npx",
      "args": ["-y", "@justmpm/image-tools"]
    }
  }
}

Instalacao global

npm install -g @justmpm/image-tools

{
  "mcpServers": {
    "image-tools": {
      "command": "image-tools"
    }
  }
}

Desenvolvimento local

git clone https://github.com/justmpm/image-tools-mcp.git
cd image-tools-mcp
npm install && npm run build

{
  "mcpServers": {
    "image-tools": {
      "command": "node",
      "args": ["D:/caminho/para/image-tools/dist/index.js"]
    }
  }
}

Configuracao MCP

O image-tools usa transporte stdio (JSON-RPC). Adicione a configuracao acima no arquivo do seu cliente:

| Cliente | Arquivo de configuracao | |---------|------------------------| | Claude Desktop | ~/.claude/claude_desktop_config.json | | OpenCode | .opencode/config.json | | Cursor | .cursor/mcp.json |

Requisitos

• Node.js >= 18

Tools Disponiveis

convert_images -- Converte imagens entre formatos

Converte imagens com controle de qualidade, resize e opcao de apagar original.

Parametros:

| Parametro | Tipo | Obrigatorio | Default | Descricao | |-----------|------|-------------|---------|-----------| | paths | string[] | Sim | -- | Caminhos absolutos de imagens ou pastas (1 nivel, sem recursao) | | format | "webp" \| "jpeg" \| "png" \| "avif" | Nao | "webp" | Formato de saida | | quality | number (1-100) | Nao | 85 | Qualidade da compressao | | maxWidth | number | Nao | -- | Largura maxima em pixels (redimensiona proporcionalmente) | | maxHeight | number | Nao | -- | Altura maxima em pixels (redimensiona proporcionalmente) | | deleteOriginal | boolean | Nao | false | Apagar original apos conversao |

Formatos de entrada suportados: PNG, JPEG, WebP, AVIF, BMP, TIFF, GIF

Exemplo:

{
  "paths": ["D:/Images/photos", "D:/Images/logo.png"],
  "format": "webp",
  "quality": 80,
  "maxWidth": 1920
}

Retorno:

Conversao concluida! 3 imagens processadas.

| Arquivo | Original | Convertido | Reducao |
|---------|----------|------------|---------|
| hero.png -> hero.webp | 245.67 KB | 89.32 KB | 63.6% |
| logo.png -> logo.webp | 120.45 KB | 45.21 KB | 62.5% |
| banner.png -> banner.webp | 890.12 KB | 340.56 KB | 61.7% |

Total economizado: 780.15 KB (62.9% medio)

analyze_images -- Analisa metadados de imagens

Lista formato, dimensoes, tamanho em disco, canal alpha e espaco de cor sem converter.

Parametros:

| Parametro | Tipo | Obrigatorio | Descricao | |-----------|------|-------------|-----------| | path | string | Sim | Caminho absoluto da pasta ou arquivo |

Exemplo:

{
  "path": "D:/Images"
}

Retorno:

12 imagem(ns) encontrada(s) em D:\Images

| Arquivo | Formato | Dimensoes | Tamanho | Alpha |
|---------|---------|-----------|---------|-------|
| hero.png | PNG | 1920x1080 | 1.24 MB | Sim |
| logo.jpg | JPEG | 512x512 | 45.2 KB | Nao |
| icon.webp | WebP | 64x64 | 2.1 KB | Sim |

Resumo: 12 imagens | 4.8 MB total | PNG: 5, JPEG: 4, WebP: 3
Maior: hero.png (1.24 MB) | Menor: icon.webp (2.1 KB)

Formatos Suportados

| Formato | Entrada | Saida | Nota | |---------|---------|-------|------| | PNG | Sim | Sim | Suporta canal alpha | | JPEG | Sim | Sim | Sem canal alpha | | WebP | Sim | Sim | Melhor compressao para web | | AVIF | Sim | Sim | Melhor compressao, processamento lento | | BMP | Sim | Nao | Apenas entrada | | TIFF | Sim | Nao | Apenas entrada | | GIF | Sim | Nao | Nao animado (frame unico) |

Exemplos de Uso

Converter pasta para WebP

{
  "paths": ["public/images"],
  "format": "webp"
}

Otimizar para web (max 1920px, qualidade 80)

{
  "paths": ["public/assets"],
  "format": "webp",
  "quality": 80,
  "maxWidth": 1920
}

Analisar antes de converter

{ "path": "D:/Images" }

Depois de ver quais imagens valem a pena:

{
  "paths": ["D:/Images"],
  "format": "webp",
  "quality": 85
}

Converter e apagar originais

{
  "paths": ["D:/legacy-photos"],
  "format": "webp",
  "quality": 85,
  "deleteOriginal": true
}

Redimensionar mantendo proporcao

{
  "paths": ["D:/Screenshots"],
  "format": "webp",
  "maxWidth": 800,
  "maxHeight": 600
}

Resumo de Qualidade

| Formato | Range | Recomendado | Nota | |---------|-------|-------------|------| | WebP | 1-100 | 80-85 | Melhor relacao qualidade/tamanho | | JPEG | 1-100 | 80-85 | Compressao lossy | | PNG | compressao 0-9 | Auto (baseado em quality) | Lossless | | AVIF | 1-100 | 60-70 | Melhor compressao, processamento lento |

Estrutura do Projeto

image-tools/
  src/
    index.ts          # Servidor MCP principal (Server + StdioServerTransport)
    types.ts          # Interfaces e constantes (ConversionResult, ImageAnalysis, ToolResponse)
    tools/
      index.ts        # Barrel export das tools
      convert.ts      # Tool: convert_images
      analyze.ts      # Tool: analyze_images
    __tests__/
      convert.test.ts # 44 testes
      analyze.test.ts # 31 testes
  dist/               # Build compilado
  package.json
  tsconfig.json
  vitest.config.ts
  README.md           # Este arquivo
  CLAUDE.md           # Documentacao para IAs
  AGENTS.md           # Guia para subagents

Desenvolvimento

# Clonar repositorio
git clone https://github.com/justmpm/image-tools-mcp

# Instalar dependencias
npm install

# Build
npm run build

# Desenvolvimento com watch
npm run dev

# Executar
npm start

# Rodar testes
npm test

Documentacao Adicional

CLAUDE.md

Documentacao tecnica para IAs sobre como o MCP funciona internamente. Inclui arquitetura, padroes de codigo e como extender com novas tools.

Para IAs: Leia CLAUDE.md para entender a arquitetura e implementacao.

AGENTS.md

Guia completo para subagents. Inclui referencia detalhada das tools, exemplos de uso, workflows recomendados, dicas de qualidade e troubleshooting.

Para Subagents: Consulte AGENTS.md para orientacoes rapidas e completas.

Limitacoes Conhecidas

• GIF animados: Sharp trata como frame unico (apenas o primeiro frame)
• Recursao: Pastas sao escaneadas em apenas 1 nivel (sem subpastas)
• AVIF: Processamento mais lento que WebP/JPEG
• Windows: Ao deletar arquivos (deleteOriginal), pode haver lock temporario do sharp

Troubleshooting

"Nenhuma imagem suportada encontrada"

Verifique se o caminho esta correto e se os arquivos possuem extensoes suportadas (.png, .jpg, .jpeg, .webp, .avif, .bmp, .tiff, .gif).

"Caminho nao encontrado"

Use caminhos absolutos. Ex: D:/Images/photos em vez de ./photos.

Reducao negativa (arquivo ficou maior)

Pode acontecer com qualidade muito alta ou formato saida pior que entrada. Reduza quality ou troque o formato.

Imagem corrompida aparece nos erros

O MCP continua processando as demais imagens. Arquivos corrompidos aparecem na secao "Erros" do retorno sem interromper o batch.

Licenca

MIT -- Koda AI Studio

Links

• Koda AI Studio: https://kodaai.app
• sharp: https://sharp.pixelplumbing.com/
• Model Context Protocol: https://modelcontextprotocol.io/
• Repositorio: https://github.com/justmpm/image-tools-mcp