OpenAI Image

@mindstone/mcp-server-openai-image

OpenAI 图像生成 MCP 服务——通过 OpenAI 的 gpt-image-2 进行文生图和图像编辑，具备清晰的文本渲染、多语言提示词、四种质量等级和三种宽高比。

工作区沙盒化的 OpenAI 图像 MCP。生成的 PNG 仅保存到 MCP_WORKSPACE_PATH 下，每个错误都会返回结构化恢复代码，且 API 密钥被硬性限定为 api.openai.com。

状态

• 版本： 0.3.2 · npm
• 身份验证： API 密钥（OPENAI_API_KEY）
• 工具： 2（图像生成、图像编辑）
• 类型： cloud-api
• 机器可读： STATUS.json

为什么创建此项目

2026 年初我们启动此连接器时，OpenAI 尚未为其图像生成功能发布 MCP 服务，而现有的社区方案要么内置自己的下载守护进程，要么将生成的字节写入主机上不受限制的路径。我们自行开发此服务，让 MCP 主机能够调用 generate_image 和 edit_image，并享有与本仓库其他部分一致的沙盒隔离、错误恢复约定和密钥处理保障——保存的 PNG 会存放在经过 realpath 限定的工作区下，每个错误都会以结构化的 { ok, code, error, resolution } 对象返回，OpenAI API 密钥则被硬性限定为 https://api.openai.com，因此攻击者控制的环境无法将提示词、图像字节或 bearer token 重定向到其他位置。

交互示例

“生成一幅 1024x1536 的竖幅肖像：柔和的晨光中，一匹比利时挽马拉着一辆啤酒厂马车。”

主机调用的工具：

1. generate_image — 提交提示词，参数为 size: portrait、quality: high、count: 1。

响应（节选）：

{
  "ok": true,
  "saved_paths": [
    "/Users/me/workspace/Chief-of-Staff/generated-images/20260519-1530-a1b2c3.png"
  ],
  "model": "gpt-image-2",
  "size": "1024x1536",
  "quality": "high"
}

失败时：

{
  "ok": false,
  "code": "WORKSPACE_FENCE_VIOLATION",
  "error": "Reference image is outside your workspace and folders linked as Spaces. Path: <workspace>/linked.png. Workspace: /Users/me/workspace.",
  "resolution": "Move or copy the file into your workspace or a folder linked as a Space, then try again."
}

要求

• Node.js 20.3+
• npm
• 具有图像生成权限的 OpenAI API 密钥

一键安装

点击按钮后，主机会提示你填写：OPENAI_API_KEY、OPENAI_IMAGE_MODEL、OPENAI_IMAGE_REQUEST_TIMEOUT_MS。

{
  "mcpServers": {
    "OpenAI Image": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-openai-image"
      ],
      "env": {
        "OPENAI_API_KEY": "",
        "OPENAI_IMAGE_MODEL": "gpt-image-2",
        "OPENAI_IMAGE_REQUEST_TIMEOUT_MS": "180000"
      }
    }
  }
}

快速开始

安装和构建

cd <path-to-repo>/connectors/openai-image
npm install
npm run build

npx（发布后使用）

npx -y @mindstone/mcp-server-openai-image

本地运行

node dist/index.js

配置

环境变量

• OPENAI_API_KEY — OpenAI API 密钥。调用工具时必需；如果未设置，服务会以未配置模式启动，每次工具调用都会返回结构化的 NOT_CONFIGURED 响应，而不会崩溃。
• MCP_WORKSPACE_PATH — 可选的工作区路径。生成的图像会写入 <workspace>/Chief-of-Staff/generated-images/。未设置时默认为 ~/Pictures/MCP-Generated-Images/。
• OPENAI_IMAGE_MODEL — 可选的模型覆盖值。默认为 gpt-image-2。
• OPENAI_IMAGE_REQUEST_TIMEOUT_MS — 可选的 OpenAI 图像 API 超时覆盖值（正整数，单位为毫秒，最长 30 分钟）。默认值：180000（3 分钟）。该值适用于 quality: 'high' 的生成；OpenAI 文档称复杂提示词最长可能需要约 2 分钟；如需更严格的时限，可调低此值。
• MCP_ALLOWED_SYMLINK_ROOTS — 可选的绝对路径 JSON 数组。连接器会通过工作区内的符号链接读取（并写入生成的图像），这些符号链接的规范目标必须位于 MCP_WORKSPACE_PATH 或其中某个声明的根路径内——这些根路径与宿主内置文件工具信任的已声明 Spaces 相同。失败时采取关闭策略：如果该值缺失、为空、JSON 格式错误、不是数组，或任何条目不是字符串、为空或为相对路径，则整个值都会被拒绝，连接器会回退到严格的仅限工作区范围检查，并输出一条结构化的 stderr 警告。独立使用开源版本的用户无需设置；Rebel 宿主会根据你声明的 Spaces 自动注入该值。
• MCP_HTTP_PORT — 可选。设置后，服务会在此端口通过 HTTP 提供 MCP 服务，并绑定到 127.0.0.1（仅限回环地址；非回环 Host 标头会被拒绝），而不是使用 stdio。适用于由宿主管理的本地部署；使用 stdio 的宿主无需设置。

