codex-imagegen-mcp 0.1.2

package/docs/DEVELOPMENT.md

@@ -0,0 +1,171 @@
+<p align="center">
+  <img src="assets/banner-development.jpg" width="100%" alt="Development — a travel-poster illustration of a surveyor's camp: a brass theodolite on a tripod aimed at a distant peak, a canvas tent and a work table with a toolbox">
+</p>
+
+# Development
+
+Build it, test it without touching OpenAI, test it live, and ship it.
+
+**On this page:** [Setup](#setup) · [Layout](#layout) · [Tests](#tests) · [Continuous integration](#continuous-integration) · [Live testing](#live-testing) · [Conventions](#conventions) · [Artwork](#artwork) · [Updating from upstream Codex](#updating-from-upstream-codex) · [Releasing](#releasing)
+
+## Setup
+
+You need Node.js 22 or newer.
+
+```bash
+git clone https://github.com/ShalomObongo/codex-imagegen-mcp.git && cd codex-imagegen-mcp
+npm ci
+npm run build        # tsc → dist/, marks dist/src/cli.js executable (works on Windows too)
+npm test             # build + the node:test suite
+npm run typecheck
+npm link             # optional: expose `codex-imagegen-mcp` globally for manual testing
+```
+
+Contribution guidelines, commit style and the pull-request checklist are in [CONTRIBUTING.md](../.github/CONTRIBUTING.md).
+
+## Layout
+
+```text
+src/             TypeScript sources (see ARCHITECTURE.md)
+test/            node:test suites; test/helpers/mock-openai.ts mocks auth.openai.com + the ChatGPT backend
+skill/imagegen/  the Agent Skill shipped with the server
+upstream/        byte-exact copy of the Codex skill it was adapted from
+scripts/         compose-doc-art.py builds docs/assets from raw generations
+docs/            this documentation; docs/assets holds the artwork
+```
+
+## Tests
+
+The suite never talks to OpenAI. Every test runs against a scriptable mock and an isolated temp home:
+
+```mermaid
+flowchart LR
+    tests["node:test suites"]:::ink
+    subgraph sandbox ["isolated temp home (test/helpers/env.ts)"]
+        server["codex-imagegen-mcp<br/>(in-process or over stdio)"]:::rust
+        files[("auth.json · history · images")]:::cream
+    end
+    subgraph mock ["test/helpers/mock-openai.ts"]
+        oauth["OAuth: PKCE-checked code exchange<br/>rotating single-use refresh tokens · revoke · device code"]:::teal
+        api["backend: images/generations · images/edits · wham/usage<br/>scripted 401 · 429 · 5xx · policy · Cloudflare"]:::teal
+    end
+    tests --> server
+    server --> files
+    server -- "CODEX_IMAGEGEN_AUTH_ISSUER" --> oauth
+    server -- "CODEX_IMAGEGEN_BASE_URL" --> api
+    classDef ink fill:#2A2523,stroke:#9A8C76,color:#E4D9C6
+    classDef rust fill:#A6553B,stroke:#7E3F2B,color:#FFFFFF
+    classDef teal fill:#4E6E63,stroke:#3A544B,color:#FFFFFF
+    classDef cream fill:#E4D9C6,stroke:#A89A80,color:#2A2523
+    style sandbox fill:#D9A05B1F,stroke:#B5813F,color:#B5813F
+    style mock fill:#D9A05B1F,stroke:#B5813F,color:#B5813F
+```
+
+- **The mock behaves like the real service where it matters.** It checks the PKCE `code_verifier` against the challenge and the `redirect_uri`, and its refresh tokens are **single-use**: a second use returns `refresh_token_reused`, just as OpenAI does.
+- **Scripting failures:** queue responses in `state.imageQueue` to simulate 401, 429, 5xx, policy and Cloudflare errors, and set delays to exercise timeouts and locking.
+- **Nothing real is touched.** `test/helpers/env.ts` builds an isolated `CODEX_IMAGEGEN_*` environment in a temp directory, so tests never read or write your credentials. The installer tests also point `HOME` and `XDG_CONFIG_HOME` at temp directories.
+
+| Suite | Covers |
+|---|---|
+| `auth-primitives` | JWT claims, PKCE, authorize URL, the 0600 store, the cross-process lock, stale locks |
+| `auth-manager` | Refresh (three concurrent processes → one refresh), permanent vs transient failures, borrowed sources, 401 recovery, revoke |
+| `login-flows` | Browser round trip, state mismatch, authorize errors, failed exchange, cancel, timeout, device code |
+| `images-client` | Exact request body and headers, edits, retries, usage limits, policy/invalid/Cloudflare mapping, the usage API |
+| `image-processing` | Codec, previews, chroma key, output planning, no-overwrite writes, input validation |
+| `install` | JSONC-preserving opencode edits, backups, idempotency, conflict protection, uninstall, snippets |
+| `server` | Full MCP over stdio: tools, resources, prompts, progress, errors, sign-in via the tool and then generation |
+| `cli` | Every command end to end against the mock |
+
+## Continuous integration
+
+Every push to `main` and every pull request runs [CI](../.github/workflows/ci.yml):
+
+| Job | What it checks |
+|---|---|
+| **Node 22 · 24 · 26** on Linux | `npm ci`, `npm run typecheck`, `npm test`, a CLI smoke test |
+| **Node 24** on macOS and Windows | The same, on the other two platforms |
+| **Package and install** | `npm pack`, a global install of the tarball, and that the installed CLI runs and ships its skill |
+
+Actions are pinned to commit SHAs, and [Dependabot](../.github/dependabot.yml) keeps them and the npm dependencies current. CodeQL code scanning runs on GitHub's default setup.
+
+## Live testing
+
+> [!CAUTION]
+> These commands use your real ChatGPT quota. `status`, `doctor` and `auth_status` are free; every generated image counts.
+
+```bash
+node dist/src/cli.js status                        # auth + usage, no quota
+node dist/src/cli.js generate "a red apple" -o tmp/live/apple.png
+node dist/src/cli.js install opencode && opencode mcp list
+opencode run -m openai/gpt-5.5 "make a transparent sticker of a cactus, save to assets/cactus.png"
+opencode run -m github-copilot/claude-sonnet-5 "…"  # Copilot providers take a different media path in opencode
+```
+
+`tmp/` is git-ignored. To see what the server did inside a client, set `CODEX_IMAGEGEN_LOG_LEVEL=debug` and read `~/.local/share/codex-imagegen-mcp/server.log`.
+
+## Conventions
+
+- **stdout is the protocol.** Never write to it from server code paths.
+- **Errors carry the next step.** Raise `ImagegenError(kind, message)`; each kind maps to that step in `describeError`.
+- **Limits live in descriptions too.** Some clients strip schema constraints before the model sees them.
+- **Claims about the backend must be measured.** Record them in [Backend](BACKEND.md) with the date.
+- **The skill tracks upstream.** Diff changes against `upstream/codex-imagegen-skill/` and keep the prompting guidance aligned.
+
+## Artwork
+
+Every image in the docs was generated with this server, following the art-direction record in [docs/assets](assets/README.md). The raw generations stay out of git (about 2 MB each). `scripts/compose-doc-art.py` turns them into the committed assets:
+
+```bash
+# 1. regenerate any source with the prompts in docs/assets/README.md, saving into tmp/art/
+# 2. rebuild every committed asset (Pillow + numpy; Superclarendon ships with macOS)
+python3 scripts/compose-doc-art.py --art tmp/art --out docs/assets
+```
+
+The script does five things:
+- **Snaps alpha.** The service returns 251–254 inside opaque areas; this rounds it to 255.
+- **Typesets wording locally.** Poster titles are set in Superclarendon, so no text is ever generated.
+- **Slices the badge grid** into six PNGs.
+- **Builds the showcase sheets.**
+- **Writes the social preview.**
+
+Paper grain is seeded, so reruns are byte-stable.
+
+## Updating from upstream Codex
+
+1. **Extract the current skill:** `CODEX_HOME=$(mktemp -d) /Applications/ChatGPT.app/Contents/Resources/codex debug prompt-input hi >/dev/null`. This installs the embedded system skills into `$CODEX_HOME/skills/.system/`.
+2. **Diff and port.** Compare that `imagegen/` with `upstream/codex-imagegen-skill/`, update the copy, and port the relevant guidance into `skill/imagegen/`.
+3. **Check the tool.** Look at `codex-rs/ext/image-generation/src/tool.rs` upstream for changes to the request body, model id or limits.
+
+## Releasing
+
+Releases are automated. A maintainer only has to:
+
+1. Make sure `main` is green in CI, and run the live smoke test: `status`, one `generate`, one edit with `-b transparent`, `doctor`, plus one `opencode run`.
+2. Bump `version` in `package.json` (then `npm install --package-lock-only`) and add a `## [X.Y.Z] - YYYY-MM-DD` entry to `CHANGELOG.md`, with its compare link at the bottom.
+3. Commit, then tag and push: `git tag -a vX.Y.Z -m "…" && git push origin main vX.Y.Z`.
+
+The [release workflow](../.github/workflows/release.yml) then:
+
+```mermaid
+flowchart LR
+    tag(["push tag vX.Y.Z"]):::ink --> test["npm ci · npm test"]:::teal
+    test --> check{"tag = package.json<br/>version?"}:::cream
+    check -- "no" --> fail(["fail the release"]):::ochre
+    check -- "yes" --> pack["npm pack<br/>+ stable-named copy<br/>+ SHA256SUMS"]:::rust
+    pack --> notes["notes from<br/>CHANGELOG.md"]:::rust
+    notes --> attest["sign build-provenance<br/>attestation"]:::teal
+    attest --> release(["GitHub release<br/>+ announcement discussion"]):::ink
+    classDef ink fill:#2A2523,stroke:#9A8C76,color:#E4D9C6
+    classDef rust fill:#A6553B,stroke:#7E3F2B,color:#FFFFFF
+    classDef ochre fill:#D9A05B,stroke:#B5813F,color:#2A2523
+    classDef teal fill:#4E6E63,stroke:#3A544B,color:#FFFFFF
+    classDef cream fill:#E4D9C6,stroke:#A89A80,color:#2A2523
+```
+
+Each release carries `codex-imagegen-mcp-X.Y.Z.tgz`, the same file as `codex-imagegen-mcp.tgz` (so `releases/latest/download/codex-imagegen-mcp.tgz` always points at the newest build), and `SHA256SUMS`. Anyone can verify a download with `gh attestation verify codex-imagegen-mcp-X.Y.Z.tgz --repo ShalomObongo/codex-imagegen-mcp`.
+
+The package itself contains `dist/src`, `skill`, `docs/*.md`, `README.md`, `CHANGELOG.md`, `LICENSE` and `NOTICE`; the artwork is excluded to keep it small. `npm pack --dry-run` shows the list.
+
+---
+
+<p align="center"><a href="ARCHITECTURE.md">← Architecture</a> &nbsp;·&nbsp; <a href="README.md">Docs home</a> &nbsp;·&nbsp; <a href="../README.md">README</a></p>

package/docs/README.md

@@ -0,0 +1,84 @@
+<p align="center">
+  <img src="assets/banner-docs.jpg" width="100%" alt="Documentation — a travel-poster illustration of a wooden signpost with blank arrow boards at a desert crossroads, roads fanning out toward a sun rising behind a peak">
+</p>
+
+# Documentation
+
+codex-imagegen-mcp puts the image generation of OpenAI Codex into any MCP client, running on your ChatGPT plan. These pages cover how to use it, how it signs in, where it plugs in, and how it works.
+
+<table>
+  <tr>
+    <td width="33%" valign="top">
+      <a href="TOOLS.md"><img src="assets/thumbs/banner-tools.jpg" alt="Tools"></a><br>
+      <b>1 · <a href="TOOLS.md">Tools</a></b><br>
+      <sub>Parameters, results, resources, prompts, errors, progress and timeouts.</sub>
+    </td>
+    <td width="33%" valign="top">
+      <a href="AUTH.md"><img src="assets/thumbs/banner-auth.jpg" alt="Authentication"></a><br>
+      <b>2 · <a href="AUTH.md">Authentication</a></b><br>
+      <sub>Browser and device-code sign-in, token storage and rotation, borrowing, security.</sub>
+    </td>
+    <td width="33%" valign="top">
+      <a href="CLIENTS.md"><img src="assets/thumbs/banner-clients.jpg" alt="Clients"></a><br>
+      <b>3 · <a href="CLIENTS.md">Clients</a></b><br>
+      <sub>opencode (automated), Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI, Codex.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td width="33%" valign="top">
+      <a href="BACKEND.md"><img src="assets/thumbs/banner-backend.jpg" alt="Backend"></a><br>
+      <b>4 · <a href="BACKEND.md">Backend</a></b><br>
+      <sub>The Codex skill and built-in tool, the HTTP API, and what the service really honors.</sub>
+    </td>
+    <td width="33%" valign="top">
+      <a href="ARCHITECTURE.md"><img src="assets/thumbs/banner-architecture.jpg" alt="Architecture"></a><br>
+      <b>5 · <a href="ARCHITECTURE.md">Architecture</a></b><br>
+      <sub>Module map, request flow, and the reasoning behind each design decision.</sub>
+    </td>
+    <td width="33%" valign="top">
+      <a href="DEVELOPMENT.md"><img src="assets/thumbs/banner-development.jpg" alt="Development"></a><br>
+      <b>6 · <a href="DEVELOPMENT.md">Development</a></b><br>
+      <sub>Build, the mock-backed test suite, live testing, artwork, releases.</sub>
+    </td>
+  </tr>
+</table>
+
+## Where to start
+
+| If you want to… | Read |
+|---|---|
+| Install it and make a first image | The [README quick start](../README.md#quick-start), then [Tools](TOOLS.md) |
+| Know how it signs in, and whether that's safe | [Authentication](AUTH.md) |
+| Use it outside opencode | [Clients](CLIENTS.md) |
+| Understand what Codex does under the hood | [Backend](BACKEND.md) |
+| Change the code | [Architecture](ARCHITECTURE.md), then [Development](DEVELOPMENT.md) |
+
+## At a glance
+
+```mermaid
+flowchart LR
+    agent["Your coding agent<br/>opencode · Claude Code · Cursor · VS Code"]:::ink
+    server["codex-imagegen-mcp<br/>local stdio MCP server"]:::rust
+    skill["imagegen skill<br/>how to prompt, where to save"]:::ochre
+    oauth["auth.openai.com<br/>ChatGPT sign-in"]:::teal
+    backend["chatgpt.com/backend-api/codex<br/>/images/generations · /images/edits"]:::teal
+    files[("your workspace<br/>assets/hero.png")]:::cream
+    skill -. guides .-> agent
+    agent -- "tools/call" --> server
+    server -- "OAuth · refresh" --> oauth
+    server -- "Bearer token" --> backend
+    server -- "PNG, never overwritten" --> files
+    classDef ink fill:#2A2523,stroke:#9A8C76,color:#E4D9C6
+    classDef rust fill:#A6553B,stroke:#7E3F2B,color:#FFFFFF
+    classDef ochre fill:#D9A05B,stroke:#B5813F,color:#2A2523
+    classDef teal fill:#4E6E63,stroke:#3A544B,color:#FFFFFF
+    classDef cream fill:#E4D9C6,stroke:#A89A80,color:#2A2523
+```
+
+## About the artwork
+
+Every picture in these docs was generated **with codex-imagegen-mcp itself**, using the `imagegen` skill it ships: the poster banners, the badges, the logo and the examples. The series follows one art direction, a 1930s WPA silkscreen travel poster in five flat inks. [The prompts, the direction record and how to rebuild the assets →](assets/README.md)
+
+---
+
+<p align="center"><a href="../README.md">← Back to the README</a> &nbsp;·&nbsp; <a href="TOOLS.md">Start with Tools →</a></p>

package/docs/TOOLS.md

@@ -0,0 +1,221 @@
+<p align="center">
+  <img src="assets/banner-tools.jpg" width="100%" alt="Tools — a travel-poster illustration of five colossal tools planted upright on a desert plain: a paintbrush, a pencil, scissors, a compass and a key">
+</p>
+
+# Tools
+
+The server exposes **five tools**, three **resources** and two **prompts**. This page documents every parameter, every result field and every error.
+
+**On this page:** [Choosing a tool](#choosing-a-tool) · [generate_image](#generate_image) · [edit_image](#edit_image) · [remove_background](#remove_background) · [auth_status](#auth_status) · [sign_in](#sign_in) · [Errors](#errors) · [Resources](#resources) · [Prompts](#prompts) · [Progress, timeouts and cancellation](#progress-timeouts-and-cancellation)
+
+| Tool | Purpose | Network | Quota |
+|---|---|---|---|
+| [`generate_image`](#generate_image) | A new image from a text prompt | ChatGPT | 1 image per variant |
+| [`edit_image`](#edit_image) | Edit images, or generate guided by 1–5 references | ChatGPT | 1 image per variant |
+| [`remove_background`](#remove_background) | Key out a flat, solid-colour backdrop | none | none |
+| [`auth_status`](#auth_status) | Sign-in, plan, credential source, usage windows | ChatGPT (usage only) | none |
+| [`sign_in`](#sign_in) | Start a ChatGPT sign-in and return a link or code | OpenAI auth | none |
+
+The server's name in client configs defaults to `imagegen`, and clients add a prefix to the tool names:
+
+| Client | Tool name as the model sees it |
+|---|---|
+| opencode | `imagegen_generate_image` |
+| Claude Code, OpenAI Codex | `mcp__imagegen__generate_image` |
+| Other clients | listed under the `imagegen` server |
+
+> [!NOTE]
+> **Relative paths** resolve against the **workspace root**. That is the first `file://` root the client reports through MCP roots (opencode reports the project directory). Without one, the server uses the directory it was started in. A filesystem root such as `/` falls back to your home directory.
+
+## Choosing a tool
+
+```mermaid
+flowchart LR
+    start(["request"]):::ink --> q1{"existing<br/>image?"}:::cream
+    q1 -- "no" --> gen["generate_image"]:::rust
+    q1 -- "yes" --> q2{"only a flat<br/>backdrop to remove?"}:::cream
+    q2 -- "yes" --> rb["remove_background<br/>local · no quota"]:::teal
+    q2 -- "no" --> edit["edit_image<br/>edit or use as reference"]:::rust
+    gen --> q3{"needs<br/>transparency?"}:::cream
+    edit --> q3
+    q3 -- "yes" --> tr["background: transparent<br/>check 'alpha verified'"]:::ochre
+    q3 -- "no" --> done(["save to output_path,<br/>report the path"]):::ink
+    tr --> done
+    classDef ink fill:#2A2523,stroke:#9A8C76,color:#E4D9C6
+    classDef rust fill:#A6553B,stroke:#7E3F2B,color:#FFFFFF
+    classDef ochre fill:#D9A05B,stroke:#B5813F,color:#2A2523
+    classDef teal fill:#4E6E63,stroke:#3A544B,color:#FFFFFF
+    classDef cream fill:#E4D9C6,stroke:#A89A80,color:#2A2523
+```
+
+## generate_image
+
+Generate a new image from a text prompt. The server calls `POST https://chatgpt.com/backend-api/codex/images/generations`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `prompt` | string, 1–32 000 chars | required | The image description. Structure it: use case, subject, style, composition, lighting, palette, exact text in quotes, constraints. |
+| `aspect_ratio` | enum | `auto` | `1:1` `4:5` `5:4` `4:3` `3:4` `3:2` `2:3` `16:9` `9:16` `21:9` `9:21`. Appended to the prompt as, for example, `Aspect ratio: 16:9, wide landscape (horizontal) canvas.` |
+| `background` | enum | `auto` | `transparent` returns a PNG with real alpha. `opaque` asks for a filled background. |
+| `n` | int, 1–4 | `1` | Variants of the *same* prompt, sent as concurrent requests. Each counts against the quota. |
+| `output_path` | string | image library | A `.png`, `.jpg` or `.jpeg` file, or a directory (existing, or ending in `/`). With `n > 1`, `-1`, `-2`… is inserted before the extension. |
+| `output_format` | `png` · `jpeg` | `png` | JPEG is converted locally, flattened on white, and can't be transparent. It's inferred from the `output_path` extension. |
+| `overwrite` | bool | `false` | When false, an existing file is never replaced; the next free `name-2.png`, `name-3.png`… is used. |
+| `include_preview` | bool | `true` | Attach a JPEG preview (longest edge 1024 px, transparency shown as a checkerboard). |
+
+> [!TIP]
+> The service picks the pixel size itself and sizes the canvas from the prompt. Measured results: `16:9` → 1672×941, `9:16` → 941×1672, `21:9` → 1916×821, `1:1` → 1254×1254. For exact dimensions, generate the closest ratio, then resize or crop locally.
+
+> [!NOTE]
+> `background: "opaque"` is a **hint**. In one measured case the service returned a transparent PNG when the prompt described a backdrop that "will be keyed out", even though `opaque` was sent. If you need a filled background, describe it as part of the picture.
+
+**Default location** (no `output_path`): `$CODEX_IMAGEGEN_OUTPUT_DIR`, which defaults to `~/.local/share/codex-imagegen-mcp/images`, in `/YYYY-MM-DD/HHMMSS-<prompt-slug>.png`.
+
+**The result has three parts:**
+
+1. **Text.** One line per saved file (path, dimensions, format, size, background, id), then any warnings, then guidance for the model.
+2. **Image blocks.** One preview per saved file, when `include_preview` is on.
+3. **`structuredContent`**, validated against the declared `outputSchema`:
+
+```json
+{
+  "images": [
+    { "id": "img_aa289474550c", "path": "/abs/project/assets/hero.png", "mime_type": "image/png",
+      "bytes": 2063882, "width": 1672, "height": 941, "background": "opaque" }
+  ],
+  "prompt": "…the exact prompt sent, including the aspect-ratio line…",
+  "elapsed_ms": 22834,
+  "failures": [],
+  "warnings": []
+}
+```
+
+When transparency was requested, each image also carries `transparent: true|false`. It records whether the decoded PNG actually contains non-opaque pixels, which is what the text reports as *alpha verified*.
+
+**Partial success:** with `n > 1`, finished variants are saved and returned, and failed ones are listed in `failures`. The call is an error (`isError: true`) only if nothing was produced.
+
+## edit_image
+
+Edit images, or generate using reference images. The server calls `POST https://chatgpt.com/backend-api/codex/images/edits` with the images inlined as data URLs. It takes every `generate_image` parameter, plus:
+
+| Parameter | Type | Description |
+|---|---|---|
+| `images` | string[], 1–5 | Local paths (absolute, `~/…`, workspace-relative), `file://` URLs, `http(s)://` URLs (downloaded with a 60 s timeout), or `data:image/…;base64,…`. PNG, JPEG or WebP, up to 15 MB each, detected by magic bytes. |
+
+- `images[0]` is **Image 1**, the primary edit target. Refer to the inputs by index in the prompt, and spell out what must stay unchanged.
+- The input files are never modified.
+- To iterate on a result, pass the previous output path as Image 1.
+
+```text
+Image 1: add a tiny woven straw hat on top of the cactus, tilted slightly.
+Keep the cactus, flowers, pot, outline and transparent background exactly unchanged.
+```
+
+## remove_background
+
+A local chroma-key cutout, ported to TypeScript from the Codex skill's `scripts/remove_chroma_key.py`. It uses the same algorithm, makes no network call and costs no quota.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `input_path` | string | required | PNG or JPEG |
+| `output_path` | string (`.png`) | `<input>-transparent.png` | Never overwrites unless `overwrite: true` |
+| `key_color` | `#rrggbb` | auto | When omitted, the median of a 6 px border band |
+| `soft_matte` | bool | `true` | Smoothstep alpha between `transparent_threshold` and `opaque_threshold`, combined with key-channel dominance |
+| `despill` | bool | `true` | Caps key-coloured channels on semi-transparent pixels |
+| `tolerance` | 0–255 | `12` | Hard key (`soft_matte: false`): the maximum per-channel distance treated as background |
+| `transparent_threshold` | 0–255 | `12` | Soft matte: at or below this distance a pixel is fully transparent |
+| `opaque_threshold` | 0–255 | `96` | Soft matte: at or above this distance a pixel is fully opaque |
+| `edge_contract` | 0–16 | `0` | Erode the matte N px (3×3 minimum filter) to remove halos |
+| `edge_feather` | 0–64 | `0` | Gaussian blur radius for the alpha edge |
+| `overwrite`, `include_preview` | bool | `false`, `true` | As above |
+
+The result reports the key colour it used and the percentage of fully transparent and soft-edge pixels. It warns when nothing matched the key, or when more than 97% of the image became transparent.
+
+<p align="center">
+  <img src="assets/examples/remove-background.jpg" width="78%" alt="A striped balloon generated on a flat green backdrop, and the same balloon cut out with remove_background">
+  <br><sub>Real run: key auto-detected as <code>#03f902</code> · 63.8% fully transparent · 0.4% soft edge pixels.</sub>
+</p>
+
+## auth_status
+
+| Parameter | Default | Description |
+|---|---|---|
+| `check_usage` | `true` | Also fetch `GET /backend-api/wham/usage` (free) for the usage windows |
+
+The text report covers:
+- the active source, account email, plan and account suffix;
+- when the token expires;
+- the usage windows, e.g. `Codex 5-hour window: 6% used, resets in 32m`;
+- any sign-in in progress, and the outcome of the last one;
+- every credential source with its state: `✓` ready, `·` missing, `✗` expired or unusable, `-` disabled.
+
+## sign_in
+
+| Parameter | Default | Description |
+|---|---|---|
+| `method` | `browser` | `browser`: an authorize link that redirects to `http://localhost:1455` on this machine. `device`: a code to enter at `https://auth.openai.com/codex/device` from any device. |
+| `open_browser` | `true` | Try to open the link on this machine |
+| `force` | `false` | Start a new sign-in even when one already exists, e.g. to switch account or workspace |
+
+The tool returns the link or code **immediately**, and the sign-in completes in the background. Only one sign-in runs at a time, so a second call returns the pending one. The model should relay the link or code verbatim, then call `auth_status` to confirm. [How sign-in works →](AUTH.md)
+
+## Errors
+
+Errors come back as `isError: true` results. The text states both the problem and the next step:
+
+| Kind | Typical message → next step |
+|---|---|
+| `not_signed_in` | *Not signed in to ChatGPT. Sign in by running `… login` … or call the `sign_in` tool* |
+| `session_expired` | *Your sign-in was invalidated … Please sign in again.* |
+| `auth_failed` | HTTP 401 means the credentials were rejected; 403 means the plan or workspace lacks the feature |
+| `usage_limit` | *You've hit your ChatGPT image-generation usage limit (plus plan). It resets in 1h 12m …* → don't retry |
+| `content_policy` | *The request was rejected by OpenAI's safety system: …* → rephrase |
+| `invalid_request` · `invalid_input` · `unsupported` | Bad parameters, paths, formats or sizes → fix the arguments |
+| `server_error` · `network` · `timeout` | Transient. The server already retried 5xx and network errors twice (after 1 s and 3 s), so one more try is reasonable |
+| `blocked` | A Cloudflare challenge → try later or from another network |
+
+The ChatGPT request id (`x-codex-imagegen-request-id`) is appended when available.
+
+## Resources
+
+| URI | Type | Content |
+|---|---|---|
+| `imagegen://history` | `application/json` | The 50 most recent saved images, newest first: id, time, tool, path, size, prompt, inputs, request ids |
+| `imagegen://images/{id}` | image blob | The saved file, or a 2048 px JPEG preview if it is larger than 8 MB. The listing shows the 25 most recent. |
+| `imagegen://skill/SKILL.md`, `imagegen://skill/references/*.md` | `text/markdown` | The bundled skill, for clients without Agent Skills support |
+
+History is also appended to `$CODEX_IMAGEGEN_HOME/history.jsonl`.
+
+## Prompts
+
+| Prompt | Arguments | Expands to |
+|---|---|---|
+| `generate` | `description` | A request to use `generate_image` with the skill's workflow checklist |
+| `edit` | `image`, `change` | A request to use `edit_image` with invariant-preserving instructions |
+
+In opencode they appear as `/imagegen:generate` and `/imagegen:edit`.
+
+## Progress, timeouts and cancellation
+
+```mermaid
+sequenceDiagram
+    participant C as MCP client
+    participant S as imagegen server
+    participant B as ChatGPT backend
+    C->>S: tools/call (with a progress token)
+    S->>B: POST /images/generations
+    loop every 5 s
+        S-->>C: notifications/progress, which resets the client's request timeout
+    end
+    B-->>S: PNG after 15–60 s
+    S-->>C: result
+    Note over C,S: notifications/cancelled aborts the HTTP request immediately
+```
+
+- **Progress:** while a request runs, the server sends a progress notification every 5 s, provided the client supplied a progress token. opencode supplies one and resets its request timeout on each notification (`resetTimeoutOnProgress`), so 15–60 s generations never hit its 60 s default.
+- **Timeout:** the backend request itself times out after `CODEX_IMAGEGEN_TIMEOUT_MS`, 300 s by default.
+- **Cancellation:** cancelling the tool call aborts the HTTP request.
+
+---
+
+<p align="center"><a href="README.md">← Docs home</a> &nbsp;·&nbsp; <a href="AUTH.md">Authentication →</a></p>

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "codex-imagegen-mcp",
+  "version": "0.1.2",
+  "description": "MCP server + Agent Skill that brings OpenAI Codex's image generation to any MCP client (opencode, Claude Code, Cursor, VS Code and more), running on your ChatGPT plan with no API key.",
+  "license": "Apache-2.0",
+  "author": "Shalom Obongo (https://github.com/ShalomObongo)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShalomObongo/codex-imagegen-mcp.git"
+  },
+  "homepage": "https://github.com/ShalomObongo/codex-imagegen-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ShalomObongo/codex-imagegen-mcp/issues"
+  },
+  "type": "module",
+  "bin": {
+    "codex-imagegen-mcp": "dist/src/cli.js"
+  },
+  "main": "dist/src/server/index.js",
+  "files": [
+    "dist/src",
+    "skill",
+    "docs/*.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/src/cli.js', 0o755)\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test --test-concurrency=1 \"dist/test/**/*.test.js\"",
+    "start": "node dist/src/cli.js serve",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "image-generation",
+    "image-editing",
+    "gpt-image",
+    "codex",
+    "openai-codex",
+    "chatgpt",
+    "opencode",
+    "claude-code",
+    "cursor",
+    "agent-skills"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "jpeg-js": "^0.4.4",
+    "jsonc-parser": "^3.3.1",
+    "pngjs": "^7.0.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^7.0.2"
+  }
+}