path: root/doc/config.md

# 設定ファイル仕様

## 1. 概要

`generate-image-sd15-mcp`のモデル構成と生成設定はTOMLファイルで管理する。起動時に次のように指定する。

```powershell
uv run generate-image-sd15-mcp --config C:\path\to\config.toml
```

`--config`を省略した場合は、現在のworking directoryにある`config.toml`を読み込む。
設定値をCLIやMCPツール入力で上書きすることはできない。

## 2. モデルディレクトリ

`model.root`の下には次のディレクトリ構成が必要である。

```text
<model.root>/
├─ checkpoints/
│  └─ <model.checkpoint>
├─ huggingface/
│  └─ Diffusersが使用するローカル構成cache
├─ vae/
│  └─ <model.vae>
├─ lora/
│  └─ <model.lora.file>
├─ controlnet/
│  ├─ <controlnet.depth.model>
│  ├─ <controlnet.openpose.model>
│  └─ <controlnet.inpaint.model>
└─ prompts/
   ├─ <prompt.positive_file>
   └─ <prompt.negative_file>
```

各モデル項目にはパスではなくファイル名だけを記述する。絶対パス、ディレクトリ名を含む
相対パス、`.`、`..`は拒否される。

## 3. 設定項目一覧

| TOML key | 型 | 必須 | 既定値 |
|---|---|---:|---|
| `model.root` | string | Yes | なし |
| `model.checkpoint` | string | Yes | なし |
| `model.vae` | string | No | 未使用 |
| `model.lora[].file` | string | LoRA使用時 | なし |
| `model.lora[].weight` | number | No | `1.0` |
| `generation.steps` | integer | No | `25` |
| `generation.cfg_scale` | number | No | `7.0` |
| `generation.scheduler` | string enum | No | `dpmpp_2m_karras` |
| `generation.default_size` | string enum | No | `square_512` |
| `generation.clip_skip` | integer | No | `0` |
| `generation.pad_last_block` | boolean | No | `false` |
| `controlnet.depth.enabled` | boolean | No | `false` |
| `controlnet.depth.model` | string | 有効時 | なし |
| `controlnet.depth.preprocessor` | string | No | `midas` |
| `controlnet.openpose.enabled` | boolean | No | `false` |
| `controlnet.openpose.model` | string | 有効時 | なし |
| `controlnet.inpaint.enabled` | boolean | No | `false` |
| `controlnet.inpaint.model` | string | 有効時 | なし |
| `output.enabled` | boolean | No | `false` |
| `output.directory` | string | No | `./outputs` |
| `server.transport` | string enum | No | `stdio` |
| `server.host` | string | No | `127.0.0.1` |
| `server.port` | integer | No | `8000` |
| `prompt.positive_file` | string | No | なし |
| `prompt.negative_file` | string | No | なし |

## 4. `[model]`

base checkpoint、VAE、LoRAを指定する必須tableである。

```toml
[model]
root = "D:/AI/models"
checkpoint = "model.safetensors"
vae = "vae.safetensors"
```

### `root`

- 必須の空でない文字列
- 絶対パスを推奨
- 相対パスの場合はconfigファイルが置かれたディレクトリを基準に解決
- 起動時にディレクトリの存在を確認

### `checkpoint`

- 必須のファイル名
- `<root>/checkpoints/<checkpoint>`として解決
- 起動時にファイルの存在を確認
- サーバ初期化時にSD1.x pipelineとしてロードできなければ起動失敗
- 単一checkpointの読込に必要なDiffusers構成は`<root>/huggingface` cacheから取得

### `vae`

- Stable Diffusion pipelineのVAE component自体は必須
- 任意のファイル名
- 指定した場合は`<root>/vae/<vae>`として解決し、base modelのVAEを置換
- 指定時は起動時にファイルの存在を確認
- 省略時はcheckpointに含まれるVAEを使用

`model.vae`が任意なのはVAE処理を省略できるという意味ではなく、外部VAEファイルによる
差し替えが任意という意味である。checkpoint内にもVAEが存在しない場合はpipelineを構築
できないため起動に失敗する。

## 5. `[[model.lora]]`

LoRAごとにarray of tablesを追加する。0個以上指定でき、記述順にadapter名が割り当てられる。

```toml
[[model.lora]]
file = "detail.safetensors"
weight = 0.8

[[model.lora]]
file = "style.safetensors"
weight = 0.5
```

| Key | 型 | 制約 |
|---|---|---|
| `file` | string | 必須のファイル名。`<root>/lora/<file>`に存在すること |
| `weight` | number | `-4.0`以上`4.0`以下。既定値`1.0` |

同じ`file`を複数回指定することはできない。LoRAを使わない場合は
`[[model.lora]]`を記述しない。

## 6. `[generation]`

