comfyui-core

ComfyUI のコア知識

ワークフロー JSON 形式（API 形式）

ComfyUI のワークフローは、文字列のノード ID をノード定義に対応付ける JSON オブジェクトです。

{
  "1": {
    "class_type": "CheckpointLoaderSimple",
    "inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" },
    "_meta": { "title": "Load Checkpoint" }
  },
  "2": {
    "class_type": "CLIPTextEncode",
    "inputs": { "text": "a cat", "clip": ["1", 1] },
    "_meta": { "title": "Positive Prompt" }
  }
}

主なルール

• ノード ID は整数の文字列です（"1"、"2" など）。
• class_type はノードの Python クラス名そのものです。
• inputs には、ウィジェットの値（スカラー）と接続（配列）の両方が含まれます。
• 接続には ["sourceNodeId", outputIndex] という形式を使います。これは 2 要素の配列で、次の内容を表します。
  • 1 番目の要素は、接続元ノードの文字列形式のノード ID です。
  • 2 番目の要素は、接続元ノードの output リスト内のインデックス（0 起点）です。
• _meta は省略可能で、表示タイトルにのみ使われます。

接続の例

"model": ["1", 0]       // Connect to node 1's first output (MODEL)
"clip": ["1", 1]        // Connect to node 1's second output (CLIP)
"vae": ["1", 2]         // Connect to node 1's third output (VAE)
"positive": ["2", 0]    // Connect to node 2's first output (CONDITIONING)
"samples": ["5", 0]     // Connect to node 5's first output (LATENT)
"images": ["6", 0]      // Connect to node 6's first output (IMAGE)

重要：API 形式と Web UI 形式の違い

• API 形式（実行／分析用）は { "1": { class_type, inputs }, "2": { ... } } です。簡潔な形式で、enqueue_workflow、create_workflow (action:"validate")、create_workflow (action:"modify") などで使われます。
• Web UI 形式（保存およびフロントエンドでの編集用）は { "nodes": [...], "links": [...] } です。レイアウトの位置やサイズ、グループ、ビジュアルメタデータが含まれているため、ComfyUI のキャンバスで開いて編集できます。
• 実行ツールは API 形式を受け取り、API 形式を返します。
• 保存したワークフローを読みやすく、ComfyUI フロントエンドで編集可能な状態に保つには、Web UI 形式で保存してください。API 形式のままでは、キャンバス上で編集できません。ライブラリには「存在」しますが、キャンバスでは何も表示されず、ユーザーがワークフローを再び開けない状態になります。その結果、エージェントは古いワークフローを再度開く代わりに、また新しいワークフローを作成してしまいがちです。このため、save_workflow は API 形式の入力を自動的に生成レイアウト付きの Web UI 形式に変換します。生成されたレイアウトでは元のノードの位置やグループが失われるため、実際の Web UI 形式（get_workflow(action="get", filename=…, format="ui") から取得）を渡すことを推奨します。
• get_workflow は分析／実行用に既定で format="api" を使います。ワークフローを読み込んで再保存する場合や、キャンバス上で編集する場合は format="ui" を使ってください。
• ミュート／バイパスされたノードは _meta.mode: "muted" として保持されます。これらのノードは非アクティブですが、ワークフローを理解できるよう表示されます。
• Get／Set 仮想ワイヤーノードは、データフローを追跡できるよう _meta.title と Constant キーを保持します。

ワークフローライブラリのツール

