gpt-image-mcp 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +68 -89
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,73 +2,51 @@
2
2
 
3
3
  基于 TypeScript 的本地 `stdio` MCP 服务，调用 GPT Image 完成文生图、图片编辑和参考风格创作，图片保存在本机，返回绝对路径及文件 URI。
4
4
 
5
- ## 安装与运行
5
+ ## 安装与配置
6
6
 
7
- 需要 Node.js 22 或更高版本，以及具有所选模型调用权限和可用额度的 OpenAI 或兼容服务商 API 密钥。支持 Linux、macOS 和 Windows；图片处理依赖 sharp 的平台二进制包，请在目标机器运行安装命令，不要跨系统复制 `node_modules`。
7
+ 需要 Node.js 22 或更高版本，以及具有所选模型调用权限和可用额度的 OpenAI 或兼容服务商 API 密钥。支持 Linux、macOS 和 Windows。无需手动安装，通过 `npx` 自动下载运行。
8
8
 
9
- ### 通过安装包使用
9
+ ### Claude Code
10
10
 
11
- 当前可分发 `gpt-image-mcp-0.2.0.tgz`，尚未发布到公共 npm 注册表。收到安装包后，在文件所在目录执行：
11
+ 一条命令完成配置（仅当前项目生效）：
12
12
 
13
13
  ```sh
14
- npm install --global ./gpt-image-mcp-0.2.0.tgz
15
- gpt-image-mcp --help
14
+ claude mcp add image-gen -- npx -y gpt-image-mcp
16
15
  ```
17
16
 
18
- 安装时 npm 会获取运行依赖，用户无需安装 TypeScript 或自行构建。每位用户在自己的 MCP 客户端中配置 Key、端点和输出目录。
17
+ 不同作用域：
19
18
 
20
- macOS / Linux 的 MCP 配置示例：
21
-
22
- ```json
23
- {
24
- "mcpServers": {
25
- "image-gen": {
26
- "command": "gpt-image-mcp",
27
- "env": {
28
- "OPENAI_API_KEY": "你的 API 密钥",
29
- "OPENAI_BASE_URL": "https://你的服务商/v1",
30
- "IMAGE_GEN_MODEL": "服务商提供的图片模型名称",
31
- "IMAGE_GEN_OUTPUT_DIR": "~/pictures"
32
- }
33
- }
34
- }
35
- }
36
- ```
19
+ | 命令 | 作用域 |
20
+ | --- | --- |
21
+ | `claude mcp add image-gen -- npx -y gpt-image-mcp` | 当前项目，仅自己可见 |
22
+ | `claude mcp add --scope project image-gen -- npx -y gpt-image-mcp` | 写入 `.mcp.json`，团队共享 |
23
+ | `claude mcp add --scope user image-gen -- npx -y gpt-image-mcp` | 全局，跨项目生效 |
37
24
 
38
- Windows 上 npm 会生成 `.cmd` 启动器，客户端如果无法直接启动它，可将上述命令配置改为：
25
+ 添加后需要设置环境变量。编辑对应配置文件，在 `image-gen` 下添加 `env` 字段：
39
26
 
40
27
  ```json
41
28
  {
42
- "command": "cmd",
43
- "args": ["/d", "/c", "gpt-image-mcp"]
29
+ "env": {
30
+ "OPENAI_API_KEY": "你的 API 密钥",
31
+ "OPENAI_BASE_URL": "https://你的服务商/v1",
32
+ "IMAGE_GEN_MODEL": "服务商提供的图片模型名称",
33
+ "IMAGE_GEN_OUTPUT_DIR": "~/pictures"
34
+ }
44
35
  }
45
36
  ```
46
37
 
