# Leonardo MCP

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
Leonardo.ai image generation as MCP tools over Streamable HTTP.

## Features

- `generate_image` — submit an image generation job to Leonardo.ai (v2 API).
- `get_generation_status` — poll a job and retrieve generated image URLs.
- Stateful Streamable HTTP transport with per-session management.
- Supports GPT Image models (quality) and Phoenix models (mode).

## Requirements

- Node.js 20+
- A Leonardo.ai API key

## Setup

```bash
npm install
```

Set the required environment variables:

```bash
export LEONARDO_API_KEY="your-api-key"
export PORT=3001   # optional, defaults to 3001
```

## Build & Run

```bash
npm run build
npm start
```

Or use the helper script (expects `LEONARDO_API_KEY` to already be exported):

```bash
./run.sh
```

The server listens on `http://0.0.0.0:3001/mcp` by default.

## MCP Client Configuration

Point your MCP client at the HTTP endpoint. Example:

```json
{
  "mcpServers": {
    "leonardo": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
```

## Tools

### `generate_image`

| Parameter        | Type     | Default                     | Description                                         |
| ---------------- | -------- | --------------------------- | --------------------------------------------------- |
| `prompt`         | string   | —                           | Detailed description of the image (required).       |
| `negative_prompt`| string   | —                           | Elements to avoid.                                  |
| `model`          | string   | `openai/gpt-image-2.5-flare`| Leonardo model ID.                                  |
| `quality`        | string   | `LOW`                       | For GPT Image models: LOW, MEDIUM, HIGH, EXTRA_HIGH, MAX. |
| `mode`           | string   | `FAST`                      | For Phoenix models: FAST, QUALITY, ULTRA.           |
| `width`          | number   | `1024`                      | Width in pixels (multiple of 8).                    |
| `height`         | number   | `1024`                      | Height in pixels (multiple of 8).                   |
| `quantity`       | number   | `1`                         | Number of images (1–8).                             |
| `style_ids`      | string[] | —                           | Optional Leonardo style UUIDs.                      |

Returns a `generation_id` to poll with `get_generation_status`.

### `get_generation_status`

| Parameter       | Type   | Description                          |
| --------------- | ------ | ------------------------------------ |
| `generation_id` | string | ID returned by `generate_image`.     |

Returns the job status and, when complete, the generated image URLs.

## Project Structure

```
src/index.ts          Main Streamable HTTP MCP server
sources/index_stdio.js Reference stdio-based implementation (v1 API)
dist/                 Compiled JavaScript output
```

## License

MIT — see [LICENSE](LICENSE).