# ChatGPT Image Bridge

ChatGPT Image Bridge gives text-only agents a portable image workflow:

1. Generate or edit a raster with the user's signed-in Codex and ChatGPT account.
2. Save it directly to `<project>/assets/generated/` when the caller supplies `project_root`.
3. Inspect, compare, transcribe, or critique it through a separate OpenAI vision turn.
4. Return the vision findings as plain text that any primary model can use.

The repository is an [Agent Plugins 1.0](https://agent-plugins.org/) package. Its actual tool boundary is standard MCP, so it is not tied to Factory, DeepSeek Harness, Codex, Cursor, VS Code, or another individual host.

> [!IMPORTANT]
> This is an independent, experimental bridge. It uses the locally installed Codex `app-server` interface and built-in `imagegen` skill, which are not a stable public provider API. A Codex update can require an adapter update. This project is not affiliated with or endorsed by OpenAI.

## What it exposes

- `imagegen_status`: verify the local Codex login, image entitlement, and vision model.
- `generate_image`: generate an image and optionally save it in an active project.
- `generate_image_edit`: edit one to four local or data-URL references.
- `get_image_job`: recover a generation that outlives the host's normal MCP timeout.
- `analyze_image`: turn a generated job, local image path, or data URL into model-readable visual evidence.

Successful jobs always retain a canonical copy in the plugin data directory. Supplying an absolute `project_root` additionally writes a uniquely named, non-overwriting copy to `assets/generated/`.

## Requirements

- macOS, Linux, or Windows with Python 3.11 or newer.
- [`uv`](https://docs.astral.sh/uv/) on `PATH` for the portable plugin launcher.
- A locally installed Codex executable. The macOS ChatGPT bundle is detected automatically; elsewhere, put `codex` on `PATH` or set `CODEX_BIN`.
- A ChatGPT account signed into Codex with image generation and a model that advertises image input.

The bridge deliberately removes API-key environment variables from the Codex child process. It is designed to use the user's local ChatGPT/Codex login, not silently spend an API key.

Each installation uses the recipient's own local Codex login and account entitlement. The plugin never bundles or transfers the publisher's login, subscription, cookies, or tokens.

## Run locally

```bash
uv sync
uv run chatgpt-image-bridge-mcp --stdio
```

For the MCP Inspector:

```bash
uv run mcp dev src/chatgpt_image_bridge_mcp/server.py
```

For a localhost-only Streamable HTTP endpoint:

```bash
uv run chatgpt-image-bridge-mcp --http --port 8788
```

The endpoint is `http://127.0.0.1:8788/mcp`. HTTP mode has no portable authentication in this alpha release and only accepts loopback bindings. Use stdio for normal installations. A future authenticated network deployment should be a separate, explicitly reviewed feature.

## Install as an Agent Plugin

The portable package entry points are:

- `plugin.json`
- `mcp.json`
- `skills/chatgpt-image-workflow/SKILL.md`

Load the repository directory in any Agent Plugins 1.0 client. The client supplies `PLUGIN_ROOT` and a writable `PLUGIN_DATA`; `mcp.json` launches the server with `uv` over stdio.

Agent Plugins standardizes the package, not a universal install command. Until clients converge on distribution UX, Git remains the most reliable source of truth.

Hosts that expose a separate built-in image tool may choose that tool by name before consulting MCP. If the built-in tool is subscription-gated, explicitly select this plugin's `generate_image` tool or its server namespace. See [client notes](docs/client-notes.md).

## Build the OpenAI/Codex compatibility package

OpenAI's current plugin directory uses a separate `.codex-plugin/plugin.json` package shape. Generate a self-contained compatibility artifact from the same source rather than maintaining a second server implementation:

```bash
python3 scripts/build_openai_plugin.py
```

The result is `dist/openai/chatgpt-image-bridge-mcp/`. It contains the same server and workflow skill, plus OpenAI's `.codex-plugin/plugin.json` and `.mcp.json` manifests. Keeping this as generated output avoids behavioral drift between the cross-vendor package and the OpenAI-specific install artifact.

The builder copies an explicit release allowlist only and rejects symbolic links, Python bytecode, or the local checkout path. This makes the compatibility artifact reproducible from a clean Git checkout and prevents ignored developer files from leaking into a release.

## Configure as plain MCP

Clients that support MCP but not Agent Plugins can launch the same server directly. Adapt the outer configuration shape to the host:

```json
{
  "command": "uv",
  "args": [
    "run",
    "--project",
    "/absolute/path/to/chatgpt-image-bridge-mcp",
    "--locked",
    "--no-dev",
    "chatgpt-image-bridge-mcp",
    "--stdio"
  ],
  "env": {
    "CHATGPT_IMAGE_BRIDGE_MCP_DATA_DIR": "/absolute/writable/path/chatgpt-image-bridge-mcp",
    "UV_PROJECT_ENVIRONMENT": "/absolute/writable/path/chatgpt-image-bridge-mcp/venv"
  }
}
```

## Intended model workflow

For generation:

1. Call `imagegen_status` once.
2. Call `generate_image` with the visual prompt and the active project's absolute root.
3. Use the returned `relative_saved_path` in the website or application.
4. If the task requires visual judgment, call `analyze_image` with the returned `job_id`.
5. Continue using the written analysis as visual evidence. Do not replace the raster with SVG or CSS merely because the primary model is text-only.

For an existing image, call `analyze_image` with exactly one source: `job_id`, `image_paths`, or `image_data_urls`.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `CODEX_BIN` | auto-detected | Codex executable path |
| `CHATGPT_IMAGE_BRIDGE_MCP_DATA_DIR` | `PLUGIN_DATA` or user data directory | Durable jobs and canonical assets |
| `CHATGPT_IMAGE_BRIDGE_MCP_WORK_DIR` | `<data>/work` | Scratch directory for Codex turns |
| `CHATGPT_IMAGE_BRIDGE_MCP_MODEL` | `account default` | Reserved text/image model choice |
| `CHATGPT_IMAGE_BRIDGE_MCP_VISION_MODEL` | `account default` | Vision-capable Codex model |
| `CHATGPT_IMAGE_BRIDGE_MCP_IMAGE_TIMEOUT` | `1800` | Maximum provider generation seconds |
| `CHATGPT_IMAGE_BRIDGE_MCP_TOOL_WAIT` | `240` | Seconds before returning a recoverable running job |
| `CHATGPT_IMAGE_BRIDGE_MCP_VISION_TIMEOUT` | `240` | Maximum visual-analysis seconds |
| `CHATGPT_IMAGE_BRIDGE_MCP_MAX_IMAGE_BYTES` | `16777216` | Per-image input/output limit |
| `CHATGPT_IMAGE_BRIDGE_MCP_MAX_PENDING_JOBS` | `8` | Maximum queued plus running generation jobs |
| `CHATGPT_IMAGE_BRIDGE_MCP_JOB_RETENTION_SECONDS` | `2592000` | Retain private job metadata and canonical assets; project copies are never cleaned |
| `CHATGPT_IMAGE_BRIDGE_MCP_ALLOWED_ROOTS` | unset | Optional OS-path-separator list restricting readable images and writable project roots |
| `CHATGPT_IMAGE_BRIDGE_MCP_CODEX_ENV_ALLOWLIST` | unset | Optional comma-separated exact environment names passed to Codex; values may reach model tools |

By default, local path access follows MCP's trusted-stdio model: a caller may name any path the account owner can read, while generated project copies are limited to `assets/generated/`. For shared or less-trusted harnesses, set `CHATGPT_IMAGE_BRIDGE_MCP_ALLOWED_ROOTS` to one or more approved project directories.

The Codex child receives a minimal operating environment rather than inheriting the host process environment. Do not add secrets to `CHATGPT_IMAGE_BRIDGE_MCP_CODEX_ENV_ALLOWLIST`.

## Development

```bash
uv sync
uv run ruff check src tests scripts
uv run pytest
uv build
python3 scripts/build_openai_plugin.py
```

The tests use a fake account runtime and make no provider calls or paid image requests. A separate live smoke test is required to prove a particular Codex build and account entitlement.

Before publishing a release, run the commands above from a clean checkout and verify one real generation plus one `analyze_image` follow-up using the packaged plugin in at least one MCP host. Runtime compatibility can change independently of this repository because the Codex app-server bridge is experimental.

## License

MIT. See [LICENSE](LICENSE).