SuperCharged-Claude-Code-Upgrade/dexto/agents/image-editor-agent/README.md

Image Editor Agent

A comprehensive AI agent for image editing and processing using the Image Editor MCP Server.

This agent provides a complete suite of image manipulation tools through a Python-based MCP server built with OpenCV and Pillow.

Features

🖼️ Viewing & Preview

• Image Preview: Get base64 previews for display in chat interfaces
• System Viewer: Open images in the system's default image viewer
• Image Details: Show detailed information in a user-friendly format
• Thumbnail Generation: Create quick thumbnail versions
• Image Comparison: Compare two images and highlight differences
• Detailed Analysis: Comprehensive image statistics and color analysis

✂️ Basic Operations

• Resize: Resize images with aspect ratio preservation
• Crop: Crop images to specified dimensions
• Format Conversion: Convert between JPG, PNG, WebP, BMP, TIFF

🎨 Filters & Effects

• Basic: Blur, sharpen, grayscale, invert
• Artistic: Sepia, vintage, cartoon, sketch
• Detection: Edge detection, emboss

⚙️ Adjustments

• Brightness & Contrast: Fine-tune image appearance
• Color Analysis: Detailed color statistics and histograms

📝 Drawing & Annotations

• Basic Shapes: Draw rectangles, circles, lines, and arrows
• Text Overlay: Add text with customizable font, size, color, and position
• Annotations: Add text with background for better visibility
• Shape Properties: Control thickness, fill, and positioning

🔍 Computer Vision

• Object Detection: Detect faces, edges, contours, circles, lines
• Image Analysis: Detailed statistics, color analysis, histogram data

🎯 Advanced Features

• Collage Creation: Create collages with multiple layout types and templates
• Batch Processing: Process multiple images with the same operation
• Filter Discovery: List all available filters and effects
• Template System: Predefined layouts for professional collages

Quick Start

Prerequisites

• Node.js 20+: For the Dexto framework
• Python 3.10+: Automatically managed by the MCP server

Installation

1. Run the Agent:

   # From the dexto project root
   dexto --agent agents/image-editor-agent/image-editor-agent.yml
   

That's it! The MCP server will be automatically downloaded and installed via uvx on first run.

Configuration

The agent is configured to use the published MCP server:

mcpServers:
  image_editor:
    type: stdio
    command: uvx
    args:
      - truffle-ai-image-editor-mcp
    connectionMode: strict

MCP Server

This agent uses the Image Editor MCP Server, which is maintained separately at:

🔗 https://github.com/truffle-ai/mcp-servers/tree/main/src/image-editor

The MCP server repository provides:

• Complete technical documentation
• Development and contribution guidelines
• Server implementation details
• Advanced configuration options

Available Tools

Viewing & Preview Tools

preview_image

Get a base64 preview of an image for display in chat interfaces.

Parameters:

• filePath (string): Path to the image file
• maxSize (integer, optional): Maximum size for preview (default: 800)

open_image_viewer

Open an image in the system's default image viewer.

Parameters:

• filePath (string): Path to the image file

show_image_details

Display detailed information about an image in a user-friendly format.

Parameters:

• filePath (string): Path to the image file

create_thumbnail

Create a thumbnail version of an image for quick preview.

Parameters:

• filePath (string): Path to the image file
• size (integer, optional): Thumbnail size (default: 150)
• outputPath (string, optional): Path for the output thumbnail

compare_images

Compare two images and show differences.

Parameters:

• image1Path (string): Path to the first image
• image2Path (string): Path to the second image

Basic Image Operations

get_image_info

Get detailed information about an image file.

Parameters:

• filePath (string): Path to the image file to analyze

resize_image

Resize an image to specified dimensions.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• width (integer, optional): Target width in pixels
• height (integer, optional): Target height in pixels
• maintainAspectRatio (boolean, optional): Whether to maintain aspect ratio (default: true)
• quality (integer, optional): Output quality 1-100 (default: 90)

crop_image

