path: root/doc/config.md

# 設定ファイル仕様

## 1. 概要

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

```powershell
uv run mcp-sd15 --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>
```

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

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

## 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"
default_size = "square_512"
```

### `steps`

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

### `cfg_scale`

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

### `scheduler`

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

| 値 | Diffusers scheduler |
|---|---|
| `dpmpp_2m` | DPM-Solver++、solver order 2 |
| `ddim` | DDIM |
| `euler` | Euler Discrete |
| `euler_a` | Euler Ancestral Discrete |

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

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

## 9. 最小設定例

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

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

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

## 10. 全設定例

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

## 11. 起動時validation

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

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

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