全ツールに共通する推論パラメータを指定する。table自体を省略した場合はすべて既定値となる。

```toml
[generation]
steps = 25
cfg_scale = 7.0
scheduler = "dpmpp_2m_karras"
default_size = "square_512"
clip_skip = 0
pad_last_block = false
```

### `steps`

- integerのみ
- 範囲は`1`以上`150`以下
- booleanや小数は不可

### `cfg_scale`

- finiteなintegerまたはfloat
- 範囲は`0.0`以上`30.0`以下
- `NaN`や無限大は不可

### `scheduler`

次の値だけを指定できる。

| 値 | Diffusers scheduler |
|---|---|
| `dpmpp_2m_karras` | `DPMSolverMultistepScheduler`。DPM++ 2M、Karras sigmas |
| `dpmpp_2m_sde_karras` | `DPMSolverMultistepScheduler`。DPM++ 2M SDE、Karras sigmas |
| `ddim` | DDIM |
| `ddim_trailing` | DDIM。`timestep_spacing="trailing"`を強制 |
| `euler_a` | Euler Ancestral Discrete |
| `lcm` | Latent Consistency Model scheduler |

`dpmpp_2m_karras`は`algorithm_type="dpmsolver++"`、`solver_order=2`、
`use_karras_sigmas=true`で構築する。`dpmpp_2m_sde_karras`は`algorithm_type`だけを
`sde-dpmsolver++`へ変更する。`ddim_trailing`は`ddim`と同じ`DDIMScheduler`を使用し、
`timestep_spacing="trailing"`だけを明示的に上書きする。他のschedulerはpipeline scheduler
configを引き継ぐ。

### LCM-LoRA設定例

LCM-LoRAも通常のLoRAと同じ方法で指定する。

```toml
[[model.lora]]
file = "lcm-lora-sdv1-5.safetensors"
weight = 1.0

[generation]
steps = 4
cfg_scale = 1.0
scheduler = "lcm"
default_size = "square_512"
```

`lcm`選択時も`steps`と`cfg_scale`はTOML値をそのまま使用する。LCM-LoRAのファイル名を
自動判定して設定を書き換えることはない。

### Hyper-SD設定例

Hyper-SD15固定step LoRAも通常のLoRAと同じ方法で指定する。`ddim_trailing`は
Hyper-SD向けの推奨schedulerであり、`timestep_spacing="trailing"`を強制する。
stepsや`cfg_scale`はTOML値をそのまま使用し、LoRAファイル名による自動判定や自動補正は
行わない。

```toml
[[model.lora]]
file = "Hyper-SD15-4steps-lora.safetensors"
weight = 1.0

[generation]
steps = 4
cfg_scale = 0.0
scheduler = "ddim_trailing"
default_size = "square_512"
```

### `default_size`

MCPツールで`size`を省略した場合に使用するサイズIDである。

| 値 | 解像度 |
|---|---:|
| `square_512` | 512 x 512 |
| `landscape_512` | 512 x 384 |
| `portrait_512` | 384 x 512 |

### `clip_skip`

`sd_embed`によるプロンプト埋め込み生成時にCLIPの最終層から何層スキップするかを指定する。

- integerのみ。範囲は`0`以上`12`以下
- `0`のとき最終層を使用（既定値）
- `1`のとき最後から2番目の層を使用
- `sd_embed`の`get_weighted_text_embeddings_sd15`の`clip_skip`引数に渡される

### `pad_last_block`

`sd_embed`によるプロンプト埋め込み生成時に最終ブロックをパディングするかを指定する。

- boolean。既定値`false`
- `true`のとき77 token単位の最終ブロックをパディングして埋め込みを生成する

## 7. `[controlnet.*]`

ControlNetは用途ごとに個別設定する。各tableを省略するとその機能は無効になる。

### Depth

```toml
[controlnet.depth]
enabled = true
model = "control_v11f1p_sd15_depth.safetensors"
preprocessor = "midas"
```

| Key | 仕様 |
|---|---|
| `enabled` | boolean。既定値`false` |
| `model` | 有効時に必須。`<root>/controlnet/<model>`として解決 |
| `preprocessor` | `midas`のみ指定可能。省略時も`midas` |

### OpenPose

```toml
[controlnet.openpose]
enabled = true
model = "control_v11p_sd15_openpose.safetensors"
```

この設定はMCPの`openpose`と`openpose_full`の両方で使用する。前者はbody、後者は
body、hand、faceを抽出する。preprocessorをMCPや設定から切り替えることはできない。

### Inpaint

```toml
[controlnet.inpaint]
enabled = true
model = "control_v11p_sd15_inpaint.safetensors"
```

元画像とmaskからControlNet Inpaint用conditionを生成する。maskの輝度が50%を超える領域が
再生成対象になる。

