██████╗ ██████╗ ███╗   ███╗███████╗██╗   ██╗██████╗ ██╗██╗      ██████╗ ████████╗
██╔════╝██╔═══██╗████╗ ████║██╔════╝╚██╗ ██╔╝██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝
██║     ██║   ██║██╔████╔██║█████╗   ╚████╔╝ ██████╔╝██║██║     ██║   ██║   ██║
██║     ██║   ██║██║╚██╔╝██║██╔══╝    ╚██╔╝  ██╔═══╝ ██║██║     ██║   ██║   ██║
╚██████╗╚██████╔╝██║ ╚═╝ ██║██║        ██║   ██║     ██║███████╗╚██████╔╝   ██║
 ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝        ╚═╝   ╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝

ComfyPilot v1.9.0

ComfyPilot は ComfyUI 向けの MCP サーバーです。 AI エージェントに、ワークフロー構築、キューイング、進捗監視、画像取得、スナップショット、VRAM 安全性のためのクリーンなツールインターフェースを提供します。

ドキュメント

• プロダクションマニュアル: docs/MANUAL.md

• ComfyUI リリース互換性監査: docs/COMFYUI_COMPATIBILITY.md

• リリースノート: CHANGELOG.md

Related MCP server: ComfyUI MCP

これについて

• AI エージェントと ComfyUI の間の実用的なブリッジ。

• ワークフロー構築、最新のジョブ検査/キャンセル、モデル管理、画像アップロード/ダウンロード、履歴、監視、スナップショット、テクニック記憶、VRAM 安全性、出力ルーティング、ブループリント、Mermaid 可視化、PNG 取り込み、n次元パラメータスイープ、パートナーAPI 発見、モデルハブ検索、Desktop 対応インスタンス制御、汎用アーティファクト、comfy-env ワーカー、comfy-cli ライフサイクル、診断のための 96 ツールの MCP サーフェス。

• ライブモデルフォルダ発見: diffusion_models/、text_encoders/、clip_vision/、style_models/、gligen/（および接続された ComfyUI が実際に公開するその他すべてのフォルダ）がデフォルトで検索されます。チェックポイント中心の死角はもうありません。

• 反復のためのワークフロー指向ループ。一回の推測ではありません。

• 動作パターンを保存・再生するための小さなテクニックライブラリ。

コア思考モデル（この MCP で考える方法）

すべての非自明なタスクにはこのループを使用してください:

1. まずシステムを確認 - モデルを読み込む前に GPU 状態を確認。comfy_get_system_stats、comfy_check_vram から開始。

2. メモリを確認 - ゼロから構築する前に、comfy_search_techniques を使用して類似のワークフローがライブラリに既に存在するか確認。

3. 小さなステップで構築 - 任意のインテント（txt2img、img2img、upscale、inpaint、controlnet、txt2video、img2video、image2_3d、txt2music、super_resolution、interpolate_frames、segment、train_lora、txt2audio）に comfy_build_workflow を使用。ファミリーは、ファミリールーティングインテントの場合、インストールされたチェックポイントから自動検出されます。ファミリーに依存しないインテント（super_resolution、interpolate_frames、segment、train_lora、txt2audio）は、チェックポイントに関係なくインテント名でディスパッチされます。一般的なレシピについては、comfy_insert_blueprint(name="flux2-txt2img") または 13 のバンドルブループリントのいずれかから開始。キューイング前に comfy_validate_workflow で検証（6パス: スキーマ、カタログ、グラフ、アンチサイクル、環境、実行リスク）。

4. 監視して取得 - comfy_queue_prompt でキューイング、comfy_watch_progress で監視、comfy_get_output_image で取得（チャット内に直接画像コンテンツブロックを返します）。

5. 変更前にスナップショット - 動作中のワークフローを変更する前に、必ず comfy_snapshot_workflow を実行。元に戻すには comfy_diff_snapshots と comfy_restore_snapshot を使用。

6. 出力をルーティング - 生成された画像を comfy_send_to_disk、comfy_send_to_td、comfy_send_to_blender でディスク、TouchDesigner、または Blender に送信。

