Local GPU Imagegen

ローカル GPU 画像生成

English | 简体中文

すでにお使いの ComfyUI 環境向けに、暗号技術によるモデル ID、明示的な承認、 永続的な実行証跡を備えた、MCP を第一に考えたコントロールプレーンです。

環境を変更せずに、Codex から対応する ComfyUI ワークフローを実行できます。

uvx local-gpu-imagegen verify
uvx local-gpu-imagegen setup codex --apply

セットアップでは、uvx --from local-gpu-imagegen==0.9.1 local-gpu-imagegen serve と同等の、解決済みでバージョンが固定されたランチャーが登録されます。一時的な uvx 環境のコンソールスクリプトには依存しません。古いエントリーで client_setup_drift が報告される場合は、そのクライアントエントリーのみを削除して、セットアップを再適用してください。ComfyUI を起動しても MCP ランチャーのエラーは修復されません。バックエンドの準備状態は、クライアントがサーバーを読み込んだ後に確認されます。

Codex に次のように尋ねます。

Run this supported ComfyUI API workflow from Codex: <path>.
Use this prompt: <prompt>. Preserve every other workflow setting.

この方法には、Python 3.11 または 3.12、Codex、すでに起動しているローカル ComfyUI インスタンス、インストール済みのモデル、対応する組み込みトポロジーを使用した通常の txt2img API ワークフローが必要です。既存のローカル画像バックエンドとモデルを使用し、モデルのダウンロードや切り替えを暗黙に行うことはありません。バックエンドのインストール、モデルのダウンロード、UI 形式の JSON の変換、未対応のカスタムノードを必要とするワークフローの実行は行いません。Windows のポータブルな管理対象起動オプションについては、以下に明記しています。

v0.9 でサポートするホスト環境は、NVIDIA 搭載の Windows 10/11 x64 です。単一の py3-none-any wheel は純粋な Python パッケージであることを示すものであり、Linux 向けの別エディションや、Linux での管理対象生成をサポートするという主張ではありません。Ubuntu CI では、プラットフォームに依存しない MCP、パッケージング、既存バックエンド、未対応プラットフォームの各コントラクトを検証します。Windows では、ポータブルブートストラップの完全なテストスイートを実行します。

ComfyUI が画像を生成します。Local GPU Imagegen は、その生成を取り巻く権限管理、再現性、レビュー、復旧を制御します。

5 分で始めるクイックスタート | 起動手順ガイド | 代替手段

ComfyUI ワークフローを自分で用意する

Codex のワークフロー登録セッションでは、対応するグラフを調査して登録し、正確なモデルコンポーネントを関連付けました。プロンプトの送信や GPU の使用は行っていません。過去に生成された画像の記録は技術監査用に引き続き利用できますが、v0.9 では宣伝用のビジュアルや、画像品質の優位性を示す証拠として使用しません。

この方法には、既存のローカル画像バックエンドとモデルが必要です。モデルのダウンロードや切り替えを暗黙に行うことはありません。

ガイド付きブートストラップ（Windows NVIDIA）

既存の環境では、bootstrap status を実行し、検証済みのポータブルルート、チェックポイント、ループバックエンドポイントのみを再利用してください。環境がまったくない状態からセットアップする場合は、bootstrap plan で、正確なポータブルアーカイブ、チェックポイント、バイト数の上限、ライセンス URL、SHA-256 ハッシュ、ディスク／VRAM 要件、および制限付きロールバックが表示されます。bootstrap apply の実行には、表示された明示的な確認が必要です。ダウンロードは再開可能で、通知なしに実行されることはありません。固定された対象範囲は、Windows 10/11 x64、NVIDIA RTX 20 シリーズ以降、VRAM 10 GiB、空きディスク容量 30 GiB です。Docker は不要です。このモデルを含まないブートストラップ契約は、画像生成や本番環境への対応を証明するものではありません。

setup は --apply を指定しない場合、読み取り専用です。適用処理では、クライアントの公式 mcp add コマンドに処理を委任します。Local GPU Imagegen はクライアントの設定ファイルを直接編集せず、モデルもダウンロードしません。

信頼性の証明： 保持された通常ルートの結果は、インストール済みの Codex セッションを 1 つ使用して得られました。検出時に重みは読み込まれていません。信頼性とルートの識別情報は明示され、成功したラウンドには上限が設定されていました。レビューには元の解像度の PNG が使用され、最終化はレビュー済みのバイト列に紐付けられ、実行状態は復元可能な状態で維持されています。この証拠が証明するのはこの 1 つの結果であり、9+3 の受け入れ条件全体、実測性能、本番環境への対応を証明するものではありません。

v0.9 のローカル受け入れ： ユーザーが承認した ComfyUI アーカイブと SDXL チェックポイントから構築した、新規の Windows/NVIDIA インストール環境で、管理対象の準備完了状態に達し、MCP ツールを正確に 17 個提供し、レビュー済みの非人間環境画像 1 枚を、ソースと最終結果のハッシュがバイト単位で一致した状態で最終化しました。成果物は、別途サニタイズしてエクスポートされるまでローカルに保持され、パッケージには同梱されません。別々に実施したキャラクター生成の試行 2 回は、手、目、または尾の厳格なレビューに合格しませんでした。そのため、人間が目立つ画像の解剖学的品質は確認されていません。

オプションの ComfyUI マネージド起動