宿主配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "OpenAIImage": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-openai-image"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Mindstone Rebel

在 Rebel 的连接器选择器中使用目录条目。Rebel 会从你配置的提供商密钥中注入 OPENAI_API_KEY，并将 MCP_WORKSPACE_PATH 指向你的活动工作区。

本地开发（无需发布 npm 包）

{
  "mcpServers": {
    "OpenAIImage": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/openai-image/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace"
      }
    }
  }
}

工具（2 个）

generate_image

输入：

• prompt（字符串，必需）— 要生成的图像的文字描述。
• size（square | portrait | landscape，可选）— 1024x1024、1024x1536、1536x1024。
• quality（low | medium | high | auto，可选）— 默认为 high。medium 通常需要约 50 秒，费用为 $0.04；high 最长可能需要 3 分钟，费用约为 $0.21。较低的质量设置可大幅降低费用。
• count（整数 1–8，可选）— 默认为 1。费用随数量线性增长。
• moderation（auto | low，可选）— 内容审核严格程度，默认为 auto。low 会降低 OpenAI 对你账户的内容过滤强度，并像其他工具输入一样传递；是否允许调用由宿主的工具审批层负责。
• output_format（png | jpeg | webp，可选）— 输出文件格式，默认为 png。保存的文件扩展名和内联预览 MIME 类型会采用所选格式（.png / .jpg / .webp）。
• output_compression（整数 0–100，可选）— 压缩级别；仅适用于 jpeg 或 webp 输出。与 png 组合时会在任何 API 调用前快速失败，并返回结构化的 INVALID_INPUT 错误。
• background（transparent | opaque | auto，可选）— 背景样式。transparent 会生成带 Alpha 通道的抠图，并要求输出格式为 png/webp，且模型支持透明背景：gpt-image-2 不支持透明背景，因此工具会快速失败并返回 INVALID_INPUT，同时提示将 OPENAI_IMAGE_MODEL 设为 gpt-image-1.5（或 gpt-image-1）。未知的模型覆盖值会传递给上游进行验证，这与连接器现有的 OPENAI_IMAGE_MODEL 处理方式一致。

成功时，返回一个文本内容块，其中包含保存路径，以及最多 5 个内联 image 内容块。失败时，返回结构化的 { ok: false, code, error, resolution } 响应。该工具标注为 destructiveHint: true, openWorldHint: true, idempotentHint: false。

edit_image

输入：

• prompt（字符串，必填）——说明要如何更改输入图像。
• image_paths（包含 1–4 个绝对文件路径的数组，必填）——源图像。每个路径都会经过验证：其词法解析结果必须位于 MCP_WORKSPACE_PATH 内，且其规范化 realpath 必须位于规范化工作区内，或位于 MCP_ALLOWED_SYMLINK_ROOTS 中声明的某个根目录内（与主机内置文件工具的路径限制一致）。位于这两者之外的路径会在任何读取发生前被拒绝，并返回 WORKSPACE_FENCE_VIOLATION。
• mask_path（PNG 路径，可选）——指示要编辑区域的 Alpha 通道蒙版。
• size、quality、count、moderation、output_format、output_compression、background——与 generate_image 的格式相同。

返回与 generate_image 相同的内容结构。注解也相同：destructiveHint / openWorldHint / idempotentHint。

恢复约定

每个工具错误都会以包含以下字段的结构化 JSON 返回：

{
  "ok": false,
  "code": "NOT_CONFIGURED | INVALID_API_KEY | RATE_LIMITED | CONTENT_POLICY | WORKSPACE_FENCE_VIOLATION | MODEL_UNAVAILABLE | NETWORK_ERROR | TIMEOUT | WRITE_FAILED | INVALID_INPUT | INVALID_IMAGE_DATA",
  "error": "Human-readable message",
  "resolution": "Concrete next step for the operator"
}

这种结构化格式可让 Agent 主机将错误路由到恢复流程，而不是直接呈现原始异常文本。

安全说明

