@isen/chatgpt-image-web-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChatGPT Image Web MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# ChatGPT Web 图片生成 MCP
+
+通过一个**通用、持久化、单例的后台 Chrome 浏览器**，自动使用 ChatGPT 网页生成图片。自动化模式默认采用新版Headless Chrome，不显示窗口、不抢前台，也不接受用户鼠标或键盘操作。
+
+该MCP不包含任何项目、品牌或业务模板逻辑。不同代码仓库可以共同复用同一个登录Profile和浏览器实例；每次调用通过`prompt`、`referenceImages`和`outputDir`决定当前项目的输入与输出。默认相对输出目录会基于启动MCP进程的工作目录解析，也建议每个项目显式传入自己的`outputDir`。
+
+## 设计目标
+
+- 所有项目的图片生成工作流复用一个通用专用浏览器实例，不为每个项目或任务重复启动浏览器。
+- 使用独立 Chrome 用户目录，不读取日常 Chrome 的 Cookie/Profile。
+- 登录、安全验证、限流提示由用户在专用窗口中处理。
+- Agent 可以上传真实参考图、填写提示词、发送、等待并保存结果。
+- 每个Agent自动绑定一个独立ChatGPT后台页面（等价于隔离标签页）；同一Agent内串行，不同Agent可并行。
+- 自动化模式没有可操作窗口，避免用户误触、焦点切换和输入干扰；只有人工登录模式临时显示窗口。
+- 默认最多3个Agent标签页同时生成，可通过环境变量调整为1～8。
+- 不调用、抓取或模拟 ChatGPT 私有接口，不导出 Cookie。
+- 发送任务使用持久化状态机（`prepared → submitting → sent → completed/needs_human`）；一旦发送动作开始，后续重复提交会被拒绝，避免重复消耗 Pro 网页额度。
+
+> Chrome 本身采用多进程架构，活动监视器里会看到浏览器、渲染器、GPU等多个子进程；这里的“单例”指一个专用浏览器实例和一个持久化用户目录；自动化任务通过Agent专属标签页隔离，不代表操作系统中只有一个Chrome子进程。
+
+## 专用浏览器数据
+
+macOS 默认位置：
+
+```text
+~/Library/Application Support/ChatGPTImageWebMCP/
+├── browser.json          # 自动化模式
+├── login-browser.json    # 人工登录模式
+├── chrome-profile/
+├── prepared-jobs/       # 按Agent隔离的待发送任务
+├── output-reservations/ # 防止不同Agent覆盖同名文件
+├── agent-job-locks/     # 每个Agent一个任务锁
+├── parallel-slots/      # 全局并行槽位
+├── launch.lock/         # 仅启动期间存在
+├── job-admission.lock/  # 接纳新任务时短暂存在
+├── maintenance.lock/    # 登录模式切换或关闭浏览器期间存在
+└── tab-assignment.lock/ # 分配标签页时短暂存在
+```
+
+关闭浏览器不会删除登录状态。不要把这个目录同步、提交或分享给其他人。
+
+默认`IMAGE_BROWSER_AUTO_CLOSE=false`，Chrome会在任务完成后继续运行以便下次复用。设置为`true`后，成功完成`submit_prepared_job`、`run_image_job`、完整批次、手动下载或清除准备任务时会尝试自动关闭；`prepare_image_job`和`needs_human`结果会保持浏览器现场。若其他Agent正在运行，或任一Agent仍有prepared/待人工处理状态，自动关闭会安全跳过。可通过`browser_status.autoCloseAfterSuccess`确认实际配置。
+
+可用环境变量：
+
+| 变量 | 用途 |
+| --- | --- |
+| `IMAGE_BROWSER_HOME` | 覆盖状态和专用Profile目录 |
+| `IMAGE_BROWSER_EXECUTABLE` | 覆盖Chrome/Brave可执行文件 |
+| `IMAGE_BROWSER_START_URL` | 默认 `https://chatgpt.com/` |
+| `IMAGE_BROWSER_DEFAULT_OUTPUT_DIR` | 默认 `generated/web-images` |
+| `IMAGE_BROWSER_AGENT_ID` | 手动指定当前MCP进程的Agent标识；默认使用`PI_SESSION_ID` |
+| `IMAGE_BROWSER_HEADLESS` | `true`时后台无窗口运行并禁用用户操作；默认true |
+| `IMAGE_BROWSER_MAX_PARALLEL_TABS` | 同时生成的Agent页面上限，默认3，范围1～8 |
+| `IMAGE_BROWSER_AUTO_CLOSE` | `true`时在成功生成、成功下载或清除待发送任务后，空闲且无待人工处理任务时自动关闭Chrome；默认false |
+| `IMAGE_BROWSER_ENABLE_STOP_TOOL` | `true`时注册`stop_current_generation`，允许明确停止当前Agent页面的生成；默认false |
+| `IMAGE_BROWSER_STOP_ON_TIMEOUT` | `true`时等待图片超时后自动点击停止，并尝试保存停止前已出现的图片；默认false |
+
+## 安装和构建
+
+前置条件：
+
+- Node.js >= 22.18；
+- Google Chrome 或 Brave；
+- 支持stdio MCP的客户端；Pi 用户还需要安装并启用 `pi-mcp-adapter`；
+- 用户自己的ChatGPT账号，登录状态和网页额度不会由本项目提供或共享。
+
+### npm安装
+
+公开包发布后，MCP配置应锁定具体版本，不建议直接使用`latest`：
+
+```json
+{
+  "mcpServers": {
+    "chatgpt-image-web": {
+      "command": "npx",
+      "args": [
+        "--yes",
+        "--package=@isen/chatgpt-image-web-mcp@0.3.0",
+        "chatgpt-image-web-mcp"
+      ],
+      "lifecycle": "lazy-keep-alive",
+      "requestTimeoutMs": 14400000,
+      "env": {
+        "IMAGE_BROWSER_AGENT_ID": "${PI_SESSION_ID}",
+        "IMAGE_BROWSER_HEADLESS": "true",
+        "IMAGE_BROWSER_MAX_PARALLEL_TABS": "2",
+        "IMAGE_BROWSER_AUTO_CLOSE": "false",
+        "IMAGE_BROWSER_ENABLE_STOP_TOOL": "false",
+        "IMAGE_BROWSER_STOP_ON_TIMEOUT": "false",
+        "IMAGE_BROWSER_DEFAULT_OUTPUT_DIR": "${HOME}/Pictures/ChatGPTImageOutput"
+      },
+      "directTools": true
+    }
+  }
+}
+```
+
+仓库中的 `mcp.example.json` 提供同样的无账号占位模板。不要提交真实 `.mcp.json`；是否关闭工具批准应由用户在自己的可信环境决定，公共示例不会设置 `approveTools: false`。
+
+`IMAGE_BROWSER_HOME` 默认值分别是：
+
+- macOS：`~/Library/Application Support/ChatGPTImageWebMCP`
+- Linux：`~/.local/share/chatgpt-image-web-mcp`
+- Windows：`%LOCALAPPDATA%\\ChatGPTImageWebMCP`
+
+所有输出目录和`referenceImages`均是运行MCP用户自己机器上的路径，Profile目录不能共享或上传。非Pi客户端应为每个会话提供稳定且唯一的`IMAGE_BROWSER_AGENT_ID`，也可以省略并接受进程重启后生成新ID。
+
+### 从源码构建
+
+```bash
+git clone <repository-url>
+cd chatgpt-image-web-mcp
+npm ci
+npm run check
+npm test
+npm run smoke
+```
+
+修改源码后重新执行 `npm run build`，然后在 Pi 中执行 `/reload` 或 `/mcp reconnect chatgpt-image-web`。从单任务版升级到多标签版时，**所有当前打开的Agent会话都必须执行一次`/reload`**。新版本检测到旧版全局任务锁时会拒绝开始生成，避免旧、新进程同时操作页面。
+
+## 第一次使用
+
+1. 调用 `open_login_browser`。
+2. 它会以**无远程调试的普通模式**打开唯一专用 Chrome，人工登录 ChatGPT Pro。
+3. 人工完成可能出现的Google登录、验证码或安全检查。
+4. 不要在日常Chrome里登录代替；两个Profile完全隔离。
+5. 登录成功并看到ChatGPT对话页后，调用 `switch_to_automation_browser`。
+6. 工具会先关闭可见登录窗口，再用同一个Profile切换为无窗口自动化模式；确认 `composerReady=true`。
+
+Google可能拒绝在自动化浏览器里登录，因此登录模式和自动化模式不会同时运行，而是在同一个专用Profile上串行切换。后续登录未失效时一直使用后台无窗口模式。不要手动打开或操作该专用Profile；需要重新登录时调用`open_login_browser`。
+
+## 推荐半自动流程
+
+### 可控模式
+
+```text
+prepare_image_job
+  ↓
+用户查看返回的 prepared 截图中的附件、模型和提示词
+  ↓
+submit_prepared_job
+  ↓
+自动等待并保存图片
+```
+
+`prepare_image_job` **不会点击发送**。它会先清空当前Agent输入框中的旧Prompt和附件，再写入本次内容，适合先确认再消耗网页额度。`submit_prepared_job`发送前会核对Prompt和可检测到的附件数量；页面内容被修改后会拒绝发送，应清除并重新准备。
+
+### 已确认后的快捷模式
+
+```text
+run_image_job
+```
+
+一次完成上传、填写、发送、等待和保存。`.mcp.json` 已关闭MCP工具批准，Agent调用后会直接执行。
+
+### 串行批量模式（推荐）
+
+```text
+run_batch_image_jobs({
+  jobs: [
+    { prompt: "第1页……", referenceImages: ["参考图.png"], outputStem: "01" },
+    { prompt: "第2页……", referenceImages: ["参考图.png"], outputStem: "02" },
+    { prompt: "第3页……", referenceImages: ["参考图.png"], outputStem: "03" }
+  ],
+  outputDir: "/path/to/current-project/generated",
+  stopOnFailure: true
+})
+```
+
+批量工具会占用当前Agent自己的任务锁，并在该Agent的专属标签页中按数组顺序执行：上一张检测完成并保存后，才上传并发送下一张。其他Agent可以同时在各自标签页执行，但不会创建第二个浏览器。
+
+- 单批最多12张。
+- 每张默认最多等待480秒。
+- 两张之间默认等待3秒。
+- 默认任一失败立即停止，浏览器保持现场供人工检查。
+- 每完成一张都会更新批次JSON，即使中途失败也能确认已完成范围。
+- 整批任务不弹出MCP批准对话框，但每个数组项都会消耗一次ChatGPT网页生成额度。
+
+### 多Agent并行
+
+每个MCP进程按以下优先级确定Agent身份：
+
+```text
+IMAGE_BROWSER_AGENT_ID
+→ PI_SESSION_ID
+→ CODEX_THREAD_ID
+→ MCP进程随机ID
+```
+
+Agent第一次调用浏览器工具时会在后台创建或认领自己的页面，并通过`window.name`持久标记。创建使用CDP `background:true`，不会激活页面或抢夺系统焦点。不同Agent的以下状态互相隔离：
+
+- ChatGPT标签页和对话上下文
+- 待发送Prompt与附件（`prepare`/`submit`两步模式也按Agent隔离；每次prepare会先清理该Agent页面的旧草稿）
+- 任务锁和批量任务
+- 图片检测与下载目标
+- 输出文件名预留；会同时检查已有文件和并发预留，同目录同前缀冲突时自动添加Agent短标识，所有最终图片使用排他写入，禁止覆盖既有结果
+
+默认允许3个Agent同时生成；第4个Agent会收到“达到安全上限”，稍后重试即可。每个Agent的批量任务在自己的标签页内仍然严格串行。
+
+### 人工在网页调整后
+
+默认Headless模式没有可操作窗口。如果明确需要长期人工查看和调整，可在没有任务运行时设置`IMAGE_BROWSER_HEADLESS=false`并重新连接，使自动化浏览器以可见模式运行。用户在该专用窗口继续对话后可以调用：
+
+```text
+download_latest_image
+```
+
+它只保存最近的生成图片，不发送消息。
+
+## MCP 工具
+
+| 工具 | 是否启动浏览器 | 是否发送消息 | 说明 |
+| --- | --- | --- | --- |
+| `browser_status` | 否 | 否 | 查看自动化/登录模式状态 |
+| `open_login_browser` | 串行切换 | 否 | 无远程调试的人工安全登录模式 |
+| `switch_to_automation_browser` | 串行切换 | 否 | 保留登录状态并切回自动化模式 |
+| `open_chatgpt_browser` | 必要时后台启动 | 否 | 打开/定位当前Agent专属后台页面，不抢前台 |
+| `prepare_image_job` | 必要时启动一次 | 否 | 上传附件并填写Prompt |
+| `clear_prepared_job` | 复用 | 否 | 取消并清空未发送任务 |
+| `submit_prepared_job` | 复用 | 是 | 发送并等待、保存 |
+| `run_image_job` | 必要时启动一次 | 是 | 完整快捷流程 |
+| `run_batch_image_jobs` | 复用Agent专属页 | 是（Agent内串行） | 按队列生成1～12张 |
+| `download_latest_image` | 复用Agent专属页 | 否 | 保存当前Agent页中最近图片 |
+| `stop_current_generation` | 复用Agent专属页 | 否 | 可选工具；停止当前Agent页的生成，需`IMAGE_BROWSER_ENABLE_STOP_TOOL=true` |
+| `close_agent_tab` | 否 | 否 | 只关闭当前Agent标签页 |
+| `close_chatgpt_browser` | 否 | 否 | 空闲时关闭整个专用实例，保留Profile |
+
+## 输出
+
+默认写入项目根目录：
+
+```text
+generated/web-images/
+├── <job-id>-prepared.png   # 发送前现场截图
+├── <job-id>-result.png     # 生成后/异常现场截图
+├── <job-id>-image.png      # 下载的图片，实际扩展名按响应格式
+├── <job-id>.json           # 单张Prompt、参考图、时间和保存方式
+└── <batch-id>-batch.json   # 批次实时进度和每张结果
+```
+
+MCP 只返回路径和元数据，不把整张图片Base64塞进Agent上下文。准备任务更换`outputDir`时会在新目录重新预留名称；手动下载和批次清单也使用同一防覆盖机制。任务完成、取消或准备失败后会释放临时预留，已生成文件本身仍会阻止后续覆盖。
+
+## 单例与失败策略
+
+- Chrome 使用固定专用 Profile；自动化模式默认使用`--headless=new`及随机本地CDP端口。
+- 自动化模式无窗口，因此用户无法误触；同时禁用后台计时器/渲染节流，避免后台图片任务被暂停。
+- Google/OpenAI登录使用无CDP的人工登录模式，成功后关闭并以同一Profile切回自动化模式。
+- 两种模式严格串行，不会同时存在；端口及 PID 保存到状态文件。
+- 启动使用原子目录锁；多个Pi/Codex会话同时启动时只有一个能创建浏览器。
+- 标签页分配使用跨进程锁，两个Agent不会认领同一标签页。
+- 每个Agent拥有独立任务锁；同一Agent不会重入，不同Agent使用并行槽位。
+- 登录模式切换和关闭整个浏览器与新任务接纳使用同一套跨进程维护门禁；任何Agent仍运行时会拒绝维护，维护开始后也会拒绝新任务，避免竞态中断。
+- 如果旧专用浏览器进程存在但无法连接，会先停止旧进程；无法停止时直接报错，绝不再启动第二个实例。
+- 页面改版、验证码或无法检测图片时，浏览器保持打开并返回 `needs_human`。
+- 默认超时不会取消网页任务；启用`IMAGE_BROWSER_STOP_ON_TIMEOUT`后才会自动点击停止，且绝不自动重发。启用`IMAGE_BROWSER_ENABLE_STOP_TOOL`后可明确调用`stop_current_generation`。
+- `submitting`、`sent` 或 `needs_human` 状态不能再次提交；用户应先检查页面并下载已有结果，确需重试时明确清除并重新准备任务。
+
+## 局限
+
+这是网页半自动化，不是OpenAI官方API：
+
+- ChatGPT页面结构变化后，选择器可能需要更新。
+- Headless模式与可见Chrome仍可能存在服务端行为差异；检测到登录或安全验证时会停止并要求切换到人工登录模式，不会尝试绕过。
+- 网页生成额度、排队和功能取决于Pro账户及当时服务状态；本地允许3个并行标签页不代表ChatGPT服务端一定接受3个并行生成。
+- 安全验证必须人工处理，本项目不会绕过。
+- 模型、图片工具或会话选择建议用户在专用浏览器中预先设置并保持。
+- 下载优先获取原始网络图片；HTTP或页面fetch得到的字节必须通过PNG/JPEG/WebP/GIF/AVIF文件签名校验，避免把登录页或错误HTML保存成图片；若网页权限阻止下载，最后才使用元素截图，并在任务JSON中标记 `element-screenshot`。
+- 使用时需遵守ChatGPT适用的服务条款。
+
+## 许可证
+
+本项目采用 [MIT License](LICENSE)。

