# 設定ファイル仕様

## 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` |
| `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"
```

### `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 |
| `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++`へ変更する。他の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のファイル名を
自動判定して設定を書き換えることはない。

### `default_size`

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

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

## 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だけを使用することを推奨する。