ツールマップ（96 ツール）

1) システム + GPU

接続状態、GPU 診断、VRAM 管理に使用。

• comfy_get_system_stats、comfy_get_gpu_info、comfy_get_features

• comfy_list_extensions、comfy_restart、comfy_free_vram

2) モデル

ComfyUI が公開するすべてのモデルファイルの発見と管理に使用。フォルダ分類は /models からライブで発見されるため、diffusion_models/、text_encoders/、clip_vision/、style_models/、または gligen/ 下に重みが存在する最新のファミリーはデフォルトでカバーされます。

• comfy_list_models - 単一フォルダ内のページネーション付きリスト（folder、limit、offset）。

• comfy_get_model_info - モデルローダーノードクラスの正規化されたノードスキーマ。

• comfy_list_model_folders - GET /models からのライブフォルダリスト。エンドポイントに到達できない場合は、16フォルダの静的デフォルトにフォールバック。source: live | fallback を報告。

• comfy_search_models - デフォルトで発見されたすべてのフォルダを検索。folders=["checkpoints", "loras"] を渡して絞り込み。空のクエリは完全なインベントリを返す。

• comfy_refresh_models - すべてのフォルダのキャッシュを再取得。フォルダごとのカウント + total_models 数を返す。

3) ワークフロー実行

キューイング、キャンセル、プロンプト実行の管理に使用。

• comfy_queue_prompt、comfy_get_queue、comfy_cancel_run

• comfy_list_jobs、comfy_get_job、comfy_cancel_jobs

• comfy_interrupt、comfy_clear_queue

• comfy_validate_workflow、comfy_export_workflow、comfy_import_workflow

4) ノード + スキーマ

ComfyUI のノードカタログの探索とウィジェットスキーマの理解に使用。

• comfy_list_node_types、comfy_get_node_info、comfy_search_nodes

• comfy_get_categories、comfy_get_embeddings、comfy_inspect_widget

5) 画像 + ビジュアル出力

生成された画像の取得に使用（チャット内に画像コンテンツブロックとして返されます）。

• comfy_get_output_image、comfy_upload_image、comfy_list_output_images

• comfy_download_batch、comfy_get_image_url

6) 履歴

過去の生成とその出力の検査に使用。

• comfy_get_history、comfy_get_run_result、comfy_delete_history

• comfy_clear_history、comfy_search_history

7) 監視 + 進捗

アクティブなジョブの追跡とワークフローダイナミクスの観察に使用。

• comfy_watch_progress、comfy_subscribe、comfy_unsubscribe

• comfy_get_events、comfy_describe_dynamics、comfy_get_status

8) ワークフロースナップショット

元に戻し/復元とワークフローバージョン追跡に使用。

• comfy_snapshot_workflow、comfy_list_snapshots、comfy_diff_snapshots

• comfy_restore_snapshot、comfy_delete_snapshot、comfy_auto_snapshot

9) テクニック記憶

再利用可能なワークフローパターンの学習、保存、再生に使用。

• comfy_save_technique - ワークフローをタグとメタデータ付きの再利用可能なテクニックとして保存。

• comfy_search_techniques - テキストクエリおよび/またはタグでライブラリを検索。

• comfy_list_techniques - 保存されたすべてのテクニックをメタデータとともに一覧表示。

• comfy_replay_technique - 保存されたテクニックのワークフローを読み込んで即座に使用。

• comfy_favorite_technique - テクニックをお気に入りとしてマークし、評価（0-5）。

テクニックストレージは ~/.comfypilot/techniques/ に個別の JSON ファイルとして保存されます。

10) 安全性 + VRAM ガード

ガードレール、事前チェック、緊急制御に使用。

• comfy_check_vram - ステータスレベル（ok/warn/critical）で GPU VRAM 使用量を確認。

• comfy_set_limits - 安全しきい値（警告%、ブロック%、最大キューサイズ）を設定。

• comfy_detect_instability - OOM 近辺の状態とスタックしたジョブをチェック。

