@jojihatzz/lemmeconvert/README.md

A comprehensive Model Context Protocol (MCP) server for advanced image processing, conversion, manipulation, filtering, watermarking, analysis, QR code generation, duplicate detection, and HEIC support with robust error handling

# LemmeConvert

<div align="center">
  <img src="https://i.imgur.com/8R2n3tg.png" alt="LemmeConvert Icon" width="128" height="128">
</div>

A comprehensive Model Context Protocol (MCP) server for advanced image processing, conversion, manipulation, QR code generation, duplicate detection, and HEIC support. Built with Sharp for high-performance image processing and featuring robust error handling.

## 🚀 Features

### Core Image Processing
- **Format Conversion**: Convert between JPG, PNG, WebP, BMP, TIFF, GIF, and ICO formats
- **Image Resizing**: Resize images to specific dimensions with precision
- **Image Compression**: Compress images with customizable quality settings
- **Image Rotation**: Rotate images by 90°, 180°, or 270°
- **Image Flipping**: Flip images horizontally or vertically

### Advanced Features
- **Smart Cropping**: Intelligent cropping with aspect ratio control and entropy-based positioning
- **Manual Cropping**: Precise cropping with custom coordinates and dimensions
- **Image Filters**: Apply blur, sharpen, brightness, contrast, saturation adjustments
- **Visual Effects**: Grayscale, sepia, and color inversion effects
- **Watermarking**: Add text or image watermarks with position and opacity control
- **Image Analysis**: Extract metadata, dimensions, and dominant colors
- **Metadata Removal**: Remove EXIF, XMP, and IPTC data for privacy protection
- **QR Code Generation**: Generate customizable QR codes with styling options
- **Duplicate Detection**: Find similar or duplicate images using perceptual hashing
- **HEIC Support**: Convert HEIC/HEIF files from iOS devices to standard formats

### File Management
- **Bulk Renaming**: Rename multiple files with flexible patterns using variables
- **Batch Processing**: Process up to 50 files simultaneously
- **Smart Output Naming**: Automatically handles filename conflicts
- **Robust Error Handling**: Comprehensive validation and user-friendly error messages

## Installation

### Global Installation
```bash
npm install -g @jojihatzz/lemmeconvert
```

### MCP Client Configuration

To use LemmeConvert as an MCP server, add it to your MCP client configuration:

#### Claude Desktop App
Add this to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "lemmeconvert": {
      "command": "npx",
      "args": [
        "-y",
        "@jojihatzz/lemmeconvert"
      ]
    }
  }
}
```

#### VS Code with MCP Extension
Add this to your `.vscode/mcp.json`:
```json
{
  "servers": {
    "lemmeconvert": {
      "command": "npx",
      "args": ["-y", "@jojihatzz/lemmeconvert"]
    }
  }
}
```

#### Other MCP Clients
For other MCP clients, use:
- **Command**: `npx`
- **Args**: `["-y", "@jojihatzz/lemmeconvert"]`

## Usage

The server provides a comprehensive set of image processing and file management tools:

## Available Tools

| Category | Tool | Description |
|----------|------|-------------|
| **Image Conversion** | `convert_image` | Convert images between different formats (JPG, PNG, WebP, BMP, TIFF, GIF, ICO) |
| | `convert_heic` | Convert HEIC/HEIF files from iOS devices to JPG, PNG, or WebP |
| **Image Processing** | `resize_image` | Resize images to specific dimensions |
| | `compress_image` | Compress images to reduce file size with quality control |
| | `rotate_image` | Rotate images by 90°, 180°, or 270° |
| | `flip_image` | Flip images horizontally or vertically |
| **Advanced Processing** | `crop_image` | Smart or manual cropping with aspect ratio support |
| | `apply_filters` | Apply blur, sharpen, brightness, contrast, saturation, grayscale, sepia, invert |
| | `add_watermark` | Add text or image watermarks with position and opacity control |
| **Analysis & Metadata** | `analyze_image` | Get image dimensions, file size, format info, and dominant colors |
| | `remove_metadata` | Remove EXIF, XMP, and IPTC metadata for privacy and smaller file sizes |
| | `detect_duplicates` | Find similar or duplicate images in folders using perceptual hashing |
| **QR Codes & Utilities** | `generate_qr` | Generate QR codes with custom styling, colors, and error correction |
| **File Management** | `bulk_rename` | Rename multiple files with custom patterns using variables like `{name}`, `{index}`, `{date}`, `{time}` |

## 🛠️ Tool Details

### Image Conversion (`convert_image`)
- Supports all major formats: JPG, PNG, WebP, BMP, TIFF, GIF, ICO
- Batch processing up to 50 files
- Custom output naming
- Special ICO format handling

### HEIC Conversion (`convert_heic`)
- Convert HEIC/HEIF files from iOS devices
- Output formats: JPG, PNG, WebP
- Quality control for JPEG output (1-100)
- Batch processing up to 20 files
- Handles corrupted file detection

### Image Processing
- **Resize** (`resize_image`): Precise dimension control up to 50,000 pixels
- **Compress** (`compress_image`): JPEG quality control (1-100), WebP lossless options
- **Rotate** (`rotate_image`): 90°, 180°, 270° rotation angles
- **Flip** (`flip_image`): Horizontal or vertical flipping

### Advanced Features
- **Smart Crop** (`crop_image`): Entropy-based intelligent cropping with aspect ratios
- **Manual Crop**: Precise coordinate-based cropping (x, y, width, height)
- **Filters** (`apply_filters`): Professional image adjustments
  - Blur (0.3-1000 radius)
  - Sharpen (0.5-10 amount)
  - Brightness/Contrast/Saturation (-100 to +100)
  - Grayscale, Sepia, Color Inversion
- **Watermarks** (`add_watermark`): Text or image watermarks
  - 9 position options (corners, edges, center)
  - Opacity control (0-100%)
  - Custom colors and sizing
- **Analysis** (`analyze_image`): Extract image metadata and dominant colors

### QR Code Generation (`generate_qr`)
- Generate QR codes from text, URLs, or any data
- Custom styling options:
  - Size control (50-2000 pixels)
  - Error correction levels (L, M, Q, H)
  - Custom colors (dark/light modules)
  - Margin control (0-10)
- PNG output format
- Custom output directory support

### Duplicate Detection (`detect_duplicates`)
- Perceptual hash-based similarity detection
- Configurable similarity threshold (0-100%)
- Recursive directory scanning option
- File extension filtering
- Detailed JSON report generation
- Hamming distance calculation for accuracy

### File Management
- **Bulk Rename** (`bulk_rename`): Pattern-based renaming
  - Variables: `{name}`, `{ext}`, `{index}`, `{date}`, `{time}`
  - File filtering by extension
  - Dry run preview mode
  - Conflict detection

## 🔧 Safety & Validation

- **Input Validation**: Comprehensive parameter checking and type validation
- **File Safety**: File existence, size limits (100MB), and format verification
- **Batch Limits**: Maximum 50 files per operation to prevent memory issues
- **Error Handling**: User-friendly error messages with clear troubleshooting guidance
- **Path Support**: Works with absolute and relative file paths
- **Conflict Resolution**: Auto-appends numbers for duplicate filenames

## Requirements

- Node.js 16 or higher
- Supported platforms: Windows, macOS, Linux

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.