# Replicate Ideogram V3 Balanced MCP Server

A Model Context Protocol (MCP) server that provides access to the ideogram-ai/ideogram-v3-balanced image generation model via Replicate. This server allows you to generate high-quality images using advanced AI technology through the Replicate platform.

## Features

- **High-Quality Image Generation**: Generate stunning images using the ideogram-ai/ideogram-v3-balanced model
- **Text-to-Image Generation**: Create images from text prompts with advanced AI
- **Inpainting Support**: Edit existing images using masks for targeted modifications
- **Style Transfer**: Apply custom styles using reference images and 60+ artistic presets
- **Flexible Sizing Options**: Support for 15 aspect ratios and 65+ custom resolutions
- **Advanced Controls**: Seed-based reproducible generation, magic prompt optimization
- **Local Image Storage**: Automatically downloads generated images to local storage
- **Prediction Tracking**: Monitor generation status and retrieve results
- **Comprehensive Schema**: Full support for all Ideogram V3 parameters

## Installation

### Option 1: Universal npx Installation (Recommended)

No local installation required! Use npx to run the server directly:

```bash
npx -y https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git
```

### Option 2: Local Installation

1. Clone this repository:
```bash
git clone https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git
cd replicate-ideogram-v3-mcp-server
```

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

3. Build the project:
```bash
npm run build
```

## Configuration

### Environment Variables

Set your Replicate API token as an environment variable:

```bash
export REPLICATE_API_TOKEN="r8_NBY**********************************"
```