• comfy_validate_before_queue - 事前チェック: VRAM ヘッドルーム + キュー容量。

• comfy_emergency_stop - 現在のジョブを中断し、キューをクリアし、すべての VRAM を解放。

11) ワークフロービルダー

ファミリー認識テンプレート構築とノード編集に使用。

• comfy_build_workflow - ファミリー認識: チェックポイントファミリー（SD 1.5、SDXL、SD 3.5、Flux 2、Qwen-Image、Wan 2.2、LTX-2、HunyuanVideo、Hunyuan3D、ACE-Step）を検出し、適切なグラフトポロジにディスパッチ。インテント: txt2img、img2img、upscale、inpaint、controlnet、txt2video、img2video、image2_3d、txt2music。

• comfy_add_node - 進行中のワークフローにノードを追加。

• comfy_connect_nodes - ノード出力を入力に配線。

• comfy_set_widget_value - ノードにウィジェット値を設定。

• comfy_apply_template - comfy_build_workflow のエイリアス。

12) 出力ルーティング

エージェントによる生成画像のクロスアプリ配信に使用。

• comfy_send_to_disk - 出力画像をローカルファイルシステムに保存。

• comfy_send_to_td - 出力を TouchDesigner プロジェクトディレクトリにルーティング。

• comfy_send_to_blender - 出力を Blender プロジェクトディレクトリにルーティング。

• comfy_list_destinations - 設定された出力先を一覧表示。

13) サブグラフブループリント

名前付きの再利用可能なマクロからワークフローを組み立てるために使用。

• comfy_list_blueprints - 利用可能なすべてのブループリント（ユーザー + バンドル）を一覧表示。

• comfy_insert_blueprint - ブループリントをワークフロー dict に具体化し、オプションでノードごとの入力オーバーライドを指定。

• comfy_publish_subgraph - ノードのセットを再利用可能な名前付きブループリントとして保存。

ブループリントストレージ: ユーザー公開は ~/.comfypilot/blueprints/（COMFY_BLUEPRINT_DIR で上書き可能）。バンドル例はリポジトリ内の blueprints/ に同梱。

14) 可視化 + 取り込み + スイープ

ワークフローのレンダリング、PNG出力の再インポート、パラメータスイープに使用。

• comfy_visualize_workflow - API 形式のワークフローを Mermaid flowchart TD ソースとしてレンダリング。

• comfy_import_workflow_from_png - ComfyUI で保存された PNG から埋め込みワークフロー JSON を抽出（'prompt' API 形式チャンクを優先、'workflow' UI チャンクにフォールバック）。

• comfy_sweep - 単一パラメータを values にわたって変化させながらワークフローの N コピーをキューイング。prompt_ids + グリッドレイアウトヒントを返す。

• comfy_sweep_grid - 複数の node_id.param 軸にわたる N 次元デカルト積スイープ。デフォルトで最大 64 組み合わせ（max_combinations で上書き可能）。

15) モデルハブ検索

公開ハブからダウンロードするモデルを発見するために使用。

• comfy_search_hub - クエリに一致するモデルを HuggingFace または CivitAI で検索。正規化されたヒット（id、name、url、downloads、tags）を返す。source="huggingface" または source="civitai" を使用。

16) パートナー API

ベンダーがホストするパートナー/API カスタムノードがインストールされているかを明らかにするために使用。

• comfy_list_partner_apis - ComfyUI のインストール済み拡張機能リストと厳選されたカタログ（Veo、Kling、ByteDance Seedance/Seedream、GPT-Image、Topaz、Tripo3D、Rodin、Recraft、Ideogram、NanoBanana、Sonilo、ElevenLabs など）を交差させ、このサーバー上でどれがアクティブかをベンダー/カテゴリ/ホームページメタデータとともに報告。

17) ライフサイクル（v1.8.0）

ComfyUI がまだ実行されていない場合のセットアップからサーバーまでのフローに使用。5 つのツールすべてが公式の comfy-cli を呼び出します。pipx install comfy-cli または uvx --from comfy-cli comfy ... でインストールしてください。