• get_workflow(action="analyze", filename=…) は、保存済みワークフローを理解するために最初に呼び出す関数です。セクション、ノード ID、主要な設定、仮想ワイヤー、接続グラフを含む、構造化されたテキストの概要を返します。生の JSON は含まず、ワークフローを推論するために必要な情報だけを提供します。summary（既定）、overview（mermaid）、detail（section mermaid）、list、flat の各ビューに対応しています。
• get_workflow (action:"list") は、ComfyUI のユーザーライブラリに保存されているすべてのワークフローを一覧表示します。
• get_workflow(action="get", filename=…) は、生のワークフロー JSON を読み込みます。enqueue_workflow、create_workflow (action:"modify")、save_workflow に渡す実際の JSON が必要な場合にのみ使用してください。内容を理解するには、代わりに action="analyze" を使ってください。JSON を save_workflow に渡す場合は、フロントエンドで編集できる状態を保つため、format="ui" を指定してください。
• save_workflow(action="save", filename=…, workflow=…) は、ワークフローをユーザーライブラリに保存します。ComfyUI のキャンバスで元のレイアウトを保つため、Web UI 形式（{ nodes, links }）を渡してください。API 形式のグラフも受け付け、自動的に生成レイアウト付きの Web UI 形式に変換されます。これは、API 形式のままではキャンバス上で編集できず、フロントエンドで開けないためです。既存のワークフローを再保存する場合は、get_workflow(action="get", filename=…, format="ui") で読み込み、それを編集してください。そうすることで、位置とグループが保持されます。

データ型

ComfyUI ノードは接続を通じて型付きデータを渡します。

型	説明	一般的なソース
MODEL	拡散モデルの重み	CheckpointLoaderSimple（出力 0）
CLIP	テキストエンコーダー	CheckpointLoaderSimple（出力 1）
VAE	変分オートエンコーダー	CheckpointLoaderSimple（出力 2）
CONDITIONING	エンコードされたテキストプロンプト	CLIPTextEncode（出力 0）
LATENT	潜在空間テンソル	EmptyLatentImage、KSampler、VAEEncode
IMAGE	ピクセル画像テンソル（BHWC）	VAEDecode、LoadImage、SaveImage
MASK	単一チャンネルのマスク	LoadImage（出力 1）
UPSCALE_MODEL	アップスケーリングモデル	UpscaleModelLoader

標準的なパイプラインパターン

テキストから画像へ（txt2img）

CheckpointLoaderSimple → MODEL, CLIP, VAE
  ├─ CLIP → CLIPTextEncode (positive) → CONDITIONING
  ├─ CLIP → CLIPTextEncode (negative) → CONDITIONING
  │
EmptyLatentImage → LATENT
  │
KSampler (model, positive, negative, latent_image) → LATENT
  │
VAEDecode (samples, vae) → IMAGE
  │
SaveImage (images)

通常のノード ID：1=Checkpoint、2=Positive、3=Negative、4=EmptyLatent、5=KSampler、6=VAEDecode、7=SaveImage

画像から画像へ（img2img）

txt2img と同じですが、EmptyLatentImage を次のように置き換えます。

LoadImage → IMAGE
VAEEncode (pixels, vae) → LATENT → KSampler.latent_image

KSampler.denoise を 0.5～0.8 に設定します（値が低いほど入力画像に近くなります）。

アップスケール

LoadImage → IMAGE
UpscaleModelLoader → UPSCALE_MODEL
ImageUpscaleWithModel (upscale_model, image) → IMAGE
SaveImage (images)

インペイント

LoadImage (image) → IMAGE → VAEEncode → LATENT
LoadImage (mask) → MASK
SetLatentNoiseMask (samples, mask) → LATENT → KSampler.latent_image

MCP ツールの使用ガイド

すばやく生成する

1. テンプレート "txt2img" とパラメーターを指定して create_workflow を実行します
2. 返された JSON を指定して enqueue_workflow(action="enqueue") を実行します。すぐに prompt_id が返されます
3. prompt_id を指定して queue（action:"status"）をポーリングし、done が true になるまで待ちます
4. get_image (action:"list_outputs")（limit 1）を使って生成された画像を見つけ、次に Read で表示します

確認と変更

• create_workflow (action:"node_info") は、利用可能なノードとそのスキーマを照会します
• create_workflow (action:"modify") は既存のワークフローにパッチを適用します（set_input、add_node、remove_node、connect、insert_between）
• visualize_workflow はワークフローを mermaid 図として表示します

