# openai-image-mcp

A minimal, production-ready MCP server that exposes OpenAI GPT Image generation as two well-defined tools: `generate_image` (returns the PNG inline as MCP image content) and `generate_image_to_file` (writes the PNG to disk for asset pipelines).

Part of the [mcp-accelerator](https://github.com/rammc/mcp-accelerator): it is the reference implementation of the accelerator's "local stdio server with externalized secrets" pattern for APIs that have no official hosted MCP server.

This documentation follows the structure of a TOGAF Architecture Definition Document (ADM phases A through F), so that both humans and AI agents can extract the intent, the contracts, and the constraints without reading the code first. If you are an AI agent, start with [Section 8: Agent Usage Contract](#8-agent-usage-contract).

---

## Table of Contents

1. [Architecture Vision (Phase A)](#1-architecture-vision-phase-a)
2. [Business Architecture (Phase B)](#2-business-architecture-phase-b)
3. [Application Architecture (Phase C)](#3-application-architecture-phase-c)
4. [Data Architecture (Phase C)](#4-data-architecture-phase-c)
5. [Technology Architecture (Phase D)](#5-technology-architecture-phase-d)
6. [Security Architecture (cross-cutting)](#6-security-architecture-cross-cutting)
7. [Implementation and Migration (Phases E and F)](#7-implementation-and-migration-phases-e-and-f)
8. [Agent Usage Contract](#8-agent-usage-contract)
9. [Operations and Troubleshooting](#9-operations-and-troubleshooting)

---

## 1. Architecture Vision (Phase A)

### 1.1 Problem statement

AI assistants such as Claude can reason about images but cannot create them with OpenAI models out of the box. OpenAI offers no official hosted MCP server for its image API. Teams therefore either paste generated images around manually or build one-off integrations per project.

### 1.2 Vision

Provide image generation as a first-class MCP capability: any MCP host (Claude Code, Claude Desktop) gains a `generate_image` tool that produces brand assets, mockup imagery, placeholder art, or documentation illustrations on demand, inside the conversation, with the API key kept out of every config file.

### 1.3 Stakeholders and concerns

| Stakeholder | Concern | How this architecture addresses it |
|---|---|---|
| Developer using Claude Code | Generate assets without leaving the terminal | Tools are available in-session after a one-line config entry |
| Project team | Reusable setup across projects | Config templates live in the mcp-accelerator, the server is generic |
| Security officer | API keys must not leak via dotfiles or repos | Key is resolved at process launch from the environment or the macOS Keychain, never stored in config |
| AI agent (Claude) | Needs deterministic tool contracts | Strict parameter validation, explicit error messages, contract documented in Section 8 |

### 1.4 Value proposition

- One capability, two delivery modes: inline image content for conversational use, file output for build and asset pipelines.
- Zero configuration drift: the server has no config file of its own. Behavior is fully determined by the tool parameters and one environment variable.
- Small enough to audit in five minutes: a single Python module of about 75 lines.

## 2. Business Architecture (Phase B)

### 2.1 Business capability

"Generative image supply for software delivery": producing visual assets (app icons drafts, hero images, empty-state illustrations, test fixtures, blog graphics) as part of the normal engineering workflow rather than as a separate design request.

### 2.2 Core use cases

| ID | Use case | Actor | Tool used |
|---|---|---|---|
| UC-1 | Generate an illustration during a conversation and inspect it immediately | Developer via Claude | `generate_image` |
| UC-2 | Generate an asset directly into the project tree (for example `assets/hero.png`) | Claude Code in an implementation task | `generate_image_to_file` |
| UC-3 | Batch-produce placeholder images for a UI prototype | Claude Code, iterating | `generate_image_to_file` |
| UC-4 | Create documentation or listing graphics (App Store, README) | Developer via Claude | either |

### 2.3 Value chain position

```mermaid
flowchart LR
    A[Requirement<br/>needs a visual] --> B[Prompt<br/>formulated by human or AI]
    B --> C[openai-image-mcp<br/>MCP tool call]
    C --> D[PNG asset]
    D --> E1[Inline review<br/>in conversation]
    D --> E2[Committed to repo<br/>asset pipeline]
```

## 3. Application Architecture (Phase C)

### 3.1 Component model

```mermaid
flowchart LR
    subgraph Host["MCP Host (Claude Code / Claude Desktop)"]
        LLM[Claude]
    end
    subgraph Server["openai-image-mcp (local process)"]
        FMCP[FastMCP runtime<br/>stdio transport]
        T1[Tool: generate_image]
        T2[Tool: generate_image_to_file]
        GEN[_generate_png<br/>validation + API call]
    end
    subgraph OpenAI["OpenAI Platform"]
        IMG[Images API<br/>model gpt-image-2]
    end
    FS[(Local filesystem)]
    KEY[/OPENAI_API_KEY<br/>env or Keychain/]

    LLM -- "JSON-RPC over stdio" --> FMCP
    FMCP --> T1 & T2
    T1 & T2 --> GEN
    GEN -- "HTTPS" --> IMG
    T2 -- "write PNG" --> FS
    KEY -. "read at process start" .-> Server
```

### 3.2 Tool catalog

| Tool | Purpose | Returns |
|---|---|---|
| `generate_image(prompt, size="auto")` | Generate a PNG and return it as MCP image content | `Image` (base64 PNG, rendered inline by the host) |
| `generate_image_to_file(prompt, output_path, size="auto")` | Generate a PNG and persist it to an absolute path | Confirmation string with path and byte count |

### 3.3 Interaction (runtime view)

```mermaid
sequenceDiagram
    participant C as Claude (MCP host)
    participant S as openai-image-mcp
    participant O as OpenAI Images API
    C->>S: tools/call generate_image_to_file(prompt, output_path, size)
    S->>S: validate prompt not empty, size allowed, path absolute
    S->>O: images.generate(model=gpt-image-2, output_format=png)
    O-->>S: b64_json payload
    S->>S: decode, create parent dirs, write file
    S-->>C: "Image saved: /path/file.png (N bytes)"
```

## 4. Data Architecture (Phase C)

### 4.1 Data flows and classification

| Data | Direction | Classification | Persistence |
|---|---|---|---|
| Prompt text | Host to server to OpenAI | Potentially confidential (leaves the machine) | Not persisted by the server |
| API key | Environment to server to OpenAI (HTTPS auth header) | Secret | Never written to disk by the server |
| Generated PNG | OpenAI to server to host or filesystem | Project asset | Only persisted when `generate_image_to_file` is used |

### 4.2 Data principles

- The server is stateless: no cache, no logs of prompts or images, no temp files.
- Prompts are transmitted to OpenAI. Do not include secrets, personal data, or unreleased confidential material in prompts.
- File writes happen only at the exact `output_path` the caller supplies (plus creation of missing parent directories).

## 5. Technology Architecture (Phase D)

### 5.1 Technology stack

| Layer | Choice | Rationale |
|---|---|---|
| Language / runtime | Python >= 3.11 | Team standard, first-class MCP SDK |
| MCP framework | `mcp[cli]` (FastMCP), pinned `<2` | Decorator-based tools, stdio transport built in |
| API client | official `openai` SDK | Maintained, typed |
| Package manager | `uv` | Fast, lockfile-based, reproducible |
| Transport | stdio | Launched and owned by the MCP host, no open ports, no daemon |
| Image model | `gpt-image-2`, PNG output | Current OpenAI image model; change in `main.py` if needed |

### 5.2 Deployment model

The server is not deployed anywhere. Each MCP host process spawns its own instance on demand as a child process and terminates it with the session. There is nothing to operate, monitor, or patch besides the Python dependencies.

## 6. Security Architecture (cross-cutting)

- Fail-fast startup: the process refuses to start without `OPENAI_API_KEY`, so misconfiguration is caught at registration time, not at first tool call.
- No secrets at rest: config templates reference the key via `${OPENAI_API_KEY}` or resolve it at launch from the macOS Keychain:

  ```bash
  security add-generic-password -s OPENAI_API_KEY -a "$USER" -w "sk-your-key"
  ```

- Input validation: empty prompts rejected, `size` restricted to an allowlist, `output_path` must be absolute (prevents surprises from host-dependent working directories).
- Network egress: exactly one destination, `api.openai.com` over HTTPS.
- Residual risk: `generate_image_to_file` writes wherever the caller points it. The MCP host's permission system is the guard rail for that; review file paths when approving tool calls.

## 7. Implementation and Migration (Phases E and F)

### 7.1 Installation

```bash
git clone https://github.com/rammc/openai-image-mcp.git ~/openai-image-mcp
cd ~/openai-image-mcp
uv sync
```

### 7.2 Claude Code (project scope `.mcp.json`)

```json
{
  "mcpServers": {
    "openai-image": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "${HOME}/openai-image-mcp", "run", "python", "main.py"],
      "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" }
    }
  }
}
```

Keychain variant (macOS, no shell profile changes needed):

```json
{
  "mcpServers": {
    "openai-image": {
      "type": "stdio",
      "command": "sh",
      "args": [
        "-c",
        "OPENAI_API_KEY=\"$(security find-generic-password -s OPENAI_API_KEY -w)\" exec uv --directory \"$HOME/openai-image-mcp\" run python main.py"
      ]
    }
  }
}
```

### 7.3 Claude Desktop (`claude_desktop_config.json`)

Claude Desktop does not inherit your shell environment, so use the Keychain variant above (same JSON, without the `"type"` field).

### 7.4 Verification

```bash
export OPENAI_API_KEY="sk-your-key"
uv run python main.py   # must start without error, then Ctrl+C
```

In Claude Code, run `/mcp` and confirm that `openai-image` is connected and lists two tools.

### 7.5 Migration notes

- Coming from a copy of this server with project-specific paths: only the `--directory` argument changes, the tool contract is identical.
- Model upgrades (for example a future `gpt-image-3`): single constant in `main.py`, no contract change expected.

## 8. Agent Usage Contract

This section is written for AI agents (Claude and others) so the repository is directly consumable without reading the source.

### 8.1 Tool contracts

```text
generate_image(prompt: str, size: str = "auto") -> MCP Image (PNG)
generate_image_to_file(prompt: str, output_path: str, size: str = "auto") -> str
```

Constraints, enforced server-side with descriptive errors:

- `prompt` must be non-empty after trimming. Write precise, visual prompts: subject, style, composition, color, background. The prompt is sent verbatim to OpenAI.
- `size` must be one of: `"auto"`, `"1024x1024"` (square), `"1536x1024"` (landscape), `"1024x1536"` (portrait). Any other value raises an error, including values like `"512x512"`.
- `output_path` must be an ABSOLUTE path ending in a filename (use `.png`). Missing parent directories are created automatically.

### 8.2 Decision rule: which tool

- The user wants to SEE or iterate on the image in conversation: use `generate_image`.
- The image is an artifact of the task (belongs in a repo, a build, a document): use `generate_image_to_file` with a path inside the project, then reference the file. Do not use `generate_image` and re-save the payload manually.

### 8.3 Behavioral notes for agents

- Calls are synchronous and take several seconds up to about a minute. Do not retry immediately on slowness.
- Each call costs real OpenAI credits. Batch thoughtfully, do not regenerate an acceptable image just to confirm.
- Validation errors (for example "The prompt must not be empty.") mean the argument was wrong, not that the service failed. Fix the argument and retry once.
- For transparent backgrounds or specific aspect ratios beyond the three sizes, state it in the prompt; the API decides best-effort.

### 8.4 Example calls

```text
generate_image(
  prompt="Flat vector illustration of a mountain trail at sunrise, warm orange and teal palette, minimal, no text",
  size="1536x1024"
)

generate_image_to_file(
  prompt="App icon draft: stylized letter M, deep red gradient background, modern, centered, no text besides the letter",
  output_path="/Users/me/project/assets/icon-draft.png",
  size="1024x1024"
)
```

## 9. Operations and Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Server fails to start: "OPENAI_API_KEY is missing" | Key not in the launch environment | Export the variable or use the Keychain launch command |
| Tool error: "size must be one of ..." | Unsupported size value | Use one of the four allowed values |
| Tool error: "output_path must be an absolute path." | Relative path passed | Pass an absolute path |
| `401` from OpenAI | Invalid or revoked key | Rotate the key, update Keychain entry |
| Server not listed in `/mcp` | Wrong `--directory` path or `uv` not installed | Verify the path and `uv --version`, then restart the session |

## License and status

MIT License, see [LICENSE](LICENSE). Version 0.1.0. Issues and extension requests: open a GitHub issue in this repo.