codex-images-mcp 0.1.0__tar.gz

codex_images_mcp-0.1.0/.dockerignore

@@ -0,0 +1,8 @@
+.git
+.venv
+**/__pycache__
+**/.pytest_cache
+packages
+tests
+docs
+examples

codex_images_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev deps
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -q
+
+  pi-extension:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/pi-codex-images
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: packages/pi-codex-images/package-lock.json
+
+      - run: npm ci
+      - run: npm test
+      - run: npm run typecheck
+      - name: Check published files
+        run: npm pack --dry-run
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - name: Build image
+        run: docker build -t codex-images-mcp:ci .
+
+      - name: Refuses public bind without a token
+        env:
+          EXPECTED: Refusing to listen on 0.0.0.0 without
+        run: |
+          set +e
+          docker run --rm codex-images-mcp:ci > out.txt 2>&1
+          code=$?
+          set -e
+          cat out.txt
+          test "$code" -eq 2
+          grep -q "$EXPECTED CODEX_IMAGES_HTTP_TOKEN" out.txt
+
+      - name: Serves MCP behind the bearer token
+        env:
+          URL: http://127.0.0.1:8324/mcp/
+        run: |
+          docker run -d --name cim -p 8324:8324 \
+            -e CODEX_IMAGES_HTTP_TOKEN=ci-token codex-images-mcp:ci
+          status() { curl -s -o /dev/null -w '%{http_code}' -X POST "$URL"; }
+          for _ in $(seq 1 30); do
+            [ "$(status || true)" = "401" ] && break
+            sleep 1
+          done
+          test "$(status)" = "401"
+          docker rm -f cim

codex_images_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing; no long-lived token
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+
+      - name: Check tag matches package version
+        shell: python
+        run: |
+          import os, tomllib
+          with open("pyproject.toml", "rb") as handle:
+              version = tomllib.load(handle)["project"]["version"]
+          assert f"v{version}" == os.environ["GITHUB_REF_NAME"], version
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+
+  ghcr:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/codex-images-mcp
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+
+      - uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  npm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # npm provenance
+    defaults:
+      run:
+        working-directory: packages/pi-codex-images
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - name: Check tag matches package version
+        run: |
+          version=$(node -p "require('./package.json').version")
+          test "v$version" = "$GITHUB_REF_NAME"
+
+      - run: npm ci
+      - run: npm test
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

codex_images_mcp-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Editable installs
+*.pth
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+.env
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Project-local
+# Probe scripts + their results (used during architecture verification, not part of package)
+probe_*.py
+probe_*.json
+probe_*.txt
+probe_*log*
+
+# Output directories from runs
+out/
+runs/
+smoke-test/
+test-runs/
+*.raw.png
+
+# Upstream clone (reference only, not part of our package)
+upstream/

