Image Processor

Name: Image Processor
Rating: 3.5 (1 reviews)
Author: aoyasong

By aoyasong 👁 8 views ▲ 0 votes

OpenClaw MCP Plugin for e-commerce image processing, optimization, and batch transformation

GitHub

Install

npm install image-processor-plugin

Configuration Example

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

README

# 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
```bash
npm install image-processor-plugin
```

### Manual Installation
1. Clone the repository:
```bash
git clone https://github.com/aoyasong/image-processor-plugin.git
cd image-processor-plugin
```

2. Install dependencies:
```bash
npm install
```

3. Configure environment variables:
```bash
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
```bash
# 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```bash
npm test
```

### Building
```bash
npm run build
```

## Docker Deployment

### Build Docker Image
```bash
docker build -t image-processor-plugin .
```

### Run with Docker Compose
```bash
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](https://github.com/aoyasong/image-processor-plugin/issues)
- Documentation: See `/docs` directory
- Examples: See `/examples` directory

tools