# image-mcp

MCP server for advanced image processing operations with AI capabilities, local processing, and comprehensive tool discovery.

## Features

- **80+ Image Processing Tools**: Comprehensive toolkit for all image manipulation needs
- **TypeScript MCP Server**: Built with @modelcontextprotocol/sdk
- **Tool Discovery System**: Built-in introspection and documentation tools
- **Tool Registry Pattern**: Dynamic tool loading and management
- **Local Processing**: CPU-based operations with Sharp.js (no API keys needed)
- **AI-Powered Tools**: Image generation, background removal, upscaling, inpainting
- **Binary Data Handling**: Automatic base64 encoding for small images (<1MB)
- **URL Reference Pattern**: Large images (>1MB) written to disk with path references
- **Batch Operations**: Process multiple images efficiently
- **Graceful Error Handling**: Provider unavailability and timeout handling
- **Cost Management**: Built-in budget controls and spending alerts
- **Health Monitoring**: Automatic provider health checks
- **File I/O Patterns**: Support for file paths, URLs, and base64 input/output
- **Diagram Generation**: Graphviz (DOT) and Mermaid diagram rendering
- **Canvas Annotations**: Draw text, shapes, and labels on images

## Quick Start

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd image-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

### Configuration

1. Copy the example environment file:

```bash
cp .env.example .env
```

2. Add your API keys (optional - local processing works without any keys):

```env
# At minimum, add ONE AI generation provider:
SEEDREAM_API_KEY=your_key_here        # Recommended for quality
FAL_KEY=your_key_here                 # Recommended for creativity
OPENAI_API_KEY=sk-your_key_here       # Recommended for ease of use
```

See the [Configuration Guide](docs/CONFIGURATION.md) for detailed setup instructions.

### MCP Server Setup

Add to your Claude Desktop or MCP client configuration:

```json
{
  "mcpServers": {
    "image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/image-mcp/dist/index.js"],
      "env": {
        "SEEDREAM_API_KEY": "your_key_here",
        "FAL_KEY": "your_key_here"
      }
    }
  }
}
```

### Verify Installation

Once connected, use the discovery tools to verify everything is working:

```
Use the "list_tools" tool to see all available image processing tools
Use the "list_providers" tool to check which AI providers are configured
Use the "get_capabilities" tool to see what operations are available
```

## Tool Categories

### Discovery Tools (Built-in Introspection)

- `list_tools` - List all available tools with descriptions and categories
- `list_providers` - List configured AI providers and their status
- `get_tool_help` - Get detailed help for a specific tool
- `get_capabilities` - See what operations are available with current configuration

### Local Processing Tools (No API Keys Required)

- **Image Manipulation**: resize, crop, rotate, flip
- **Format Conversion**: JPEG, PNG, WebP, AVIF, TIFF, GIF
- **Compression**: Optimize file sizes for web and storage
- **Color Adjustments**: brightness, contrast, saturation, tint
- **Filters**: blur, sharpen, grayscale
- **Watermarking**: Add text or image watermarks
- **Compositing**: Overlay and blend images
- **Metadata**: Extract EXIF and image information

### AI-Powered Tools (Requires API Keys)

- **Image Generation**: Create images from text prompts (Seedream, FLUX, DALL-E, Ideogram)
- **Background Removal**: Professional background removal (Photoroom, Remove.bg)
- **Upscaling**: AI super-resolution (Replicate)
- **Inpainting**: Remove objects and fill intelligently (Replicate, IOPaint)

### Batch Processing Tools

- Process multiple images in parallel
- Apply transformations to entire folders
- Progress tracking and error handling

### Diagram Generation Tools

- **Graphviz**: Generate graphs from DOT language
- **Mermaid**: Flowcharts, sequence diagrams, class diagrams, Gantt charts
- **Specialized Diagrams**: Flowcharts, dependency graphs, ER diagrams, architecture diagrams

### Canvas & Annotation Tools

- Draw text with custom fonts and styles
- Add shapes (rectangles, circles, arrows)
- Label images for documentation
- Create visual annotations

### Fetch & Screenshot Tools

- Fetch images from URLs
- Capture website screenshots
- Handle image downloads

## Example Workflows

### Web Optimization Pipeline

```
1. Fetch image from URL
2. Resize to target dimensions (1920x1080)
3. Compress with quality 85
4. Convert to WebP format
5. Generate thumbnail (400x300)
```

