mcp-gpt-image 0.2.0__tar.gz

mcp_gpt_image-0.2.0/.env.example

@@ -0,0 +1,14 @@
+# Required. Standard OpenAI variable, reused as-is.
+OPENAI_API_KEY=sk-...
+
+# Where generated images are written. Created on first use.
+GPT_IMAGE_OUTPUT_DIR=./generated-images
+
+# Image model. Set to gpt-image-2-2026-04-21 to pin a snapshot and freeze behaviour.
+GPT_IMAGE_MODEL=gpt-image-2
+
+# Seconds before an image call is abandoned. Large sizes and complex prompts are slow.
+GPT_IMAGE_TIMEOUT=300
+
+# Same, for refine_image, which runs a reasoning model in front of the drawing.
+GPT_IMAGE_REFINE_TIMEOUT=300

mcp_gpt_image-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Lint and test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --all-extras --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: make test

mcp_gpt_image-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+# Publishing runs on a published GitHub release, never on a tag push, so a tag
+# pushed by mistake cannot ship a version to PyPI.
+#
+# Credentials: none. PyPI is configured with a trusted publisher pointing at this
+# repository, this workflow file and the "pypi" environment below, and the upload
+# is authorised by the OIDC token minted by `id-token: write`.
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --all-extras
+
+      - name: Check the tag matches the packaged version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          packaged="$(uv run python -c 'import tomllib,pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          if [ "$tag" != "$packaged" ]; then
+            echo "Release tag $GITHUB_REF_NAME does not match version $packaged in pyproject.toml"
+            exit 1
+          fi
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: make test
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-gpt-image
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

mcp_gpt_image-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Default output directory. Generated images are artefacts, not sources.
+generated-images/