codex_images_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+First release of codex-images-mcp, a fork of [VelmoAI/codex-imagen](https://github.com/VelmoAI/codex-imagen).
+
+### Added
+
+- Native Codex Images engine (`/backend-api/codex/images/{generations,edits}`, gpt-image-2): prompts sent verbatim, native transparency, references and masks.
+- `codex_images` and `codex_images_artifact` MCP tools returning `codex-images.result/v2` with verified `resource_link` artifacts (SHA-256, MIME, dimensions).
+- Output size policies `native`, `exact`, `fit` and `cover`.
+- Streamable HTTP server `codex-images-mcp-http`: built-in bearer auth, refuses a public bind without a token, signed single-use downloads.
+- Docker image and example compose file.
+- `codex-images-mcp login` / `logout`: a device-code ChatGPT session of its own, stored with mode 0600.
+- SSRF-hardened remote references: HTTPS, public addresses only, pinned IP, no redirects.
+- Pi / Gentle Shell extension `pi-codex-images`.
+- Optional OpenAI API engine (`CODEX_IMAGES_ENGINE=api` + `OPENAI_API_KEY`) that honors `model` (default `gpt-image-2.6-flare`), `quality` and `complexity`; the plan route ignores them with a warning. Results report the engine in `models.engine`.
+- CI on Linux, macOS and Windows; releases to PyPI, GHCR and npm.
+
+### Changed
+
+- Package, CLI and MCP server renamed to `codex-images-mcp` / `codex-images`. `setup` keeps existing `codex-imagen` entries and explains how to remove them.
+- A borrowed Codex CLI login (`CODEX_HOME/auth.json`) is used read-only and never refreshed.
+
+### Removed
+
+- The prompt-rewriting model, reasoning modes, skill-file injection and chroma-key pipeline. Their input fields are accepted and ignored with a warning.
+- The Python SDK (`imagen`, `ImagenOptions`, `ImagenResult`) and the `imagen` console script.
+- The `codex-image-gen` dependency.

codex_images_mcp-0.1.0/Dockerfile

@@ -0,0 +1,26 @@
+# codex-images-mcp — self-hosted Streamable HTTP server.
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    CODEX_HOME=/data/codex \
+    CODEX_IMAGES_AUTH_FILE=/data/auth.json \
+    CODEX_IMAGES_OUTPUT_DIR=/data/out \
+    CODEX_IMAGES_HTTP_HOST=0.0.0.0 \
+    CODEX_IMAGES_HTTP_PORT=8324
+
+WORKDIR /src
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install --no-cache-dir ".[http]" \
+    && useradd --create-home --uid 10001 app \
+    && mkdir -p /data/codex /data/out \
+    && chown -R app:app /data
+
+USER app
+WORKDIR /home/app
+VOLUME ["/data"]
+EXPOSE 8324
+
+# Refuses to start on 0.0.0.0 unless CODEX_IMAGES_HTTP_TOKEN is set.
+CMD ["codex-images-mcp-http"]

codex_images_mcp-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 wauwa
+Copyright (c) 2026 JlMoreno00
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+This project bundles ideas from the upstream `codex-image-gen` library by
+Small Turtle 2 (MIT-licensed). See https://github.com/smturtle2/codex-image-gen.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_images_mcp-0.1.0/NOTICE

@@ -0,0 +1,14 @@
+codex-images-mcp
+Copyright (c) 2026 JlMoreno00. Licensed under the MIT License (see LICENSE).
+
+This project is a fork of codex-imagen
+  https://github.com/VelmoAI/codex-imagen
+  Copyright (c) 2026 wauwa. MIT License.
+
+The OAuth token loading and refresh in src/codex_images_mcp/_auth.py derive from
+codex-image-gen
+  https://github.com/smturtle2/codex-image-gen
+  Copyright (c) 2026 Small Turtle 2. MIT License.
+
+Not affiliated with or endorsed by OpenAI. "ChatGPT", "Codex" and "gpt-image-2"
+are trademarks or product names of OpenAI.

codex_images_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: codex-images-mcp
+Version: 0.1.0
+Summary: Self-hosted MCP server for Codex Images (gpt-image-2 on your ChatGPT plan): stdio and HTTP, verifiable artifacts, masks
+Project-URL: Homepage, https://github.com/JlMoreno00/codex-images-mcp
+Project-URL: Repository, https://github.com/JlMoreno00/codex-images-mcp
+Project-URL: Issues, https://github.com/JlMoreno00/codex-images-mcp/issues
+Author: wauwa, JlMoreno00
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai,cli,codex,gpt-image,image generation,mcp,openai,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: mcp<2,>=1.27
+Requires-Dist: pillow>=10.0
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: starlette>=0.40; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Provides-Extra: http
+Requires-Dist: starlette>=0.40; extra == 'http'
+Requires-Dist: uvicorn>=0.30; extra == 'http'
+Description-Content-Type: text/markdown
+
+# codex-images-mcp
+
+Generate and edit images from any MCP client with **gpt-image-2 on the ChatGPT plan you already pay for**. No OpenAI API key, no per-image bill.
+
+codex-images-mcp is an MCP server for the Codex Images endpoint. It runs locally over stdio, or as a **self-hosted HTTP server** that your laptop, your VPS agents and your Pi / Gentle Shell sessions can share. Every image comes back as a verifiable artifact: SHA-256, byte count, MIME type and real dimensions.
+
+> **Unofficial.** Not affiliated with or endorsed by OpenAI. It signs in with your own ChatGPT account and uses the same endpoint as the Codex CLI. You are bound by OpenAI's terms for your account, and image generation counts against your plan's limits.
+
+## What you get
+
+- **Two tools**: `codex_images` (generate/edit) and `codex_images_artifact` (fetch an image by URI, inline or through a short-lived signed download).
+- **Batches**: `parallel`, `variants`, `chain` and `branded-parallel` (every image references a shared anchor for brand-consistent sets).
+- **Edits with references and masks**: up to five references per request, HTTPS URLs or inline images.
+- **Native transparency**: real alpha PNGs from the model, with a warning when a result comes back opaque.
+- **Exact output sizes**: `native`, `exact`, `fit` or `cover` post-processing, so a 1200×630 card is 1200×630.
+- **Prompts sent verbatim**: no hidden rewriting model in between.
+- **Optional API-key engine**: set `CODEX_IMAGES_ENGINE=api` with an `OPENAI_API_KEY` to choose the model yourself (Images 2.6 `gpt-image-2.6-sunburst` / `-flare`), with quality up to `max` and complexity control. This engine is billed to your API account. On the default ChatGPT plan route OpenAI chooses the model, and the API selectors (`model`, `quality`, `complexity`) are ignored.
+- **Self-hosting that is safe by default**: built-in bearer auth, refuses to listen publicly without a token, SSRF-hardened URL fetching (HTTPS, public addresses only, pinned IP, no redirects), no server paths in results.
+- **Its own ChatGPT session**: `codex-images-mcp login` uses a device code and keeps a separate session, so it never rotates (and breaks) your Codex app's sign-in.
+
+## Quick start (local, stdio)
+
+```bash
+uvx --from codex-images-mcp codex-images-mcp login     # sign in once (device code)
+uvx --from codex-images-mcp codex-images-mcp setup     # register in Claude Code, Claude Desktop, Codex, Cursor, OpenCode
+```
+
+Or try it from the terminal:
+
+```bash
+uvx --from codex-images-mcp codex-images-mcp generate "a ceramic mug, studio light" --transparent --pretty
+```
+
+Already signed in to the Codex CLI? codex-images-mcp can use that login **read-only** until its token expires. It never refreshes it; run `login` for a session of its own.
+
+## Self-hosted (HTTP)
+
+```bash
+export CODEX_IMAGES_HTTP_TOKEN=$(openssl rand -hex 32)
+docker compose up -d
+docker compose run --rm codex-images codex-images-mcp login
+```
+
+Then point your clients at `https://your-host/mcp/` with `Authorization: Bearer $CODEX_IMAGES_HTTP_TOKEN`. See [docs/self-hosting.md](docs/self-hosting.md) for the reverse proxy, signed downloads and every setting.
+
+## Pi and Gentle Shell
+
+[`pi-codex-images`](packages/pi-codex-images) is a Pi extension for a self-hosted server. It reads the local files you authorize, sends them inline, and writes verified results atomically into your project:
+
+```bash
+pi install npm:pi-codex-images
+```
+
+## Documentation
+
+- [MCP tools reference](docs/mcp.md): inputs, results, error codes.
+- [CLI](docs/cli.md): `generate`, `login`, `logout`, `setup`, `status`, `uninstall`.
+- [Self-hosting](docs/self-hosting.md): Docker, reverse proxy, configuration, security model.
+- [Examples](docs/examples.md): batches, edits, masks, transparency, exact sizes.
+- [Comparison](docs/comparison.md): how this differs from similar projects.
+
+## Credits
+
+codex-images-mcp started as a fork of [VelmoAI/codex-imagen](https://github.com/VelmoAI/codex-imagen) by wauwa. The installer and much of the original structure come from there. The OAuth token handling derives from [codex-image-gen](https://github.com/smturtle2/codex-image-gen) by Small Turtle 2. The generation engine was replaced with the native Codex Images endpoint, and the prompt-rewriting and chroma-key layers were removed.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

codex_images_mcp-0.1.0/README.md

@@ -0,0 +1,68 @@
+# codex-images-mcp
+
+Generate and edit images from any MCP client with **gpt-image-2 on the ChatGPT plan you already pay for**. No OpenAI API key, no per-image bill.
+
+codex-images-mcp is an MCP server for the Codex Images endpoint. It runs locally over stdio, or as a **self-hosted HTTP server** that your laptop, your VPS agents and your Pi / Gentle Shell sessions can share. Every image comes back as a verifiable artifact: SHA-256, byte count, MIME type and real dimensions.
+
+> **Unofficial.** Not affiliated with or endorsed by OpenAI. It signs in with your own ChatGPT account and uses the same endpoint as the Codex CLI. You are bound by OpenAI's terms for your account, and image generation counts against your plan's limits.
+
+## What you get
+
+- **Two tools**: `codex_images` (generate/edit) and `codex_images_artifact` (fetch an image by URI, inline or through a short-lived signed download).
+- **Batches**: `parallel`, `variants`, `chain` and `branded-parallel` (every image references a shared anchor for brand-consistent sets).
+- **Edits with references and masks**: up to five references per request, HTTPS URLs or inline images.
+- **Native transparency**: real alpha PNGs from the model, with a warning when a result comes back opaque.
+- **Exact output sizes**: `native`, `exact`, `fit` or `cover` post-processing, so a 1200×630 card is 1200×630.
+- **Prompts sent verbatim**: no hidden rewriting model in between.
+- **Optional API-key engine**: set `CODEX_IMAGES_ENGINE=api` with an `OPENAI_API_KEY` to choose the model yourself (Images 2.6 `gpt-image-2.6-sunburst` / `-flare`), with quality up to `max` and complexity control. This engine is billed to your API account. On the default ChatGPT plan route OpenAI chooses the model, and the API selectors (`model`, `quality`, `complexity`) are ignored.
+- **Self-hosting that is safe by default**: built-in bearer auth, refuses to listen publicly without a token, SSRF-hardened URL fetching (HTTPS, public addresses only, pinned IP, no redirects), no server paths in results.
+- **Its own ChatGPT session**: `codex-images-mcp login` uses a device code and keeps a separate session, so it never rotates (and breaks) your Codex app's sign-in.
+
+## Quick start (local, stdio)
+
+```bash
+uvx --from codex-images-mcp codex-images-mcp login     # sign in once (device code)
+uvx --from codex-images-mcp codex-images-mcp setup     # register in Claude Code, Claude Desktop, Codex, Cursor, OpenCode
+```
+
+Or try it from the terminal:
+
+```bash
+uvx --from codex-images-mcp codex-images-mcp generate "a ceramic mug, studio light" --transparent --pretty
+```
+
+Already signed in to the Codex CLI? codex-images-mcp can use that login **read-only** until its token expires. It never refreshes it; run `login` for a session of its own.
+
+## Self-hosted (HTTP)
+
+```bash
+export CODEX_IMAGES_HTTP_TOKEN=$(openssl rand -hex 32)
+docker compose up -d
+docker compose run --rm codex-images codex-images-mcp login
+```
+
+Then point your clients at `https://your-host/mcp/` with `Authorization: Bearer $CODEX_IMAGES_HTTP_TOKEN`. See [docs/self-hosting.md](docs/self-hosting.md) for the reverse proxy, signed downloads and every setting.
+
+## Pi and Gentle Shell
+
+[`pi-codex-images`](packages/pi-codex-images) is a Pi extension for a self-hosted server. It reads the local files you authorize, sends them inline, and writes verified results atomically into your project:
+
+```bash
+pi install npm:pi-codex-images
+```
+
+## Documentation
+
+- [MCP tools reference](docs/mcp.md): inputs, results, error codes.
+- [CLI](docs/cli.md): `generate`, `login`, `logout`, `setup`, `status`, `uninstall`.
+- [Self-hosting](docs/self-hosting.md): Docker, reverse proxy, configuration, security model.
+- [Examples](docs/examples.md): batches, edits, masks, transparency, exact sizes.
+- [Comparison](docs/comparison.md): how this differs from similar projects.
+
+## Credits
+
+codex-images-mcp started as a fork of [VelmoAI/codex-imagen](https://github.com/VelmoAI/codex-imagen) by wauwa. The installer and much of the original structure come from there. The OAuth token handling derives from [codex-image-gen](https://github.com/smturtle2/codex-image-gen) by Small Turtle 2. The generation engine was replaced with the native Codex Images endpoint, and the prompt-rewriting and chroma-key layers were removed.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

codex_images_mcp-0.1.0/RELEASING.md

@@ -0,0 +1,40 @@
+# Releasing
+
+A `vX.Y.Z` tag runs `.github/workflows/release.yml`, which publishes three artifacts from the same commit:
+
+| Artifact | Where | Auth |
+|---|---|---|
+| Python package `codex-images-mcp` | PyPI | Trusted Publishing (OIDC, no stored token) |
+| Docker image `codex-images-mcp` (amd64, arm64) | `ghcr.io/jlmoreno00/codex-images-mcp` | `GITHUB_TOKEN` |
+| Pi extension `pi-codex-images` | npm, with provenance | `NPM_TOKEN` secret |
+
+Each job fails if the tag does not match the version it publishes.
+
+## One-time setup
+
+1. **PyPI**: on https://pypi.org/manage/account/publishing/ add a *pending publisher* for project `codex-images-mcp`, owner `JlMoreno00`, repository `codex-images-mcp`, workflow `release.yml`, environment `pypi`. Then create the `pypi` environment under **Settings → Environments** (optionally with required reviewers).
+2. **npm**: create a granular access token that can publish `pi-codex-images` and add it as the repository secret `NPM_TOKEN`.
+3. **GHCR**: nothing to configure. After the first push, open the package settings and set its visibility to public.
+
+## Each release
+
+1. Bump the version in all three places:
+   - `pyproject.toml` (`version`)
+   - `src/codex_images_mcp/__init__.py` (`__version__`)
+   - `packages/pi-codex-images/package.json` (`version`, then `npm install` to refresh the lockfile)
+2. Add the release notes to `CHANGELOG.md`.
+3. Commit, push to `main`, wait for CI to pass.
+4. Tag and push the tag:
+
+   ```bash
+   git tag v0.1.1
+   git push origin v0.1.1
+   ```
+
+5. Watch https://github.com/JlMoreno00/codex-images-mcp/actions, then check a clean install:
+
+   ```bash
+   uvx --from codex-images-mcp codex-images-mcp --version
+   docker run --rm ghcr.io/jlmoreno00/codex-images-mcp:latest codex-images-mcp --version
+   npm view pi-codex-images version
+   ```

codex_images_mcp-0.1.0/docker-compose.yml

@@ -0,0 +1,20 @@
+# Example deployment. Put a TLS reverse proxy (Caddy, nginx, Traefik) in front
+# and point CODEX_IMAGES_PUBLIC_BASE_URL at its public HTTPS origin if you want
+# signed downloads for large artifacts.
+services:
+  codex-images:
+    build: .
+    image: ghcr.io/jlmoreno00/codex-images-mcp:latest
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:8324:8324"
+    environment:
+      CODEX_IMAGES_HTTP_TOKEN: ${CODEX_IMAGES_HTTP_TOKEN:?set a random token}
+      # CODEX_IMAGES_PUBLIC_BASE_URL: https://images.example.com
+      # Optional paid engine with model choice (Images 2.6):
+      # CODEX_IMAGES_ENGINE: api
+      # OPENAI_API_KEY: ${OPENAI_API_KEY}
+    volumes:
+      # ChatGPT session (auth.json) and generated artifacts.
+      # Sign in once: docker compose run --rm codex-images codex-images-mcp login
+      - ./data:/data