Image Processor Plugin

OpenClaw MCP Plugin for image processing, optimization, format conversion and e-commerce image generation. The seventh plugin in the cross-border e-commerce plugin suite.

Features

Core Image Processing

• Image compression and optimization (WebP, AVIF format support)
• Format conversion (JPEG, PNG, WebP, GIF, AVIF)
• Resizing, cropping and intelligent processing
• E-commerce product image standardization (main images, detail images, thumbnails)
• White background image generation and background removal
• Batch image processing and optimization pipeline
• Watermark addition and position control
• Responsive image srcset generation

E-commerce Scene Optimization

• E-commerce product image presets (thumbnail 200x200, main image 800x800, detail image 1200x1200)
• White background standardization (Amazon and other platform requirements)
• Multi-size image batch generation
• Image CDN optimization and lazy loading image generation
• Product gallery generation and layout

Technical Architecture

• Node.js v18+, MCP protocol (@modelcontextprotocol/sdk)
• Primary engine: Sharp library (high performance, modern image format support)
• Fallback engine: ImageMagick (complex operations, traditional format support)
• Smart engine selection: Automatically selects the best engine based on image type and operation
• Cache mechanism: Permanent cache based on content hash, processed image caching
• Performance optimization: Streaming processing, batch parallel processing, memory management

Installation

Prerequisites

• Node.js 18 or higher
• For full functionality:
  • sharp library (automatically installed via npm)
  • imagemagick (optional, for complex operations)

Install from npm

npm install image-processor-plugin

Manual Installation

1. Clone the repository:

git clone https://github.com/aoyasong/image-processor-plugin.git
cd image-processor-plugin

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env

MCP Tools

1. image_resize_optimize

Description: Resize image with optimization for web and e-commerce

Parameters:

• image_data (string, required): Base64 encoded image data
• width (integer, required): Target width in pixels
• height (integer, required): Target height in pixels
• fit (string): How to resize ("cover", "contain", "fill", "inside", "outside")
• format (string): Target format ("jpeg", "png", "webp", "avif", "gif")
• quality (integer): Image quality 1-100
• engine (string): Processing engine ("sharp", "imagemagick", "auto")

2. image_convert_format

Description: Convert image to different format with optimization

Parameters:

• image_data (string, required): Base64 encoded image data
• target_format (string, required): Target format ("jpeg", "png", "webp", "avif", "gif")
• quality (integer): Image quality 1-100
• lossless (boolean): Use lossless compression
• engine (string): Processing engine ("sharp", "imagemagick", "auto")

3. image_batch_process

Description: Batch process multiple images with different operations

Parameters:

• images (array, required): List of images with operations
• parallel_limit (integer): Maximum parallel processing operations
• engine (string): Processing engine ("sharp", "imagemagick", "auto")

4. image_generate_ecommerce_variants

Description: Generate e-commerce image variants (thumbnail, main, detail, etc.)

Parameters:

• image_data (string, required): Base64 encoded image data
• variants (array): List of variants to generate
• background_removal (boolean): Remove background (white background for e-commerce)
• watermark (boolean): Add watermark if configured
• engine (string): Processing engine ("sharp", "imagemagick", "auto")

5. image_analyze_quality

Description: Analyze image quality, dimensions, compression, and metadata

Parameters:

• image_data (string, required): Base64 encoded image data
• check_exif (boolean): Extract and check EXIF metadata
• detect_faces (boolean): Attempt to detect faces in the image
• ecommerce_suitability (boolean): Check suitability for e-commerce

6. image_remove_background

Description: Remove background from image (AI, threshold, or magic wand)

Parameters:

• image_data (string, required): Base64 encoded image data
• method (string): Background removal method ("ai", "threshold", "magic_wand")
• tolerance (integer): Color tolerance 1-100
• output_format (string): Output format ("png", "jpeg", "webp")
• background_color (string): Background color to replace (hex)

7. image_add_watermark

Description: Add watermark to image with position and opacity control

Parameters:

• base_image (string, required): Base64 encoded base image data
• watermark_image (string, required): Base64 encoded watermark image data
• position (string): Watermark position
• opacity (number): Watermark opacity 0-1
• scale (number): Watermark scale relative to base image
• margin (integer): Margin from edges in pixels

