# gpt-image-mcp

OpenAI の画像生成／編集を MCP ツールとして出すサーバ。
**同じキャラクターの差分絵（口の形・目の開閉）を作る**用途を主目的にしている。

## なぜ単なるAPIラッパーではないか

`/v1/images/edits` は、マスクを渡しても**画像全体を再生成する**。

実測（2026-08-12・`gpt-image-2`・1024x1024）:

| | マスク内で変化 | **マスク外で変化** | マスク外の最大差分 |
|---|---|---|---|
| 口を「あ」に編集 | 7,184px (35.8%) | **9,425px (0.92%)** | **220** |
| 口を「い」に編集 | 1,498px (7.5%) | **7,431px (0.72%)** | **216** |

最大差分220は「ほぼ別の色」。**編集結果をそのまま動画のコマに使うと、口が変わるたびに髪や輪郭も動く**——
30fps で切り替えると顔が揺れる。

このサーバは対処を同梱している。**編集結果は「口の形の参考」として扱い、土台は1枚に固定して、
マスク領域だけをローカルで貼り直す**（`compose_region`）。土台はビット単位で保たれる。

| | マスク外の最大差分 |
|---|---|
| 編集結果をそのまま使う | 220 |
| 単純にぼかして合成 | 55（ぼけがマスク外へ滲む） |
| **`compose_region`（内側だけぼかす）** | **10（知覚不能）** |

## ツール

| ツール | 課金 | 何をするか |
|---|---|---|
| `list_image_models` | なし | このキーで使える画像モデルを列挙。**キーが生きているかの確認にも使う** |
| `generate_image` | あり | プロンプトから生成し、ファイルに保存してパスを返す |
| `edit_image` | あり | マスク指定で編集。**そのままコマに使わないこと**（上記） |
| `compose_region` | なし | 編集結果のマスク領域だけを土台へ貼る。土台の汚れを自動検証する |
| `make_mask` | なし | 楕円マスクを作る（比率指定） |

画像は base64 で返さず**ファイルに書いてパスを返す**。会話の文脈を食い潰さないため。

## APIキーの扱い

**このサーバはキーを保持しない。** 呼ぶたびに、次の順で解決する。

1. 環境変数 `OPENAI_API_KEY`
2. macOS Keychain（`OPENAI_KEYCHAIN_SERVICE` にサービス名を設定した場合）

エラー本文にキーが混ざった場合は `[REDACTED]` に置換してから返す。

Keychain へ入れる場合（**コマンド履歴にキーを残さない形**）:

```bash
printf 'key: '; stty -echo; read -r K; stty echo; echo
security add-generic-password -a "$USER" -s openai-image -U -w "$K"; unset K
```

> ⚠ `security` の対話入力（`-w` を引数なしで最後に置く形）は**128文字で切り捨てる**。
> `sk-proj-` 形式のキーは164文字あるため、上の「値として渡す」形を使うこと。

## 設定

`.mcp.json` / Claude Code の MCP 設定に追加する。

```json
{
  "mcpServers": {
    "gpt-image": {
      "command": "node",
      "args": ["/path/to/gpt-image-mcp/src/index.mjs"],
      "env": { "OPENAI_KEYCHAIN_SERVICE": "openai-image" }
    }
  }
}
```

## 必要なもの

- Node.js 18+（`fetch` / `FormData` を使う）
- Python 3 ＋ Pillow（`compose_region` / `make_mask`）。`numpy` があれば土台の汚れを自動検証する

```bash
npm install
pip install Pillow numpy
```

## アバターの作り方（この構成での標準手順）

1. `generate_image` で**土台を1枚**作る。背景は単色、影とグラデーションを禁止、正面向き、口は閉じ目は開く
2. `make_mask` で口の領域（目安 `0.40 / 0.455 / 0.60 / 0.575`）と目の領域（`0.34 / 0.32 / 0.66 / 0.42`）のマスクを作る
3. `edit_image` で口の形（あいうえお）と閉じた目を作る
4. **`compose_region` で全部を土台へ貼り直す** ← ここを飛ばすと顔が揺れる
5. 口の形は母音ごとに1枚。日本語の口パクは `a i u e o` ＋ 閉じ口の6枚で足りる

⚠ 「い」のように**変化が小さい口の形は生成が弱い**（実測でマスク内の変化が7.5%しか出ず、
マスク外のほうが動いた）。プロンプトを形で具体的に指示するか、その口だけ手で描くほうが早い。

## 生成物の権利

生成画像を**販売物**に使う場合、「動画に使ってよい」と「販売する教材に使ってよい」が
別条項のことがある。**使う前に、使うキーのアカウントの利用規約を確認すること。**
借りたキーで作った素材を自社商品に使わない。

## ライセンス

MIT