# agy-image-mcp

**中文** | [English](README.en.md)

**讓 Claude Code 用你的 Google AI Pro 訂閱生圖** —— 不需要 Gemini API key，也不用按張付費。

這是一個 MCP server（MCP 是讓 Claude 使用新工具的標準方式），包裝 Google 官方的 Antigravity CLI（`agy`）。
Claude 會拆解需求、寫 prompt、生圖、看預覽圖檢查、不滿意就自己修改重試，最後交出精確尺寸的成品。

目前版本：**1.0.0**（[更新紀錄](CHANGELOG.md)）

## 主要功能

- 🆓 **用訂閱配額生圖**：走 Google AI Pro 的訂閱額度，不需要 API key，沒有每張圖的費用。
- 🛡️ **只用官方工具**：只呼叫官方 `agy` 執行檔，不讀取登入憑證、不呼叫任何私有 API。
- 📐 **尺寸精確**：自動選最接近的長寬比，再裁切成你要的像素尺寸（例如 1080×1350），不靠 AI 目測。
- 👀 **Claude 自己檢查、自己重試**：Claude 看縮小的預覽圖判斷（省 token），不符需求就修改 prompt 重試；每張圖最多 3 次，超過會停下來問你。
- ✍️ **文字後製，不靠 AI 寫字**：生圖模型寫中文常出錯，所以標題、標語由 Claude 用 Noto Sans 排上去，生圖時會先保留留白；背景的小字則不強求去除。
- 📊 **配額看得到**：生圖前先查剩餘配額（不消耗配額，用完就不啟動、不計次數），並告訴你還要等多久。
- ⏱️ **不卡住、不空等**：執行中一偵測到配額用盡就立刻停下回報；圖片一生好就結束，一張約 30–60 秒。
- ✅ **有自動化測試**：附離線測試（不耗配額）與實機生圖測試。

## 運作方式

<p align="center">
  <img src="docs/flow.png" alt="agy-image-mcp 生圖流程圖" width="540">
</p>

## 快速開始