Crop an image to specified dimensions.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• x (integer): Starting X coordinate for cropping
• y (integer): Starting Y coordinate for cropping
• width (integer): Width of the crop area
• height (integer): Height of the crop area

convert_format

Convert an image to a different format.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• format (string): Target format (jpg, jpeg, png, webp, bmp, tiff)
• quality (integer, optional): Output quality 1-100 for lossy formats (default: 90)

Filters & Effects

apply_filter

Apply various filters and effects to an image.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• filter (string): Type of filter (blur, sharpen, grayscale, sepia, invert, edge_detection, emboss, vintage, cartoon, sketch)
• intensity (number, optional): Filter intensity 0.1-5.0 (default: 1.0)

list_available_filters

List all available image filters and effects.

Parameters: None

Adjustments

adjust_brightness_contrast

Adjust brightness and contrast of an image.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• brightness (number, optional): Brightness adjustment -100 to 100 (default: 0)
• contrast (number, optional): Contrast multiplier 0.1 to 3.0 (default: 1.0)

Drawing & Annotations

draw_rectangle

Draw a rectangle on an image.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• x (integer): X coordinate of top-left corner
• y (integer): Y coordinate of top-left corner
• width (integer): Width of the rectangle
• height (integer): Height of the rectangle
• color (string, optional): Color in hex format (default: "#FF0000")
• thickness (integer, optional): Line thickness (default: 3)
• filled (boolean, optional): Whether to fill the rectangle (default: false)

draw_circle

Draw a circle on an image.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• centerX (integer): X coordinate of circle center
• centerY (integer): Y coordinate of circle center
• radius (integer): Radius of the circle
• color (string, optional): Color in hex format (default: "#00FF00")
• thickness (integer, optional): Line thickness (default: 3)
• filled (boolean, optional): Whether to fill the circle (default: false)

draw_line

Draw a line on an image.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• startX (integer): X coordinate of line start
• startY (integer): Y coordinate of line start
• endX (integer): X coordinate of line end
• endY (integer): Y coordinate of line end
• color (string, optional): Color in hex format (default: "#0000FF")
• thickness (integer, optional): Line thickness (default: 2)

draw_arrow

Draw an arrow on an image.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• startX (integer): X coordinate of arrow start
• startY (integer): Y coordinate of arrow start
• endX (integer): X coordinate of arrow end
• endY (integer): Y coordinate of arrow end
• color (string, optional): Color in hex format (default: "#FF00FF")
• thickness (integer, optional): Line thickness (default: 2)
• tipLength (number, optional): Arrow tip length as fraction of line (default: 0.3)

add_text_to_image

Add text overlay to an image.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• text (string): Text to add to the image
• x (integer): X coordinate for text placement
• y (integer): Y coordinate for text placement
• fontSize (integer, optional): Font size in pixels (default: 30)
• color (string, optional): Text color in hex format (default: "#FFFFFF")

add_annotation

Add an annotation with background to an image.

Parameters:

• inputPath (string): Path to the input image file
• outputPath (string, optional): Path for the output image
• text (string): Text to add to the image
• x (integer): X coordinate for text placement
• y (integer): Y coordinate for text placement
• fontSize (integer, optional): Font size in pixels (default: 20)
• textColor (string, optional): Text color in hex format (default: "#FFFFFF")
• backgroundColor (string, optional): Background color in hex format (default: "#000000")
• padding (integer, optional): Padding around text (default: 5)

Computer Vision

detect_objects

Detect objects in an image using OpenCV.

Parameters:

• inputPath (string): Path to the input image file
• detectionType (string): Type of detection (faces, edges, contours, circles, lines)

analyze_image

Analyze image statistics and properties.

Parameters:

• inputPath (string): Path to the input image file

Advanced Features

create_collage

Create a collage from multiple images with various layout options.

Parameters:

