# cf-image-gen MCP Server

Generate images and video from text prompts using **Cloudflare Workers AI** (Stable Diffusion) or **Google Gemini models** via Cloudflare AI Gateway.

## Architecture

```
Text Prompt → cf-image-gen MCP Server → Cloudflare AI Gateway
                                           ├── Workers AI (Stable Diffusion XL)
                                           ├── Gemini Image Models (generateContent)
                                           └── Gemini Text Models (Interactions API)
```

## Models

### Workers AI (Direct)
| Model | ID | Output |
|-------|-----|--------|
| Stable Diffusion XL | `@cf/stabilityai/stable-diffusion-xl-base-1.0` | 1024×1024 PNG |

### Google Gemini (via AI Gateway)
Use `google-ai-studio/{modelName}` format.

#### Image Models (generateContent)
| Model | Format | Notes |
|-------|--------|-------|
| `gemini-3.1-flash-image` | image/jpeg | No text, 1120 image tokens |
| `gemini-3-pro-image` | image/jpeg | +157 reasoning tokens |
| `gemini-2.5-flash-image` | image/png | Returns text + image |

#### Text Models (Interactions API)
| Model | Notes |
|-------|-------|
| `gemini-3.5-flash` | Latest text model |

## Prerequisites

- Node.js 18+
- Cloudflare account with:
  - Account ID
  - API Token (Workers AI)
  - AI Gateway ID
  - AI Gateway Auth Token (for Gemini models)
- Google AI Studio API key (for Gemini models)

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CLOUDFLARE_ACCOUNT_ID` | ✅ | Cloudflare Account ID |
| `CLOUDFLARE_API_TOKEN` | ✅ | Cloudflare API Token |
| `CLOUDFLARE_GATEWAY_ID` | For Gemini | AI Gateway ID |
| `GOOGLE_AI_STUDIO_API_KEY` | For Gemini | Google AI Studio API Key |
| `CF_AIG_TOKEN` | For Gemini | AI Gateway Auth Token |
| `CF_IMAGE_OUTPUT_DIR` | ❌ | Output directory (default: `.opencode/mcp/cf-image-gen/output`) |

## Usage

### Via MCP Tool

```json
{
  "prompt": "a samurai warrior standing on a mountain at sunset, pixel art style, 8-bit game aesthetic",
  "model": "google-ai-studio/gemini-3.1-flash-image"
}
```

Or with Stable Diffusion (default):

```json
{
  "prompt": "a red apple on white background"
}
```

### Example Output

**Gemini 3.1 Flash Image** — `google-ai-studio/gemini-3.1-flash-image`
> Prompt: *"a samurai warrior standing on a mountain at sunset, pixel art style, 8-bit game aesthetic"*

![Samurai Example](docs/samurai-example.jpg)

## How It Works

1. **Workers AI path**: Direct call to `POST /accounts/{id}/ai/run/{model}` with Cloudflare API Token
2. **AI Gateway path**: Routes through `gateway.ai.cloudflare.com/v1/{account}/{gateway}/`
   - Image-capable models → `v1beta/models/{model}:generateContent` with `generationConfig.responseModalities: ["IMAGE"]`
   - Text-only models (gemini-3-flash*) → `v1beta/interactions` with plain string input

## Development

```bash
# Install dependencies
cd .opencode/mcp/cf-image-gen
npm install

# Run standalone (stdio)

# Configure in opencode.jsonc as MCP server
```

## License

MIT