• comfy_launch_server - ComfyUI を起動（comfy launch --background --port N --listen H）。

• comfy_stop_server - 実行中のサーバーを停止（comfy stop）。

• comfy_install_node - Comfy Manager 経由でスラッグによるカスタムノードパッケージをインストール。

• comfy_list_installed_nodes - 現在インストールされているカスタムノードを一覧表示。

• comfy_download_model - URL からモデルを選択した models/<folder> にダウンロード（CivitAI トークン対応）。

18) 診断（v1.8.0）

ワークフローの内観、ハードウェア判定、トレースバック抽出、信頼性チェックに使用。

18) 可視化・監査ツール

• comfy_extract_schema - ワークフローレベルで制御可能なパラメータ＋依存関係のサマリー（パラメータ一覧、モデル依存関係、埋め込み参照、出力ノード、summary_onlyモード対応）。

• comfy_fetch_logs - /history/{prompt_id}からエラーのトレースバックと完了ノード一覧のみを抽出 — status.exec_info.errorsとstatus.messagesの両方の形式に対応。

• comfy_inspect_workflow - 信頼性チェック：すべてのclass_typeを標準/カスタムに分類し、信頼できないワークフローをキューに入れる前に警告を表示。

• comfy_recommend_runtime - ハードウェア判定（ok / marginal / cloud）＋このハードウェアに適したcomfy-cliインストールフラグ。

• comfy_suggest_timeout - 長時間実行される出力クラスに基づくワークフロー別のHTTPタイムアウト推奨値（デフォルト300秒、トレーニング時は最大3600秒）。

19) 便利機能（v1.8.0）

エージェントが手動でスクリプト化するであろう複数ステップのフローを圧縮するために使用します。

• comfy_install_workflow_deps - ワークフローが参照するすべての不足しているカスタムノードパッケージを自動インストール（comfy node install-deps --workflowをラップ）。

• comfy_run_with_inputs - ローカル画像をアップロード＋ワークフロー入力として注入＋キュー投入 — img2img / inpaintの3ステップフローを1回の呼び出しに圧縮。

• comfy_randomize_seeds - seed=-1のセンチネルを暗号学的に安全なランダムuint32値に置換；force=Trueですべてのシードウィジェットをランダム化。

20) デスクトップインスタンス＋アーティファクト＋ワーカー

ワークスペースやポートを推測するのではなく、接続された正確なDesktopインストールを制御するために使用します。

• comfy_instance_doctor - 接続されたPID、所有者/スーパーバイザー、ポート、コード/データ/ユーザー/入力/出力/モデルのルート、Desktopインストール、バージョン、セキュリティ警告を解決。

• comfy_list_artifacts - 画像、動画、音声、メッシュ、その他の出力を一覧表示。履歴リセット後はローカルの出力ディレクトリでフォールバック。

• comfy_get_artifact - 1つの出力アーティファクトについて、パストラバーサルを許さずに安全なメタデータを解決。

• comfy_get_environment_status - 設定/キャッシュされたcomfy-env環境とランタイムヘルスを検査。

• comfy_list_workers - アクティブな分離ワーカー、PID、環境、ヘルスを一覧表示。

MCPリソース

6つの固定リソース：

• comfy://system/info - システム統計、GPU情報、ComfyUIバージョン

• comfy://server/capabilities - 検出されたサーバープロファイル、バージョン、フロントエンドバージョン、認証方法、WebSocket利用可能性、OpenAPIバージョン、キャッシュプロバイダー

• comfy://nodes/catalog - ノードカタログプレビュー（最初の100個の名前）

• comfy://models/{folder} - フォルダ別のモデル一覧（checkpoints、loras、vae、diffusion_models、text_encodersなど）

• comfy://embeddings - 利用可能な埋め込み

• comfy://api/openapi - 接続されたデプロイメントが/openapi.jsonを公開している場合、オプションのOpenAPI 3.1取り込み；それ以外の場合は{"error": ...}を返す。

