kmamine/IQA-Server

IQA-Server: Image Quality Assessment MCP Server

A comprehensive Model Context Protocol (MCP) server that provides image quality assessment capabilities using various metrics including PSNR, SSIM, LPIPS, and MSE.

Features

• Multiple Quality Metrics: Supports PSNR, SSIM, LPIPS, and MSE calculations
• Flexible Input: Accepts file paths, base64 data URLs, and PIL Image objects
• Comprehensive Analysis: Provides detailed image statistics and quality interpretations
• GPU Acceleration: Automatic GPU detection and utilization for deep learning models
• MCP Integration: Full Model Context Protocol compliance for seamless integration

Supported Metrics

Traditional Metrics

• PSNR (Peak Signal-to-Noise Ratio): Measures reconstruction quality in decibels
• SSIM (Structural Similarity Index): Evaluates perceived image quality based on luminance, contrast, and structure
• MSE (Mean Squared Error): Calculates pixel-wise differences between images

Perceptual Metrics

• LPIPS (Learned Perceptual Image Patch Similarity): Uses deep learning to assess perceptual similarity

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Basic Installation

git clone https://github.com/kmamine/IQA-Server.git
cd IQA-Server
pip install -r requirements.txt

Development Installation

git clone https://github.com/kmamine/IQA-Server.git
cd IQA-Server
pip install -e .[dev]

GPU Support (Optional)

For CUDA-enabled GPU acceleration:

pip install -e .[gpu]

Usage

Running the Server

python -m iqa_server.main

With verbose logging:

python -m iqa_server.main --verbose

Available Tools

1. Calculate PSNR

{
  "name": "calculate_psnr",
  "arguments": {
    "image1": "/path/to/image1.jpg",
    "image2": "/path/to/image2.jpg"
  }
}

2. Calculate SSIM

{
  "name": "calculate_ssim",
  "arguments": {
    "image1": "/path/to/image1.jpg",
    "image2": "/path/to/image2.jpg"
  }
}

3. Calculate LPIPS

{
  "name": "calculate_lpips",
  "arguments": {
    "image1": "/path/to/image1.jpg",
    "image2": "/path/to/image2.jpg"
  }
}

4. Calculate MSE

{
  "name": "calculate_mse",
  "arguments": {
    "image1": "/path/to/image1.jpg",
    "image2": "/path/to/image2.jpg"
  }
}

5. Get Image Statistics

{
  "name": "get_image_stats",
  "arguments": {
    "image": "/path/to/image.jpg"
  }
}

6. Comprehensive Assessment

{
  "name": "comprehensive_assessment",
  "arguments": {
    "image1": "/path/to/image1.jpg",
    "image2": "/path/to/image2.jpg"
  }
}

Input Formats

The server supports multiple input formats:

1. File paths: /path/to/image.jpg
2. Base64 data URLs: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...
3. Raw bytes: Binary image data

Example Integration

import asyncio
from mcp.client.stdio import stdio_client

async def assess_image_quality():
    async with stdio_client(["python", "-m", "iqa_server.main"]) as client:
        # List available tools
        tools = await client.list_tools()
        
        # Calculate PSNR
        result = await client.call_tool(
            "calculate_psnr",
            {
                "image1": "original.jpg",
                "image2": "compressed.jpg"
            }
        )
        print(result.content[0].text)

asyncio.run(assess_image_quality())

Quality Interpretation

The server provides interpretations for quality metrics:

PSNR Levels

• > 30 dB: High quality similarity
• 20-30 dB: Moderate quality similarity
• < 20 dB: Low quality similarity

SSIM Levels

• > 0.9: Excellent similarity
• 0.7-0.9: Good similarity
• 0.5-0.7: Fair similarity
• < 0.5: Poor similarity

Architecture

iqa_server/
├── main.py              # Main server implementation
├── __init__.py          # Package initialization
└── utils/               # Utility modules
    ├── __init__.py
    ├── image_utils.py   # Image processing utilities
    └── metrics.py       # Quality metric implementations

Development

Running Tests

pytest tests/

Code Formatting

black iqa_server/
isort iqa_server/

Type Checking

mypy iqa_server/

Configuration

Environment Variables

• IQA_DEVICE: Force device selection (cpu, cuda, cuda:0, etc.)
• IQA_LOG_LEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR)

Model Configuration

The server automatically detects available hardware and configures models accordingly:

• GPU Available: Uses CUDA for LPIPS calculations
• CPU Only: Falls back to CPU processing

Troubleshooting

Common Issues

LPIPS Model Loading Fails

WARNING: Failed to initialize deep learning models: ...

Solution: Ensure PyTorch is installed correctly. LPIPS functionality will be disabled but other metrics will work.

CUDA Out of Memory

RuntimeError: CUDA out of memory

Solution: Set IQA_DEVICE=cpu environment variable to force CPU usage.

Image Loading Errors

ValueError: Unsupported image input type

Solution: Ensure images are in supported formats (JPEG, PNG, etc.) and paths are correct.

Performance Tips

1. Use GPU: Enable CUDA for faster LPIPS calculations
2. Batch Processing: Process multiple comparisons in sequence for better throughput
3. Image Preprocessing: Resize large images before processing to reduce memory usage

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/kmamine/IQA-Server.git
cd IQA-Server
pip install -e .[dev]
pre-commit install

License

This project is licensed under the MIT License - see the file for details.

Citation

If you use this software in your research, please cite:

@software{iqa_server,
  title={IQA-Server: Image Quality Assessment MCP Server},
  author={Mohamed Amine KEKROURI},
  year={2025},
}