codex-image-generation 0.3.0__py3-none-any.whl

codex_image_generation-0.3.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: codex-image-generation
+Version: 0.3.0
+Summary: A local Codex MCP server for Responses image generation using existing provider credentials
+Keywords: codex,mcp,fastmcp,image-generation,responses
+Author: TangRuoJie
+Author-email: TangRuoJie <3177065378@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Dist: fastmcp>=4.1.4,<5
+Requires-Dist: openai>=3.42.0,<4
+Requires-Dist: pillow>=11.3,<14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Codex Image Generation MCP
+
+为使用中转站的 Codex 提供本地图像生成和编辑工具。安装后，直接告诉 Codex：
+
+> 生成一只阳光、动漫风格的可爱小狗，保存在当前项目中。
+
+Codex 调用 `generate_image`，工具复用用户已有的 Codex URL、API Key 和模型设置，保存原图并返回文件路径和预览。默认直接保存到当前任务目录，也可以指定文件夹、文件名和 PNG / JPEG / WebP 格式。
+
+无需另配图像模型；请求通过 Responses API 的 `image_generation` 工具完成，不发送 `tools[].model`。中转站必须支持这一接口，并允许所选对话模型调用图像工具。
+
+本项目由 TangRuoJie 维护，采用 [MIT 许可证](LICENSE)，是独立社区项目，与 OpenAI 无隶属关系。
+
+## 生成效果展示
+
+示例：阳光下、动漫风格的可爱小狗。
+
+![阳光下坐在草地上的动漫风格可爱小狗](sunny-anime-puppy.png)
+
+## 下载包后安装
+
+当前版本：**0.3.0**。分发包为 `codex-image-generation-0.3.0.zip`，内含 wheel、源码包、安装说明、许可证、配置示例和 SHA-256 校验清单。这是 Python 安装包，需要 [uv](https://docs.astral.sh/uv/getting-started/installation/)；首次安装需要联网下载 Python（如果缺少）和依赖。
+
+分享给别人时，发送 `dist/codex-image-generation-0.3.0.zip` 即可，对方按照包内 `INSTALL.md` 操作。以后公开 Release 后，下载其中的同名附件；GitHub 自动提供的 `Source code.zip` 是源码归档，不是这个安装分发包。
+
+**第 1 步：准备自己的环境。** 对方需要已安装 Codex、已有可用的中转站配置，并安装 uv。执行 `uv --version` 确认命令可用。URL、API Key 和模型复用对方自己的 Codex 配置，不需要复制作者的配置。
+
+**第 2 步：安装并检查。** 解压 ZIP，在包含 `.whl` 文件的解压目录打开终端。下面的命令适用于 Windows PowerShell、macOS 和 Linux：
+
+~~~sh
+uv tool install --python 3.11 ./codex_image_generation-0.3.0-py3-none-any.whl
+codex-image-generation --version
+codex-image-generation --check
+~~~
+
+如果系统找不到 `codex-image-generation`，执行 `uv tool update-shell` 后重新打开终端。版本应显示 `0.3.0`，检查结果应包含 `configured: true`；`connection_verified: false` 是正常的，因为此命令只检查本地配置，不请求中转站。检查失败时，先按 [安装说明中的故障排查](docs/INSTALL.md#常见问题) 修正现有配置。
+
+**第 3 步：生成接入配置。** 执行：
+
+~~~sh
+codex-image-generation --print-config
+~~~
+
+**第 4 步：保存配置。** 将上一步输出的整个 `[mcp_servers.image_generation]` TOML 配置块加入**自己电脑**的 Codex 用户配置文件并保存。这条命令只打印内容，不会自动完成接入。
+
+| 系统 | 默认配置文件 |
+| --- | --- |
+| Windows | `%USERPROFILE%\.codex\config.toml` |
+| macOS / Linux | `~/.codex/config.toml` |
+
+设置过 `CODEX_HOME` 时使用该目录下的 `config.toml`。已有同名 `[mcp_servers.image_generation]` 时替换该节，避免重复。保留已有的模型和 provider 设置。若认证依赖环境变量，启动 Codex 的环境也必须能读取这些变量。
+
+**第 5 步：重启 Codex 并验证。** 保存配置后重启 Codex，打开需要保存图片的项目，确认 MCP 已加载且包含 `generate_image` 工具。首次测试可以明确说：
+
+> 请使用 image_generation MCP，生成一只阳光、动漫风格的可爱小狗，保存在当前项目中。
+
+成功时应收到原图路径，并能在当前项目目录找到图片；仅安装成功或 `--check` 通过不代表已经验证上游出图能力。之后日常直接描述图片和保存位置即可，Codex 会按配置启动服务，无需每次安装或手动常驻一个终端。
+
+安装过程不会自动修改 Codex 配置。生成的接入配置使用安装环境中 Python 的绝对路径，不依赖项目源码目录或下载目录；常规安装完成后可以删除解压文件。包内不包含发布者的 URL、API Key 或 Codex 配置。
+
+完整的安装、升级、卸载、离线限制和故障排查见 [安装说明](docs/INSTALL.md)。也提供 [本地 wheel 的 uv 启动配置](examples/codex-uvx.toml)，采用该方式时需要保留 wheel。
+
+## 日常使用
+
+| 你对 Codex 说 | 工具行为 |
+| --- | --- |
+| 生成一张安静的书桌插画 | 在当前任务目录保存唯一命名的 PNG |
+| 生成透明背景的茶杯图标，存到 assets/tea.webp | 保存到指定目录，使用 WebP 和透明背景 |
+| 把这张图片中的沙发改成蓝色 | 将参考图传给上游进行编辑 |
+| 按上一张继续调整，光线暖一些 | 在同一 provider 支持历史引用时继续编辑 |
+
+风格可以是写实、动漫、插画、像素画、海报等，由提示词和上游图像模型决定。本项目封装官方 Responses 图像工具的调用方式；不保证与 ChatGPT 网页或 Codex 内置工具的模型路由、全部功能、界面和效果完全相同。
+
+支持的主要能力：
+
+- PNG、JPEG（含 `jpg` 别名）、WebP 静态图片；透明背景使用 PNG / WebP。
+- 尺寸、质量、背景、JPEG / WebP 压缩率等选项，具体可用值由上游模型决定。
+- 参考图、蒙版，以及同一 provider 的历史响应 / 图像 ID。
+- 可选流式中间图与 MCP 进度；客户端是否实时显示取决于其支持。
+- 原图落盘、受大小限制的预览、绝对路径和结构化结果。
+- 已有文件不覆盖；部分图片失败时保留成功结果；不会自动重试付费生成。
+
+不输出 SVG、GIF 动画或视频。所有参数、返回字段和限制见 [工具参考](docs/TOOLS.md)。
+
+## 模型、凭据与当前目录
+
+工具公开参数只有一个必需的业务输入 `prompt`，以及由 Codex 从任务上下文提供的绝对工作目录 `cwd`。用户不必在每次对话中手动填写路径；没有指定输出位置时，直接保存到 `cwd`。
+
+模型选择顺序：
+
+1. Codex 能可靠获知当前会话的精确 API 模型 ID 时，调用时传入 `current_model`。
+2. 未传入时，读取所选 Codex 配置中的 `model`。
+3. 两处都没有模型时明确报错，不硬编码兜底模型。
+
+普通 MCP 协议不保证提供当前会话模型。因此，界面临时切换模型后能否立即同步，取决于 Codex 是否传入可靠上下文；不能仅凭读取配置文件就承诺跟随所有界面切换。`current_model` 是调用参数，无需用户另建模型配置。
+
+连接设置只读取所选用户级 Codex provider：
+
+- 复用 `base_url`、环境变量 API Key、配置中的 bearer token、请求头和查询参数。
+- 在所选 provider 要求 API Key 认证时，支持读取 Codex 文件存储的 API Key。
+- 支持已有 profile；使用 `--profile` 选择。
+- 不扫描其他 provider 寻找密钥，不读取项目 `.env`，不实现 ChatGPT OAuth 或系统钥匙串登录。
+
+`--print-config` 会生成所需环境变量**名称**的白名单，不复制密钥值。若 provider 使用环境变量认证，启动 Codex 的环境也必须能访问这些变量。
+
+| 可选启动设置 | 用途 |
+| --- | --- |
+| `--codex-home` / `CODEX_HOME` | 定位已有 Codex 配置目录 |
+| `--profile` / `CODEX_IMAGE_PROFILE` | 选择已有 profile |
+| `CODEX_IMAGE_TIMEOUT` | 上游超时秒数，默认 300，范围大于 0 且不超过 3600 |
+
+## 系统兼容性
+
+项目使用 Python 3.11+，wheel 为 `py3-none-any`，不写死开发者目录。依赖中包含本机二进制组件，因此这一标签不表示任意旧系统都能直接安装。
+
+| 平台 | 验证情况 |
+| --- | --- |
+| Windows x64 | 本地测试、安装包独立环境启动和 stdio 验证 |
+| Linux x64 | 容器内安装、测试和 stdio 验证 |
+| macOS Apple Silicon | 已检查依赖 wheel 可获取；尚无 macOS 实机运行验证 |
+| macOS Intel | 当前 cryptography 50 系列缺少 Intel wheel，可能需要本机构建；尚未验证完整安装 |
+
+建议使用仍受支持的现代系统。旧版 Linux（例如 glibc 2.17）可能缺少当前 Pillow 的预编译包。首次安装需要联网；不将此包描述为免依赖、完全离线的可执行文件。
+
+## 源码开发与构建分发包
+
+仅使用工具时无需下载源码。维护项目时，在源码目录执行：
+
+~~~sh
+uv sync --locked
+uv run --locked python -B -m unittest discover -s tests -v
+uv run --locked python scripts/build_release.py
+uv run --locked python scripts/smoke_wheel.py --wheel dist/codex_image_generation-0.3.0-py3-none-any.whl
+~~~
+
+构建输出：
+
+~~~text
+dist/
+  codex_image_generation-0.3.0-py3-none-any.whl
+  codex_image_generation-0.3.0.tar.gz
+  codex-image-generation-0.3.0.zip
+  SHA256SUMS-0.3.0.txt
+~~~
+
+构建脚本检查包内容，不纳入本地配置、凭据或虚拟环境。源码包包含 README 使用的展示图 `sunny-anime-puppy.png`，其他生成图片不纳入；wheel 不包含展示图。安装冒烟测试使用临时安装目录、假凭据和无网络图像请求，从其他工作目录验证 CLI 与 MCP；不会替换你的全局安装。
+
+仓库包含 Windows、Linux、macOS 的 CI 工作流，执行测试、打包和安装验证，并保存构建产物。维护者可手动运行发布工作流，为已存在的版本标签创建 GitHub Release 草稿；只有全部检查通过才会创建草稿。工作流是否通过以实际运行结果为准。当前产物在本地构建，尚未上传 PyPI 或其他公开下载服务；不要将裸命令 `uvx codex-image-generation` 视为已验证的安装入口。
+
+详见 [发布维护说明](docs/RELEASING.md) 和 [更新记录](CHANGELOG.md)。
+
+## 贡献、反馈与许可
+
+- 作者：TangRuoJie；邮箱：[3177065378@qq.com](mailto:3177065378@qq.com)。
+- 贡献代码或改进文档，请先阅读 [贡献指南](CONTRIBUTING.md)。
+- 普通问题可通过仓库 Issues 反馈；漏洞或凭据泄漏请按 [安全报告说明](SECURITY.md) 私下联系。
+- 本项目采用 [MIT 许可证](LICENSE)，允许使用、修改和商业分发，分发时需保留版权及许可声明。第三方依赖遵循各自的许可证。
+
+## 官方参考
+
+- [Responses 图像生成工具](https://developers.openai.com/api/docs/guides/tools-image-generation)
+- [Responses Create API](https://developers.openai.com/api/reference/resources/responses/methods/create)
+- [Codex MCP 配置](https://developers.openai.com/codex/mcp)
+- [Codex 配置参考](https://developers.openai.com/codex/config-reference)

codex_image_generation-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+codex_image_generation/__init__.py,sha256=H7nTbAzkK3C6JxhF9YrKONoC1H-QQuWd3QpyzlQGsEU,186
+codex_image_generation/__main__.py,sha256=Gy54Uxu1CdZCQzCFewyVRqDgvKoqu7dFQ7q1vO2Ceis,115
+codex_image_generation/cli.py,sha256=jSsQBWsqIY3OLg1M3m2VPVgYlEvZUjIKFdH4Q3XfebE,3059
+codex_image_generation/config.py,sha256=qV-F7_JkzKF7MBSRsn02dZE0K3FKb8U-rR8i1UyZAiY,19187
+codex_image_generation/errors.py,sha256=zaynRJaawkWNxY8rQaH2p4Kqnp4rDkMyIPDg7qYpn2g,159
+codex_image_generation/generator.py,sha256=JK5TBnFfZIk6OLFJbhSqr0afioY9psF36wwwWpbFJE4,32791
+codex_image_generation/server.py,sha256=bme9bDe3EzwvIensN8Ne95iMd74Y-E5DnAIS9DcOJJc,13836
+codex_image_generation/storage.py,sha256=6ZQZnvB9um0qpIMbZjy7xTYcv6aVNIumuICnKiPY8_0,21773
+codex_image_generation-0.3.0.dist-info/licenses/LICENSE,sha256=rmlbW-0RPtyhDatbGAROzen6akA6RGz-cpYXxAWkA9E,1067
+codex_image_generation-0.3.0.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
+codex_image_generation-0.3.0.dist-info/entry_points.txt,sha256=ckqmeCr4jHbi-emfK-3fmuCLkAlR4il0XTZbwaMhw2w,72
+codex_image_generation-0.3.0.dist-info/METADATA,sha256=uhzB0OppbYkRhkVm0s7VZ0c6kqj7IbRSujs_h6yd8No,11425
+codex_image_generation-0.3.0.dist-info/RECORD,,

codex_image_generation-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.23
+Root-Is-Purelib: true
+Tag: py3-none-any

codex_image_generation-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+codex-image-generation = codex_image_generation:main
+

codex_image_generation-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TangRuoJie
+
+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.