# @image-converter/mcp

An MCP (Model Context Protocol) server for converting images to AVIF and WebP formats using ImageMagick. Optimizes images for better web performance with support for batch conversion, quality control, and more.

## Prerequisites

### ImageMagick Installation

This package requires [ImageMagick](https://imagemagick.org/) to be installed on your system.

**Windows:**
- Download from https://imagemagick.org/script/download.php
- Install and ensure `magick` command is in your PATH

**macOS:**
```bash
brew install imagemagick
```

**Linux (Ubuntu/Debian):**
```bash
sudo apt-get install imagemagick
```

**Verify Installation:**
```bash
magick -version
```

## Installation

### MCP Configuration

Add to your MCP configuration file:

**For Claude Code (`.claude.json`):**
```json
{
  "mcpServers": {
    "image-converter": {
      "command": "node",
      "args": ["path/to/node_modules/@image-converter/mcp/src/index.js"]
    }
  }
}
```

**For OpenCode (`opencode.json`):**
```json
{
  "mcp": {
    "image-converter": {
      "type": "local",
      "command": ["node", "path/to/node_modules/@image-converter/mcp/src/index.js"],
      "enabled": true
    }
  }
}
```

**For Other MCP Clients:**
```bash
# Install globally
npm install -g @image-converter/mcp

# Or use npx
npx @image-converter/mcp
```

## Available Tools

### convert_image

Convert a single image to AVIF or WebP format.

**Parameters:**
| Parameter       | Type    | Required | Default |             Description              |
|-----------------|---------|----------|---------|--------------------------------------|
| `inputPath`     | string  | Yes      | -       | Path to input image                  |
| `outputFormat`  | string  | Yes      | -       | Output format: "avif" or "webp"      |
| `outputPath`    | string  | No       | auto    | Custom output path                   |
| `quality`       | number  | No       | 75      | Quality 1-100                        |
| `critical`      | boolean | No       | false   | If true, applies 25% quality drop    |

**Example:**
```javascript
convert_image({
  inputPath: "logo.png",
  outputFormat: "avif",
  quality: 75
})
```

### convert_folder

Batch convert all images in a folder to AVIF or WebP format.

**Parameters:**
| Parameter       | Type     | Required | Default |          Description              |
|-----------------|----------|----------|---------|-----------------------------------|
| `inputFolder`   | string   | Yes      | -       | Path to input folder              |
| `outputFolder`  | string   | No       | same    | Output folder path                |
| `outputFormat`  | string   | Yes      | -       | Output format: "avif" or "webp"   |
| `quality`       | number   | No       | 75      | Quality 1-100                     |
| `critical`      | boolean  | No       | false   | If true, applies 25% quality drop |
| `recursive`     | boolean  | No       | false   | Include subfolders                |
| `skipExisting`  | boolean  | No       | true    | Skip if output exists             |

**Example:**
```javascript
convert_folder({
  inputFolder: "./images",
  outputFormat: "avif",
  quality: 80,
  recursive: false,
  skipExisting: true
})
```

### get_image_info

Get information about an image.

**Parameters:**
| Parameter | Type    | Required |     Description    |
|-----------|---------|----------|--------------------|
| `path`    | string  | Yes      | Path to image file |
 
**Example:**
```javascript
get_image_info({ path: "photo.jpg" })
```

### list_images

List all images in a folder.

**Parameters:**
| Parameter   | Type    | Required | Default |              Description               |
|-------------|---------|----------|---------|----------------------------------------|
| `folder`    | string  | Yes      | -       | Path to folder                         |
| `recursive` | boolean | No       | false   | Include subfolders                     |
| `formats`   | array   | No       | all     | Filter by formats, e.g. ["png", "jpg"] |

**Example:**
```javascript
list_images({
  folder: "./assets",
  formats: ["png", "jpg", "webp"]
})
```

## Usage Examples

### Convert Single Image
```
User: "Convert logo.png to AVIF"
Agent calls: convert_image({ inputPath: "logo.png", outputFormat: "avif" })
Result: Creates logo.avif alongside logo.png
```

### Batch Convert Folder
```
User: "Optimize all images in /assets to AVIF at quality 80"
Agent calls: convert_folder({ 
  inputFolder: "/assets", 
  outputFormat: "avif", 
  quality: 80 
})
Result: Creates .avif files for all supported images in /assets
```

### Critical Mode (Maximum Compression)
```
User: "Convert image.jpg to AVIF with maximum compression"
Agent calls: convert_image({ 
  inputPath: "image.jpg", 
  outputFormat: "avif", 
  critical: true 
})
Result: Applies 75% of the quality setting (default 75 = ~56 effective)
```

## Supported Formats

**Input:**
- PNG, JPG/JPEG, WebP, GIF, BMP, TIFF

**Output:**
- AVIF (default recommended)
- WebP

## Why AVIF?

AVIF offers significant advantages over traditional formats:
- **50-70% smaller** file sizes compared to JPEG/PNG
- **Better quality** than WebP at similar file sizes
- **Supported** by all modern browsers
- **Lossy & lossless** compression options

## Technology

This MCP server uses:
- [ImageMagick](https://imagemagick.org/) - Image processing
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol) - MCP implementation

## License

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

## Author

Pratham Bindal

## Contributing

Contributions welcome! Please open an issue or submit a PR.