# Image Foundry

一个调用 PackyAPI `gpt-image-2` 的本地图片工作台，同时提供标准 MCP Server，方便 Codex 直接调用。

## 1. 配置 API Key

MCP Server 从环境变量或项目根目录的 `.env` 读取 Sora 分组令牌，不把令牌放进代码或 Codex 配置文件。最方便的方式是：

```bash
cp .env.example .env
# 然后编辑 .env，填入 PACKY_API_KEY
```

`.env` 已加入 `.gitignore`，不会被提交。

可选环境变量：

```bash
export PACKY_API_BASE_URL="https://www.packyapi.com"
export IMAGE_FOUNDRY_OUTPUT_DIR="$HOME/Code/create_image/output"
```

## 2. 接入 Codex

在终端执行：

```bash
codex mcp add image_foundry --env PACKY_API_KEY="$PACKY_API_KEY" --env PACKY_API_BASE_URL="https://www.packyapi.com" -- node "$HOME/Code/create_image/mcp-server.mjs"
```

确认注册成功：

```bash
codex mcp get image_foundry --json
```

如果你不想使用 `.env`，也可以让 MCP 进程继承当前 shell 的环境变量：

```bash
codex mcp add image_foundry -- node "$HOME/Code/create_image/mcp-server.mjs"
```

注册后重新打开一个 Codex task，Codex 就能发现这些工具：

- `generate_image`：根据提示词生成图片
- `edit_image`：编辑本地图片，可选传入 mask
- `get_image_config`：查看模型、API 地址和输出目录，不会返回 API Key

示例请求：

```text
请用 generate_image 生成一张横向 1536x1024 的图片：雨夜的上海街头，霓虹灯倒映在湿地面上，电影感摄影。
```

生成文件默认位于 `~/Code/create_image/output/`。调用 `edit_image` 时，把本地图片的绝对路径传给 `image_path`。
编辑请求默认不发送 `input_fidelity`，行为与 PackyAPI 官方 curl 示例一致；确实需要最大程度保留原图细节时可显式传入 `input_fidelity: "high"`。

## 3. 启动本地 Web 服务(可选, 可以不依赖智能体直接使用 Web 端制图)

进入当前项目后执行:
```bash
npm run dev
```

然后打开 <http://127.0.0.1:4173/>。页面只调用本地同源接口，API Key 由 Node 后端从项目根目录的 `.env` 读取，不会进入页面、浏览器存储或网络请求代码。

可用配置：

```bash
IMAGE_FOUNDRY_WEB_PORT=4173
PACKY_REQUEST_TIMEOUT_MS=600000
```

图片生成和高清编辑经常超过 60 秒，默认上游超时为 10 分钟。服务日志会输出请求 ID、接口阶段、尺寸、质量、文件大小、耗时和状态码，但不会记录 API Key、图片内容或完整提示词。

## 4. MCP 传输说明

`mcp-server.mjs` 使用 MCP 标准 stdio JSON-RPC 传输，不依赖第三方 npm 包，Codex 通过启动命令拉起它。图片编辑的上游上传使用 macOS/Linux 自带的 `curl`(powershell 可能需要额外适配)，避免 Node `fetch` 在长时间图片生成连接中约 60 秒被中断；API Key 通过 curl 配置 stdin 传递，不会出现在进程命令行。服务只向 stdout 输出 MCP 消息，诊断信息写入 stderr，适合被 Codex 稳定托管。