# Image Convert MCP Server

<p align="center">
  <a href="https://buymeacoffee.com/shanthistream">
    <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee">
  </a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.11+-blue?style=flat-square&logo=python" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="MIT License">
  <img src="https://img.shields.io/badge/MCP-Compatible-purple?style=flat-square" alt="MCP Compatible">
</p>

> 💡 **If this tool saves you time, please consider [buying me a coffee](https://buymeacoffee.com/shanthistream)!** Your support helps maintain and improve this project.

---

A Model Context Protocol (MCP) server for high-performance image format conversion supporting WebP and AVIF formats with parallel processing capabilities.

## 🚀 Features

- **Multiple Format Support**: Convert images to WebP, AVIF, or both formats simultaneously
- **Batch Processing**: Process entire directories with configurable parallel workers
- **Image Resizing**: Optional width/height constraints with aspect ratio preservation
- **Quality Control**: Configurable quality settings for both WebP and AVIF
- **High Performance**: Multi-process parallel execution for batch operations
- **Flexible Input**: Supports PNG, JPG, JPEG, TIFF, BMP, and WebP as input formats

## 📋 Requirements

- Python 3.11+
- MCP Python SDK (`mcp>=1.0.0`)
- Pillow (PIL)
- pillow-avif-plugin
- libavif-dev (system dependency)

## 🔧 Installation

### Using pip

```bash
cd /path/to/image-convert-mcp
pip install -e .
```

Or install requirements directly:

```bash
pip install -r requirements.txt
```

## 💻 CLI Usage

After installation, you can use the `image-convert` command directly:

```bash
# Convert to both WebP and AVIF
image-convert photo.png

# Convert to WebP only
image-convert photo.png -f webp -q 85

# Use a preset
image-convert photo.png --preset thumbnail

# Batch convert a directory
image-convert ./images/ --batch -f webp

# Show compression statistics
image-convert photo.png -f webp --stats

# List available presets
image-convert --list-presets
```

### Available Presets

| Preset | Description |
|--------|-------------|
| `web` | Optimized for web (WebP, quality 80, max 1920px) |
| `thumbnail` | Small thumbnails (WebP, 300x300) |
| `social` | Social media images (1200x630) |
| `hd` | HD resolution (1920x1080) |
| `4k` | 4K resolution (3840x2160) |
| `archive` | High quality archival (both formats) |
| `lossless` | Lossless WebP compression |
| `max-compression` | Maximum file size reduction (AVIF) |

### Using Docker

```bash
docker build -t image-convert-mcp .
```

## 📖 Usage

The MCP server implements the Model Context Protocol with support for both Stdio and Unified HTTP transports.

## 🚌 Transport Modes

The server supports two transport mechanisms:

### 1. Stdio (Default)
Standard communication via stdin/stdout. Ideal for local use with MCP clients like Claude Desktop.

```bash
python mcp_server.py --transport stdio
```

### 2. HTTP (Unified)
Web-based communication via HTTP. This is the modern, recommended transport for remote MCP access.

```bash
python mcp_server.py --transport http --host 0.0.0.0 --port 8000
```

When running in HTTP mode, the server provides a unified MCP endpoint at the root path (e.g., `http://localhost:8000/`).

### MCP Tools

#### `convert_image_single`
Convert a single image to WebP and/or AVIF format.

**Parameters:**
- `input_path` (required): Path to the input image file
- `output_dir` (optional): Directory for output files (default: same as input)
- `format` (optional): Output format - "webp", "avif", or "both" (default: "both")
- `webp_quality` (optional): WebP quality 1-100 (default: 80)
- `avif_quality` (optional): AVIF quality 1-100 (default: 50)
- `lossless` (optional): Enable lossless WebP compression (default: false)
- `max_width` (optional): Maximum output width
- `max_height` (optional): Maximum output height

#### `convert_image_batch`
Convert multiple images in a directory to WebP and/or AVIF format.

**Parameters:**
- `input_path` (required): Path to directory containing images
- `output_dir` (optional): Directory for output files (default: same as input)
- `format` (optional): Output format - "webp", "avif", or "both" (default: "both")
- `webp_quality` (optional): WebP quality 1-100 (default: 80)
- `avif_quality` (optional): AVIF quality 1-100 (default: 50)
- `lossless` (optional): Enable lossless WebP compression (default: false)
- `max_width` (optional): Maximum output width
- `max_height` (optional): Maximum output height
- `workers` (optional): Number of parallel workers (default: CPU count)

## 🔑 Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `mode` | string | `"single"` | Processing mode: `"single"` or `"batch"` |
| `input_path` | string | **required** | Path to image file (single mode) or directory (batch mode) |
| `output_dir` | string | parent of input | Directory for output files |
| `format` | string | `"both"` | Output format: `"webp"`, `"avif"`, or `"both"` |
| `webp_quality` | int | `80` | WebP quality (1-100) |
| `avif_quality` | int | `50` | AVIF quality (1-100) |
| `lossless` | bool | `false` | Enable lossless compression for WebP |
| `max_width` | int | `null` | Maximum output width (maintains aspect ratio) |
| `max_height` | int | `null` | Maximum output height (maintains aspect ratio) |
| `workers` | int | CPU count | Number of parallel workers (batch mode only) |

## 🐳 Docker Usage

```bash
# Build the image
docker build -t image-convert-mcp .

# Run conversion
echo '{"params":{"input_path":"/app/input.png","format":"webp"}}' | \
  docker run -i -v /path/to/images:/app image-convert-mcp
```

## 🔌 MCP Configuration

Add to your MCP settings file (e.g., `opencode.json`):

```json
{
  "mcpServers": {
    "image-convert": {
      "command": "python",
      "args": ["/path/to/image-convert-mcp/mcp_server.py"],
      "disabled": false
    }
  }
}
```

Or using Docker:

```json
{
  "mcpServers": {
    "image-convert": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${workspaceFolder}:/workspace",
        "image-convert-mcp"
      ],
      "disabled": false
    }
  }
}
```

## 📊 Output Format

### Single Mode
```json
{
  "result": {
    "input": "/path/to/input.png",
    "webp": "/path/to/output/input.webp",
    "avif": "/path/to/output/input.avif"
  }
}
```

### Batch Mode
```json
{
  "result": [
    {
      "input": "/path/to/image1.png",
      "webp": "/path/to/output/image1.webp"
    },
    {
      "input": "/path/to/image2.jpg",
      "webp": "/path/to/output/image2.webp"
    }
  ]
}
```

## 🎯 Supported Input Formats

- PNG (`.png`)
- JPEG (`.jpg`, `.jpeg`)
- TIFF (`.tiff`)
- BMP (`.bmp`)
- WebP (`.webp`)

## 🛠️ Development

### Project Structure
```
image-convert-mcp/
├── mcp_server.py      # Main MCP server implementation
├── requirements.txt   # Python dependencies
└── Dockerfile         # Docker container definition
```

## 🤖 For AI Agents

**Quick Summary:** This MCP server converts images to WebP/AVIF formats for web optimization.

| Task | Tool | Example |
|------|------|---------|
| Single image | `convert_image_single` | `{"input_path": "/path/to/image.png", "format": "webp"}` |
| Batch directory | `convert_image_batch` | `{"input_path": "/path/to/dir/", "workers": 4}` |

📖 See [AGENT_GUIDE.md](AGENT_GUIDE.md) for detailed usage patterns.

## ☕ Support This Project

If this MCP server saves you time or helps your projects, consider supporting its development:

<a href="https://buymeacoffee.com/shanthistream">
  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="50" width="210" alt="Buy Me A Coffee">
</a>

**Your support enables:**
- 🚀 New format support (JPEG XL, HEIC)
- 📊 Progress reporting features
- 🔒 Security enhancements
- 📚 Better documentation

## 📝 License

MIT License

## 🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## 🔮 Roadmap

- [ ] Support for JPEG XL format
- [ ] Metadata preservation options
- [ ] Progress reporting for long operations
- [ ] Comprehensive test suite
- [ ] Input validation and security enhancements
- [ ] Caching for frequently converted images