内容
# ai-slides-mcp
## ⚠️ 免责声明
本项目仅用于**个人学习和研究**。它**反向工程了ChatGPT的网页后端**：
- **与OpenAI无关、未得到OpenAI的认可或赞助**。
- 使用它**违反OpenAI的使用条款**。您的账户可能会被限制速率或**永久封禁**。
- **请使用备用/次要账户 — 永远不要使用重要的账户**。
按原样提供，**不提供任何保证**。您承担所有风险。如果您不接受这些条款，请不要使用此软件。
## 功能
- 根据文本提示以选择的宽高比（16:9，1:1，3:4，4:3，9:16或原始`WxH`）生成图像。
- **推理努力**（`thinking`）：可选地让模型在绘制之前思考更长时间（`standard` < `extended` < `max`）— 明显提高了渲染文本的保真度，例如越南语的音调符号。
- **自动增强**提示通过您的ChatGPT账户的文本模型在绘制之前（镜像网页UI的静默操作）。三种幻灯片样式：`auto`，`slide`，`fintech`。
- 从一组图像构建**全出血** PowerPoint（`.pptx`）幻灯片。
- **品牌幻灯片**：自动从您的徽标检测品牌颜色，生成那些颜色的幻灯片，并将您的徽标复合到每个幻灯片上。
- **样式幻灯片**：匹配参考图像的设计样式和调色板（不复制其文本/内容）。
- **多个账户（自动旋转）**：登录多个ChatGPT账户；该工具探测每个账户的剩余图像配额，并在其中一个账户用完时旋转到下一个账户，以便多个免费账户的每日上限合并成一个幻灯片。如果所有账户都用完，您将获得一个部分幻灯片和重置时间。
- 作为MCP服务器在**Claude Code，Codex和Antigravity**上运行，通过stdio。
- 多账户，完全本地身份验证 - 您的令牌永远不会离开您的机器。
## 需求
- **[uv](https://docs.astral.sh/uv/)** — 处理Python和依赖项（您不需要单独安装Python；`uv`会自动获取Python 3.12）。
- **git**
- 一个**ChatGPT账户**（使用次要账户 — 请参见免责声明）
安装`uv`（每个机器一次）：
```powershell
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
## 安装
### 一键安装程序（推荐）
克隆后，运行安装程序 — 它将安装`uv`（如果缺少），同步依赖项，带您完成登录过程，并注册MCP服务器：
```bash
git clone https://github.com/vuhai2002/ai-slides-mcp.git
cd ai-slides-mcp
```
```powershell
# Windows (PowerShell) — 或右键install.ps1 -> 用PowerShell运行
powershell -ExecutionPolicy Bypass -File install.ps1
```
```bash
# macOS / Linux
bash install.sh
```
### 手动安装
```bash
git clone https://github.com/vuhai2002/ai-slides-mcp.git
cd ai-slides-mcp
uv sync
uv run cgimg login
# 打开浏览器 -> 登录ChatGPT -> 您将进入一个platform.openai.com页面（可能会显示“抱歉”）。
# 复制地址栏中的完整回调URL，然后运行：
uv run cgimg login --callback "<粘贴回调URL>"
```
> 如果您将仓库**私有**，则克隆机器必须登录具有访问权限的GitHub账户（例如`gh auth login`）。
### 为什么登录分为两步
登录使用带有PKCE的OAuth。步骤1构建授权URL并在磁盘上存储一次性密钥（PKCE *校验器*）。步骤2用代码交换令牌 — 而该交换需要步骤1生成的**相同校验器**。将其分成两个命令可以让校验器在构建URL和兑换代码之间持续存在，而不是在浏览器将控制权返回给您时丢失。
## 注册为MCP服务器
配置的形状与**Claude Code，Codex和Antigravity**相同：
```json
{
"mcpServers": {
"ai-slides": {
"command": "uv",
"args": ["run", "cgimg-mcp"],
"cwd": "<克隆仓库的绝对路径>"
}
}
}
```
将`cwd`替换为克隆仓库的绝对路径（例如Windows上的`D:\\ai-slides-mcp` — 注意JSON中的双反斜杠）。对于Claude Code，您可以改为运行：
```bash
claude mcp add ai-slides -- uv run cgimg-mcp
```
## MCP工具
服务器（`src/cgimg/server.py`）公开了六种工具：
| 工具 | 参数 | 返回值 | 描述 |
|------|--------|---------|-------------|
| `login_status` | — | `{authed, accounts, ready_count}` | 列出已登录的账户（廉价，基于提示；使用CLI `cgimg accounts`获取实时配额）。 |
| `generate_image` | `prompt`，`aspect="16:9"`，`n=1`，`out_dir="out"`，`enhance=True`，`style="auto"`，`thinking="auto"`，`brand_colors=None`，`reserve_corner=None` | `{paths}` | 从提示生成`n`张图像。返回保存的PNG路径。 |
| `build_pptx` | `image_paths`，`out_path="deck.pptx"`，`aspect="16:9"` | `{path}` | 将现有图像组装成全出血PPTX。 |
| `generate_slide_deck` | `prompts`，`aspect="16:9"`，`out_pptx="deck.pptx"`，`out_dir="out"`，`enhance=True`，`style="slide"`，`thinking="auto"`，`brand_colors=None`，`reserve_corner=None` | `{path, image_paths, incomplete, generated, total, reset_at}` | 为每个提示生成一张图像（每个提示一张幻灯片，名为`s01.png`...），然后组装成PPTX。如果账户用完配额，则返回部分幻灯片。 |
| `branded_deck` | `logo_path`，`prompts`，`aspect="16:9"`，`out_pptx="deck.pptx"`，`out_dir="out"`，`logo_position="top-left"`，`logo_scale=0.15`，`thinking="auto"` | `{path, image_paths, brand_colors, incomplete, generated, total, reset_at}` | 自动从徽标检测品牌颜色，生成那些颜色的幻灯片，并将**原始徽标**复合到每个幻灯片上。 |
| `styled_deck` | `ref_image`，`prompts`，`aspect="16:9"`，`out_pptx="deck.pptx"`，`out_dir="out"`，`thinking="auto"` | `{path, image_paths, brand_colors, incomplete, generated, total, reset_at}` | 匹配**参考图像**的设计样式+颜色（不复制其文本/内容）。 |
对于`generate_slide_deck` / `branded_deck` / `styled_deck`，每个提示是**一张幻灯片的内容** — 将原始幻灯片内容传递给增强器设计。
## 幻灯片样式
当`enhance=True`时，提示在绘制之前由您的ChatGPT账户的文本模型扩展。`style`参数选择设计处理：
| 样式 | 外观 | 增强 |
|-------|------|-------------|
| `auto` | 通用 — 密集的信息图表，或如果提示命名真实场景的摄影场景。 | 如果提示已经很长（≥280个字符），则跳过。 |
| `slide` | 清洁的编辑幻灯片：浅奶油色背景，一个温暖的强调色，柔和的3D英雄视觉效果，幻灯片编号药丸，底部摘要横幅。 | **始终运行**。 |
| `fintech` | 高级浅蓝色仪表盘外观：玻璃态卡片，圆形蓝色渐变图标徽章，可选3D机器人+图表小部件，底部蓝色横幅。 | **始终运行**。 |
**内容补全（适用于`slide` / `fintech`）**：这些样式补全您的内容成为一个**完整、信息丰富的幻灯片** — 每个主要点都有一个粗体标签**和** 2行支持描述，稀疏输入智能扩展成一个有意义的幻灯片，提示明确要求**所有**文本都被完整渲染（从不丢失或缩写）。它保持可读（不是一堆小文本），并且从不捏造虚假统计数据。参见[`docs/styles.md`](./docs/styles.md)获取完整参考。
> `generate_image`和CLI `gen`接受`style`值`auto`，`slide`和`fintech`。`generate_slide_deck`默认为`slide`。
## 推理努力（`thinking`）
ChatGPT的网页UI有一个“智能”选择器，使图像模型在绘制之前进行更多推理。`generate_image`，幻灯片工具和CLI通过`thinking`公开相同的功能：
| `thinking` | 效果 |
|------------|--------|
| `auto`（默认） | 发送无偏好 — ChatGPT自己的默认值（快速）。 |
| `standard` | 轻度推理。 |
| `extended` | 更多推理。 |
| `max` | 最大推理 — **渲染文本最佳**（例如越南语音调符号），最慢。 |
更高的努力明显提高了图像中的文本保真度。如果生成的幻灯片在默认情况下弄乱了越南语音调符号，请尝试`--thinking max`（CLI）或`thinking="max"`（MCP）。值传递给ChatGPT的图像后端作为`thinking_effort`；上述以外的任何值都被后端拒绝。
## CLI用法
```bash
# 1. 登录（两步，见上方）
uv run cgimg login
uv run cgimg login --callback "<粘贴回调URL>"
# 多个账户（自动旋转）：为每个账户重复登录。为了添加
# 不同的账户，请先退出chatgpt.com或使用隐身/私人
# 窗口（登录捕获当前登录的账户）。然后：
uv run cgimg accounts # 列出具有实时剩余配额的账户
uv run cgimg logout you@example.com # 删除一个（按电子邮件或user_id）
uv run cgimg logout --all # 删除所有账户
# 池自动旋转：它耗尽一个账户，然后移动到下一个。比
# 您的总配额更大的幻灯片停止并返回**部分**幻灯片 + 重置时间。
# 注意：旋转许多账户会提高禁止检测的风险 - 使用一次性账户。
# 2. 生成图像（自动增强默认开启；添加--no-enhance以发送提示原样）
uv run cgimg gen "一个宁静的山湖在黎明" --aspect 16:9 --n 1 --out out
uv run cgimg gen "AI代理用于客户支持" --style slide # 清洁的编辑幻灯片
uv run cgimg gen "实时欺诈检测" --style fintech # 浅蓝色仪表盘幻灯片
uv run cgimg gen "ai agent" --aspect 1:1 --no-enhance # 原样发送提示
uv run cgimg gen "Trí tuệ nhân tạo cho doanh nghiệp" --thinking max # 最大推理 = 越南语文本最佳
uv run cgimg gen "RAG pipeline" --style slide --accent "#10B981" --reserve-corner top-left # 品牌颜色 + 为以后添加徽标保留角落
# 3. 生成多幻灯片幻灯片（每个提示一张图像；幻灯片保存为s01.png，s02.png...）
uv run cgimg deck --prompts "介绍" "工作原理" "定价" --style slide --out deck.pptx
uv run cgimg deck --prompts-file slides.txt --thinking max --accent "#10B981" --reserve-corner top-left
# --prompts-file: 每行一个提示（空白行和以#开头的行将被跳过）
# --no-enhance + --style: 通过简洁的离线模板应用幻灯片外观（适用于密集的越南文本）
# 4. 从现有图像构建幻灯片
uv run cgimg ppt img1.png img2.png --out deck.pptx --aspect 16:9
# 5. 品牌幻灯片 — 幻灯片以您的品牌颜色显示您的徽标复合在每个幻灯片上
uv run cgimg branded logo.png \
--prompts "什么是RAG？" "RAG pipeline" "好处" \
--out deck.pptx --position top-left --scale 0.15
# 6. 样式幻灯片 — 匹配参考图像的设计（不复制其文本/内容）
uv run cgimg styled reference-slide.png \
--prompts "介绍" "工作原理" "定价" \
--out deck.pptx
```
`gen`和`deck`接受`--accent <hex>`（强制品牌颜色）和`--reserve-corner <pos>`（保留一个角落以便以后添加徽标；模型不会绘制任何徽标/文本）。`branded`和`styled`也接受`--aspect`和`--out-dir`（默认为`out`）。它们打印幻灯片路径和每个生成的图像路径。
## 宽高比
| 宽高比 | 发送尺寸 | ChatGPT返回 |
|--------|-----------|-----------------|
| `16:9` | 1920x1080 | ~1672x941 |
| `1:1` | 1024x1024 | 1024x1024 |
| `3:4` | 1024x1536 | ~1086x1448 |
| `9:16` | 1080x1920 | ~941x1672 |
| `4:3` | 1440x1080 | ~1448x1086 |
| `WxH` | 给定尺寸 | ChatGPT标准化 |
ChatGPT遵循**比率**，而不是确切的像素 — 它标准化为其自己的原生尺寸（因此`16:9`大约为`1672x941`，而不是确切的`1920x1080`）。这是预期的。
PPTX输出为**全出血**：图像填充幻灯片边缘到边缘，因此图像宽高比应与幻灯片宽高比匹配以避免裁剪或Letterboxing。
## 工作原理
- 供应商[chatgpt2api](https://github.com/basketikun/chatgpt2api)的成熟OAuth + 图像后端（在`src/cgimg/_vendor/`下）。
- 在Windows上将单个账户令牌存储在`%APPDATA%\cgimg\auth.json`，在Linux/macOS上存储在`~/.config/cgimg/auth.json`。它**从未提交**。
- 通过存储的`refresh_token`在令牌过期时自动刷新访问令牌。
## 示例
此服务器生成的演示幻灯片可在[`examples/sample-slides/`](./examples/sample-slides/)中找到 — 混合了`slide`/`fintech`样式、密集的多任务幻灯片、自定义布局和表格。
## 故障排除
| 症状 | 原因/修复 |
|---------|-------------|
| `not logged in` | 运行`uv run cgimg login`（两步）。 |
| Token过期/身份验证错误 | 重新运行登录流程。 |
| 生成速度慢（~30–90秒每张图像） | 正常 — 它会轮询ChatGPT直到图像准备好。 |
| 提示被拒绝/阻止 | ChatGPT的内容审查拒绝了它。调整提示并重试 — 拒绝通常是暂时的（`styled_deck`自动重试最多3次）。 |
| 图像尺寸不完全符合您的要求 | 预期 — ChatGPT遵循比率并标准化为其原生尺寸。 |
| `cgimg accounts`显示“探测失败”，或账户突然401 | OpenAI撤销了会话，通常在大量/快速检查后（每次`accounts`/探测= 3次后端调用）。这**不是**速率限制 - 等待不会有帮助，强制刷新无法恢复它。 为该账户重新运行`cgimg login`，并谨慎探测。 |
## 归属和许可证
本项目供应商代码来自：
- [**chatgpt2api**](https://github.com/basketikun/chatgpt2api) — Copyright (c) 2026 kunkun, MIT License. 驱动OAuth + 图像后端。 在`src/cgimg/_vendor/`下提供。
被vendored的文件保留其原始行为。参见[`NOTICE`](./NOTICE)获取详细信息。
