内容
# Pixel Bridge MCP
[](https://github.com/Mrshahidali420/pixel-bridge-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](CONTRIBUTING.md)
[](package.json)
**免费 AI 图片生成，适用于 Claude Code — 通过您已有的 ChatGPT 和 Gemini 网页账户。** 一个本地 [MCP](https://modelcontextprotocol.io) 服务器，通过 Playwright 驱动一个真实的浏览器访问提供商的网页界面，这样您就可以使用 `generate_image` / `edit_image` 工具，而无需任何图片生成 API 密钥。您只需手动登录一次；Claude Code 会使用其自身的视觉检查结果。
*桥梁 Claude Code → 您的浏览器 → ChatGPT / Gemini 图片生成。由此得名。*
## 工作原理
```
Claude Code ──MCP──> Pixel Bridge ──Playwright──> 您登录的浏览器配置文件
├─ chatgpt.com
└─ gemini.google.com
图片保存到 ./assets/… <── 实际生成的文件下载
Claude Code 读取文件并使用其自身的视觉检查质量。
```
关键原则：
- **您手动认证，一次。** 每个提供商都获得一个持久的 Chromium 配置文件 (`~/.pixel-bridge/profiles/<provider>`)。您自己登录 — 包括任何 CAPTCHA 或 MFA。服务器**从不**触及凭证，从不尝试绕过安全挑战。
- **MCP 不是艺术评论家。** 它返回文件路径 + 元数据；调用的 Claude Code 模型检查图像并决定是否保留或重新生成更好的提示。
- **从不静默地 "成功"。** 如果无法检索实际图片字节，作业会失败，并带有原因（拒绝文本、超时、UI 更改、捕获失败）和调试截图保存在 `~/.pixel-bridge/logs/`。
## 安装（在您的机器上）
### 选项 A — 受控浏览器（默认）
```bash
git clone https://github.com/Mrshahidali420/pixel-bridge-mcp
cd pixel-bridge-mcp
npm install
npx playwright install chromium # 一次
npm run build
# 每个提供商的一次手动登录（打开可见的浏览器窗口）：
npm run login -- chatgpt
npm run login -- gemini
```
提示：设置 `PIXEL_BRIDGE_BROWSER_CHANNEL=chrome` 以使用您安装的 Google Chrome 代替捆绑的 Chromium。
### 选项 B — 附加到您自己的浏览器（使用现有的登录）
与其让 Pixel Bridge 启动自己的浏览器，您可以将其附加到您启动的真实 Chrome/Edge/Brave **，** 它将使用该浏览器已经拥有的登录。 使用调试端口和专用配置文件启动您的浏览器：
```bash
# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\pixel-bridge-chrome"
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--remote-debugging-port=9222 --user-data-dir="$HOME/pixel-bridge-chrome"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/pixel-bridge-chrome"
```
在该窗口中登录 chatgpt.com / gemini.google.com （一次 - 配置文件持续存在），然后使用以下命令运行 MCP：
```
PIXEL_BRIDGE_CDP_URL=http://127.0.0.1:9222
```
Pixel Bridge 在该浏览器中打开**自己的标签页**，从不触及您的标签页，在关闭时仅关闭其标签页并断开连接 - 您的浏览器继续运行。 您可以实时查看每次生成并在同一窗口中处理任何登录挑战。
> **为什么不使用我的日常 Chrome 配置文件？** Chrome 本身拒绝在默认配置文件上进行远程调试（自 Chrome 136 以来的安全措施，保护您的 cookie 不被基于调试器的盗窃），而正在运行的 Chrome 会锁定其配置文件。 这就是为什么附加模式需要专用 `--user-data-dir` - 您仍然只需在那里登录一次，它像您的正常浏览器一样保持登录状态。 Pixel Bridge 不会尝试绕过此保护。
注册 Claude Code - 将其添加到您的项目的 `.mcp.json`（或 `claude mcp add`）：
```json
{
"mcpServers": {
"pixel-bridge": {
"command": "node",
"args": ["/absolute/path/to/pixel-bridge-mcp/dist/index.js"]
}
}
}
```
## 工具
| 工具 | 用途 |
|---|---|
| `generate_image` | 通过 `chatgpt` 或 `gemini` 生成；保存本地；返回路径 + 元数据。 |
| `edit_image` | 上传本地图片 + 编辑指令；保存编辑结果。 |
| `generate_with_both` | 通过 **两个** 提供商并行发送相同提示 → 比较两个文件。 |
| `get_generation_status` | 通过 `job_id` 轮询慢速作业（可选阻塞直到 `wait_seconds`）。 |
| `download_generated_image` | 将已完成的作业的图片复制到其他位置。 |
| `check_provider_session` | 持久会话是否登录并可用？ |
| `provider_login` | 打开提供商网站（头部）并等待 **您** 手动登录。 |
### 作业模型（与原始规范有意设计变更）
网页生成可能需要几分钟，这可能会超过 MCP 客户端超时。 因此，每个生成都作为一个**后台作业运行，保存其自己的输出**：
1. `generate_image` 内联等待（默认为 150 秒）。 通常网站在时间内完成，您可以直接获得保存的文件路径。
2. 如果没有，您将获得一个带有状态 `running` 的 `job_id` - 轮询 `get_generation_status`。
3. 作业将图片写入原始请求的 `output_path` **，当它完成时，即使没有人轮询** - 客户端超时永远不会丢失已完成的图片。 因此，`download_generated_image` 仅用于额外复制。
### 文件处理
- `output_path` 可以是文件 (`./assets/hero.png`) 或目录（自动派生文件名，或传递 `filename`）。
- 目录自动创建。 支持 PNG / JPEG / WebP - 扩展名遵循提供商提供的实际内容类型。
- 现有文件 **永远不会** 被覆盖，除非 `overwrite: true`；否则使用 `-1`、`-2`... 后缀。
- 结果包括绝对路径和项目相对路径、字节大小、内容类型和 `capture_method`：
- `"download"` - 实际生成的图片被获取（完整质量）。
- `"screenshot"` - 最后一个元素的截图备用（诚实报告，以便 Claude 可以决定重试）。
### 宽高比
网页界面没有可靠的宽高比控制，因此 `aspect_ratio`（例如 `"16:9"`）被折叠为自然语言。 **通过视觉验证** 结果 - 工具输出提醒调用模型检查此项。
## 意图的 Claude Code 工作流程
1. 使用具体提示询问 `generate_image`（或 `generate_with_both`），例如 16:9 的英雄图片规格。
2. 读取返回的文件并使用视觉检查。
3. 判断：提示匹配、构图、伪影、手/脸、非预期的文本/水印、宽高比。
4. 保留它，或优化提示并重新生成。 MCP 永远不会自己评估质量。
## 架构
```
src/
├── index.ts MCP 服务器 + 工具定义（stdio 传输）
├── cli-login.ts `npm run login -- <provider>` 首次运行助手
├── config.ts 环境驱动配置（无凭证，无硬编码路径）
├── logger.ts stderr + 滚动文件日志（stdout 是 MCP 协议）
├── files.ts 路径解析、mkdir、无冲突命名
├── jobs.ts 后台作业管理器（客户端超时无法丢失图片）
├── browser.ts 每个提供商的持久 Chromium 配置文件 + 每个提供商的队列
└── providers/
├── types.ts ImageProvider 接口
├── base.ts 共享编排：选择器回退、新图片检测、
│ 忙/拒绝检测、下载截图回退
├── chatgpt.ts ChatGPT 网页适配器（~60 行提供商特定配置）
├── gemini.ts Gemini 网页适配器（~70 行）
└── registry.ts 添加未来提供商
```
可靠性决策：
- **没有脆弱的 DOM 假设**：每个提供商都提供 *候选* 选择器列表，按顺序尝试；结果被通用地检测为“出现并稳定了一个新的 ≥300 像素图像，模型停止响应后”，而不是通过提供商的 DOM 结构。
- **拒绝检测**：如果模型完成回复且没有图像，则在错误中返回回复文本，以便 Claude 可以重新措辞。
- **每个提供商的序列化**：对一个提供商的并发调用会排队；不同的提供商并行运行（这就是 `generate_with_both` 的工作原理）。
- **可调试性**：每个失败都将页面截图保存到 `~/.pixel-bridge/logs/`，并且作业结果包括最近的逐步日志。
## 配置（环境变量，均可选）
| 变量 | 默认值 | 含义 |
|---|---|---|
| `PIXEL_BRIDGE_HOME` | `~/.pixel-bridge` | 配置文件 + 日志根目录 |
| `PIXEL_BRIDGE_PROFILE_DIR` | `<home>/profiles` | 浏览器配置文件位置 |
| `PIXEL_BRIDGE_HEADLESS` | `false` | 默认头部 - 更适合消费者站点，需要手动登录 |
| `PIXEL_BRIDGE_BROWSER_CHANNEL` | – | 例如 `chrome` 以使用您安装的 Chrome 代替捆绑的 Chromium |
| `PIXEL_BRIDGE_EXECUTABLE_PATH` | – | 显式浏览器二进制路径 |
| `PIXEL_BRIDGE_CDP_URL` | – | 附加模式：连接到您自己的正在运行的浏览器（例如 `http://127.0.0.1:9222`）而不是启动一个 |
| `PIXEL_BRIDGE_GENERATION_TIMEOUT_S` | `300` | 每个生成的硬上限 |
| `PIXEL_BRIDGE_DEFAULT_WAIT_S` | `150` | 默认内联等待，然后返回作业 ID |
| `PIXEL_BRIDGE_LOGIN_TIMEOUT_S` | `300` | 手动登录等待 |
| `HTTPS_PROXY` | – | 设置时转发到浏览器（企业代理） |
## 安全姿态
- 代码、配置或日志中没有凭证；无需硬编码。
- 会话仅存在于本地浏览器配置文件中 - `.gitignore` 排除配置文件；永远不要提交它们（它们包含活动 cookie）。
- CAPTCHA、MFA 和机器人检查 **永远不会** 被自动化。 当提供商提出挑战时，工具会报告它，并且 `provider_login` 将控制权交给您在可见窗口中。
- 尊重每个提供商的服务条款；这驱动您自己的帐户通过其正常网页界面，以人为触发、低频率。
## 状态 / 已验证的内容
在无头云环境中构建并进行了烟雾测试：
- ✅ 编译干净；服务器启动并通过 MCP stdio 提供所有 7 种工具。
- ✅ 使用单元检查验证了文件命名/冲突/扩展名逻辑。
- ✅ 验证了作业生命周期、错误传播和失败截图。
- ⏳ 直播浏览器流程（登录 → 生成 → 下载）需要在真实桌面上运行测试 - 云沙盒没有显示，完全阻止 chatgpt.com，并且其 TLS 拦截代理干扰 Playwright 驱动的导航。 第一次本地测试：`npm run login -- gemini`，然后要求 Claude Code 将测试图片生成到 `./assets/`。
## 添加提供商
实现 `BaseChatProvider`（URL，选择器候选者，已登录/忙碌检测，提示措辞 - 见 `chatgpt.ts` 了解其小规模）并在 `providers/registry.ts` 中注册它。 非聊天界面可以直接实现 `ImageProvider` 接口。
## 贡献
非常欢迎贡献 - 尤其是 **当提供商界面更改时的选择器修复** 和 **新的提供商适配器**（Bing Image Creator、Ideogram、Playground、...）。 有关设置、适配器指南和硬规则的详细信息，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)（无凭证处理，无 CAPTCHA/MFA/机器人检测绕过，无静默成功）。 如果此项目对您有帮助，则 ⭐ 帮助其他人找到它。
## 许可证
[MIT](LICENSE) © Shahid Ali
## 免责声明
Pixel Bridge 通过其正常网页界面以人为规模自动化 **您自己的** 帐户。 请尊重每个提供商的服务条款和速率限制；您负责如何使用它。 本项目与 OpenAI、Google 或 Anthropic 无关。