さらに4つのリソーステンプレート（パラメータ化されたURI）：

• comfy://nodes/catalog/{page} - ページ分割されたノードカタログ、1ページあたり100ノード（{page} = 0, 1, 2, ...）

• comfy://nodes/by-category/{category} - カテゴリが指定されたプレフィックスで始まるノードのclass_type（例：sampling、loaders/video）

• comfy://templates/catalog - ComfyUIコア＋カスタムノードが提供するワークフローテンプレート（/workflow_templates経由）

• comfy://docs/{node_class} - /docs/<class>/en.mdからのローカライズされた埋め込みMarkdown。構造化フォークとオブジェクト情報のフォールバック付き。

使い方（実践的なワークフロー）

1. MCPクライアントをComfyPilotに接続する。

2. システム状態とVRAM空き容量を確認する。

3. ワークフローを構築する（テンプレートまたはカスタムAPI JSON）。

4. 検証し、プロンプトをキューに入れる。

5. 完了するまで進捗を監視する。

6. 出力画像を取得する（チャットにインライン表示）。

7. 必要に応じてディスク/TD/Blenderにルーティングする。安定したマイルストーンでスナップショットを取る。

得意なこと

• 会話を通じてComfyUIワークフローを構築および反復する。

• 11のモデルファミリー（SD 1.5、SDXL、SD 3.5、Flux 2、Qwen-Image、Wan 2.2、LTX-2、HunyuanVideo、Hunyuan3D、ACE-Step、Ernie Image）にわたるファミリー認識生成。画像、動画、3Dメッシュ、音楽をカバー。さらに5つのファミリー非依存インテント（SUPIRによる超解像、RIFE/FILMによるフレーム補間、SAM 3.1によるセグメンテーション、ネイティブLoRAトレーニング、Stable Audioによるテキスト→音声）。

• 各ファミリー用のバンドル済みブループリント（repo内に13個同梱）から始めて、そこからカスタマイズする。

• 6パスのワークフロー検証（スキーマ＋カタログ＋グラフ＋アンチサイクル＋環境＋実行リスク）により、ComfyUIに到達する前に壊れたリンク、サイクル、欠落モデル、非推奨モデル、過大な潜在変数を検出する。

• VRAMGuardによるGPUリソース監視とOOM（メモリ不足）状況の防止。

• 生成された画像をチャット内に直接返す（画像コンテンツブロック）。

• TouchDesignerおよびBlenderへのアプリ間出力ルーティング（アトミック書き込み＋サイドカー・マニフェスト（prompt_id、シード、モデル参照、寸法）付き）。

• 非破壊的なワークフロー実験のためのスナップショット/復元（再起動後もオプションで永続化）。

• テクニックライブラリによる再利用可能なワークフローパターンの学習と再生。

• パラメータスイープ（単一のウィジェット値のN個のバリエーションをキューに入れる）。

• 保存されたPNGの埋め込みメタデータからワークフローを再インポートする。

• 任意のワークフローをMermaidとしてレンダリングし、素早く視覚的に検査する。

• HuggingFaceとCivitAIを直接検索してモデルを探す。

苦手なこと

• 芸術的ディレクションをそれ自体で代替すること。

• リアルタイムビデオ出力のストリーミング（スナップショットとポーリング、ライブフレームではない）。

• 反復的な洗練なしでの「ワンショット完璧な生成」。

• どこかで動作するComfyUIインスタンス（クラウドまたはローカル）なしでの実行。ライフサイクルツール（comfy_launch_server、comfy_install_node、comfy_install_workflow_deps、comfy_download_model）はローカルインストールをゼロから準備状態にできますが、PATHにcomfy-cliが必要です — 最初にpipx install comfy-cliまたはuvx --from comfy-cli comfy ...でインストールしてください。

モデルファミリー

11のファーストクラスモデルファミリーと5つのファミリー非依存インテントオーバーライド。各ファミリーには、適切なグラフトポロジに一致するワークフローを出力するビルダーテンプレート（または複数）があります。ファミリーはチェックポイントファイル名から検出されます；checkpoint=パラメータを渡すことでオーバーライドできます。インテントオーバーライドはファミリー検出をスキップし、インテント名でディスパッチします。