mcp_gpt_image-0.2.0/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.2.0 - 2026-08-14
+
+A breaking release, top to bottom. The package has a new name, a new import path, one supported
+model and a third tool. Nothing from 0.1.x is carried forward: there are no compatibility
+shims, no deprecated aliases and no dual code paths, because the model this server was written
+against is being retired and a transitional layer would only have made the migration slower to
+find.
+
+Migrating is a matter of changing the command your MCP client runs, renaming five environment
+variables, and deleting the `model` and `input_fidelity` arguments from any tool call you have
+scripted.
+
+### Added
+
+- **`refine_image`, multi-turn refinement.** The reason this release exists. It runs through the
+  OpenAI Responses API with the built-in image generation tool, driven by the mainline model
+  `gpt-5.6`, and returns a `session_id` alongside the saved image. Passing that id on the next
+  call continues the same conversation, so a correction is one sentence rather than a rewritten
+  prompt plus a re-uploaded image. Sessions last about 30 days. It costs more per image than
+  `generate_image`, because a reasoning model is doing the steering, and it pays for itself from
+  the second turn on.
+- **Local validation of the refinement session id.** An id that cannot be an OpenAI response id
+  is rejected here with a message telling you to omit it, rather than spending a round trip on an
+  id an agent invented.
+- **Custom sizes, validated before the request leaves.** Any `WIDTHxHEIGHT` with both dimensions
+  a multiple of 16, an aspect ratio between 1:3 and 3:1 and a maximum of 3840x2160 is accepted,
+  and the four rules are checked locally so a malformed size costs a validation error instead of
+  a billed refusal.
+- **`output_format` on every result.** Callers previously had to infer the format from the file
+  extension, which was the wrong thing to trust. See the format detection change below.
+- **A documentation set** under [docs/](docs/): getting started, a full tool reference, the
+  refinement workflow, configuration, and troubleshooting organised by symptom.
+
+### Changed
+
+- **Package renamed from `openai-imagegen-mcp` to `mcp-gpt-image`.** The old name described a
+  family of models that no longer exists, and it put the vendor first in a name that people type.
+  The console script is now `mcp-gpt-image`, so client configs need their `args` updated.
+- **Import path renamed from `openai_imagegen_mcp` to `gpt_image_mcp`.** Only relevant if you
+  imported the server to embed it; the MCP surface is unaffected.
+- **Environment variables renamed from `OPENAI_IMAGEGEN_*` to `GPT_IMAGE_*`.**
+  `OPENAI_IMAGEGEN_OUTPUT_DIR` becomes `GPT_IMAGE_OUTPUT_DIR`,
+  `OPENAI_IMAGEGEN_DEFAULT_MODEL` becomes `GPT_IMAGE_MODEL`, and `OPENAI_IMAGEGEN_TIMEOUT`
+  becomes `GPT_IMAGE_TIMEOUT`, joined by the new `GPT_IMAGE_REFINE_TIMEOUT`. The prefix now
+  matches the package rather than the vendor. `OPENAI_API_KEY` deliberately keeps its standard
+  name so an existing OpenAI setup works untouched.
+- **Only gpt-image-2 is supported.** `dall-e-2` and `dall-e-3` were shut down on 2026-05-12, and
+  on 2026-06-02 OpenAI announced that `gpt-image-1.5`, `gpt-image-1-mini` and
+  `chatgpt-image-latest` retire on 2026-12-01, all migrating to gpt-image-2. Supporting a family
+  of models with one live member would have been a menu of expiry dates. `GPT_IMAGE_MODEL` still
+  lets you choose between the floating `gpt-image-2` and the pinned snapshot
+  `gpt-image-2-2026-04-21`, which is the only choice left that changes anything.
+- **Errors surface as MCP tool errors instead of an `{"error": ...}` payload.** The old shape
+  returned a successful tool result whose content happened to describe a failure, and agents read
+  that as an image that exists. A tool error carrying the API's own message is something a caller
+  can actually react to, and the message is passed through untouched so it can.
+- **The output format is detected from the returned bytes, not from the request.** The API
+  sometimes answers a webp request with PNG data, and a file named `.webp` holding PNG bytes
+  breaks whatever opens it next, far away from the cause. Files are now named after their real
+  content and the result reports what was written, which means `output_format` in a result can
+  differ from the `output_format` you asked for. That is the deliberate behaviour.
+- **Default timeouts raised to 300 seconds.** gpt-image-2 plans before it draws, and complex
+  prompts can take up to two minutes, with large sizes at the top of that range. The old
+  180-second budget cancelled calls that would have succeeded.
+- **Python floor raised to 3.12**, and dependencies moved to `fastmcp>=3.4.7,<4` and
+  `openai>=3.0,<4`. The FastMCP floor is where Starlette is pinned above CVE-2026-48710, and an
+  OpenAI SDK older than 3.0 predates gpt-image-2 entirely.
+
+### Removed
+
+- **The `model` parameter on the tools.** With one supported model, a per-call override could
+  only ever be a way to get an error from OpenAI. The model is a server setting now, which is
+  also the right place for a decision about reproducibility.
+- **`input_fidelity` on `edit_image`.** gpt-image-2 always processes input images at high
+  fidelity, so the parameter has nothing left to select. Faces, logos and lettering survive an
+  edit without a setting to remember, which is a straight improvement: forgetting to raise it was
+  the usual reason a logo came back smudged.
+- **`background="transparent"`.** gpt-image-2 does not support transparent backgrounds and the
+  API refuses the value, so it is absent from the schema and a client asking for it gets an
+  immediate schema error rather than a billed refusal. This is a real regression against the
+  previous generation: pipelines that relied on a cut-out subject now need a mask or an external
+  background remover.
+- **HTTP transport and the cloud entrypoint.** The streamable-http mode, the `PORT` variable and
+  the root-level `fastmcp_server.py` are gone. Every real use of this server was a local MCP
+  client spawning it on stdio, and the HTTP path carried a deployment story, an authentication
+  question and a surface area that nothing was using.
+- **The Docker image and its Dockerfile.** They existed to serve the HTTP mode, and they went
+  with it. A stdio server is started by its client and has nothing to containerise.
+- **The `response_format` parameter.** It belonged to the DALL-E models and returns a 400 on
+  gpt-image-2, which returns base64 through `output_format` directly.
+
+### Fixed
+
+- **Concurrent calls sharing a prompt no longer overwrite each other.** Filenames carry a UTC
+  timestamp with microsecond precision, so two tools invoked at the same moment with the same
+  prompt write two files rather than one.
+- **A malformed API payload no longer writes a broken file.** Bytes that are not a PNG, a JPEG or
+  a WEBP are refused with a typed error and nothing is written, instead of leaving a file on disk
+  that fails to open later.
+- **File descriptors no longer stay open across an await in `edit_image`.** Input images are read
+  into memory and sent as multipart tuples, so a slow API call cannot hold handles open for its
+  duration.
+
+## 0.1.0
+
+Initial release, as `openai-imagegen-mcp`. Two tools, `generate_image` and `edit_image`, on
+`gpt-image-1.5`, over stdio or streamable-http. Never published to PyPI, so 0.2.0 is the first
+version anyone can install.