• imagePaths (array): List of image file paths
• layout (string, optional): Layout type (grid, horizontal, vertical, mosaic, random, custom) (default: grid)
• outputPath (string, optional): Path for the output collage
• maxWidth (integer, optional): Maximum width for individual images (default: 1200)
• spacing (integer, optional): Spacing between images (default: 10)
• canvasWidth (integer, optional): Custom canvas width for mosaic/random/custom layouts
• canvasHeight (integer, optional): Custom canvas height for mosaic/random/custom layouts
• backgroundColor (string, optional): Background color in hex format (default: "#FFFFFF")
• customPositions (array, optional): List of {x, y} coordinates for custom layout
• randomSeed (integer, optional): Seed for reproducible random layouts

create_collage_template

Create a collage using predefined templates.

Parameters:

• imagePaths (array): List of image file paths
• template (string, optional): Template type (photo_wall, storyboard, featured, instagram_grid, polaroid) (default: photo_wall)
• outputPath (string, optional): Path for the output collage
• maxWidth (integer, optional): Maximum canvas width (default: 1200)
• backgroundColor (string, optional): Background color in hex format (default: "#FFFFFF")

list_collage_templates

List all available collage templates and layouts.

Parameters: None

batch_process

Process multiple images with the same operation.

Parameters:

• inputPaths (array): List of input image paths
• operation (string): Operation type (resize, filter, brightness_contrast, convert)
• outputDirectory (string, optional): Output directory for processed images
• Additional parameters depend on the operation type

Supported Image Formats

• JPEG/JPG: Lossy compression, good for photos
• PNG: Lossless compression, good for graphics with transparency
• WebP: Modern format with good compression
• BMP: Uncompressed bitmap format
• TIFF: High-quality format for professional use

Dependencies

• OpenCV: Computer vision operations and image processing
• Pillow: Image manipulation and text rendering
• NumPy: Numerical operations
• MCP: Model Context Protocol server implementation

Example Usage

Basic Image Operations

"Resize the image at /path/to/image.jpg to 800x600 pixels"
"Crop the image to show only the top-left quarter"
"Convert the image to PNG format"

Interactive Viewing

"Show me a preview of the image"
"Open this image in the system viewer"
"Display detailed information about the image"

Filters and Effects

"Apply a vintage filter to the image"
"Create a cartoon effect on the image"
"Apply edge detection to find contours"

Analysis and Detection

"Analyze the color statistics of the image"
"Detect faces in the image"
"Compare two images and show differences"

Drawing and Annotations

"Draw a red rectangle around the face in the image"
"Add a circle to highlight the center point"
"Draw an arrow pointing to the important feature"
"Add an annotation saying 'Face detected' with a black background"
"Draw a line connecting two points in the image"

Advanced Features

"Create a mosaic collage from these images"
"Create a featured layout collage with one large image"
"Create an Instagram grid from 9 photos"
"Create a custom collage with specific positions"
"List all available collage templates"
"Batch process all images in the folder to apply a blur filter"
"Show me a preview of the image"

Troubleshooting

Common Issues

1. OpenCV Installation: If you encounter issues with OpenCV, ensure you have the required system dependencies:

   # macOS
   brew install opencv
   
   # Ubuntu/Debian
   sudo apt-get install libopencv-dev
   

2. Font Issues: If text rendering fails, the server will fall back to the default font.

3. Memory Issues: For large images, consider resizing before processing to avoid memory constraints.

4. Path Issues: Ensure all file paths are absolute or correctly relative to the working directory.

Troubleshooting

Common Issues

1. Server Installation: The MCP server will be automatically installed via uvx on first run. No manual setup required.

2. OpenCV Installation: The server includes OpenCV installation - this may take a moment on first run due to the large download (35MB+).

3. Memory Issues: For large images, consider resizing before processing to avoid memory constraints.

4. Path Issues: Ensure all file paths are absolute or correctly relative to the working directory.

Getting Help

• MCP Server Issues: Report at the mcp-servers repository
• Agent Configuration: Report at the main Dexto repository
• Feature Requests: Use the mcp-servers repository for tool-related requests

License

This project is part of the Dexto AI agent framework.