### Social Media Export Workflow

```
1. Generate image with AI (landscape concept)
2. Remove background (if needed)
3. Resize for Instagram (1080x1080)
4. Resize for Twitter (1200x675)
5. Add watermark to both
6. Compress for web delivery
```

### Screenshot Annotation Workflow

```
1. Fetch screenshot from URL
2. Add text labels to highlight features
3. Draw arrows pointing to key elements
4. Add rectangular highlights
5. Export as PNG for documentation
```

### AI-Assisted Design Workflow

```
1. Generate base image with AI
2. Remove background
3. Upscale to high resolution
4. Adjust brightness and contrast
5. Add watermark
6. Export in multiple formats
```

See [docs/WORKFLOWS.md](docs/WORKFLOWS.md) for detailed workflow examples.

## Documentation

- [Configuration Guide](docs/CONFIGURATION.md) - Complete setup instructions for all providers
- [Usage Guide](docs/USAGE.md) - How to use each tool category
- [Workflows](docs/WORKFLOWS.md) - Common workflow examples and patterns
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Solutions to common problems
- [Architecture](docs/ARCHITECTURE.md) - Technical implementation details
- [API Reference](docs/API.md) - Programmatic usage guide

## Development

```bash
npm run dev   # Watch mode with hot reload
npm run lint  # Run ESLint
npm run test  # Run Jest tests
npm run format # Format code with Prettier
```

### Adding New Tools

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for guide on adding new tools to the registry.

## Architecture

```
src/
├── index.ts                    # Server entry point
├── server.ts                   # MCP server implementation
├── types.ts                    # Core type definitions
├── config/
│   ├── provider-config.ts      # API key and provider configuration
│   ├── health-monitor.ts       # Provider health monitoring
│   └── cost-tracker.ts         # Cost tracking and budget controls
├── registry/
│   └── tool-registry.ts        # Tool registry for dynamic loading
├── utils/
│   ├── binary.ts               # Binary data handling utilities
│   ├── timeout.ts              # Timeout handling utilities
│   ├── diagram-utils.ts        # Diagram generation utilities
│   └── screenshot.ts           # Screenshot capture utilities
└── tools/
    ├── discovery-tools.ts      # Tool discovery and introspection
    ├── sharp-tools.ts          # Local image processing (Sharp.js)
    ├── ai-generation-tools.ts  # AI image generation
    ├── bg-removal-tools.ts     # Background removal
    ├── upscaling-tools.ts      # AI upscaling
    ├── inpainting-tools.ts     # AI inpainting
    ├── batch-tools.ts          # Batch processing
    ├── canvas-tools.ts         # Canvas annotations
    ├── diagram-tools.ts        # Diagram generation
    ├── fetch-tools.ts          # URL fetching and screenshots
    └── example-tools.ts        # Example implementations
```

## Cost Management

The server includes built-in cost tracking and budget controls:

```env
# Set spending limits
PROVIDER_DAILY_COST_LIMIT=10.00
PROVIDER_MONTHLY_COST_LIMIT=100.00
PROVIDER_PER_OPERATION_LIMIT=1.00

# Enable cost alerts
PROVIDER_COST_ALERTS=true
PROVIDER_COST_ALERT_THRESHOLDS=50,75,90
```

See [docs/COST_MANAGEMENT.md](docs/COST_MANAGEMENT.md) for details.

## Health Monitoring

Automatic health checks keep track of provider availability:

```env
PROVIDER_HEALTH_CHECK_ENABLED=true
PROVIDER_HEALTH_CHECK_INTERVAL=300  # 5 minutes
PROVIDER_HEALTH_CHECK_TIMEOUT=10    # 10 seconds
```

Use the `list_providers` tool with `checkHealth: true` to see current status.

## Graceful Degradation

The server automatically falls back to alternative providers if the primary fails:

```env
PROVIDER_GRACEFUL_DEGRADATION=true
PROVIDER_FALLBACKS=seedream:flux,dalle3;openai:replicate
```

## Security

- API keys loaded from environment variables only
- Keys never logged or exposed in error messages
- Validation of API key format on startup
- Secure handling of temporary files
- No credential storage in code or configuration files

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT

## Support

- GitHub Issues: Report bugs or request features
- Documentation: Check [docs/](docs/) folder for detailed guides
- Use `get_tool_help` tool for specific tool documentation