# aidada-image

用于完整控制 **OpenAI Images API** 的 MCP 服务。支持生图、图片编辑、多图参考、蒙版、流式预览和任务恢复；每次请求都可以选择模型与参数。

可独立接入支持 stdio MCP 的 Agent，也可通过 Magpie 的 MCP 库管理。使用者提供自己的 OpenAI API 凭据，不需要作者的 Magpie 配置。

## 快速安装

需要 Node.js 22 或更高版本，以及 npm。

```sh
git clone https://github.com/aidada/aidada-image.git
cd aidada-image
npm ci
npm run build
node dist/index.js --doctor
```

也可从 [GitHub Releases](https://github.com/aidada/aidada-image/releases) 下载已经编译的 `.tgz` 安装包。克隆构建更适合查看源码或修改代码。

最后一步只检查本地配置，不发起图片请求。未配置凭据时 `key_present=false` 是正常状态。没有发布 npm registry 包，不要直接运行 `npx aidada-image`；请使用上面克隆构建的版本。

## 接入 Agent

在 Agent 的 MCP 设置中添加以下 stdio 配置，或参考 [examples/mcp.json](examples/mcp.json)。替换两个绝对路径，并在自己的客户端配置或其凭据管理功能中提供 `OPENAI_API_KEY`。

```json
{
  "mcpServers": {
    "aidada-image": {
      "command": "node",
      "args": ["/absolute/path/to/aidada-image/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "SET_LOCALLY_DO_NOT_COMMIT",
        "AIDADA_IMAGE_OUTPUT_DIR": "/absolute/path/to/image-output"
      }
    }
  }
}
```

示例中的凭据占位符不能用于真实调用。配置完成后重新加载 MCP 或开启新的 Agent 会话。若桌面 Agent 找不到 `node`，将 `command` 改为本机 Node 的绝对路径。不同客户端的配置外层结构可能不同，`command`、`args`、`env` 的内容相同。

先调用 `aidada_image_capabilities` 检查 `key_present` 和参数，再调用 `aidada_image_models` 查看自己账户可用的模型。默认模型为 `gpt-image-2.6-sunburst`，也可通过环境变量或每次请求的 `model` 修改。模型、预览功能和参数组合是否可用，由 OpenAI 账户权限与上游接口决定。

## 可以直接这样说

> 用 aidada-image 生成一个青瓷绿和香槟金的三维游戏图标，model 使用我的账户可用的图片模型，complexity=high、quality=max、size=1024x1024、background=transparent、output_format=png。只提交一次，完成后展示图片。

> 用 aidada-image 编辑这张图片，保留构图和人物动作，只修改衣服颜色。图片路径是 /absolute/path/to/reference.png。输出 1440x2560 的 PNG。

完整参数样例见 [生图 JSON](examples/generate.json) 和 [编辑 JSON](examples/edit.json)。这些样例使用 Sunburst 参数；换用其他模型时，需要按其能力调整。`quality` 与 `complexity` 独立控制，不将其中一个替换成另一个。

## 工具

| 工具 | 用途 |
| --- | --- |
| `aidada_image_capabilities` | 查看默认配置、参数约束及凭据是否存在 |
| `aidada_image_models` | 查询当前账户可见的图片模型 |
| `aidada_image_generate` | 文字生图；支持模型开放的 PNG/JPEG/WebP/SVG/GIF |
| `aidada_image_edit` | 编辑、扩图、多图合成、蒙版、标注引导 |
| `aidada_image_result` | 查询进度、预览、原图资源、用量与请求记录 |
| `aidada_image_cancel` | 中止本地请求，保留已经收到的图片 |
| `aidada_image_jobs` | 找回近期本地任务及 `job_id` |
| `aidada_image_upload` | 持久上传参考图，获得可复用的 `file_id` |

支持 `model`、`complexity`、`quality`、`size`、`background`、`n`、`output_format`、`output_compression`、`stream`、`partial_images`、`mask`、`markup`、`input_fidelity` 等字段；完整说明见 [API 覆盖表](docs/API-COVERAGE.md)。

未填写的参数保持省略，由上游采用默认值。尚未进入 schema 的新字段可通过 `extra_body` 传递，不能覆盖已经命名的字段。MCP 能传递字段，不代表所有模型都接受该字段。服务包装 Images API，不包装 Responses API 的多轮对话编排。

## 任务与图片

生成、编辑默认等待 1 秒，返回 `job_id`。如果状态为 `running`，继续调用 `aidada_image_result` 查询同一个任务，单次 `wait_ms` 最长 20000。不要因为等待结束而重复提交。

参考图支持 `{path}`、`{image_url}`、`{file_id}`，最多 16 张。纯本地文件通过 multipart 发送；混合引用时，本地文件临时上传后尝试删除。显式调用 `aidada_image_upload` 的文件会保留。

原图保存在输出目录下的 `<job_id>/final-*`，通过 MCP 资源或本地绝对路径读取。`include_preview=true` 返回总计不超过 4 MiB 的受支持内联图片，更大的图片仍可读取原图资源。

每个任务还保存请求参数、响应、用量和状态。这些记录可能包含提示词、参考图片路径和图片内容，默认 `generated/` 已被 Git 忽略。服务退出会终止该进程尚未完成的请求；重启可读取已经保存的图片，但不会自动重发收费任务。

独立 CLI 在已经配置 `OPENAI_API_KEY` 后可使用：

```sh
node scripts/call.mjs aidada_image_capabilities
node scripts/call.mjs aidada_image_jobs
```

该客户端在生图过程中会持续持有 MCP 连接，并查询同一个任务直到结束。没有 `OPENAI_API_KEY` 时，此便捷脚本会尝试使用本机 Magpie 的 `openai` provider。

## 可选：通过 Magpie 管理

仅在已安装 Magpie、且配置了 `openai` provider 时使用：

```sh
node scripts/start-magpie.mjs --doctor
node scripts/install-magpie.mjs --dry-run --agents codex,claude
node scripts/install-magpie.mjs --agents codex,claude
node scripts/check-magpie.mjs
```

将 `--agents` 替换为自己的 Agent 名称。不指定时，安装器采用当前 Magpie 库中已有 MCP 的目标 Agent 集合。`--dry-run` 只展示即将注册的路径和目标；实际安装只对本条目设置 `local + direct`。

启动器只在进程内读取当前使用者的 Magpie provider key，`OPENAI_API_KEY` 若存在则优先使用。不会将密钥写进项目或其他 Agent 配置。Magpie 不在默认位置时，可通过 `MAGPIE_BINARY` 指定 CLI 路径。

项目目录搬动后需要重新核对 MCP 的绝对路径；安装器遇到同名但不同路径的条目会停止，避免覆盖。移除接入使用 `magpie library mcp rm aidada-image`，生成的图片仍然保留。

## 环境变量

| 变量 | 说明 |
| --- | --- |
| `OPENAI_API_KEY` | 使用者自己的 API key，优先于 Magpie |
| `OPENAI_BASE_URL` | 默认 `https://api.openai.com/v1`；兼容接口必须使用 HTTPS，本机测试地址除外 |
| `OPENAI_ORG_ID` / `OPENAI_PROJECT_ID` | 可选组织、项目请求头 |
| `AIDADA_IMAGE_MODEL` | 默认 `gpt-image-2.6-sunburst`，每次请求可覆盖 |
| `AIDADA_IMAGE_OUTPUT_DIR` | 图片和任务目录；默认项目目录下 `generated/`，建议明确指定绝对路径 |
| `AIDADA_IMAGE_TIMEOUT_MS` | 单任务超时，默认 `1200000` |
| `AIDADA_IMAGE_MAX_CONCURRENT` | 每个服务进程的并发上限，默认 `2` |
| `AIDADA_IMAGE_INPUT_ROOTS` | 可选输入目录范围，使用系统 PATH 分隔符分隔 |
| `AIDADA_IMAGE_MAGPIE_PROVIDER` | 启用 Magpie 凭据读取；专用启动器默认 `openai` |
| `AIDADA_IMAGE_MAGPIE_CONFIG` | 可选 providers.json 路径，默认当前用户的 Magpie 配置 |
| `AIDADA_IMAGE_HTTP_TOKEN` | HTTP 模式的访问令牌，至少 16 字符 |

也支持本机 Streamable HTTP：配置 `AIDADA_IMAGE_HTTP_TOKEN` 后运行 `node dist/index.js --http --port 3438`，客户端连接 `http://127.0.0.1:3438/mcp` 并携带 Bearer 令牌。只监听 loopback，验证 Host、Origin 和令牌；它不是公网多租户服务。

## 开发与验证

```sh
npm test
npm run check
```

集成测试只访问本机 mock 上游，不调用付费 OpenAI 图片接口。覆盖现代/旧 MCP 协议、请求字段、JSON/multipart、流式、资源、取消、跨进程任务和 HTTP 鉴权。

可选真实验收使用 `node scripts/live-smoke.mjs`，会实际生成和编辑各一张图片，产生 API 用量。普通安装和单元测试不需要运行它。

该服务没有产品 UI，主要采用 CLI 和真实 MCP 客户端验收。包括可选内置浏览器 Inspector 在内的步骤、预期、失败判断与恢复方式见 [验收清单](docs/ACCEPTANCE.md)。已在作者环境验证生图、编辑、透明背景、流式、最高质量及 2K/4K 图片；没有逐项实测所有模型和 SVG/GIF/蒙版组合。

项目锁定 MCP 协议 `2026-07-28`、官方 TypeScript server/client SDK `2.4.0`，保留旧客户端协议协商。长任务采用显式 `job_id` 工具流程，不声称实现可选 Tasks 扩展。

## 许可证

[MIT](LICENSE)。可以使用、修改和分享代码；API 服务的访问权限与费用由使用者自己的账户承担。