ai-image-generate/README.md

MCP Server for image generation using Replicate's flux-schnell model

# AI Image Generate

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server implementation for generating images using Replicate's models.

This tool can be executed as a command-line application `ai-image-generate`.

## Features

- Generate images from text prompts
- Configurable image parameters (resolution, aspect ratio, quality)
- Save generated images to specified directory
- Full MCP protocol compliance
- Error handling and validation
- Caching of generated images
- Retry mechanism for image downloads
- Concurrent image downloads
- Atomic file writes

## Prerequisites

- Node.js 16+
- Replicate API token

## Setup

1. Clone the repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the project:
   ```bash
   npm run build
   ```
4. Install the package globally to use the CLI command:
   ```bash
   npm install -g .
   ```

## Usage

After installation, you can use the `ai-image-generate` command. The server listens for MCP requests on standard I/O.

### Environment Variables

- `REPLICATE_API_TOKEN` (required): Your API token from Replicate.
- `REPLICATE_MODEL` (optional): The Replicate model to use. Defaults to `black-forest-labs/flux-schnell`.

### Running the server

To run the server, execute the command in your terminal. You must provide the `REPLICATE_API_TOKEN`.

```bash
export REPLICATE_API_TOKEN="your-replicate-api-token-here"
export REPLICATE_MODEL="black-forest-labs/flux-schnell" # optional
ai-image-generate
```

To use with a client like Cursor:
1. Go to Settings -> Features -> MCP Servers.
2. Click "Add new MCP Server".
3. Set Type to "Command".
4. Set Command to: `ai-image-generate`
5. Set Environment Variables for `REPLICATE_API_TOKEN` and optionally `REPLICATE_MODEL`.

## API Parameters

| Parameter           | Type    | Required | Default | Description                                     |
|--------------------|---------|----------|---------|------------------------------------------------|
| `prompt`           | string  | Yes      | -       | Text prompt for image generation               |
| `output_dir`       | string  | Yes      | -       | Server directory path to save generated images |
| `filename`         | string  | No       | -       | Base name for the output file(s)               |
| `go_fast`          | boolean | No       | false   | Enable faster generation mode                  |
| `megapixels`       | string  | No       | "1"     | Resolution quality ("1", "2", "4")            |
| `num_outputs`      | number  | No       | 1       | Number of images to generate (1-4)            |
| `aspect_ratio`     | string  | No       | "1:1"   | Aspect ratio ("1:1", "4:3", "16:9")          |
| `output_format`    | string  | No       | "webp"  | Image format ("webp", "png", "jpeg")         |
| `output_quality`   | number  | No       | 80      | Compression quality (1-100)                   |
| `num_inference_steps`| number| No       | 4       | Number of denoising steps (4-20)             |

## Example Request

```json
{
  "prompt": "black forest gateau cake spelling out 'FLUX SCHNELL'",
  "output_dir": "/var/output/images",
  "filename": "black_forest_cake",
  "output_format": "webp",
  "go_fast": true,
  "megapixels": "1",
  "num_outputs": 2,
  "aspect_ratio": "1:1"
}
```

## Example Response

```json
{
  "image_paths": [
    "/var/output/images/black_forest_cake_1.webp",
    "/var/output/images/black_forest_cake_2.webp"
  ],
  "metadata": {
    "model": "black-forest-labs/flux-schnell",
    "inference_time_ms": 2847,
    "cache_hit": false
  }
}
```

## Error Handling

The server handles the following error types:

- Validation errors (invalid parameters)
- API errors (Replicate API issues)
- Server errors (filesystem, permissions)
- Unknown errors (unexpected issues)

Each error response includes:
- Error code
- Human-readable message
- Detailed error information

## License

ISC