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

ComfyPilot v1.9.0

ComfyPilot — это MCP-сервер для ComfyUI. Он предоставляет AI-агенту чистую поверхность инструментов для построения рабочих процессов, постановки в очередь, мониторинга прогресса, получения изображений, снимков и безопасности VRAM.

Документация

• Производственное руководство: docs/MANUAL.md

• Аудит совместимости с релизами ComfyUI: docs/COMFYUI_COMPATIBILITY.md

• Примечания к релизам: CHANGELOG.md

Related MCP server: ComfyUI MCP

Что это такое

• Практический мост между AI-агентами и ComfyUI.

• Поверхность MCP из 96 инструментов для построения рабочих процессов, современной проверки/отмены заданий, управления моделями, загрузки/скачивания изображений, истории, мониторинга, снимков, памяти техник, безопасности VRAM, маршрутизации вывода, блюпринтов, визуализации Mermaid, импорта PNG, n-мерных переборов параметров, обнаружения партнёрских API, поиска в хабах моделей, управления экземплярами с учётом Desktop, общих артефактов, рабочих процессов comfy-env, жизненного цикла comfy-cli и диагностики.

• Живое обнаружение папок моделей: 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. Стройте маленькими шагами — Используйте comfy_build_workflow для любой цели (txt2img, img2img, upscale, inpaint, controlnet, txt2video, img2video, image2_3d, txt2music, super_resolution, interpolate_frames, segment, train_lora, txt2audio). Семейство автоматически определяется из установленного чекпоинта для целей, маршрутизируемых по семейству; цели, не зависящие от семейства (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. Маршрутизируйте выводы — Отправляйте сгенерированные изображения на диск, в TouchDesigner или Blender с помощью comfy_send_to_disk, comfy_send_to_td, comfy_send_to_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 — Проверить использование VRAM GPU с уровнями состояния (ok/warn/critical).

• comfy_set_limits — Настроить пороги безопасности (warn %, block %, max queue size).

• 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 — Материализовать блюпринт в словарь рабочего процесса с необязательными переопределениями входов для каждого узла.

• comfy_publish_subgraph — Сохранить набор узлов как именованный повторно используемый блюпринт.

Хранилище блюпринтов: опубликованные пользователем в ~/.comfypilot/blueprints/ (переопределяется через COMFY_BLUEPRINT_DIR); примеры встроенных поставляются в blueprints/ внутри репозитория.

14) Визуализация + Импорт + Перебор

Используется для рендеринга рабочих процессов, повторного импорта PNG-выводов и перебора параметров.

• comfy_visualize_workflow — Отобразить рабочий процесс в формате API как исходный код Mermaid flowchart TD.

• comfy_import_workflow_from_png — Извлечь встроенный JSON рабочего процесса из PNG, сохранённого ComfyUI (предпочитает блок 'prompt' в формате API, запасной вариант — блок 'workflow' UI).

• comfy_sweep — Поставить в очередь N копий рабочего процесса с одним параметром, изменяющимся по values; возвращает prompt_ids + подсказку макета сетки.

• comfy_sweep_grid — N-мерный перебор декартова произведения по нескольким осям node_id.param. По умолчанию ограничен 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 ещё не запущен. Все пять инструментов обращаются к официальному 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)

Используется для интроспекции рабочего процесса, заключений об оборудовании, извлечения трассировок и проверок доверия.

• 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 в один вызов.

• comfy_randomize_seeds — Замена значений seed=-1 на криптографически стойкие случайные uint32; force=True рандомизирует все виджеты seed.

20) Экземпляр рабочего стола + Артефакты + Работники

Используется для управления точным подключённым экземпляром рабочего стола, а не для угадывания рабочей области или порта.

• comfy_instance_doctor — Определение подключённого PID, владельца/супервизора, порта, корневых каталогов кода/данных/пользователя/ввода/вывода/моделей, установки рабочего стола, версий и предупреждений безопасности.

• comfy_list_artifacts — Инвентаризация изображений, видео, аудио, сеток и других выходных данных с локальным резервным каталогом вывода после сброса истории.