Windows のセットアップでは、既存のポータブルルートを 1 つ登録してマネージド起動できます。

uvx local-gpu-imagegen setup codex --apply `
  --auto-start-comfyui `
  --comfyui-root "<ComfyUI_windows_portable>"

オプトインコマンドは、固定されたポータブル構成を検証し、python_embeded\python.exe -s ComfyUI\main.py を 127.0.0.1:8188 で登録します。ComfyUI のインストールやモデルのダウンロードは行いません。すでに起動しているエンドポイントは再利用しますが、所有したり停止したりすることはありません。MCP プロセスが起動した子プロセスは、キューが空の場合に限り MCP の終了時に停止します。キューが空でない場合は、そのまま維持され、報告されます。どちらのモードも、既存のバックエンドとモデルを使用し、モデルのダウンロードや切り替えを暗黙に行いません。ワークフローの実行は、サポート対象の組み込みトポロジーに限られます。マネージド起動によって、選択したポータブルインストールにすでに存在するカスタムノードが削除または管理されることはありません。

このアニメーションは、決定論的なプロトコルのシミュレーションデモであり、モデル出力や画像品質を示すものではありません。プロトコルおよびテストのエビデンスを補足するものです。モデル不要のテストで検証するのはプロトコルとバックエンドの契約であり、画像品質、より広範な名前付きクライアントでの生成、パフォーマンス、または 9+3 の完全な受け入れではありません。

Claude Code では、uvx local-gpu-imagegen setup claude-code --apply を実行します。エントリを削除するには、codex mcp remove local-gpu-imagegen または claude mcp remove --scope user local-gpu-imagegen を実行します。uvx local-gpu-imagegen doctor を使用すると、ローカルバックエンドの準備状況を確認できます。セットアップの契約と同等の stdio 起動は検証済みです。Codex では、インストール済みクライアントを使った生成を 1 件実施していますが、Claude Code での生成は未完了です。クライアントの互換性をご覧ください。

DeepSeek Harness（DSH）はセットアップコマンドなしで、同じ標準の stdio MCP プロトコル経由で接続します。dsh plugin --profile <name> add でサーバーを登録するか、MCP 対応の任意のクライアントから scripts/mcp_server.py を指定してください。実際の DSH による実行では、稼働中の ComfyUI チェックポイントを使用し、discover_models (api_only) → recommend_models → start_run → get_run → generate_round の全シーケンスが完了し、round-01.png アーティファクトが生成されました。initialize／tools/list／ping、verify_mcp.py、verify_client_configs.py はすべて合格しています。

PyPI に公開する前に、検証済みの wheel またはソースチェックアウトをインストールし、同等の local-gpu-imagegen verify コマンドと local-gpu-imagegen setup ... コマンドを使用してください。

このプロジェクトを選ぶ理由

• エージェントから対応済みのワークフローを実行： ComfyUI の API グラフを一からスクリプトとして作り直すのではなく、確認して登録します。
• バックエンドを再利用するか、明示的に管理： ComfyUI は既存ワークフローの主要な実行経路です。オプトイン方式の Windows ポータブルスーパーバイザーを使うと、既存のプロセスを引き継ぐことなく、手動での起動が不要になります。AUTOMATIC1111／Forge と Diffusers は引き続き互換性のある実行経路です。
• 実行を再現可能に： ワークフロー、モデルの識別情報、プロンプト、設定、シード、予算、出力ハッシュを永続的なマニフェストに固定します。
• インストール済みの CLI を使用： ソースをチェックアウトしなくても、準備状況を確認し、セットアップを公式の Codex または Claude Code コマンドに委任できます。
• モデルの選択権を明確に維持： 検出によって重みが読み込まれることはなく、生成時にモデルが暗黙にダウンロードされたり切り替わったりすることもありません。
• 構造化された証拠を保持： ルート、予算、試行、画像ハッシュ、レビュー、復旧操作は、機械可読かつ永続的な形式で保存されます。
• 承認はユーザーに委ねる： 元の解像度でのレビューと、後からバイト列にひも付けて確定する手順により、生成画像と承認済みの最終画像を区別します。
• エージェントによるガイド付きワークフロー： 同梱の Agent Skill により、自然言語の概要から、カタログで許可された確認済みの実行へと進められます。
• 3 つの提供プロファイル： 単体のイラスト、プレゼンテーション用ビジュアル、UI ビジュアルアセットで、決定的な実行とレビューの共通契約を使用します。
• 監査可能なホットリビジョン： 不変の子実行に保持／変更の契約を記録し、プロンプトの調整、img2img、または明示的に確認されたインペインティングを使用します。
• 依存関係を抑えた MCP レイヤー： プロトコルの確認とテストには Python 標準ライブラリを使用し、GPU は不要です。
• 対象を絞った範囲： 画像生成を、計画、メモリ、その他の無関係なエージェント機能から切り離しています。

実験的な構図制御

標準の実行経路では、通常の sdxl-txt2img を使用します。sdxl-regional-txt2img と sdxl-two-stage-copy-subject は引き続き実験的な機能であり、標準の実行経路には含まれず、通常のルートからのフォールバックも提供しません。保持された否定的な証拠から、視覚品質が向上したとは結論付けられません。

画像品質の境界