mcp_gpt_image-0.2.0/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md, mcp-gpt-image
+
+## Purpose
+
+MCP server exposing OpenAI's `gpt-image-2` as three tools: `generate_image`,
+`edit_image` and `refine_image`. The point of the server is chaining: Claude
+generates a picture, feeds the returned path back in, and keeps correcting it.
+
+## Architecture
+
+Three layers, dependencies pointing inward only.
+
+- **Domain** (`domain/`): `types.py` holds every Literal alias and constant that
+  mirrors an API constraint; `results.py` the data carried between layers;
+  `image_store.py` the only module that writes files; `errors.py` the exception
+  hierarchy. Imports neither `openai` nor `fastmcp`.
+- **Adapters** (`adapters/`): `images_client.py` for `/v1/images`,
+  `responses_client.py` for the Responses API image tool, `_errors.py` for the
+  single translation from SDK exceptions to domain errors. The only modules that
+  call the OpenAI SDK. `server.py` names `AsyncOpenAI` too, but for a type
+  annotation on the injection seam, never to make a call.
+- **Tools** (`tools/`): one file per MCP tool, plus `_base.py` (dependency bundle
+  and the error decorator) and `_validation.py`.
+- **Composition root**: `server.py`. Nothing else builds a client or a store.
+
+## Key conventions
+
+- **Tool discovery is automatic.** `tools/__init__.py` imports every module in the
+  package that does not start with `_` and calls its `register(mcp, deps)`. A tool
+  module without that function raises at startup. Adding a tool means adding a
+  file; helpers must be underscore-prefixed or they will be treated as tools.
+- **The schema is the validation.** `Literal` aliases and `Field(ge=, le=)`
+  become enums and bounds in the MCP tool schema, so the client is refused before
+  a call is billed. `_validation.py` only holds what JSON Schema cannot express:
+  parsing a free-form size, and touching the filesystem.
+- **File paths as the interface.** Tools return paths, never bytes. An image never
+  enters the conversation, so passing it between tools costs nothing.
+- **The extension follows the bytes.** `ImageStore.sniff_format` reads the magic
+  bytes and names the file after what actually arrived. The API sometimes answers a
+  webp request with PNG, and a `.webp` file holding PNG bytes breaks the next tool
+  that opens it.
+- **Errors surface as `ToolError`.** The `reports_errors` decorator in
+  `tools/_base.py` converts domain and validation errors. FastMCP passes the
+  message through untouched, which is what lets a calling agent fix its own call.
+  Anything unlisted crashes on purpose.
+- **Async all the way.** `AsyncOpenAI`, awaited directly. There is no
+  `asyncio.to_thread` wrapper any more.
+
+## What gpt-image-2 refuses
+
+Learned the hard way, do not reintroduce:
+
+- `background="transparent"` returns an API error. The `Background` alias has two
+  values for that reason.
+- `input_fidelity` is rejected: the model always works at high fidelity.
+- `response_format` and `style` belong to DALL-E, which was shut down in May 2026.
+- `moderation` exists on generations but not on edits.
+- Inside the Responses `image_generation` tool object, only `quality` is confirmed
+  as a configuration key. Framing and format live on the other two tools.
+
+The model id is the single point of change: `MODEL` in `domain/types.py`, or the
+`GPT_IMAGE_MODEL` variable to pin the `gpt-image-2-2026-04-21` snapshot.
+`ORCHESTRATOR_MODEL` (`gpt-5.6`) is the mainline model driving `refine_image`; an
+image model cannot be the primary model of a Responses call.
+
+## Commands
+
+```bash
+make install   # uv sync --all-extras
+make check     # lint + test, what CI runs
+make lint      # ruff check, ruff format --check, mypy
+make test      # pytest, fully mocked, never hits the network
+make run       # start the server on stdio
+make build     # uv build
+```
+
+## Testing
+
+Every test drives the real MCP surface: `fastmcp.Client(server)` calling tools by
+name. The single seam is `create_server(settings, sdk=...)`, which injects a mock
+in place of `AsyncOpenAI`; there is no `patch()` on an import path. Tests assert on
+what was sent to the SDK as much as on what came back, because half the contract is
+about parameters this server must never send.
+
+Building SDK exceptions in tests needs a duck-typed response object, not a real
+one: `openai` 3.x runs on HTTPX2 and constructing a genuine response is a trap.
+
+## Publishing
+
+Version lives in `pyproject.toml` only. A published GitHub release triggers
+`release.yml`, which checks the tag against that version, runs the gates, builds,
+then uploads through PyPI trusted publishing. No token exists anywhere.

mcp_gpt_image-0.2.0/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Fabien Vauchelles
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+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.
+
+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.

mcp_gpt_image-0.2.0/Makefile

@@ -0,0 +1,29 @@
+.PHONY: install build check lint format test run clean
+
+install:
+	uv sync --all-extras
+
+build:
+	uv build
+
+# What CI runs, and what to run before pushing.
+check: lint test
+
+lint:
+	uv run ruff check src tests
+	uv run ruff format --check src tests
+	uv run mypy
+
+format:
+	uv run ruff format src tests
+	uv run ruff check --fix src tests
+
+test:
+	uv run pytest
+
+run:
+	uv run mcp-gpt-image
+
+clean:
+	rm -rf dist .pytest_cache .ruff_cache .mypy_cache
+	find src tests -name __pycache__ -type d -exec rm -rf {} +