リバースエンジニアリング

• visualize_workflow はワークフロー JSON を mermaid 図に変換します
• visualize_workflow (action:"mermaid") は mermaid 図をワークフロー JSON に変換します（スキーマ解決には /object_info を使用します）

モデル管理

• list_local_models はインストール済みのモデルを表示します
• download_model action:"search" は HuggingFace 上のモデルを検索します
• download_model は ComfyUI の models ディレクトリにダウンロードします

モデルを手動でダウンロードするようユーザーに依頼しないでください。必要なモデルが見つからない場合は、自分で検索してダウンロードしてください。

1. 最初に list_local_models を確認します
2. 見つからない場合は、download_model action:"search" で HuggingFace を検索するか、REST API で CivitAI を検索します
3. download_model を使って、正しいサブフォルダーに直接インストールします

CivitAI API（CIVITAI_API_TOKEN 環境変数が利用可能な場合）：

• 検索：GET https://civitai.com/api/v1/models?query={query}&types=Checkpoint&sort=Most+Downloaded&limit=5
• 詳細：GET https://civitai.com/api/v1/models/{modelId}
• ダウンロード：GET https://civitai.com/api/download/models/{modelVersionId}?token={token}

ファインチューニング済みモデル、コミュニティ評価の高いチェックポイント、特化型 LoRA には CivitAI が適しています。 公式モデル／ベースモデル（SDXL、Flux、SD 1.5）には HuggingFace が適しています。

カスタムノード

• search_custom_nodes は ComfyUI Registry を検索（action: "search"）するか、1 つのパックの詳細を取得します（action: "details"）
• list_packs（action: "generate_skill"）はノードパック用のスキルファイルを自動生成します

ワークフローの実行

enqueue_workflow は ComfyUI のキューに送信し、すぐに prompt_id とキュー内の位置を返します。処理完了まで待機しません。

バックグラウンドでの進行状況の監視

1 つ以上のワークフローをキューに登録した後、バックグラウンドの Bash タスクを使って進行状況を通知せずに監視します。

# Single job
Bash(run_in_background: true):
node "${CLAUDE_PLUGIN_ROOT}/scripts/monitor-progress.mjs" <prompt_id>

# Multiple jobs (batch)
Bash(run_in_background: true):
node "${CLAUDE_PLUGIN_ROOT}/scripts/monitor-progress.mjs" <id1> <id2> <id3>

このスクリプトは ComfyUI の WebSocket に接続し、次の情報を報告します。

• ステップごとの進行状況（例：KSampler step 12/20 (60%)）
• 出力ファイル名と所要時間を含む成功情報
• ノードの詳細とメッセージを含むエラー情報

標準的な生成手順：

1. create_workflow、またはワークフロー JSON を作成して enqueue_workflow(action="enqueue") を実行します（バッチ処理の場合は繰り返します）
2. すべての prompt_ids を指定して、バックグラウンドモニターを起動します
3. 会話を続けます。ジョブが完了すると結果が表示されます
4. get_image (action:"list_outputs") または Read を使って、生成された画像を表示します

queue (action:"status") をループ内でポーリングしないでください。バックグラウンドモニターを使えば、ポーリングは不要です。

モニタースクリプトを利用できない場合は、queue (action:"status") に切り替え、done が true になるまでポーリングします。

キュー管理

1 つのツール queue を、action パラメーターで操作します。

• queue (action:"list") は、実行中／保留中のジョブ数と prompt_ids を表示します
• queue (action:"status") は、特定の prompt_id が実行中、保留中、完了のいずれかを確認します
• queue (action:"cancel") は、実行中のジョブを中断します（特定のジョブを対象にする場合は、任意の prompt_id を渡します）
• queue (action:"cancel_queued") は、prompt_id を指定して、キュー内の特定の保留中ジョブを削除します
• queue (action:"clear") は、保留中のジョブをすべて削除します（現在実行中のジョブは停止しません）