モデルとワークフローの品質は、引き続きユーザーが用意します。Local GPU Imagegen は明示的な実行、レビュー、復旧、証拠を追加しますが、拡散アルゴリズムを変更したり、プロンプトのワークフローによって画像が改善されると保証したりするものではありません。レビューでは、要求された製品の媒体、主題、実用目的、またはアセット枠を変更することを、代替画像のほうがより洗練されて見える場合でも、意味上のすり替えであり制約違反と見なすようになりました。

画像品質の制御と、凍結されたワークフローの非回帰ゲートを参照してください。保持されたゲートの最終結果は FAIL_WORKFLOW_REGRESSION です。画像品質の優位性を公に主張する根拠はありません。

ソースのチェックアウトとバックエンドのセットアップ

1. MCP サーバーを確認する

この確認には Python 3.11 または 3.12 で十分です。GPU、モデル、AI クライアントは必要ありません。

python .\scripts\verify_mcp.py

想定される結果：

{
  "ok": true,
  "transport": "stdio",
  "python": "<current-python>",
  "server": {"name": "local-gpu-imagegen", "version": "0.9.1"},
  "protocolVersion": "2024-11-05",
  "tools": [
    "local_gpu_branch_run",
    "local_gpu_cleanup_run",
    "local_gpu_confirm_mask",
    "local_gpu_discover_models",
    "local_gpu_finalize_run",
    "local_gpu_generate_image",
    "local_gpu_generate_round",
    "local_gpu_get_run",
    "local_gpu_imagegen_check",
    "local_gpu_list_profiles",
    "local_gpu_prepare_mask",
    "local_gpu_recommend_models",
    "local_gpu_record_review",
    "local_gpu_register_workflow",
    "local_gpu_set_model_trust",
    "local_gpu_start_run",
    "local_gpu_inspect_workflow"
  ]
}

2. バックエンドを選択する

バックエンド	最適なケース	セットアップ	ネットワーク動作
WebUI	AUTOMATIC1111 または Forge がすでにインストールされている	API アクセスを有効にして起動します	プロンプト／画像は設定済みの WebUI URL に送信されます
ComfyUI	すでに ComfyUI を実行しており、確認済みのグラフ実行を利用したい	自分で起動するか、既存の Windows ポータブルインストールが 1 つある場合は setup --auto-start-comfyui --comfyui-root <root> を選択します	プロンプト／画像はループバックまたは個別に確認されたエンドポイントにのみ送信されます
Diffusers	自己完結型の Python パイプラインを利用したい	scripts/install.ps1 でプロジェクトの .venv を作成します	明示的に許可しない限り、モデル／LoRA のダウンロードはブロックされます

現在の準備状況を確認します：

python .\scripts\check_gpu.py

このコマンドは JSON を返します。ready: false は有効な診断状態であり、プロトコルの失敗ではありません。

管理対象の起動は明示的に指定する必要があり、Windows のポータブル環境でのみ利用できます。Python の -s 分離を強制してユーザーサイトの Torch パッケージがポータブルランタイムに混入するのを防ぎ、 MCP の初期化が遅れないようバックグラウンドで起動します。また、最初の管理対象の準備状況チェックでは、設定済みの起動タイムアウトまで待機できます。 doctor 自体は読み取り専用で、バックエンドを起動することはありません。

特定の仮想環境で MCP サーバーを検証し、MCP 経由で準備状況を確認するには：

python .\scripts\verify_mcp.py `
  --python .\.venv\Scripts\python.exe `
  --check-readiness

3. MCP クライアントを接続する

同梱の .mcp.json では相対パスのコマンドと cwd を使用しています。グローバル設定を使うクライアントでは、<project-root> をこのクローンの絶対パスに置き換えます：

{
  "mcpServers": {
    "local-gpu-imagegen": {
      "command": "python",
      "args": ["<project-root>\\scripts\\mcp_server.py"]
    }
  }
}

クライアントを再起動し、最初の画像生成の前に local_gpu_imagegen_check を呼び出します。

4. ビジュアルアセットを依頼する

同梱のエージェントスキルは、一般的な依頼に対応します。たとえば、次のように依頼できます。

生成テキストを含まない、16:9 の独立したアニメキャラクターのイラストを作成してください。成功する生成は最大 2 回までとし、ダウンロードは無効のままにして、シードを変更する前に確認してください。

このスキルは、チェックポイントのファイル名から推測したり、バックエンドを無断で選択したりしません。現在のローカルインベントリを調査し、ユーザー側で設定した信頼設定を適用して、具体的なルートを 1 つ提案します。モデルをダウンロードすることなく、確認を待ちます。

エージェントスキルのワークフロー

