# generate-image-sd15-mcp

ローカルの NVIDIA GPU と Stable Diffusion 1.x 互換 checkpoint を使う、stdio MCP
サーバです。Text-to-Image、Depth/Openpose 誘導生成、ControlNet Inpaint を公開します。

プロンプトは `sd_embed` を用いた `prompt_embeds` ベースで処理され、77 token制限を超える
長文プロンプトとAUTOMATIC1111互換の重み付き記法`(word:1.5)`に対応します。`clip_skip`と
`pad_last_block`は`[generation]`で指定できます。

## セットアップ

1. NVIDIA driverがCUDA 13.2対応PyTorchを実行できることを`nvidia-smi`で確認します。
2. `config.example.toml` をコピーし、モデルの root とファイル名を設定します。
3. `uv sync` を実行します。PyTorchは専用indexからCUDA 13.2版が導入されます。
4. `uv run generate-image-sd15-mcp --config path/to/config.toml` で起動します。

トランスポートはTOMLの`[server]`で切り替えます。省略時は`stdio`です。
`streamable-http`を使う場合は次のように設定します。

```toml
[server]
transport = "streamable-http"
host = "127.0.0.1"
port = 8000
```

この場合、MCPクライアントは`http://127.0.0.1:8000/mcp`へ接続します。

全ツールで共通するbase promptを`[prompt]`で指定できます。プロンプトファイルは
`<root>/prompts/`に配置し、TOMLにはファイル名だけを記述します。

```toml
[prompt]
positive_file = "positive.txt"
negative_file = "negative.txt"
```

起動時にファイルを読み込み、LLMからのプロンプトと結合してpipelineへ渡します。
positiveは`base, user`の順でカンマ区切り、negativeは`base\nuser`の順で改行区切りです。

モデルは `<root>/checkpoints`、`vae`、`lora`、`controlnet` からだけ読み込みます。
VAE componentは生成に常に必要です。`model.vae`を省略した場合はcheckpoint内蔵VAEを使い、
指定した場合だけ外部VAEへ置き換えます。設定されたLoRAは初回生成時にすべてロードされ、3つの
生成ツールに共通して適用されます。MCP呼び出しごとのLoRA切替には対応しません。
Depth/Openpose の annotator 重みは `controlnet_aux` のローカルキャッシュに事前配置して
ください。推論時のダウンロードは行いません。

MCP の `input_image` / `mask_image` は PNG または JPEG の Base64（data URI も可）です。
mask は白い領域が再生成対象です。出力は PNG の画像 content で、seed 等は PNG metadata
にも記録されます。

GPU を使わないテストは `uv run pytest`、lint は `uv run ruff check .`、型検査は
`uv run pyright` で実行できます。実モデルの smoke test は環境依存のため自動テストには
含めていません。

起動・MCP初期化・ツール一覧取得では画像モデルをロードせず、CUDAを初期化しません。
設定とモデルファイルの存在は起動時に確認し、有効な生成要求の実行時にSD本体・VAE・LoRAを
ワーカースレッドでロードします。モデル互換性やCUDAのエラーは初回生成時に返されます。
同一プロセスではロード済みモデルを再利用し、stdioプロセスの終了で解放します。
一覧取得と生成を別プロセスで行うクライアントでは、生成プロセスごとのロードが必要です。

実際のCLI/stdio経路の一覧取得とVRAMを確認するには次を実行します（常駐化は不要です）。

```powershell
uv run python script\smoke_stdio.py --config data\config.toml `
  --result data\verification-lazy-load\list.json
```

`--images 2`を追加すると、固定seedで同じ接続から2枚生成し、PNG、画素ハッシュ、時間、
PNGメタデータ、stderr、生成前後とプロセス終了後の`nvidia-smi`結果を記録します。
seed固定は確認スクリプト内だけに適用され、製品のMCPスキーマやseed処理は変えません。
要求の待機上限は`--timeout`で指定します（既定300秒）。Windowsでプロセス別VRAMが
`N/A`の場合は取得不能として扱い、GPU全体の使用量とプロセスの終了も確認してください。

実GPUとMCP経路を使う`generate_image` smoke testは次のように実行できます。

```powershell
uv run python script\smoke_generate_image.py `
  --config data\config.generate-image.toml `
  --output data\outputs\generate-image-mcp-512.png
```

同じ2つのseedでMCP生成を行い、処理時間、PyTorch allocatorのpeak VRAM、白背景率、
prompt token数をJSONへ記録する比較用benchmarkは次のように実行できます。

```powershell
uv run python script\benchmark_generate_image.py `
  --config data\config.toml `
  --label anime-quality `
  --output-dir data\outputs\benchmark `
  --result data\outputs\benchmark\results\anime-quality.json
```

benchmarkはMCP schemaを変更せず、計測処理内だけでseedを固定します。1枚目にはCUDAの初回
warm-upが含まれるため、定常速度の比較には2枚目の`elapsed_seconds`を使用してください。