# Replicate Recraft V3 MCP Server

A Model Context Protocol (MCP) server that provides access to the recraft-ai/recraft-v3 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 recraft-ai/recraft-v3 model
- **Multiple Generation Methods**: Support for synchronous and asynchronous generation with prediction tracking
- **Flexible Sizing Options**: Support for various sizes and aspect ratios
- **Advanced Style Control**: Multiple style options including realistic images and digital illustrations
- **Local Image Download**: Automatically downloads generated images to local storage in WebP format
- **Prediction Management**: Create, track, and cancel predictions
- **Webhook Support**: Optional webhook notifications for completed requests

## 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-recraft-v3-mcp-server.git
```

### Option 2: Local Installation

1. Clone this repository:
```bash
git clone https://github.com/PierrunoYT/replicate-recraft-v3-mcp-server.git
cd replicate-recraft-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-recraft-v3": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/replicate-recraft-v3-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_NBY**********************************"
      }
    }
  }
}
```

#### Local Installation Configuration

For local installations, use:

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

## Available Tools

### 1. `recraft_v3_generate`

Generate images using the standard synchronous method.

**Parameters:**
- `prompt` (required): Text prompt for image generation
- `size` (optional): Size of the generated image (default: "1024x1024")
  - Options: "1024x1024", "1365x1024", "1024x1365", "1536x1024", "1024x1536", "1820x1024", "1024x1820", "1024x2048", "2048x1024", "1434x1024", "1024x1434", "1024x1280", "1280x1024", "1024x1707", "1707x1024"
- `aspect_ratio` (optional): Aspect ratio of the generated image (default: "Not set")
  - Options: "Not set", "1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "1:2", "2:1", "7:5", "5:7", "4:5", "5:4", "3:5", "5:3"
- `style` (optional): Style of the generated image (default: "any")
  - Options: "any", "realistic_image", "digital_illustration", "digital_illustration/pixel_art", "digital_illustration/hand_drawn", "digital_illustration/grain", "digital_illustration/infantile_sketch", "digital_illustration/2d_art_poster", "digital_illustration/handmade_3d", "digital_illustration/hand_drawn_outline", "digital_illustration/engraving_color", "digital_illustration/2d_art_poster_2", "realistic_image/b_and_w", "realistic_image/hard_flash", "realistic_image/hdr", "realistic_image/natural_light", "realistic_image/studio_portrait", "realistic_image/enterprise", "realistic_image/motion_blur"

**Example:**
```json
{
  "prompt": "a wildlife photography photo of a red panda using a laptop in a snowy forest",
  "size": "1365x1024",
  "style": "realistic_image/natural_light"
}
```

### 2. `recraft_v3_generate_async`

Generate images using asynchronous method with prediction tracking.

**Parameters:** Same as `recraft_v3_generate` plus:
- `webhook` (optional): URL for webhook notifications
- `webhook_events_filter` (optional): Events to send to webhook (default: ["completed"])

**Returns:** A prediction ID for tracking the job

### 3. `recraft_v3_get_prediction`

Get the status and results of a prediction created with `recraft_v3_generate_async`.

**Parameters:**
- `prediction_id` (required): The prediction ID from async generation

### 4. `recraft_v3_cancel_prediction`

Cancel a running prediction to prevent unnecessary work and reduce costs.

**Parameters:**
- `prediction_id` (required): The prediction ID to cancel

## Sizes and Aspect Ratios

### Supported Sizes
- `1024x1024` - Square (default)
- `1365x1024`, `1024x1365` - Landscape/Portrait
- `1536x1024`, `1024x1536` - Wide landscape/Portrait
- `1820x1024`, `1024x1820` - Ultra-wide landscape/Portrait
- `1024x2048`, `2048x1024` - Extra tall/wide
- `1434x1024`, `1024x1434` - Custom ratio
- `1024x1280`, `1280x1024` - 4:5 ratio
- `1024x1707`, `1707x1024` - Golden ratio

### Supported Aspect Ratios
- `1:1` - Square
- `4:3`, `3:4` - Standard ratios
- `3:2`, `2:3` - Classic photo ratios
- `16:9`, `9:16` - Widescreen ratios
- `1:2`, `2:1` - Tall/wide ratios
- `7:5`, `5:7` - Custom ratios
- `4:5`, `5:4` - Social media ratios
- `3:5`, `5:3` - Extended ratios

## Style Options

### Realistic Images
- `realistic_image` - General realistic style
- `realistic_image/b_and_w` - Black and white photography
- `realistic_image/hard_flash` - Hard flash photography
- `realistic_image/hdr` - HDR photography
- `realistic_image/natural_light` - Natural lighting
- `realistic_image/studio_portrait` - Studio portrait style
- `realistic_image/enterprise` - Professional/corporate style
- `realistic_image/motion_blur` - Motion blur effects

### Digital Illustrations
- `digital_illustration` - General digital art
- `digital_illustration/pixel_art` - Pixel art style
- `digital_illustration/hand_drawn` - Hand-drawn appearance
- `digital_illustration/grain` - Textured/grainy style
- `digital_illustration/infantile_sketch` - Childlike sketch style
- `digital_illustration/2d_art_poster` - 2D poster art
- `digital_illustration/handmade_3d` - 3D handmade style
- `digital_illustration/hand_drawn_outline` - Outlined hand-drawn style
- `digital_illustration/engraving_color` - Colored engraving style
- `digital_illustration/2d_art_poster_2` - Alternative 2D poster style

## Output

Generated images are automatically downloaded to a local `images/` directory with descriptive filenames in WebP format. The response includes:

- Local file paths
- Original URLs
- Image filenames
- Generation parameters used
- Prediction IDs for tracking

## Error Handling

The server provides detailed error messages for:
- Missing API tokens
- Invalid parameters
- Network issues
- API rate limits
- Generation failures

## Development

### Running in Development Mode

```bash
npm run dev
```

### Testing the Server

```bash
npm test
```

### Getting the Installation Path

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

## API Reference

This server implements the recraft-ai/recraft-v3 API via Replicate. For detailed API documentation, visit:
- [Replicate Recraft V3](https://replicate.com/recraft-ai/recraft-v3)
- [Replicate API Documentation](https://replicate.com/docs)

## 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-recraft-v3-mcp-server/issues)
- Check the [Replicate documentation](https://replicate.com/docs)

## Changelog

### v1.0.0
- Initial release with recraft-ai/recraft-v3 integration
- Support for synchronous and asynchronous generation
- Prediction tracking and management
- Multiple size and aspect ratio options
- Comprehensive style control options
- Local image download functionality in WebP format
- Comprehensive error handling