1. インベントリが不明な場合は、api_only モードで local_gpu_discover_models を呼び出します。より広範なスキャンでは、ファイルシステムにアクセスする前に、スキャン計画を表示して明確な確認を得る必要があります。
2. local_gpu_set_model_trust は、正確な識別情報を1つ表示し、その信頼を確認する明確な応答を得た後にのみ使用します。プライベート利用と公開エビデンスは、別々のスコープです。
3. 意図する認可スコープに対して local_gpu_list_profiles を呼び出します。既知の簡潔な値は再利用し、影響の大きい境界条件のうち不足しているものだけを尋ねます。
4. local_gpu_recommend_models を呼び出します。ハード要件を弱めることなく、正確なルートを1つ、代替案を最大2つ返します。
5. 解決された正確な model_choice、バックエンド、識別情報の強度／ハッシュまたはバインド警告、ワークフロー、コンパイラー、寸法、予算を表示します。その表示後、新たに明示的な確認を得るまで待ちます。
6. 固定されたルートを開始し、永続化された固定実行を読み取り、完全な生成計画を作成して、確認済みの成功ラウンド予算を超えない範囲でのみ処理します。プロンプトとパラメーターを追加する前に、ルート、識別情報、ワークフロー、コンパイラー、ポリシー、予算の各フィールドをすべてその実行からコピーします。保持された画像は1ラウンドとして数え、バックエンドの失敗は数えません。
7. ビジョン対応ホストでは、元画像をフル解像度で表示して確認します。必要な解剖学的構造、足／接地、手／物体、テキスト／ウォーターマークの確認を、完全な評価基準とともに記録します。プレビューだけでは不十分です。確認に失敗した場合、または確信が持てない場合は、refine または explore が必要です。refine ではシードを維持し、explore ではシードを変更します。
8. 対象となるレビューで品質ステータス candidate が返されたら、制限事項、画像の SHA-256、正確な finalize:<run_id>:<round_number>:<image_sha256> 値を表示して停止します。後続のユーザーメッセージに表示した値が含まれている場合にのみ、最終化を承認できます。エージェントは自分自身の候補を承認できません。
9. テキストのみのホストでは、成功したラウンドを正確に1つ保持し、review unavailable と記録して、未レビューのパスを報告したら停止します。スコアを捏造したり、レビュー／最終化ツールを呼び出したりしないでください。

レビュー済みまたは最終化済みの候補ができた後、ユーザーは維持する点と変更する点を説明できます。Skill は監査可能な維持／変更契約を提示し、別途1～3ラウンドの修正予算を尋ね、確認後にのみ不変の子実行を作成します。破壊性が最も低いモードを選びます。順に、同一シードでのプロンプト調整、低強度の img2img、明示的なマスクオーバーレイ確認を伴うインペインティングです。マスクなしでの維持はベストエフォートです。

オプションの copy-subject-v1 ルートでは、エージェントは正規化された2つの領域を小数とパーセンテージの両方で表示し、両方の領域のプロンプトと強度、正確な sdxl-regional-txt2img ルート、確認前の成功ラウンド予算を提示します。この実行ではジオメトリが固定されます。調整では領域のプロンプトや強度を変更できますが、領域を移動するには、新たに確認されたルートまたは子実行が必要です。領域機能が利用できない場合、またはドリフトしている場合でも、プロンプトのみの sdxl-txt2img にはフォールバックしません。

オプションの sdxl-two-stage-copy-subject ルートでは、local_gpu_set_model_trust は正確な two_stage_layout を受け付けます。呼び出し側が control_sha256 を指定することはありません。サーバーはそのレイアウトを正規化し、同梱ワークフローを検査して、コントロールのダイジェストを導出します。また、表示される信頼確認にワークフロー、バンドル、コントロールの各ダイジェストを含めます。承認と後続のルーティングでは、同一の正規化レイアウト、ワークフロー、コンポーネントバンドル、エンドポイント、モデル識別情報が必要です。エージェントはピクセル単位のジオメトリとパーセンテージ、ベースシードと派生サブジェクトシード、サブジェクトのコンディショニング、2段階の予算も表示します。1ラウンドには2ステージ分のユニットが必要で、役割に紐づくPNGを3つ保持します。ベース成果物、マスク成果物、最終成果物です。レビュー前に保護ピクセルと保存済みマスクのゲートが実行されます。部分的な結果が生じた場合はフォールバックせずに停止します。ベースと最終成果物の両方をステージごとにフル解像度でレビューし、候補になれるのは最終成果物のみです。最初の実GPUゲートは、正確に2段階の1ラウンドです。 従来の単一パスの copy-subject-v1 リージョナルルートは、保持された否定的エビデンスおよび実験的な互換性として引き続き残されています。モデル不要の制御コントラクトには引き続き価値がありますが、観測された出力からビジュアル品質の向上が立証されるわけではありません。保持されたフル解像度の受け入れ結果が得られるまで、いずれのルートも画像品質の肯定的なエビデンスとして提示されません。

適応型のシーケンスは、discovery -> 必要に応じた trust -> スコープを絞ったカタログ -> brief -> 正確なルートの推奨 -> 表示後の確認 -> 開始 -> 永続化された実行の読み取り -> 完全なプランの構築 -> 生成 -> フル解像度での検査 -> レビュー -> 改良／探索、または候補の表示 -> ユーザーの次のメッセージを待機 -> 完了です。設定する max_rounds は 1 から 3 の範囲とし、緊急性やサンクコストを理由に延長してはなりません。

ビジュアルプロファイルとスコープ

プロファイル	サポートされるサブタイプ	提供時の重点
standalone-illustration	character、environment、wallpaper	単体で完結するイラストの出力です。
presentation-visual	cover、section、content-background	セーフエリアとオーバーレイの制約に配慮した、ビジュアルのみのスライド素材です。
ui-visual-asset	hero、section-illustration、rectangular-background、decorative-texture	インターフェースに組み込めるラスター画像です。

完全な PPT デッキは対象外です。フロントエンドのコードとコンポーネントは対象外です。本番用アイコン、SVG、透過 PNG は対象外です。自動セグメンテーションは対象外です。シームレスなテクスチャの保証は対象外です。このプロジェクトが生成するのは検査可能なラスター素材であり、スライドレイアウトやインターフェースの実装ではありません。