### Annotatorモデル

MiDaSとOpenPoseのannotator重みは`controlnet_aux`のローカルcacheに事前配置する必要がある。
サーバは推論時に外部ネットワークから自動取得せず、`local_files_only=true`でロードする。
annotator重みの場所をこのTOMLから指定する項目はない。

## 8. `[output]`

生成したPNGをMCPレスポンスに加えてローカル保存するかを指定する。

```toml
[output]
enabled = false
directory = "./outputs"
```

| Key | 仕様 |
|---|---|
| `enabled` | `true`で保存、`false`でMCP返却のみ。既定値`false` |
| `directory` | 保存先。既定値`./outputs` |

## 9. `[server]`

MCPトランスポートとHTTP待受アドレスを指定する。table自体を省略した場合は
`stdio`トランスポートになる。

```toml
[server]
transport = "stdio"
```

streamable-httpトランスポートを使う場合は次のように指定する。

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

### `transport`

次の値だけを指定できる。

| 値 | 動作 |
|---|---|
| `stdio` | 標準入出力でMCPクライアントと通信する。既定値 |
| `streamable-http` | HTTPでMCPクライアントと通信する。`http://<host>:<port>/mcp`で接続する |

`sse`はMCP仕様で非推奨のため選択できない。

### `host`

- `transport`が`streamable-http`のときに使用する待受アドレス
- 既定値は`127.0.0.1`（localhostのみ）
- `0.0.0.0`を指定すると全インターフェースでリッスンする
- `transport`が`stdio`のときは使用されない

### `port`

- `transport`が`streamable-http`のときに使用する待受ポート
- `1`以上`65535`以下のinteger
- 既定値は`8000`
- `transport`が`stdio`のときは使用されない

## 10. `[prompt]`

全ツールで共通するbase promptを指定する。プロンプトファイルは`<root>/prompts/`に
配置し、TOMLにはファイル名だけを記述する。table自体を省略した場合はbase promptなし
（後方互換）となる。

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

起動時にファイルを読み込み、LLMからのプロンプトと結合してpipelineへ渡す。

### 結合規則

| 項目 | 結合方式 |
|---|---|
| positive | `base_positive, user_positive` の順でカンマ区切り |
| negative | `base_negative\nuser_negative` の順で改行区切り |

baseが空の場合はuserプロンプトのみになる。userの`positive_prompt`が空の場合は
従来通りエラーになる。

### `positive_file`

- `<root>/prompts/<positive_file>`として解決
- ファイル名のみ指定可能。パスは拒否される
- 省略時はbase positiveなし

### `negative_file`

- `<root>/prompts/<negative_file>`として解決
- ファイル名のみ指定可能。パスは拒否される
- 省略時はbase negativeなし

相対`directory`はconfigファイルのディレクトリを基準に解決する。保存が有効な場合、
ディレクトリは最初の保存時に作成され、ファイル名はランダムUUIDの`<uuid>.png`となる。

## 11. 最小設定例

Text-to-Imageだけを使用する最小構成は次のとおり。

```toml
[model]
root = "D:/AI/models"
checkpoint = "model.safetensors"
```

この場合、VAEとLoRAは使用せず、全ControlNetとローカル保存は無効になる。生成設定には
既定値が使用される。

## 12. 全設定例

```toml
[model]
root = "D:/AI/models"
checkpoint = "model.safetensors"
vae = "vae.safetensors"

[[model.lora]]
file = "detail.safetensors"
weight = 0.8

[[model.lora]]
file = "style.safetensors"
weight = 0.5

[generation]
steps = 25
cfg_scale = 7.0
scheduler = "dpmpp_2m_karras"
default_size = "square_512"

[controlnet.depth]
enabled = true
model = "control_v11f1p_sd15_depth.safetensors"
preprocessor = "midas"

[controlnet.openpose]
enabled = true
model = "control_v11p_sd15_openpose.safetensors"

[controlnet.inpaint]
enabled = true
model = "control_v11p_sd15_inpaint.safetensors"

[output]
enabled = false
directory = "./outputs"

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

## 13. 起動時validation

次のいずれかに該当するとMCPサーバは起動しない。

- TOML syntaxが不正
- 必須tableまたは必須値がない
- 値の型、列挙値、数値範囲が不正
- モデル項目にファイル名以外のパスが指定されている
- LoRAファイル名が重複している
- `model.root`が存在しない
- checkpoint、指定VAE、LoRA、有効なControlNetのファイルが存在しない
- CUDAが利用できない
- base checkpoint、VAE、LoRAがDiffusersでロードできない

未定義のkeyは現在の実装ではエラーにはならないが、処理には使用されない。タイプミスを
見逃さないため、この文書に記載したkeyだけを使用することを推奨する。