8. image_optimize_for_web

Description: Optimize image for web delivery with size targets and srcset generation

Parameters:

• image_data (string, required): Base64 encoded image data
• target_size_kb (integer): Target file size in kilobytes
• target_width (integer): Target width in pixels
• target_format (string): Target format for optimization
• generate_srcset (boolean): Generate srcset with multiple sizes
• lazy_load_placeholder (boolean): Generate low-quality placeholder for lazy loading

Configuration

Environment Variables

# Main Processing Engine Configuration
SHARP_ENGINE_ENABLED=true
IMAGEMAGICK_PATH=/usr/local/bin/convert

# Performance Configuration
MAX_IMAGE_SIZE_MB=50
MAX_PROCESSING_TIME_MS=30000
PARALLEL_LIMIT=4

# Cache Configuration
IMAGE_CACHE_DIR=./.cache/images
CACHE_TTL_DAYS=30

# E-commerce Preset Configuration
ECOMMERCE_PRESET_THUMBNAIL=200x200
ECOMMERCE_PRESET_MAIN=800x800
ECOMMERCE_PRESET_DETAIL=1200x1200
ECOMMERCE_PRESET_WHITE_BACKGROUND=true

Configuration Files

The plugin includes preset configurations in /config directory:

• formats.json: Supported image formats and capabilities
• presets.json: E-commerce and social media image presets
• quality-profiles.json: Quality optimization profiles

Integration with Other Plugins

1. Amazon SP API Plugin

Amazon product image optimization and upload

// Example integration
const amazonImages = await image_generate_ecommerce_variants(image_data, {
  variants: amazon_presets
});
await amazon_upload_product_images(product_id, amazonImages);

2. 1688 Data Plugin

1688 supplier image processing and optimization

// Process supplier images
const optimizedImages = await image_batch_process(supplierImages, {
  operations: ['resize_800x800', 'format_webp', 'white_background']
});

3. E-commerce DB Plugin

Store image processing records and metadata

// Store processing records
await db_store_image_processing_record({
  image_id: 'img_123',
  original_size: 1024000,
  processed_size: 256000,
  operations: ['resize', 'compress', 'format_convert'],
  quality_score: 0.95
});

4. Listing Optimization Agent

A/B test different image effects

// Generate variants for A/B testing
const variants = await image_generate_ecommerce_variants(image_data, {
  variants: [
    { name: 'variant_a', width: 800, height: 800, background_removal: true },
    { name: 'variant_b', width: 800, height: 800, background_removal: false }
  ]
});

Performance Metrics

Metric	Target	Description
Single image processing	< 500ms	800x800 WebP conversion
Batch processing (10 images)	< 3 seconds	Parallel processing
Memory usage	< 100MB	Maximum image processing
Cache hit rate	> 60%	Reduce repeat processing

Development

Project Structure

image-processor-plugin/
├── src/
│   ├── processors/
│   │   ├── sharp-processor.js     # Sharp engine
│   │   ├── imagemagick-processor.js # ImageMagick engine
│   │   └── processor-manager.js   # Processor manager
│   ├── presets/                   # E-commerce presets
│   ├── utils/                     # Utility functions
│   ├── tools.js                   # MCP tool definitions
│   └── index.js                   # Main entry point
├── config/                        # Configuration files
├── test/                          # Test files
├── examples/                      # Usage examples
└── docker/                        # Docker configuration

Running Tests

npm test

Building

npm run build

Docker Deployment

Build Docker Image

docker build -t image-processor-plugin .

Run with Docker Compose

docker-compose up

Docker Configuration

The Docker image includes:

• Node.js 18+ environment
• Sharp library with AVIF support
• ImageMagick for complex operations
• Cache volume for processed images
• Health check endpoint

License

MIT License - see LICENSE file for details.

Contributing

This is the seventh core plugin in the cross-border e-commerce plugin suite. Image processing is crucial for e-commerce conversion rates. Please ensure efficient image processing pipelines and e-commerce scenario optimizations.

Support

• GitHub Issues: https://github.com/aoyasong/image-processor-plugin/issues
• Documentation: See /docs directory
• Examples: See /examples directory