• comfy_get_artifact — Получение безопасных метаданных для одного выходного артефакта без возможности обхода пути.

• comfy_get_environment_status — Проверка настроенных/кэшированных сред comfy-env и состояния выполнения.

• comfy_list_workers — Список активных изолированных работников, PID, сред и состояния здоровья.

Ресурсы MCP

Шесть фиксированных ресурсов:

• 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 3.1, если подключённое развёртывание предоставляет /openapi.json; в противном случае возвращает {"error": ...}.

Плюс четыре шаблона ресурсов (параметризованные URI):

• comfy://nodes/catalog/{page} — Постраничный каталог узлов, 100 узлов на страницу ({page} = 0, 1, 2, ...)

• comfy://nodes/by-category/{category} — Классы узлов (class_types), категория которых начинается с заданного префикса (например, sampling, loaders/video)

• comfy://templates/catalog — Шаблоны рабочих процессов, предлагаемые ядром ComfyUI + пользовательскими узлами (через /workflow_templates)

• comfy://docs/{node_class} — Локализованная встроенная документация Markdown из /docs/<class>/en.md с резервными вариантами structured-fork и object-info.

Как использовать (практический рабочий процесс)

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).

• Начало с встроенных шаблонов для каждого семейства (13 поставляются в репозитории) и настройка оттуда.

• 6-этапная проверка рабочего процесса (схема + каталог + граф + антицикл + среда + риск выполнения), выявляющая разорванные связи, циклы, отсутствующие модели, устаревшие модели, слишком большие латентные представления до запуска ComfyUI.

• Мониторинг ресурсов GPU и предотвращение ситуаций OOM с помощью VRAMGuard.

• Возврат сгенерированных изображений непосредственно в чат (блоки содержимого изображений).

• Межприкладная маршрутизация вывода в TouchDesigner и Blender с атомарной записью и манифестами (prompt_id, seeds, ссылки на модели, размеры).

• Создание и восстановление снимков для неразрушающего экспериментирования с рабочими процессами, теперь опционально сохраняемых между перезапусками.

• Изучение и повторное использование шаблонов рабочих процессов через библиотеку техник.

• Перебор параметров (постановка в очередь N вариаций одного значения виджета).

• Импорт рабочего процесса обратно из встроенных метаданных сохранённого PNG.

• Визуализация любого рабочего процесса в виде Mermaid для быстрого визуального просмотра.

• Поиск моделей напрямую на HuggingFace и CivitAI.

Что он умеет плохо

• Замена художественного направления самостоятельно.

• Потоковый вывод видео в реальном времени (снимки и опрос, не живые кадры).

• «Идеальная генерация с одного раза» без итеративного уточнения.

• Работа без работающего экземпляра ComfyUI где-либо (облако или локально). Инструменты жизненного цикла (comfy_launch_server, comfy_install_node, comfy_install_workflow_deps, comfy_download_model) могут привести локальную установку от нуля до готовности, но им требуется comfy-cli в PATH — сначала установите через 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. Дважды щелкните файл (или перетащите его в панель Settings > Extensions в Claude Desktop).

3. Claude Desktop отобразит форму для COMFY_URL, COMFY_API_KEY и других полей конфигурации — заполните необходимые.

4. Нажмите Install. Перезапуск выполняется автоматически.

MCPB использует режим сервера type: "uv", поэтому зависимости Python (mcp, httpx, pydantic, websockets) разрешаются uv при первом запуске. На хосте должен быть установлен uv — установить 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 и настольное приложение используют эту конфигурацию. Перезапустите Codex после изменения MCP-серверов.

Локальное переопределение

Если ваш экземпляр ComfyUI находится не по адресу 127.0.0.1:8188 (Tailscale, удаленная локальная сеть, нестандартный порт), скопируйте .mcp.local.json.example в .mcp.local.json и отредактируйте его. Файл .mcp.local.json добавлен в .gitignore, поэтому URL-адреса и секреты для каждой машины никогда не попадут в репозиторий.

MCP Bundle (Standardized)

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