需要：Windows 10/11、Python 3.10 以上、Git、[Claude Code](https://docs.claude.com/en/docs/claude-code)（需要終端機版的 `claude` 指令）、
**付費的 Google AI Pro 訂閱**。

> **第一次安裝建議照 [DEPLOY.md](DEPLOY.md) 逐步做**：它多了每一步的確認方式、設定檔範例與疑難排解。以下是快速版。

**1. 安裝並登入 agy**（Google 官方安裝腳本，會驗證檔案雜湊）：

```powershell
irm https://antigravity.google/cli/install.ps1 | iex
```

裝完**開一個新的 PowerShell 視窗**，執行 `agy`，在瀏覽器用 Google AI Pro 帳號登入。**接下來的指令都在這個新視窗執行。**

**2. 下載本專案並安裝**：

```powershell
git clone https://github.com/sshenwen-glitch/agy-image-mcp.git C:\tools\agy-image-mcp
cd C:\tools\agy-image-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe tests\test_acceptance.py   # 離線測試，不耗配額
```

**3. 註冊到 Claude Code**：

```powershell
claude mcp add agy-image --scope user `
  -- "C:\tools\agy-image-mcp\.venv\Scripts\python.exe" "C:\tools\agy-image-mcp\server.py"
```

註冊後可用 `claude mcp get agy-image` 確認顯示 `Connected`。接著：

4. **拉長工具逾時**：每張圖約 30–60 秒。編輯 `%USERPROFILE%\.claude\settings.json`：
   - 檔案不存在 → 新建，內容只放：
     ```json
     {
       "env": { "MCP_TOOL_TIMEOUT": "360000" }
     }
     ```
   - 檔案已存在 → 在最外層 `{ }` 裡加一行 `"env": { "MCP_TOOL_TIMEOUT": "360000" }`，**和前一行之間要有逗號**；
     原本已有 `"env"` 時，改把 `"MCP_TOOL_TIMEOUT": "360000"` 加進去。不要整個覆蓋。
5. **套用生圖規則**：把 [CLAUDE_SNIPPET.md](CLAUDE_SNIPPET.md) 貼進 `%USERPROFILE%\.claude\CLAUDE.md`（沒有就新建），並把其中的 `<repo>` 換成 `C:\tools\agy-image-mcp`。
6. **（選用）下載字型**讓 Claude 自動排標題：把 [`NotoSansTC[wght].ttf`](https://github.com/google/fonts/raw/main/ofl/notosanstc/NotoSansTC%5Bwght%5D.ttf) 放到 `C:\tools\agy-image-mcp\fonts\`（`fonts` 資料夾要先建立；用 PowerShell 複製時請用 `Copy-Item -LiteralPath`，否則 `[wght]` 會被當成萬用字元）。
7. **重開 Claude Code**：在 Claude Code 輸入 `/exit`（或關閉終端機），再重新執行 `claude`。Claude 要重開後才會載入工具與規則。

## 使用方式

裝好後，在 Claude Code 直接用平常的話提出需求即可，例如：

- 「幫我做一張 1080×1350 的店家公告底圖，主題是颱風天照常營業，標題寫『颱風天照常營業』」
- 「生一張 1920×1080 的網站橫幅，咖啡廳的早晨氛圍，左側留白放標語」
- 「做一張 1080×1080 的 IG 貼文，夏季冰飲主題，不用文字」

Claude 會：

1. 把需求整理成 prompt，呼叫生圖工具（工具會自動先查配額，用完就直接告訴你要等多久）。
2. 生圖後看預覽圖逐項檢查，不符合就修改重試（最多 3 次，超過會先問你）。
3. 有標題時，用 Noto Sans 把文字排到預留的位置（需先完成快速開始第 6 步；沒有字型時會交付底圖並列出要放的文字）。
4. 回報成品路徑。

圖片存在 `%USERPROFILE%\agy-images\<job_id>\`（可用 `AGY_IMAGE_OUT_DIR` 更改）：`final_<n>.png` 是成品，`final_<n>_text.png` 是排好字的版本。

沒指定尺寸時預設 1080×1350（4:5 社群直式）。想知道還剩多少配額，可以直接問 Claude「生圖配額還剩多少？」。

## 限制

- 只在 **Windows** 上驗證過；只在 **Claude Code** 上測試過。
- 每張約 30–60 秒（agy 啟動偶爾更慢）。不同的圖可以同時生成；同一張圖的重試會依序進行。同時生成多張時配額消耗也會加快。
- 尺寸上限預設每邊 8192 px（`AGY_IMAGE_MAX_SIDE` 可調整）。
- 生圖模型的輸出比例是固定的幾種，會再裁切成你要的尺寸。常見尺寸（例如 1080×1350）約裁掉 7% 的畫面；
  少見的比例會裁更多，回傳的 `crop_loss_pct` 會顯示實際比例。
- 標題文字不由 AI 畫，一律後製；背景招牌上的文字可能是錯亂的字。
- 生圖次數受你的 Google AI Pro 配額限制。配額分成 `Gemini Models`（Flash／Pro 共用）、`Gemini 4 Argon`、
  `Claude and GPT models` 三個群組，各有每週與 5 小時上限；生圖用的是 `Gemini Models`。

## 安全性

- 本工具只執行 Google 官方的 `agy`，不讀取你的登入憑證，也不呼叫任何未公開的 API。
- **請了解這個信任前提**：agy 必須以「自動核准」模式執行（`--dangerously-skip-permissions`），因為背景執行時沒辦法逐一詢問你。
  這代表 agy 的 AI 代理在執行期間**可以自動使用它的所有工具**，本工具只能降低、無法完全杜絕風險：
  - 加上 `--sandbox`：限制終端機指令（但實測曾有指令仍被執行，因此另有下方的回報機制）。
  - 給 agy 的指示只要求生圖，不要它讀寫檔案或執行指令；`--add-dir` 只額外加入該次生圖的資料夾，但**不保證** agy 碰不到其他檔案。
  - 只接受 agy 這次在自己資料夾產生的新圖片，不會因為 agy 回覆了某個路徑就搬動你的檔案。
  - 參考圖（`ref_images`）只接受真正的圖片檔，避免其他檔案被一併送出。
  - agy 執行了終端機指令（`agy_ran_commands`）或用到生圖以外的工具（`agy_unexpected_tools`）時，結果中會列出，方便你檢查。
- 建議只在你信任的電腦與帳號上使用，並留意上述回報。

## 常見問題

**會不會被 Google 停權？**
本工具只透過官方 CLI 操作，和你自己在終端機使用 agy 相同。但服務條款由 Google 決定，請自行確認並遵守 Antigravity 的服務條款。

**可以生幾張？**
依你的 Google AI Pro 配額而定。問 Claude「生圖配額還剩多少？」就會顯示各群組剩餘百分比與重置時間。
某個對話模型的群組用完時，可改 `AGY_MODEL` 換到另一個群組（見[環境變數](#環境變數)）。

**需要付費嗎？**
需要有付費的 Google AI Pro 訂閱；除此之外不需額外付費，生圖使用的是訂閱內的額度。

**能用在 macOS / Linux 或 Claude Desktop 嗎？**
程式本身不限平台，但目前只在 Windows + Claude Code 上驗證過，其他環境可能需要調整。

## 疑難排解

| 狀況 | 怎麼辦 |
|---|---|
| 裝完 agy 後顯示錯誤，或 `agy` 不是可辨識的指令 | 開一個**新的** PowerShell 視窗再試（舊視窗讀不到新的 PATH） |
| `claude mcp get agy-image` 不是 `Connected` | 確認註冊指令裡兩個路徑都是完整路徑、檔案存在；重做快速開始第 2 步 |
| 生圖途中 Claude Code 顯示工具逾時 | 完成快速開始第 4 步並重開 Claude Code |
| Claude 沒有使用生圖工具，或不照規則做 | 重開 Claude Code；確認 `CLAUDE.md` 有貼上規則、`<repo>` 已換成實際路徑 |

其他狀況（配額用盡、`BUSY`、排字超出圖片等）見 [DEPLOY.md 疑難排解](DEPLOY.md#疑難排解)。

## 更新與移除

- **更新**：`git pull` 後重新安裝套件、跑測試、重開 Claude Code；若 [CHANGELOG](CHANGELOG.md) 註明規則有更新，也要重新貼上 `CLAUDE_SNIPPET.md`。步驟見 [DEPLOY.md 更新](DEPLOY.md#更新)。
- **移除**：`claude mcp remove agy-image -s user`，再刪除設定與資料夾。步驟見 [DEPLOY.md 移除](DEPLOY.md#移除)。

## 回報問題

歡迎到 [GitHub Issues](https://github.com/sshenwen-glitch/agy-image-mcp/issues) 回報，請附上：

- 問 Claude「執行 image_status」得到的結果（含本工具與 agy 的版本）
- 發生了什麼、你預期的結果、錯誤訊息（`error_type` 與 `message`）
- 相關的 log：`%USERPROFILE%\agy-images\<job_id>\agy_log_<n>.ndjson` 與 `agy_cli_<n>.log`

> ⚠️ log 裡會有你的 prompt、檔案路徑與 Google 帳號 email，貼上前請先檢查並刪掉不想公開的內容。

> 本專案為個人開源專案，與 Google 無關。

---

## 進階

### 提供的工具

| 工具 | 說明 |
|---|---|
| `generate_image` | 輸入 prompt、寬、高 → 產出精確尺寸的 `final_<n>.png` 與長邊 ≤1024 的 `preview_<n>.png`。預設不畫標題等主要文字並保留留白；同一張圖 3 次（`job_id` 不分大小寫），使用者同意後可帶 `user_approved_more_attempts=true` 再加 3 次；`ref_images` 只接受圖片檔 |
| `image_status` | 查看本工具與 agy 的版本、使用模型、各配額群組剩餘百分比、`can_generate`、最近 10 個 job 的已用次數（不耗配額） |

完整的參數、回傳欄位與錯誤類型見 [SPEC.md 第 3 節](SPEC.md#3-mcp-工具介面)。

### 生圖規則

[CLAUDE_SNIPPET.md](CLAUDE_SNIPPET.md) 是給 Claude 的生圖流程規則（拆需求、檢查重點、重試與錯誤處理、文字後製），部署時貼進 `CLAUDE.md`。

### 文字後製腳本

[scripts/add_title.py](scripts/add_title.py) 在底圖上方排主標與副標，Claude 會自動呼叫，也可以手動使用（在專案資料夾內執行）：

```powershell
.venv\Scripts\python.exe scripts\add_title.py final_1.png out.png `
  --font "fonts\NotoSansTC[wght].ttf" --title "標題文字" --subtitle "副標文字"
```

標題過長會自動換行（主標盡量 2 行內、避免在詞中間斷行），也可以用 `\n` 指定換行位置；顏色可寫 `#RGB` 或 `#RRGGBB`。
文字超出圖片時會印出 `overflow=true` 並以結束碼 3 結束（圖仍會存檔）。全部參數見 `--help`。

### 環境變數

| 變數 | 預設 | 說明 |
|---|---|---|
| `AGY_IMAGE_OUT_DIR` | `~/agy-images` | 輸出根目錄 |
| `AGY_MODEL` | `gemini-3.8-flash-low` | 呼叫生圖子代理的對話模型；`agy models` 可列出。空字串則用 agy 預設 |
| `AGY_PATH` | 自動搜尋 | agy 執行檔路徑 |
| `AGY_IMAGE_MAX_ATTEMPTS` | `3` | 每個 job 的嘗試上限 |
| `AGY_IMAGE_TIMEOUT` | `300` | 單次呼叫的總時間上限（秒，含等待同一 job 的前一次嘗試與查配額），也是 `timeout_s` 的上限。調高時 `MCP_TOOL_TIMEOUT` 也要跟著調高（至少多 60 秒） |
| `AGY_EXTRA_ARGS` | 空 | 額外 agy 參數 |
| `AGY_QUOTA_CHECK` | `1` | 生圖前以 `/usage` 檢查配額；`0` 關閉 |
| `AGY_USAGE_TTL` | `60` | 配額查詢結果快取秒數 |
| `AGY_EARLY_FINISH` | `1` | 圖片完整寫入就結束 agy，不等它寫完回覆（每張省 30–40 秒）；`0` 關閉 |
| `AGY_IMAGE_MAX_SIDE` | `8192` | 寬或高的上限（px），避免超大尺寸用光記憶體 |
| `AGY_STATE_RETENTION_DAYS` | `30` | 超過幾天沒用的 job 次數紀錄自動清除；`0` 不清 |
| `AGY_LOG_RETENTION_DAYS` | `30` | 超過幾天的 agy log 自動清除；`0` 不清。**圖片一律不會自動刪除** |
| `AGY_BRAIN_DIR` | `~/.gemini/antigravity-cli/brain` | agy 存圖的資料夾；agy 改版搬家時才需要設定（`image_status` 的 `brain_dir_found` 會提醒） |

環境變數在註冊時用 `-e` 設定，例如 `claude mcp add agy-image --scope user -e AGY_IMAGE_OUT_DIR="D:\my-images" -- ...`。

### 輸出結構

```
<AGY_IMAGE_OUT_DIR>/
├── state.json                 # 各 job 嘗試次數、429 重置時間（state.lock 用於多個工作階段同時寫入）
├── .locks/<job_id>.lock       # 同一個 job 的跨工作階段鎖（過期的會隨舊 log 一起清掉）
└── <job_id>/
    ├── raw_<n>.*              # agy 原始輸出（jpg/png/webp）
    ├── final_<n>.png          # 精確尺寸成品
    ├── preview_<n>.png        # 長邊 ≤1024，給 Claude 檢查用
    ├── final_<n>_text.png     # 排好標題的版本（有後製文字時）
    ├── final_<n>_text_preview.png  # 排字版的預覽圖
    ├── ref_<n>_<i>.*          # 參考圖副本（有提供時）
    ├── agy_log_<n>.ndjson     # agy 的 stream-json 紀錄
    └── agy_cli_<n>.log        # agy 內部 log（用於偵測配額用盡）
```

## 參與開發

測試、重新產生流程圖、修改時要同步哪些檔案、發布流程，見 [CONTRIBUTING.md](CONTRIBUTING.md)。
規格與設計決策見 [SPEC.md](SPEC.md)，開發與驗收過程見 [docs/DEVELOPMENT_LOG.md](docs/DEVELOPMENT_LOG.md)。

## 授權

[MIT License](LICENSE)