47
- 如果 GUI 客户端的 PATH 中没有 npm 全局目录，可运行 `npm root --global` 找到安装位置，再配置 `command: "node"`，将该目录下 `gpt-image-mcp/dist/index.js` 的绝对路径填入 `args`。这个方式适用于三个系统。
48
-
49
- 也可以通过本地压缩包临时运行，无需全局安装（替换为安装包实际路径）：
50
-
51
- ```sh
52
- npx --yes --package="/安装包绝对路径/gpt-image-mcp-0.2.0.tgz" gpt-image-mcp --help
53
- ```
54
-
55
- ### 从源码运行
56
-
57
- ```sh
58
- npm ci
59
- npm run build
60
- ```
38
+ 仅 `OPENAI_API_KEY` 必填，其余按需配置。详见下方[配置](#配置)章节。
61
39
 
62
- 在 MCP 客户端配置中注册服务。通过 `node` 直接运行构建结果，启动位置不影响默认输出目录。
40
+ ### Claude Desktop
63
41
 
64
- macOS / Linux 示例（把项目路径改成实际绝对路径）：
42
+ 编辑 `claude_desktop_config.json`（macOS 路径 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
65
43
 
66
44
  ```json
67
45
  {
68
46
  "mcpServers": {
69
47
  "image-gen": {
70
- "command": "node",
71
- "args": ["/你的项目路径/gpt-image-mcp/dist/index.js"],
48
+ "command": "npx",
49
+ "args": ["-y", "gpt-image-mcp"],
72
50
  "env": {
73
51
  "OPENAI_API_KEY": "你的 API 密钥"
74
52
  }
@@ -77,26 +55,64 @@ macOS / Linux 示例（把项目路径改成实际绝对路径）：
77
55
  }
78
56
  ```
79
57
 
80
- Windows 示例，JSON 中使用正斜杠可避免反斜杠转义：
58
+ ### Cursor
59
+
60
+ 在项目根目录创建 `.cursor/mcp.json`：
81
61
 
82
62
  ```json
83
63
  {
84
64
  "mcpServers": {
85
65
  "image-gen": {
86
- "command": "node",
87
- "args": ["C:/你的项目路径/gpt-image-mcp/dist/index.js"],
66
+ "command": "npx",
67
+ "args": ["-y", "gpt-image-mcp"],
88
68
  "env": {
89
- "OPENAI_API_KEY": "你的 API 密钥",
90
- "IMAGE_GEN_OUTPUT_DIR": "D:/pictures"
69
+ "OPENAI_API_KEY": "你的 API 密钥"
91
70
  }
92
71
  }
93
72
  }
94
73
  }
95
74
  ```
96
75
 
97
- 如果客户端找不到 `node`，将 `command` 替换为本机 Node.js 可执行文件的绝对路径。工具执行超时建议设为至少 360 秒，具体配置字段由客户端决定；服务自身的 API 超时默认为 300 秒。
76
+ ### OpenAI Codex
98
77
 
99
- 服务启动后会等待 MCP 输入，直接在终端运行时没有欢迎输出属于正常行为。日志只写入 stderr，stdout 保留给 MCP 协议。
78
+ 在 `.codex/config.toml` 中配置，需要写全 `npx` 的绝对路径（运行 `which npx` 获取）：
79
+
80
+ ```toml
81
+ [mcp_servers.image-gen]
82
+ command = "/你的npx路径/bin/npx"
83
+ args = ["-y", "gpt-image-mcp"]
84
+
85
+ [mcp_servers.image-gen.env]
86
+ OPENAI_API_KEY = "你的 API 密钥"
87
+ ```
88
+
89
+ ### Windows 补充
90
+
91
+ Windows 上如果客户端无法直接启动 npx，可将 `command` 和 `args` 改为：
92
+
93
+ ```json
94
+ {
95
+ "command": "cmd",
96
+ "args": ["/d", "/c", "npx", "-y", "gpt-image-mcp"]
97
+ }
98
+ ```
99
+
100
+ ### 全局安装（可选）
101
+
102
+ 如果希望避免首次启动的下载等待，也可以全局安装后直接使用命令名：
103
+
104
+ ```sh
105
+ npm install --global gpt-image-mcp
106
+ ```
107
+
108
+ 安装后将配置中的 `"command"` 改为 `"gpt-image-mcp"`，去掉 `"args"`。
109
+
110
+ ### 通用说明
111
+
112
+ - 锁定版本可将 `args` 改为 `["-y", "gpt-image-mcp@0.2.1"]`
113
+ - 工具执行超时建议设为至少 360 秒，具体配置字段由客户端决定；服务自身的 API 超时默认为 300 秒
114
+ - 服务启动后会等待 MCP 输入，直接在终端运行时没有欢迎输出属于正常行为
115
+ - 日志只写入 stderr，stdout 保留给 MCP 协议
100
116
 
101
117
  ## 配置
102
118
 
@@ -109,8 +125,6 @@ Windows 示例，JSON 中使用正斜杠可避免反斜杠转义：
109
125
  | `IMAGE_GEN_TIMEOUT_MS` | `300000` | API 请求超时，单位毫秒，必须为不小于 1000 的整数 |
110
126
  | `IMAGE_GEN_RESPONSE_FORMAT` | `b64_json` | API 返回图片的方式：`b64_json`（返回 Base64 数据）或 `url`（返回下载地址，服务自动下载保存）。默认 `b64_json` 时不向 API 发送此参数，仅配置 `url` 时才显式发送。部分代理对新模型（如 `gpt-image-2.5-sunburst`）可能不支持此参数，遇到 `unknown_parameter` 错误时请保持默认值 |
111
127
 
112
- `.env.example` 仅作为变量示例，服务不会自动读取 `.env`。本地调试可运行 `node --env-file=.env dist/index.js`，或通过 MCP 客户端的 `env` 传入变量。
113
-
114
128
  `OPENAI_BASE_URL` 填写 API 根地址；未配置、空字符串或纯空格均使用官方端点。只有地址不包含路径时自动补 `/v1`，已有路径则按用户配置保留，避免破坏代理前缀或其他版本。尾部斜杠会去除，不会重复追加 `/v1`。
115
129
 
116
130
  | 用户填写 | 实际使用的 API 根地址 |
@@ -136,12 +150,6 @@ Key、提示词和输入图片会发送到你配置的服务商。服务不会
136
150
  gpt-image-mcp --check
137
151
  ```
138
152
 
139
- 从源码使用 `.env` 时：
140
-
141
- ```sh
142
- node --env-file=.env dist/index.js --check
143
- ```
144
-
145
153
  诊断最多等待 30 秒，不自动重试，只请求 `GET /models`，不会调用图片生成或编辑接口。结果说明：
146
154
 
147
155
  | 字段 | 含义 |
@@ -238,33 +246,4 @@ Windows: C:\Users\用户名\gpt-image-mcp\images\2026\09\10\cozy-otter-paints-mo
238
246
 
239
247
  失败返回 `isError: true` 和错误说明。服务关闭自动重试；超时或断线不代表上游没有执行，重新调用可能再次计费。图片生成成功但本地保存失败时会明确提示，不会重新调用生成接口。客户端取消会传递给 API 请求，但无法保证取消上游已开始的计费。
240
248
 
241
- ## 开发与验证
242
-
243
- ```sh
244
- npm run check
245
- npm run test:package
246
- ```
247
-
248
- 执行类型检查、测试及构建。测试通过真实 OpenAI SDK 的模拟 HTTP 响应，覆盖 MCP 工具发现与调用、文生图、多图编辑、自定义端点路由、诊断结果边界、遮罩校验、本地保存、中文及空格路径、并发命名、失败不重试。测试不需要真实密钥，也不消耗图片 API 额度。
249
-
250
- `test:package` 会在临时目录打包和安装，验证发布文件白名单、npm 命令入口和安装后的 MCP 握手；安装依赖时需要访问 npm 或具有完整本地缓存。
251
-
252
- GitHub Actions 配置了 Linux、macOS、Windows 和 Node.js 22/24 的检查矩阵。配置存在不代表已在全部系统实际跑过；本地测试不能代替目标系统 CI 或真实 API 验收。
253
-
254
249
  真实验收建议用 `quality: "low"` 各执行一次文生图和图生图，确认账号模型权限、网络、图片效果与客户端展示行为。
255
-
256
- ## 制作分发包
257
-
258
- 在源码目录执行：
259
-
260
- ```sh
261
- npm ci
262
- npm run check
263
- npm pack
264
- ```
265
-
266
- `npm pack` 会自动构建，生成 `gpt-image-mcp-0.2.0.tgz`。分发包仅包含编译结果、`package.json`、README 和 `.env.example`，不包含真实 `.env`、测试文件、源码或 `node_modules`。同一压缩包可发给三种系统的用户安装，安装时会选择对应平台依赖。
267
-
268
- 如以后发布到公共 npm，需要先确定自己有权使用的包名或作用域、发布账号和许可证。当前未执行 `npm publish`，不能假定注册表中的同名包属于本项目；现阶段请使用此项目生成的 `.tgz` 文件。
269
-
270
- 接口依据：[OpenAI 图片生成文档](https://developers.openai.com/api/docs/guides/image-generation)、[MCP 服务开发文档](https://modelcontextprotocol.io/docs/develop/build-server)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gpt-image-mcp",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "支持文生图、图片编辑和参考风格生成的本地 MCP 服务",
5
5
  "license": "MIT",
6
6
  "author": "WainZeng",