独自のモデルを安全に使用する

ディスカバリーには api_only、selected_folders、common_locations、full_drive の4つのレベルがあります。ファイルシステムのディスカバリーは2段階で行います。index はチェックポイントのペイロードを開かずに、範囲を限定したメタデータを記録します。fingerprint は、明示的に選択されたインデックス済みの候補に限り、SHA-256 を計算します。.ckpt の内容は不透明なまま扱われ、スキャンではシンボリックリンク、ジャンクション、再解析ポイントをたどりません。

信頼情報は、リポジトリの外にある OS のユーザー状態ディレクトリに保存されます。保存先は LOCAL_GPU_IMAGEGEN_STATE_DIR で上書きできます。backend_binding ID を信頼できるのは、private 用途に限られます。ComfyUI のルートが分割されている場合、信頼ツールはまず、プライマリモデル、テキストエンコーダー、VAE、レビュー済みワークフローを1つの正規化された SHA-256 バンドルにまとめる、変更を加えない検査アクションを提示します。正確なバンドルダイジェストは、後続の信頼確認とルートトークンに含まれます。暗号学的に検証されたバンドルを public_evidence の候補とするには、すべての構成要素について正確な出典、ライセンス、出力の再配布に関するメタデータが必要です。また、エクスポート前に受け入れ権限者が同じバンドルを承認する必要があります。

安全なワークフローのオンボーディング

既存のComfyUI API形式ワークフローは、単一のチェックポイントまたはモデルを分割した構成のいずれかを使用する一般的な txt2img グラフであれば、呼び出し元がノード ID を指定しなくても検査および登録できます。制限付きの手順は次のとおりです。

API-only discovery (when current inventory is absent)
-> local_gpu_inspect_workflow
-> display hashes, inferred binding, components, limitations, confirmation
-> later exact user confirmation
-> local_gpu_register_workflow
-> separate local_gpu_set_model_trust with `registered_workflow_id`

検査では、明示的に指定されたローカル JSON ファイルを1つ読み込み、単独の API グラフ、または一意な prompt ラッパーを受け付け、source_sha256、workflow_sha256、トポロジー、推定されたバインディング、所有する出力、およびコンポーネント ID を報告します。登録可能な結果には register_workflow:<source_sha256>:<proposal_digest> が含まれます。診断結果には確認用の情報がありません。UI 形式への変換は行われません。登録しても、モデルへの信頼や公開権限が付与されることはありません。GPU を使用しない実クライアントのオンボーディング証拠は保持されています。生成の証拠は別途管理されます。

モデルの重みは同梱されていません。リポジトリのカタログには、すでにレビュー済みのローカル WebUI チェックポイントを示す監査可能な ID civitai/anything-v5@30163 が含まれています。ダウンロードは引き続き未承認です。その他のローカルモデルは、検出と明示的な信頼を経た場合に限り、プライベートカタログに登録できます。モデルの品質は引き続きユーザーのモデルに依存します。このプロジェクトが提供するのは、より安全なルーティング、永続的なレビュー、ホットリビジョンであり、優れたプロンプト翻訳機能を謳うものではありません。

ComfyUI には、レビュー済みのワークフローファイル sd15-txt2img-v1.json、sdxl-txt2img-v1.json、sdxl-regional-txt2img-v1.json、sdxl-two-stage-copy-subject-v1.json、z-image-turbo-txt2img-v1.json、anima-txt2img-v1.json が同梱されています。検出では CheckpointLoaderSimple、UNETLoader、CLIPLoader、VAELoader を区別します。プライベートなバックエンド限定ルートでは、プライマリーローダーのみをバインドする場合がありますが、分割ワークフローを公開証拠の対象とするには、現在の API ID と、凍結された各コンポーネントのファイルシステム上の SHA-256 ID が必要です。分割モデルのみのインストール環境には、チェックポイントの選択肢がない場合があります。シェル、Python／スクリプト／プロセス実行、ネットワーク／ダウンロード／Webhook／フェッチノード、コマンド、不明なカスタムノード、未バインドのパラメーター、およびリソース上限超過は拒否されます。

ワークフローファイルには、モデルの重みは含まれておらず、インストール、信頼、ライセンスの対象にもなりません。Z-Image と Anima では引き続き、正確なローカル検出、ユーザーの承認、および確認済みのルートが必要です。Anima はオプションのアニメ向けルートであり、上流の重みに関する制限に従うため、商用利用や公開証拠向けのデフォルトとして提示してはなりません。ComfyUI アダプター：契約テスト済み。ローカルでの Z-Image および Anima アダプターの実行：確認済み。公開受け入れ証拠：保持されていません。

ツールリファレンス

公開 MCP サーフェスには、互換性ツール2つと、検出／オンボーディング／実行／リビジョン用の高レベルツール15個の、合計17個のツールがあります。

local_gpu_imagegen_check

Python パッケージ、CUDA デバイス、WebUI への到達性、および総合的な準備状況を報告します。ツール呼び出し自体が成功しても、マシンが準備未完了の場合があります。

local_gpu_generate_image

次をサポートします。

• txt2img、img2img、およびインペインティング
• 固定シード
• WebUI のチェックポイントおよびサンプラーの選択
• Diffusers のスケジューラー選択
• LoRA の読み込み
• VAE タイリングおよびオプションの CPU オフロード
• 明示的な CPU フォールバック
• モデル／LoRA のダウンロード許可の明示