キューツールを使う場面：

• 状態を確認するには、簡単な真偽値の確認に queue (action:"status") を使います（継続的な追跡には、バックグラウンドモニターを優先してください）
• 中止するには、queue (action:"cancel") で現在実行中のジョブを停止し、queue (action:"cancel_queued") で保留中のジョブを削除します
• 最初からやり直すには、queue (action:"clear") を実行し、必要に応じて queue (action:"cancel") を実行します

監視と復旧

• get_system_stats は GPU、VRAM、Python のバージョン、OS の詳細を報告します
• queue (action:"list") は実行中／保留中のジョブを表示します（上記の「キュー管理」にも記載）

ComfyUI が応答しない、またはクラッシュした場合：

1. get_system_stats を試します。失敗した場合、ComfyUI は停止しています
2. restart_comfyui を action: "restart" で使用します（以前の action: "stop" の起動引数を保持しています）
3. 再起動に失敗した場合（保存されたプロセス情報がない場合）、restart_comfyui を action: "start" で使用するか、ユーザーに手動で起動するよう依頼します
4. ComfyUI の復旧後、失敗または失われたワークフローを再度キューに登録します

ジョブが停止しているように見える場合（モニターに [STALL] と表示される場合）：

1. get_system_stats を確認し、VRAM の使用量を確認します（OOM により停止することがあります）
2. queue (action:"cancel") を試して、停止したジョブを中断します
3. キャンセルに失敗した場合は、restart_comfyui を使って強制的に再起動します
4. 再試行する前に、再起動後の GPU メモリを解放するため clear_vram を使います

KSampler のパラメーター

パラメーター	型	一般的な値
seed	int	ランダム（0～2^48）。省略すると自動でランダム化されます。
steps	int	20（標準）、4-8（turbo/lightning モデル）
cfg	float	7-8（SD 1.5/SDXL）、1.0（Flux）、3.5（turbo）
sampler_name	string	"euler"、"euler_ancestral"、"dpmpp_2m"、"dpmpp_sde"
scheduler	string	"normal"、"karras"、"sgm_uniform"
denoise	float	1.0（txt2img）、0.5-0.8（img2img）、0.75-0.9（inpaint）

Mermaid の可視化規約

visualize_workflow ツールは、次の特徴を持つ Mermaid フローチャートを生成します。

• カテゴリー別にノードをまとめるサブグラフ：loading、conditioning、sampling、image、output
• データ型を示すエッジラベル：-->|MODEL|、-->|CLIP|、-->|LATENT| など
• class_type と、必要に応じてウィジェットの値を示すノードラベル
• デフォルトでは方向は LR（左から右）、大規模なワークフローでは TB（上から下）

visualize_workflow (action:"mermaid") ツールは Mermaid を解析してワークフロー JSON に戻し、接続タイプのラベルを使って /object_info スキーマから正しい入力／出力スロットを特定します。

よくある間違いと回避方法

1. 接続形式の誤り。 [1, 0] ではなく ["1", 0] を使用してください。ノード ID は文字列です
2. Web UI 形式。 { nodes: [], links: [] } を渡さず、API 形式を使用してください
3. VAE の指定漏れ。 CheckpointLoaderSimple の出力は 3 つあります：MODEL(0)、CLIP(1)、VAE(2)
4. 出力インデックスの誤り。 create_workflow (action:"node_info") でノードの出力リストの順序を確認してください
5. シードの処理。 disable_random_seed: true を指定しない限り、enqueue_workflow はデフォルトでシードをランダム化します

出典

• 公式： ComfyUI のワークフロー／API の規約（https://github.com/comfyanonymous/ComfyUI および https://docs.comfy.org）
• 実証ベース： MCP ツールのレシピと KSampler のデフォルト値の表は、ベンダーのプロンプトガイドではなく、製品に関する／実証に基づくメモです。