インテントオーバーライド（ファミリー非依存；検出されたチェックポイントファミリーに関わらずインテント名でディスパッチ）：

トランスポート

• stdio（デフォルト） - Claude Code、Claude Desktop、Cursorなどのローカルクライアントに最適。

• streamable-http - ホスト型/リモートデプロイメントに最適。以下で有効化：

uv run comfypilot --transport streamable-http --host 0.0.0.0 --port 8765

サポートマトリックス

クイックセットアップ

オプション 1: MCPB (ワンクリック、Claude Desktop)

Claude Desktop ユーザーに最も簡単な方法:

1. 最新リリース から comfypilot-v1.9.0.mcpb をダウンロード。

2. ファイルをダブルクリック（または Claude Desktop の Settings > Extensions パネルにドラッグ）。

3. Claude Desktop が COMFY_URL、COMFY_API_KEY、その他の設定フィールドのフォームを表示 — 必要な項目を入力。

4. Install をクリック。再起動は自動的に行われます。

MCPB は type: "uv" サーバーモードを使用するため、Python 依存関係 (mcp, httpx, pydantic, websockets) は初回実行時に uv によって解決されます。ホストに uv がインストールされている必要があります — install uv。

バンドルには manifest.json + pyproject.toml + 完全な src/comfy_mcp/ パッケージ + 13 のバンドルブループリントが含まれています。マニフェスト: manifest.json。

オプション 2: ローカル開発ランタイム

git clone https://github.com/dreamrec/ComfyPilot.git
cd ComfyPilot
uv sync
uv run comfypilot

オプション 3: Claude Code プラグイン

claude plugin add /path/to/ComfyPilot

オプション 4: Codex

チェックアウトをインストールし、その stdio サーバーを登録:

uv sync
codex mcp add comfypilot --env COMFY_URL=http://127.0.0.1:8188 -- uv run --directory /path/to/ComfyPilot comfypilot

Codex は MCP 設定を ~/.codex/config.toml に保存します。CLI、IDE 拡張機能、デスクトップアプリはその設定を共有します。MCP サーバーを変更した後は Codex を再起動してください。

ローカルオーバーライド

ComfyUI インスタンスが 127.0.0.1:8188 以外の場所（Tailscale、リモートLAN、カスタムポート）にある場合、.mcp.local.json.example を .mcp.local.json にコピーして編集してください。.mcp.local.json ファイルは gitignore されているため、マシンごとの URL やシークレットがコミットされることはありません。

MCP バンドル (標準化)

ComfyPilot はリポジトリ内に標準 MCP バンドルを同梱:

• mcp/manifest.json

• mcp/profiles/claude-desktop.json, cursor.json, generic.json

バンドルされたプロファイル JSON ファイルは uv run を --directory で固定しています。クライアント設定にコピーする際は、/path/to/ComfyPilot をチェックアウトパスに置き換えてください。このリポジトリ内から起動する場合、.mcp.json は既に ${CLAUDE_PLUGIN_ROOT} を使用しています。

手動クライアント設定例 (Claude Desktop):

{
  "mcpServers": {
    "comfypilot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ComfyPilot", "comfypilot"],
      "env": {
        "COMFY_URL": "http://127.0.0.1:8188",
        "COMFY_API_KEY": ""
      }
    }
  }
}

環境変数

テストスイート

テストスイートを実行する：

uv run pytest -v

特定のカテゴリを実行する：

uv run pytest tests/test_builder.py -v

簡単なスモークテストを行う：

uv run pytest -q

信頼性の習慣

すべての重要なタスクでこれを必須と見なしてください：生成前にVRAMを確認し、ワークフロー変更前にスナップショットを取得し、ビルド後に検証し、エラー後にcomfy_detect_instabilityを確認します。

ライセンス

MIT

dreamrec // ComfyPilot // live laugh diffuse