ツールスキーマは、バックエンドプロセスの開始前に、型、範囲、列挙値、不明なフィールド、画像モードの要件、および寸法を検証します。

これら2つの互換性ツールは、15個の高レベルツールと並行して引き続き利用できます。特に、低レベルの local_gpu_generate_image 互換性ツールには変更がありません。オプションのモデル値は直接渡される互換性用パススルーのままであり、カタログによって制限される Agent ワークフローではありません。WebUI／Diffusers のオプションと、明示的なモデルダウンロード制御にも変更はありません。

高レベルの実行ツール

ツール	責務
local_gpu_discover_models	モデルの重みを読み込まずに、範囲を限定した API／ファイルシステムのインベントリを計画または実行します。
local_gpu_inspect_workflow	通常の ComfyUI API txt2img ワークフローを 1 つ検査し、診断用または登録可能なハッシュとバインディングを返します。
local_gpu_register_workflow	後でダイジェストに紐づく確認を行った後、正確な提案を再確認し、変更不可能な登録済みワークフローのコピーを保存します。
local_gpu_set_model_trust	コンポーネントバンドルを変更せずに検査するか、確認後にユーザーのローカル状態で正確な ID を 1 つ承認／取り消します。
local_gpu_recommend_models	決定性のあるルートを 1 つと、説明付きの代替案を最大 2 つ返します。
local_gpu_list_profiles	登録済みのユースケースプロファイルと現在のバックエンド機能を一覧表示します。
local_gpu_start_run	確認済みの意図、プロファイル、制約、バックエンドの選択、ラウンド予算を永続化します。
local_gpu_get_run	永続化されたマニフェストと、その recoverable_next_actions を読み取ります。
local_gpu_branch_run	レビュー済みの親ラウンド 1 つから変更不可能な子実行を作成し、コントラクトを維持または変更します。
local_gpu_prepare_mask	ユーザー指定または矩形／多角形のマスクを準備し、範囲を限定した JPEG オーバーレイを返します。
local_gpu_confirm_mask	ユーザーの明示的な承認後、変更されていない準備済みマスクを確認します。
local_gpu_generate_round	ルートまたは固定モードの子ラウンドを 1 つ生成し、範囲を限定した JPEG プレビューを任意で返します。
local_gpu_record_review	評価スコア、必須の構造化された視覚チェック、重大な失敗、制約と保持の結果、批評、次のアクションを保存します。
local_gpu_finalize_run	画像に紐づくユーザー確認を検証し、指定された対象適格ラウンドを最終ローカル PNG として公開します。
local_gpu_cleanup_run	中間生成物または確認済みの実行ディレクトリ全体を削除します。

max_rounds は 1 から 3 の範囲で指定する必要があります。正常に保持された PNG ラウンドのみがこの予算を消費します。バックエンドの失敗は、ラウンドを消費しない試行として記録されます。レビューを新たに行うには、目立つ人物がいるかどうかにかかわらず full_resolution_inspected: true とし、手足の分離、足／接地、手／所持物、文字／透かしについて明示的な所見を記録する必要があります。人体構造のチェックを not_applicable にすることはできません。必須項目のいずれかが fail または uncertain の場合、次に要求できるのは refine または explore のみです。

適格なレビューでは、品質ステータスとして candidate が提示されます。承認を示すことはありません。また、実行、ラウンド、保持された画像の SHA-256 に紐づけられます。エージェントは元の画像、制限事項、ハッシュ、正確な finalize:<run_id>:<round_number>:<image_sha256> を表示してから、その後のユーザーメッセージを待ちます。local_gpu_finalize_run には、その正確な確認に加えて、指定する round_number と概要が必要です。実行ロックの下で候補を再検証した後、より高いスコアのラウンドに差し替えることなく、指定されたレビュー済みラウンドを公開します。公開された結果にのみ accepted が付与されます。

適格でないレビュー済み成果物は公開されません。確認済みの予算が残っている場合は refine または explore を行います。それ以外の場合は成果物を保持し、公開せずに新たなユーザー判断を求めます。既存の確定済みマニフェストと、下位レベルのストア互換パスには、引き続き needs_user_review が含まれる場合があります。ただし、構造化された視覚チェックのない未確定のレガシーレビューから、公開エンジンの候補を生成することはできません。

local_gpu_list_profiles は、スコープが適用された統合カタログと現在の機能を返します。local_gpu_start_run には、表示された正確な route_token、認可スコープ、モデル、バックエンド、寸法、ワークフロー、コンパイラーが必要です。ID の不一致がある場合、バックエンドを呼び出す前に失敗します。ルート実行と子実行が、ルートを暗黙に切り替えることはありません。

実行ファイル、再試行、復旧

デフォルトの永続化レイアウトは次のとおりです。

outputs/
  runs/
    <run_id>/
      manifest.json
      parent-source.png
      round-01.png
      round-01-preview.jpg
      final.png
      final-upscaled.png
      masks/
        mask-01.png
        mask-01-overlay.jpg