You can get your API token from [Replicate](https://replicate.com/).

### MCP Client Configuration

#### Universal npx Configuration (Recommended)

Add this server to your MCP client configuration:

```json
{
  "mcpServers": {
    "replicate-ideogram-v3": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_NBY**********************************"
      }
    }
  }
}
```

#### Local Installation Configuration

For local installations, use:

```json
{
  "mcpServers": {
    "replicate-ideogram-v3": {
      "command": "node",
      "args": ["/path/to/replicate-ideogram-v3-mcp-server/build/index.js"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_NBY**********************************"
      }
    }
  }
}
```

## Available Tools

### 1. `generate_image`

Generate images using the Ideogram V3 Balanced model with comprehensive parameter support.

**Parameters:**
- `prompt` (required): Text prompt for image generation
- `aspect_ratio` (optional): Aspect ratio (default: "1:1")
  - Options: "1:1", "1:2", "2:1", "1:3", "3:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "10:16", "16:10"
- `resolution` (optional): Specific resolution (overrides aspect_ratio, default: "None")
  - 65+ options from "512x1536" to "1536x640"
- `magic_prompt_option` (optional): Magic prompt optimization (default: "Auto")
  - Options: "Auto", "On", "Off"
- `image` (optional): Image file for inpainting (requires mask)
- `mask` (optional): Black and white mask for inpainting
- `style_type` (optional): Style aesthetic (default: "None")
  - Options: "None", "Auto", "General", "Realistic", "Design"
- `style_reference_images` (optional): Array of style reference image URLs
- `seed` (optional): Random seed for reproducible results (0-2147483647)
- `style_preset` (optional): Predefined artistic style (default: "None")
  - 60+ options including: "Art Deco", "Cubism", "Oil Painting", "Watercolor", "Pop Art", "Vintage Poster", etc.

**Example:**
```json
{
  "prompt": "A majestic mountain landscape at sunset with vibrant colors",
  "aspect_ratio": "16:9",
  "magic_prompt_option": "On",
  "style_type": "Realistic",
  "style_preset": "Golden Hour",
  "seed": 12345
}
```

### 2. `get_image_status`

Check the status of an image generation request using a prediction ID.

**Parameters:**
- `prediction_id` (required): The prediction ID to check status for

**Returns:** Status information including completion state, errors, logs, and generated image URLs when complete.

## Aspect Ratios and Resolutions

### Supported Aspect Ratios
- `1:1` - Square (default)
- `1:2`, `2:1` - Tall/wide ratios
- `1:3`, `3:1` - Ultra tall/wide ratios
- `2:3`, `3:2` - Classic photo ratios
- `3:4`, `4:3` - Standard ratios
- `4:5`, `5:4` - Social media ratios
- `9:16`, `16:9` - Widescreen ratios
- `10:16`, `16:10` - Extended ratios

### Custom Resolutions
Choose from 65+ specific resolutions ranging from 512x1536 to 1536x640 pixels. The resolution parameter overrides the aspect_ratio setting when specified.

**Popular Resolutions:**
- `1024x1024` - Square HD
- `1536x640` - Ultra-wide
- `768x1344` - Portrait
- `1344x768` - Landscape

## Magic Prompt

The Magic Prompt feature interprets and optimizes your prompts to maximize variety and quality:
- `Auto` (default) - Automatically decides when to use magic prompt
- `On` - Always applies magic prompt optimization
- `Off` - Uses your prompt exactly as written

Magic Prompt also supports prompts in different languages and can enhance simple prompts with rich details.

## Style Controls

### Style Types
Control the overall aesthetic approach:
- `None` (default) - No specific style applied
- `Auto` - Automatically selects appropriate style
- `General` - General purpose style
- `Realistic` - Photorealistic style
- `Design` - Design-focused style

### Style Presets
Choose from 60+ predefined artistic styles:

**Art Movements:**
- Art Deco, Art Brut, Bauhaus, Cubism, Pop Art

**Photography Styles:**
- Golden Hour, Long Exposure, Dramatic Cinema, Editorial

**Artistic Techniques:**
- Oil Painting, Watercolor, Woodblock Print, Halftone Print

**Design Styles:**
- Flat Art, Minimal Illustration, Blueprint, Vintage Poster

**And many more including:** 80s Illustration, Anime, Graffiti, Surreal Collage, Travel Poster, etc.

## Inpainting

Use the `image` and `mask` parameters for targeted image editing:
- `image`: The base image to edit (URL or file path)
- `mask`: Black and white image where black pixels are inpainted and white pixels are preserved

**Inpainting Example:**
```json
{
  "prompt": "A beautiful garden with flowers",
  "image": "https://example.com/base-image.jpg",
  "mask": "https://example.com/mask.jpg"
}
```

## Style Reference Images

Provide an array of image URLs in `style_reference_images` to guide the style of generated images. The model will analyze these references and apply similar aesthetic qualities to your generation.

**Style Reference Example:**
```json
{
  "prompt": "A modern cityscape",
  "style_reference_images": [
    "https://example.com/style1.jpg",
    "https://example.com/style2.jpg"
  ]
}
```

## Reproducible Generation

Use the `seed` parameter (0-2147483647) to generate reproducible results. The same prompt with the same seed will produce identical images.

**Reproducible Example:**
```json
{
  "prompt": "A red rose in a garden",
  "seed": 42,
  "aspect_ratio": "1:1"
}
```

## Output

Generated images are automatically downloaded to a local `generated_images/` directory with timestamped filenames. The response includes:

- **Image URLs**: Direct links to generated images
- **Local Paths**: Local file locations for downloaded images
- **Generation Details**: All parameters used in generation
- **Metadata**: Timestamps, filenames, and technical details

**Example Output:**
```
Successfully generated image with Ideogram V3 Balanced model.

**Prompt:** A majestic mountain landscape at sunset
**Aspect Ratio:** 16:9
**Style Preset:** Golden Hour
**Seed:** 12345

**Generated Images:**
1. https://replicate.delivery/pbxt/abc123.png

**Local Copies:**
1. /path/to/generated_images/ideogram_2024-01-15T10-30-00-000Z_1.png
```

## Error Handling

The server provides detailed error messages for:
- Missing or invalid API tokens
- Invalid parameter values
- Network connectivity issues
- API rate limits and quotas
- Generation failures and timeouts
- File download errors

## Development

### Running in Development Mode

```bash
npm run dev
```

### Testing the Server

```bash
npm test
```

### Building the Project

```bash
npm run build
```

### Getting the Installation Path

```bash
npm run get-path
```

## API Reference

This server implements the ideogram-ai/ideogram-v3-balanced API via Replicate. For detailed API documentation, visit:
- [Replicate Ideogram V3 Balanced](https://replicate.com/ideogram-ai/ideogram-v3-balanced)
- [Replicate API Documentation](https://replicate.com/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## Examples

### Basic Text-to-Image
```json
{
  "prompt": "A cute cat wearing a wizard hat"
}
```

### High-Resolution Landscape
```json
{
  "prompt": "Epic mountain vista with dramatic clouds",
  "resolution": "1536x640",
  "style_preset": "Dramatic Cinema"
}
```

### Artistic Portrait
```json
{
  "prompt": "Portrait of a wise old man",
  "aspect_ratio": "3:4",
  "style_type": "Realistic",
  "style_preset": "Oil Painting"
}
```

### Reproducible Design
```json
{
  "prompt": "Modern logo design for a tech company",
  "aspect_ratio": "1:1",
  "style_type": "Design",
  "seed": 2024,
  "magic_prompt_option": "Off"
}
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

For issues and questions:
- Open an issue on [GitHub](https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server/issues)
- Check the [Replicate documentation](https://replicate.com/docs)
- Review the [MCP specification](https://modelcontextprotocol.io/)

## Changelog

### v1.0.0
- Initial release with ideogram-ai/ideogram-v3-balanced integration
- Comprehensive parameter support with full schema implementation
- Text-to-image generation with 60+ style presets
- Inpainting support with image and mask parameters
- Style reference images for custom aesthetics
- Magic prompt optimization with multilingual support
- 15 aspect ratios and 65+ custom resolutions
- Seed-based reproducible generation
- Local image download with organized storage
- Robust error handling and status tracking