1 files changed, 290 insertions, 0 deletions
diff --git a/doc/config.md b/doc/config.md
new file mode 100644
index 0000000..f200cdc
--- /dev/null
+++ b/doc/config.md
@@ -0,0 +1,290 @@
+# 設定ファイル仕様
+
+## 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>
+├─ 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としてロードできなければ起動失敗
+
+### `vae`
+
+- 任意のファイル名
+- 指定した場合は`<root>/vae/<vae>`として解決し、base modelのVAEを置換
+- 指定時は起動時にファイルの存在を確認
+- 省略時はcheckpointに含まれるVAEを使用
+
+## 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だけを使用することを推奨する。