aidada-image

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

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

快速安装

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

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

也可从 GitHub Releases 下载已经编译的 .tgz 安装包。克隆构建更适合查看源码或修改代码。

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

Related MCP server: kie-image-mcp

接入 Agent

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

{
  "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 和 编辑 JSON。这些样例使用 Sunburst 参数；换用其他模型时，需要按其能力调整。quality 与 complexity 独立控制，不将其中一个替换成另一个。

工具

支持 model、complexity、quality、size、background、n、output_format、output_compression、stream、partial_images、mask、markup、input_fidelity 等字段；完整说明见 API 覆盖表。

未填写的参数保持省略，由上游采用默认值。尚未进入 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 后可使用：

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 时使用：

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，生成的图片仍然保留。

环境变量

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

开发与验证

npm test
npm run check

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

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

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

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

许可证

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