outputs/runs/<run_id>/manifest.json は、確認済みの入力、試行、ラウンド、レビュー、警告、最終メタデータ、状態リビジョンの信頼できる唯一の情報源です。最初のラウンドが成功すると、round-01.png が保持され、round-01-preview.jpg が作成されることがあります。後続のラウンドでは、同じハイフン区切りのプレビューパターンが使われます。round-01.preview.jpg を参照する保存済みの旧形式のマニフェストも読み取り可能で、書き換えられることはありません。最終化すると final.png が公開されます。プレビューファイルは必須ではありません。MCP の応答にはサイズ制限付きの JPEG プレビューを含めることができ、full_image_path はフル解像度のローカル PNG を示します。プレビューの警告やエンコードの失敗によって、検証済みの PNG が破棄されることはありません。

不変の子実行では、選択した親の PNG を parent-source.png にコピーし、親子関係とハッシュを記録します。親のマニフェストに書き込むことはありません。Img2img とインペイントでは、この保持されたソースを使用します。インペイントではさらに、確認済みの masks/mask-01.png が必要です。masks/mask-01-overlay.jpg は、先に承認用として返されます。ソースまたはマスクのバイト列が変わると、確認は無効になります。

各生成リクエストには idempotency_key が必要です。同じキーと同じリクエストを再度送ると、完了済みのラウンドが返されるか、試行が処理中であることが報告されます。異なる入力に同じキーを再利用すると、拒否されます。中断後は local_gpu_get_run を呼び出し、recoverable_next_actions に従ってください。検証済みのフルサイズ PNG がすでに保持されている場合、エンジンは古い試行を再利用し、プレビューの作成を再開できます。

クリーンアップは明示的に行います。intermediates と all のどちらの場合も、確認文字列は run_id と完全に一致する必要があります。intermediates スコープではマニフェストと公開済みの最終ファイルが保持され、all では確認済みの実行ディレクトリが削除されます。

オプションの Anime Real-ESRGAN 後処理

アニメ専用の 4x 後処理は、明示的にローカルで実行します。ツールのルートは LOCAL_GPU_IMAGEGEN_REALESRGAN_DIR でのみ設定してください。サーバーが受け付けるのは、そのルート以下にある realesrgan-ncnn-vulkan.exe と、サポート対象のモデルペア realesrgan-x4plus-anime または realesr-animevideov3-x4 のいずれかだけです。任意の実行ファイルパスやモデル名は受け付けず、バイナリやモデルのダウンロードも行いません。

後処理は自動では実行されません。upscale_policy: auto であっても記録されるのは許可のみです。呼び出し側は local_gpu_finalize_run に正確な postprocess オブジェクトを渡す必要があり、確認済みのスタイルは anime でなければなりません。リクエストが成功すると、元の final.png が保持され、final-upscaled.png が返されます。また、モデル、スケール、ソースと出力のパス、ハッシュ、寸法、MIME タイプが最終後処理メタデータに記録されます。後処理を利用できない場合や失敗した場合は、構造化された警告とともに元の最終画像にフォールバックします。実際のバイナリ、GPU、品質、パフォーマンスに関する動作は未検証です。

スタンドアロンでの使用

すでに起動している WebUI を通じて生成します。

python .\scripts\generate_image.py `
  --backend webui `
  --prompt "a small robot reading a circuit diagram, clean concept art" `
  --width 1024 --height 1024 --seed 42

プロジェクトローカルの Diffusers 環境を作成します。

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Diffusers はデフォルトでは、不足しているモデルファイルを取得しません。モデルのライセンスと必要なストレージ容量を確認した後、特定の実行に対してオプトインしてください。

.\.venv\Scripts\python.exe .\scripts\generate_image.py `
  --backend diffusers `
  --model stabilityai/sd-turbo `
  --allow-download `
  --prompt "a compact lunar research station, technical concept art" `
  --seed 42

互換ツールのファイルは、デフォルトで outputs/ に保存されます。LOCAL_GPU_IMAGEGEN_OUTPUT_DIR または --output-dir で上書きできます。高レベルの実行では、その出力ルートの下に runs/<run_id>/ レイアウトが使用されます。

アーキテクチャ

flowchart LR
    A["MCP client"] -->|"stdio JSON-RPC"| B["Thin MCP server"]
    B --> H["Discovery + trust + capability router"]
    H --> C["Frozen route + durable run engine"]
    C --> E["AUTOMATIC1111 / Forge adapter"]
    C --> I["Reviewed ComfyUI workflow adapter"]
    C --> F["Diffusers compatibility runner"]
    E --> G["Full local PNG + bounded preview"]
    I --> G
    F --> G
    G --> C
    C --> B
    B --> A

トランスポート層は、JSON-RPC、スキーマ、検証、ディスパッチ、タイムアウト、構造化された結果を担当します。実行エンジンはオーケストレーションを担当し、永続状態の管理を RunStore に委譲します。バックエンドの読み込みと画像生成は scripts/generate_image.py にあります。

制御フローとエラーモデルの詳細については、アーキテクチャを参照してください。

安全性とプライバシー

• MCP プロセスは、アプリケーション固有のクラウド画像 API を使用しません。
• 確認済みの LAN WebUI／ComfyUI エンドポイントには、プロンプトと元画像が送信されます。ループバックはローカルです。各 LAN エンドポイントへの送信には個別の明示的な確認が必要で、パブリックインターネット上のエンドポイントは拒否されます。
• 検出時にリンクをたどったり、チェックポイントのペイロードを読み込んだりすることはありません。より広範なファイルシステムのスキャンには、有効期限が切れておらず変更もされていないプランと、明示的な確認が必要です。
• 信頼状態は Git の外部に保持されます。プライベートな信頼によってパブリックな証拠が承認されることはなく、認証情報は再帰的に拒否されます。
• ユーザーが scripts/install.ps1 を実行すると、Python パッケージがダウンロードされます。
• Diffusers のモデルと LoRA のダウンロードには、--allow-download または MCP の allow_download: true が必要です。
• モデルのセーフティチェッカーの無効化は明示的に指定する必要があり、デフォルトでは無効です。
• 入力画像と生成ファイルは通常のローカルファイルとして保持されます。機密性に応じた OS 権限で、それらのディレクトリを保護してください。