• 指定本地文件的工具输入（edit_image.image_paths、edit_image.mask_path）在读取前必须通过两道关卡：先通过词法工作区预检（路径按词法解析后必须位于 MCP_WORKSPACE_PATH 内），再通过规范路径包含性检查（路径的 realpath 必须位于规范工作区内，或位于 MCP_ALLOWED_SYMLINK_ROOTS 中声明的某个根目录内；判断依据是 path.relative 的路径段语义，绝不使用 startsWith）。工作区和声明根目录之外的路径会被拒绝，并返回 WORKSPACE_FENCE_VIOLATION，以防止符号链接逃逸和路径遍历。写入前也会对生成图像的输出目录执行相同的包含性检查，与宿主内置的 Write 工具保持一致。
• 读取采用先打开、再验证的方式，并将围栏判定绑定到已打开的 inode：围栏批准规范路径后，连接器会打开一个文件描述符，通过 fstat 验证打开的 inode 与基准 stat 一致；随后会在打开后重新解析规范路径（要求其与围栏批准的路径逐字节相同），并通过 lstat 检查该路径仍指向已固定的 inode——如果叶子路径在两次检查之间被切换为符号链接再切回，这种切换会被发现，而不会跟随符号链接。在 Linux 上，还会通过 /proc/self/fd/<fd> 解析文件描述符本身（这是内核为已固定 inode 提供的规范路径，不受任何路径名竞态影响），并重新检查其包含性。读取始终通过已固定的文件描述符进行，因此任何时刻发生的路径切换都会以 WORKSPACE_FENCE_VIOLATION 安全失败。**平台说明：**在 macOS/Windows 上（没有 /proc，且 Node 未提供 openat/F_GETPATH），仍存在一个范围有限的风险：本地攻击者若在打开后重新解析与身份检查之间的瞬间，原子替换工作区内的目录路径段，就能重定向该检查。只有当目标文件位于与工作区不同的文件系统时，这种攻击才切实可行（否则，普通硬链接无需任何竞态即可绕过围栏——这是所有操作系统上规范路径前缀包含性检查的一项既有平台限制）；每次尝试失败都会显示为围栏违规错误。在 Linux 上，此类风险已被完全消除。
• 写入绝不会再次信任已验证的路径名：围栏批准输出目录的规范路径后（mkdir 创建目录后会再次完整检查），数据会先暂存到在规范目录内原子创建的全新、不可预测的 mkdtemp 目录中（权限模式为 0700）。该目录不含任何符号链接路径段，因此检查后使用期间，即使有任何路径段被替换为符号链接，也无法重定向写入。文件以 wx（权限模式为 0600）打开，通过单个文件描述符写入，然后通过硬链接放置到目标位置（如果目标名称已被实际文件或预先放置的符号链接占用，link 会因 EEXIST 失败；不支持硬链接的文件系统则回退为在目标位置以独占方式创建文件）。在任何数据流动前，都会重新验证目录的规范身份：暂存写入前、创建硬链接前后，以及回退的独占创建前后。执行期间发生的路径切换会以 WORKSPACE_FENCE_VIOLATION 安全失败，并移除暂存目录。
• 围栏错误仅会显示模型提供的输入路径和工作区根目录，不会显示符号链接目标的规范 realpath，因此 Agent 可以自行修正，而不会泄露链接所指向的 Space 目标。错误中回显的调用方可控值（工具输入路径、配置的模型）会用 <untrusted-content source="…"> 封装，并对结束标签进行转义处理（见 src/untrusted-content.ts），防止经过构造的值关闭结果封装。
• 上游成功响应会进行架构验证（格式错误的响应体会以 NETWORK_ERROR 安全失败），返回的图像字节必须包含所请求格式的魔数；格式不匹配的响应会以 INVALID_IMAGE_DATA 拒绝，而不会以错误的扩展名或 MIME 类型保存。上游错误响应体和状态文本仅用于分类，绝不会出现在模型可见的错误中。
• 生成的文件以 0o600 权限模式写入。
• 日志、结构化错误响应和堆栈跟踪中的 OPENAI_API_KEY 值都会被清除——参见 src/index.ts 中的 sanitizeUserFacingText。
• 默认情况下，提示词和绝对文件路径会从日志输出中脱敏；日志仅记录元数据（数量、大小、耗时、状态码）。
• OpenAI API 基础 URL 固定为 https://api.openai.com；没有环境变量覆盖项。

旧版文件夹迁移

此前在工作区下使用名为 RebelImages/ 的文件夹的宿主，将在首次运行时看到一次性、符号链接安全的重命名，文件夹将改为 MCP-Generated-Images/。此迁移具有幂等性，并会在目标路径已存在时跳过；任一路径存在符号链接都会中止重命名。此迁移仅用于保留现有用户文件；新安装会直接使用 MCP-Generated-Images/。

许可证

FSL-1.1-MIT —— Functional Source License 1.1 版，附带 MIT 未来许可证。该软件将于 2030-04-08 转为 MIT 许可证。