# generate-image-sd15-mcp repository instructions

## 作業の進め方

- 作業前に`doc/Specifications.md`を要件、`doc/Design.md`を責務分割の正本として読む。
  設定を扱う場合は`doc/config.md`、MCP公開面を扱う場合は`doc/mcp.md`も読む。
- 不明点は既存コード、テスト、文書から確認する。要件を変える推測やスコープ拡大が必要な場合だけ
  利用者へ確認する。
- 設計変更では、影響する責務、設定、MCP schema、エラー、テスト、文書を先に洗い出す。
- 実装依頼では調査や提案だけで終わらず、コード、テスト、必要な文書更新、検証まで完了する。
- 既存の単純な構成と責務境界を維持し、依頼されていない汎用化や将来機能を追加しない。
- 変更対象外の利用者の差分を保持する。`data/`以下のモデル、設定、生成物をGitへ追加しない。

## 固定システム要件

- Pythonは3.11、パッケージ管理は`uv`、依存関係の正本は`pyproject.toml`と`uv.lock`とする。
- 対象はStable Diffusion 1.x互換モデル、NVIDIA CUDA GPU、FP16、8GB級VRAMである。
  SDXL、FLUX、CPU推論、複数GPU対応を暗黙に追加しない。
- PyTorchはCUDA 13.2版を使用する。CUDA非対応と推測してCPU版へ置き換えない。
- 推論時の外部ダウンロードを前提にしない。モデルはTOMLで指定されたローカルパスから読む。
- VAE componentは必須である。外部VAE指定時は置換し、省略時はcheckpoint内蔵VAEの存在を確認する。
- LoRAはTOMLの`[[model.lora]]`で0個以上指定し、起動時に全Toolへ共通適用する。
  MCP入力から動的に切り替えない。
- ControlNetはDepth、Openpose、Openpose Full、Inpaintのみを扱い、同時利用は1種類とする。
- 生成は1枚固定、GPUジョブはセマフォで1件ずつ直列化する。
- サイズは`square_512`、`landscape_512`、`portrait_512`だけをMCPへ公開し、任意width/heightを
  追加しない。
- 生成パラメータ、モデル、VAE、LoRA、ControlNet、schedulerはTOML側で管理し、明示的な要件なしに
  MCP Tool入力やCLI引数へ公開しない。
- schedulerは`dpmpp_2m_karras`、`dpmpp_2m_sde_karras`、`euler_a`、`ddim`、`lcm`だけを許可する。
  既定値は`dpmpp_2m_karras`とし、変換処理は`pipeline_factory.py`へ集約する。
- LCM選択時もstepsとCFGを自動変更しない。LCM-LoRAも通常のLoRAとしてTOMLで設定する。

## アーキテクチャ境界

- `server.py`と`tools/`はMCP schema、入力変換、結果変換だけを担当する。
- `service.py`は要求の振り分け、直列化、エラー境界を担当し、Diffusers固有の構築分岐を持たない。
- `config.py`はTOML読込、既定値、型・enum・パス検証を担当する。不正設定は起動時に失敗させる。
- `model_manager.py`はモデルのライフサイクルを管理し、`pipeline_factory.py`はDiffusers pipelineと
  schedulerの構築を担当する。
- MCPの公開Toolは`generate_image`、`generate_guided_image`、`inpaint_image`の3つを維持する。
  schema変更は明示的な仕様変更として扱い、`doc/mcp.md`とschemaテストを同時に更新する。
- 内部例外、ローカルパス、機密情報をMCPエラーへ露出しない。

## 完了ゲート

変更を完了と報告する前に、変更範囲に応じて次を満たす。

1. 要件と責務境界に沿い、関連する正常系・異常系・境界値テストを追加または更新する。
2. 設定、MCP schema、利用方法、設計判断が変わる場合は対応する`doc/`文書と設定例を同期する。
3. `uv run ruff format src tests script`を実行する。
4. `uv run ruff check .`を成功させる。
5. `uv run ruff format --check src tests script`を成功させる。
6. `uv run pyright`をエラーなしで成功させる。
7. `uv run pytest -q`を全件成功させる。
8. `git diff --check`で空白エラーがなく、`git status --short`で意図したファイルだけが変更されている
   ことを確認する。

GPU、実モデル、annotatorを必要とする変更では、利用可能ならREADME記載のsmoke testも実行する。
環境やモデル不足で実行できない場合は、自動テスト成功とsmoke test未実施を明確に区別して報告し、
未確認の動作を成功扱いしない。

## 作業報告

- 変更結果、重要な設計判断、更新ファイル、実行した検証と結果、未実施事項を簡潔に報告する。
- テスト失敗を既存問題として無視しない。今回の差分によるものかを調査し、解消できない場合は根拠と
  影響を報告する。
- コミット、push、PR作成は利用者が明示的に依頼した場合だけ行う。