WebUI API を localhost の外部に公開する前に、Security を確認してください。

テスト

テストスイートは GPU を必要とせず、モデルもダウンロードしません。

python -m unittest discover -s tests -v
python .\scripts\verify_mcp.py

カバレッジには、プロトコルの初期化／一覧表示／ping、17 個のツールに関する厳密な契約、範囲を限定した検出／オンボーディング／信頼／ルーティング、WebUI と ComfyUI のアダプター契約、永続的なルート／子の遷移、固定された 2 領域 SDXL のルート／条件付け／枯渇の挙動、マスクの確認、冪等性、古くなった試行の復旧、アトミックな公開、範囲を限定したプレビュー処理、モックを使用したモデル不要のアニメーションループ、固定された 9 件のブリーフと 3 件の子の改訂、フェイクランナーによる後処理、ダウンロードポリシーが含まれます。

プロジェクトの状況

検証済み：

• stdio MCP の初期化、ツール一覧表示、ping、ツールコントラクト
• 構造化されたツールの成功／エラー結果
• モック／モデル非依存のテストでカバーされる、15 個の高レベルな探索／オンボーディング／実行／改訂ツールと 2 個の互換性ツール
• 適応型 Agent Skill ブリーフィング、モデルの正確な確認、成功ラウンドの予算管理、テキストのみの場合に正直に停止するポリシー
• ローカルモデルの正確な識別、ユーザー単位の信頼、決定論的なルート、ドリフト拒否のコントラクト
• フェイクランナーのテストで明示的に確認された、アニメ専用 Real-ESRGAN アダプターの動作
• コントラクトテスト済みの WebUI および ComfyUI アダプターの成功／失敗パス
• 永続的なマニフェストの遷移、冪等性、復旧、レビュー、確定、クリーンアップのコントラクト
• 3 つの Profile コントラクトに加え、不変の保持／変更子ランと確認済みのジオメトリ／ユーザーマスク
• 固定コピー／被写体ジオメトリ、領域別コンディショニング、ルートのドリフト拒否、モデル非依存の 2 ラウンド領域別垂直スライス
• サーバー導出による 2 段階の制御 ID、制御に紐付いた信頼確認、矛盾するバインディングの拒否、正確なモデル非依存ルートの復旧
• 9 つの固定ブリーフと 3 つの子改訂を対象とする、フェイクバックエンドのコントラクトマトリックス
• デフォルトでローカルのみを対象とする Diffusers ハブポリシー
• インストール可能な serve、doctor、verify、config、読み取り専用がデフォルトの setup CLI コントラクト。分離された wheel のスモークテストを含みます
• 公式 Codex および Claude Code のセットアップコントラクト解析と、同等の正確な 17 ツールによる stdio 起動。Claude Desktop は従来のレンダリング専用テンプレートのままです

1.0 を表明する前に必要な項目：

• 実際のホスト／ビジョンによる、保持された完全な 9+3 受け入れマトリックス
• 実際の Real-ESRGAN バイナリ／GPU 実行の証拠
• 保持された Codex の結果に加え、Claude Code を含む、生成された名前付きクライアントのセッション証拠の追加
• 実測のパフォーマンスまたは VRAM データ
• 本番環境への対応を示すあらゆる表明

モック／モデル非依存のマトリックスは、決定論的なプロトコルの証拠であり、保持された実際の Codex／ビジョン／GPU の結果ではありません。フェイクバックエンドを使用して 9 つの固定ブリーフと 3 つの子改訂を実行しますが、視覚的な品質を証明するものではありません。プロジェクトアダプターを介したローカルの Z-Image および Anima の呼び出しは確認済みですが、これはローカル開発での検証であり、一般公開向けの受け入れ証拠ではありません。過去の生成画像の記録は技術監査資料であり、v0.9 の宣伝用ビジュアルではありません。テストスイートは本番用モデル、GPU バックエンド、Real-ESRGAN バイナリを読み込みません。本番環境、パフォーマンス、VRAM、画質の優位性、Star の保証、またはより広範な名前付きクライアントでの生成について、いかなる表明も行いません。

リポジトリには、承認済みの v0.9 宣伝用画像も、実際の 9+3 画像受け入れマトリックスの完全版もありません。一般化された画質、パフォーマンス、または VRAM に関する表明は行いません。対象環境を確認するには、上記の準備状況確認コマンドを使用してください。

ドキュメント

• アーキテクチャとエラーモデル
• トラブルシューティング
• クライアントの互換性
• プロトコルデモの範囲
• リリースチェックリスト
• Stable Diffusion 統合に関する注意事項
• コントリビューション
• 変更履歴

ライセンス

MIT License のもとで公開されています。モデルの重み、バックエンドアプリケーション、生成された出力には、それぞれ独自のライセンスと利用条件が適用されます。このリポジトリによって、それらが再ライセンスされることはありません。