package/dist/browser-manager.d.ts

@@ -0,0 +1,100 @@
+import { type Browser, type BrowserContext, type Page } from "playwright-core";
+export interface BrowserMetadata {
+    pid: number;
+    port: number;
+    headless: boolean;
+    executable: string;
+    profileDir: string;
+    launchedAt: string;
+}
+export interface LoginBrowserMetadata {
+    pid: number;
+    executable: string;
+    profileDir: string;
+    launchedAt: string;
+}
+export interface BrowserStatus {
+    running: boolean;
+    endpoint?: string;
+    metadata?: BrowserMetadata;
+    loginModeActive: boolean;
+    loginBrowser?: LoginBrowserMetadata;
+    maxParallelTabs: number;
+    autoCloseAfterSuccess: boolean;
+    stopToolEnabled: boolean;
+    stopOnTimeout: boolean;
+    activeJobs: Array<{
+        agentId: string;
+        pid: number;
+        startedAt: string;
+    }>;
+    profileDir: string;
+    stateDir: string;
+    reason?: string;
+}
+export interface ConnectedBrowser {
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+    metadata: BrowserMetadata;
+    agentId: string;
+    tabName: string;
+}
+export declare class BrowserManager {
+    private connectedBrowser?;
+    private connectedContext?;
+    private connectedMetadata?;
+    readonly stateDir: string;
+    readonly profileDir: string;
+    readonly metadataPath: string;
+    readonly loginMetadataPath: string;
+    readonly activePortPath: string;
+    readonly launchLockPath: string;
+    readonly tabLockPath: string;
+    readonly jobAdmissionLockPath: string;
+    readonly maintenanceLockPath: string;
+    readonly legacyJobLockPath: string;
+    readonly jobLocksDir: string;
+    readonly slotLocksDir: string;
+    readonly maxParallelTabs: number;
+    readonly autoCloseAfterSuccess: boolean;
+    readonly stopToolEnabled: boolean;
+    readonly stopOnTimeout: boolean;
+    constructor(stateDir?: string);
+    private agentKey;
+    private tabName;
+    findExecutable(): string;
+    private readMetadata;
+    private readLoginMetadata;
+    private readActivePort;
+    private endpointIsHealthy;
+    private lockOwner;
+    private removeStaleLock;
+    private activeJobOwners;
+    private assertNoActiveJobs;
+    status(): Promise<BrowserStatus>;
+    private withDirectoryLock;
+    private withLaunchLock;
+    private withJobAdmissionLock;
+    private beginExclusiveMaintenance;
+    private withExclusiveMaintenance;
+    ensureRunning(): Promise<BrowserMetadata>;
+    openLoginBrowser(): Promise<LoginBrowserMetadata>;
+    switchToAutomationBrowser(agentId?: string): Promise<ConnectedBrowser>;
+    private browserConnection;
+    private readPageName;
+    private isChatGptPage;
+    private createBackgroundPage;
+    private pageForAgent;
+    connect(options?: {
+        navigateToChatGpt?: boolean;
+        agentId?: string;
+        bringToFront?: boolean;
+    }): Promise<ConnectedBrowser>;
+    acquireJobLock(agentId?: string): Promise<() => void>;
+    closeAgentTab(agentId: string): Promise<boolean>;
+    private hasPendingPreparedJobs;
+    closeDedicatedBrowser(options?: {
+        preservePreparedJobs?: boolean;
+    }): Promise<boolean>;
+}