# mcp-server-openai-image-generator

An MCP (Model Context Protocol) server that exposes an OpenAI image generation tool over HTTP. It generates images from text prompts, saves them locally, and serves them via an integrated static file server.

## Stack

- **Runtime / Language:** [Bun](https://bun.com) + TypeScript
- **MCP Transport:** HTTP — standard JSON responses (`POST /mcp`)
- **Image generation:** OpenAI Images API (`gpt-image-2` by default)
- **CORS:** `Access-Control-Allow-Origin: *` on all routes

## Prerequisites

- [Bun](https://bun.com) >= 1.0
- An OpenAI API key with access to the Images API

## Installation

```bash
bun install
```

## Configuration

Edit `config.json` at the project root:

```json
{
  "port": 1980,
  "model": "gpt-image-2",
  "size": "1024x1536",
  "quality": "low",
  "imagesDir": "images"
}
```

| Field       | Description                                  | Default         |
| ----------- | -------------------------------------------- | --------------- |
| `port`      | HTTP server listening port                   | `1980`          |
| `model`     | OpenAI image model                           | `"gpt-image-2"` |
| `size`      | Generated image dimensions                   | `"1024x1536"`   |
| `quality`   | Image quality (`"low"`, `"medium"`, `"high"`) | `"low"`         |
| `imagesDir` | Directory where generated images are stored  | `"images"`      |

The `imagesDir` directory is created automatically if it does not exist.

## API Key

Provide your OpenAI key via the environment variable:

```bash
export OPENAI_API_KEY=sk-...
```

## Usage

```bash
# production
bun run start

# development (watch mode)
bun run dev
```

The server starts on the configured port (default: `http://localhost:1980`).

## MCP Tool: `generate_image`

### Request

`POST /mcp` with a JSON-RPC 2.0 body:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_image",
    "arguments": {
      "description": "A futuristic city at sunset, digital art"
    }
  }
}
```

### Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "url": "http://localhost:1980/images/1720000000000.png",
    "filename": "1720000000000.png",
    "model": "gpt-image-2",
    "size": "1024x1536",
    "prompt": "A futuristic city at sunset, digital art"
  }
}
```

Generated images are saved as `<timestamp>.png` in `imagesDir` and immediately accessible at `GET /images/:filename`.

## Project Structure

```
src/
  index.ts          # Entry point — loads config, starts server
  server.ts         # Bun HTTP server, routes requests
  mcpHandler.ts     # JSON-RPC 2.0 MCP handler
  imageGenerator.ts # OpenAI Images API integration
  staticHandler.ts  # Static file serving for generated images
  config.ts         # Config loading from config.json
  types.ts          # Shared TypeScript types
config.json         # Server configuration
images/             # Generated images (auto-created)
```

## License

Private — all rights reserved.