# AI Image Generation MCP

An AI image generation MCP tool powered by the Nano Banana Pro API. It creates high-quality images from text prompts.

## Features

- Intelligent image generation from text prompts
- GPT Image-2 text-to-image task creation
- Optional platform-side content filtering control
- Optional callback URL for completed tasks
- Async task polling through `query-task`
- Cloud generation with image URLs returned by the API

## Installation

```bash
npm install
npm run build
```

## Configuration

Set the `KIE_API_KEY` environment variable:

```bash
export KIE_API_KEY=your_api_key_here
```

Get an API key at [https://kie.ai/api-key](https://kie.ai/api-key).

You can optionally set `KIE_MODEL` to override the default model:

```bash
export KIE_MODEL=gpt-image-2-text-to-image
```

## Usage

### Tool 1: generate-image

Creates an image generation task. If the image completes within 2 seconds, the tool returns the image URL directly. Otherwise, it returns a task ID for async polling.

**Parameters:**

- `prompt` (required): Image generation prompt. Describe the desired image in detail, up to 20,000 characters.
- `nsfw_checker` (optional): Whether to disable platform-side content filtering. Defaults to `false`.
- `callBackUrl` (optional): Callback URL invoked after the task completes.

**Example:**

```json
{
  "prompt": "A cute orange cat sitting on a windowsill, looking out at a snowy landscape",
  "nsfw_checker": false
}
```

**Example with callback URL:**

```json
{
  "prompt": "A watercolor-style mountain cabin at sunrise, soft light, detailed brush texture",
  "nsfw_checker": false,
  "callBackUrl": "https://example.com/callback"
}
```

**Synchronous success response:**

```json
{
  "status": "success",
  "message": "Image generation completed.",
  "prompt": "A cute orange cat sitting on a windowsill, looking out at a snowy landscape",
  "nsfw_checker": false,
  "imageUrl": "https://static.aiquickdraw.com/tools/example/image.png"
}
```

**Async response:**

```json
{
  "status": "async",
  "message": "Image generation is taking longer than expected and has switched to async mode.",
  "taskId": "281e5b0*********************f39b9",
  "prompt": "A cute orange cat sitting on a windowsill, looking out at a snowy landscape",
  "nsfw_checker": false,
  "tip": "Use the query-task tool to check task progress and results."
}
```

### Tool 2: query-task

Queries the status and progress of an image generation task.

**Parameters:**

- `taskId` (required): Task ID returned by `generate-image`.

**Example:**

```json
{
  "taskId": "281e5b0*********************f39b9"
}
```

**Response format:**

```json
{
  "taskId": "281e5b0*********************f39b9",
  "state": "success",
  "model": "gpt-image-2-text-to-image",
  "elapsedSeconds": 45,
  "imageUrl": "https://static.aiquickdraw.com/tools/example/1763662100739_DlBXJvdR.png",
  "failCode": null,
  "failMsg": null,
  "createdAt": "2026-01-22T03:00:00.000Z",
  "completedAt": "2026-01-22T03:00:45.000Z"
}
```

**State values:**

- `waiting`: The task is queued or still processing.
- `success`: The task completed successfully. Retrieve the image from `imageUrl`.
- `fail`: The task failed. Check `failMsg` for details.

## Prompt Tips

For better results:

1. Describe the subject, environment, lighting, colors, and other details.
2. Specify the desired artistic style or visual reference.
3. Describe composition details such as camera angle, depth of field, and focal point.
4. Include the mood or atmosphere you want the image to convey.

**Good prompt examples:**

- "A girl in a red dress dancing under cherry blossom trees, soft sunlight filtering through the petals, dreamy pink tones, cinematic composition"
- "A cyberpunk Tokyo street after rain, neon signs glowing, wet pavement reflecting colorful light, wide-angle lens"
- "An oil painting of a mountain cabin in autumn, golden leaves, warm fireplace light through the window, peaceful atmosphere"

## API Notes

This tool uses the Nano Banana Pro API. See [https://kie.ai/api-key](https://kie.ai/api-key) for details.

## Development

```bash
# Development mode
npm run dev

# Build
npm run build

# Clean
npm run clean
```

## License

MIT