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

ComfyPilot v1.9.0

ComfyPilot es un servidor MCP para ComfyUI. Proporciona a un agente de IA una superficie de herramientas limpia para la construcción de flujos de trabajo, el encolado, el monitoreo de progreso, la recuperación de imágenes, instantáneas y la seguridad de VRAM.

Documentación

• Manual de producción: docs/MANUAL.md

• Auditoría de compatibilidad de versiones de ComfyUI: docs/COMFYUI_COMPATIBILITY.md

• Notas de la versión: CHANGELOG.md

Related MCP server: ComfyUI MCP

Qué es esto

• Un puente práctico entre agentes de IA y ComfyUI.

• Una superficie MCP de 96 herramientas para la construcción de flujos de trabajo, inspección/cancelación moderna de trabajos, gestión de modelos, subida/descarga de imágenes, historial, monitoreo, instantáneas, memoria de técnicas, seguridad de VRAM, enrutamiento de salidas, planos, visualización Mermaid, ingesta de PNG, barridos de parámetros n-dimensionales, descubrimiento de API de socios, búsqueda en centros de modelos, control de instancias con conocimiento del escritorio, artefactos genéricos, trabajadores de comfy-env, ciclo de vida de comfy-cli y diagnóstico.

• Descubrimiento en vivo de carpetas de modelos: diffusion_models/, text_encoders/, clip_vision/, style_models/, gligen/ (y cualquier otra carpeta que el ComfyUI conectado exponga realmente) se buscan por defecto — sin más puntos ciegos centrados en checkpoints.

• Un bucle orientado a flujos de trabajo construido para la iteración, no para adivinanzas de un solo tiro.

• Una pequeña biblioteca de técnicas para guardar y reproducir patrones de trabajo.

Modelo de pensamiento central (Cómo pensar con este MCP)

Usa este bucle para cada tarea no trivial:

1. Verificar el sistema primero — Lee el estado de la GPU antes de cargar modelos. Comienza con comfy_get_system_stats, comfy_check_vram.

2. Verificar la memoria — Antes de construir desde cero, usa comfy_search_techniques para comprobar si ya existe un flujo de trabajo similar en la biblioteca.

3. Construir en pasos pequeños — Usa comfy_build_workflow para cualquier intención (txt2img, img2img, upscale, inpaint, controlnet, txt2video, img2video, image2_3d, txt2music, super_resolution, interpolate_frames, segment, train_lora, txt2audio). La familia se detecta automáticamente a partir del checkpoint instalado para intenciones enrutadas por familia; las intenciones independientes de la familia (super_resolution, interpolate_frames, segment, train_lora, txt2audio) se envían por nombre de intención independientemente del checkpoint. Para recetas comunes, comienza desde comfy_insert_blueprint(name="flux2-txt2img") o cualquiera de los 13 planos incluidos. Valida con comfy_validate_workflow antes de encolar (6 pasos: esquema, catálogo, grafo, anti-ciclo, entorno, riesgo de ejecución).

4. Monitorear y recuperar — Encola con comfy_queue_prompt, observa con comfy_watch_progress, recupera con comfy_get_output_image (devuelve bloques de contenido de imagen directamente en el chat).

5. Instantánea antes de cambios — Siempre comfy_snapshot_workflow antes de modificar un flujo de trabajo en funcionamiento. Usa comfy_diff_snapshots y comfy_restore_snapshot para deshacer.

6. Enrutar salidas — Envía las imágenes generadas a disco, TouchDesigner o Blender con comfy_send_to_disk, comfy_send_to_td, comfy_send_to_blender.

Mapa de herramientas (96 herramientas)

1) Sistema + GPU

Úsalas para la salud de la conexión, diagnóstico de GPU y gestión de VRAM.

• comfy_get_system_stats, comfy_get_gpu_info, comfy_get_features

• comfy_list_extensions, comfy_restart, comfy_free_vram

2) Modelos

Úsalas para descubrir y gestionar cada archivo de modelo que ComfyUI expone. La taxonomía de carpetas se descubre en vivo desde /models, por lo que las familias modernas cuyos pesos residen en diffusion_models/, text_encoders/, clip_vision/, style_models/ o gligen/ están cubiertas por defecto.

• comfy_list_models — Listado paginado dentro de una sola carpeta (folder, limit, offset).

• comfy_get_model_info — Esquema de nodo normalizado para una clase de nodo cargador de modelo.

• comfy_list_model_folders — Lista de carpetas en vivo desde GET /models, con respaldo a un valor estático predeterminado de 16 carpetas cuando el endpoint no está disponible. Reporta source: live | fallback.

• comfy_search_models — Busca en todas las carpetas descubiertas por defecto. Pasa folders=["checkpoints", "loras"] para limitar. Una consulta vacía devuelve un inventario completo.

• comfy_refresh_models — Vuelve a obtener el caché en todas las carpetas; devuelve conteos por carpeta + un número total_models.

3) Ejecución de flujo de trabajo

Úsalas para encolar, cancelar y gestionar la ejecución de prompts.

• 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) Nodos + Esquema

Úsalas para explorar el catálogo de nodos de ComfyUI y comprender los esquemas de widgets.

• comfy_list_node_types, comfy_get_node_info, comfy_search_nodes

• comfy_get_categories, comfy_get_embeddings, comfy_inspect_widget

5) Imágenes + Salida visual

Úsalas para recuperar imágenes generadas (devueltas como bloques de contenido de imagen en el chat).

• comfy_get_output_image, comfy_upload_image, comfy_list_output_images

• comfy_download_batch, comfy_get_image_url

6) Historial

Úsalas para inspeccionar generaciones pasadas y sus salidas.

• comfy_get_history, comfy_get_run_result, comfy_delete_history

• comfy_clear_history, comfy_search_history

7) Monitoreo + Progreso

Úsalas para rastrear trabajos activos y observar la dinámica del flujo de trabajo.

• comfy_watch_progress, comfy_subscribe, comfy_unsubscribe

• comfy_get_events, comfy_describe_dynamics, comfy_get_status

8) Instantáneas de flujo de trabajo

Úsalas para deshacer/restaurar y seguimiento de versiones de flujos de trabajo.

• comfy_snapshot_workflow, comfy_list_snapshots, comfy_diff_snapshots

• comfy_restore_snapshot, comfy_delete_snapshot, comfy_auto_snapshot

9) Memoria de técnicas

Úsalas para aprender, guardar y reproducir patrones de flujo de trabajo reutilizables.

• comfy_save_technique — Guarda un flujo de trabajo como una técnica reutilizable con etiquetas y metadatos.

• comfy_search_techniques — Busca en la biblioteca por consulta de texto y/o etiquetas.

• comfy_list_techniques — Lista todas las técnicas guardadas con metadatos.

• comfy_replay_technique — Carga el flujo de trabajo de una técnica guardada para uso inmediato.

• comfy_favorite_technique — Marca técnicas como favoritas y las califica (0-5).

El almacenamiento de técnicas reside en ~/.comfypilot/techniques/ como archivos JSON individuales.

10) Seguridad + Guardia de VRAM

Úsalas para barreras de protección, verificaciones previas al vuelo y control de emergencia.

• comfy_check_vram — Verifica el uso de VRAM de la GPU con niveles de estado (ok/warn/critical).

• comfy_set_limits — Configura umbrales de seguridad (warn %, block %, tamaño máximo de cola).

• comfy_detect_instability — Verifica condiciones de casi OOM y trabajos atascados.

• comfy_validate_before_queue — Verificación previa al vuelo: espacio libre de VRAM + capacidad de cola.

• comfy_emergency_stop — Interrumpe el trabajo actual, limpia la cola, libera toda la VRAM.

11) Constructor de flujo de trabajo

Úsalas para la construcción de plantillas con conocimiento de familia y edición de nodos.

• comfy_build_workflow — Conocedor de familias: detecta la familia del checkpoint (SD 1.5, SDXL, SD 3.5, Flux 2, Qwen-Image, Wan 2.2, LTX-2, HunyuanVideo, Hunyuan3D, ACE-Step) y envía a la topología de grafo correcta. Intenciones: txt2img, img2img, upscale, inpaint, controlnet, txt2video, img2video, image2_3d, txt2music.

• comfy_add_node — Agrega un nodo a un flujo de trabajo en progreso.

• comfy_connect_nodes — Conecta salidas de nodos a entradas.

• comfy_set_widget_value — Establece valores de widgets en los nodos.

• comfy_apply_template — Alias de comfy_build_workflow.

12) Enrutamiento de salidas

Úsalas para la entrega entre aplicaciones orquestada por agente de imágenes generadas.

• comfy_send_to_disk — Guarda la imagen de salida en el sistema de archivos local.

• comfy_send_to_td — Enruta la salida al directorio del proyecto de TouchDesigner.

• comfy_send_to_blender — Enruta la salida al directorio del proyecto de Blender.

• comfy_list_destinations — Lista los destinos de salida configurados.

13) Planos de subgrafo

Úsalas para ensamblar flujos de trabajo a partir de macros reutilizables con nombre.

• comfy_list_blueprints — Lista todos los planos disponibles (usuario + incluidos).

• comfy_insert_blueprint — Materializa un plano en un diccionario de flujo de trabajo con anulaciones de entrada por nodo opcionales.

• comfy_publish_subgraph — Guarda un conjunto de nodos como un plano reutilizable con nombre.

Almacenamiento de planos: publicados por el usuario en ~/.comfypilot/blueprints/ (anular con COMFY_BLUEPRINT_DIR); los ejemplos incluidos se envían en blueprints/ dentro del repositorio.

14) Visualización + Ingesta + Barrido

Úsalas para renderizar flujos de trabajo, reimportar salidas PNG y realizar barridos de parámetros.

• comfy_visualize_workflow — Renderiza un flujo de trabajo en formato API como fuente de Mermaid flowchart TD.

• comfy_import_workflow_from_png — Extrae el JSON de flujo de trabajo incrustado de un PNG guardado por ComfyUI (prefiere el fragmento de formato API 'prompt', recurre al fragmento de UI 'workflow').

• comfy_sweep — Encola N copias de un flujo de trabajo con un único parámetro variando a través de values; devuelve prompt_ids + sugerencia de diseño de cuadrícula.

• comfy_sweep_grid — Barrido de producto cartesiano N-dimensional sobre múltiples ejes node_id.param. Limitado a 64 combinaciones por defecto (anular con max_combinations).

15) Búsqueda en centro de modelos

Úsalas para descubrir modelos para descargar desde centros públicos.

• comfy_search_hub — Busca en HuggingFace o CivitAI modelos que coincidan con una consulta. Devuelve resultados normalizados (id, name, url, downloads, tags). Usa source="huggingface" o source="civitai".

16) API de socios

Úsalas para descubrir qué API de socios / nodos personalizados alojados por proveedores están instalados.

• comfy_list_partner_apis — Interseca la lista de extensiones instaladas de ComfyUI con un catálogo curado (Veo, Kling, ByteDance Seedance/Seedream, GPT-Image, Topaz, Tripo3D, Rodin, Recraft, Ideogram, NanoBanana, Sonilo, ElevenLabs, etc.) e informa cuáles están activos en este servidor con metadatos de proveedor / categoría / página de inicio.

17) Ciclo de vida (v1.8.0)

Úsalas para el flujo completo de configuración a servidor cuando ComfyUI aún no se está ejecutando. Las cinco herramientas se ejecutan en el comfy-cli oficial — instálalo mediante pipx install comfy-cli o uvx --from comfy-cli comfy ....

• comfy_launch_server — Inicia ComfyUI (comfy launch --background --port N --listen H).

• comfy_stop_server — Detiene el servidor en ejecución (comfy stop).

• comfy_install_node — Instala un paquete de nodo personalizado por slug a través de Comfy Manager.

• comfy_list_installed_nodes — Lista los nodos personalizados actualmente instalados.

• comfy_download_model — Descarga un modelo por URL en una carpeta models/<folder> elegida (soporta token de CivitAI).

18) Diagnóstico (v1.8.0)

Úsalas para introspección de flujo de trabajo, veredictos de hardware, extracción de trazas y comprobaciones de confianza.

19) Conveniencia (v1.8.0)

Úselo para comprimir flujos de varios pasos que un agente, de otro modo, escribiría manualmente.

• comfy_extract_schema - Resumen controlable de parámetros y dependencias a nivel de flujo de trabajo (lista de parámetros, dependencias de modelos, referencias de embeddings, nodos de salida, con modo summary_only).

• comfy_fetch_logs - Extrae solo el traceback de error y la lista de nodos completados de /history/{prompt_id} — maneja tanto las formas status.exec_info.errors como status.messages.

• comfy_inspect_workflow - Verificación de confianza: clasifica cada class_type como stock / personalizado y muestra advertencias antes de encolar flujos de trabajo no confiables.

• comfy_recommend_runtime - Veredicto de hardware (ok / marginal / cloud) + la bandera de instalación de comfy-cli correcta para este hardware.

• comfy_suggest_timeout - Sugerencia de tiempo de espera HTTP por flujo de trabajo basada en clases de salida de larga duración (por defecto 300s, hasta 3600s para entrenamiento).

20) Instancia de Escritorio + Artefactos + Trabajadores

Úselo para controlar la instalación exacta de Escritorio conectada en lugar de adivinar un espacio de trabajo o puerto.

• comfy_instance_doctor - Resuelve el PID conectado, propietario/supervisor, puerto, raíces de código/datos/usuario/entrada/salida/modelo, instalación de Escritorio, versiones y advertencias de seguridad.

• comfy_list_artifacts - Inventario de imágenes, videos, audio, mallas y otras salidas, con un respaldo de directorio de salida local después de reinicios del historial.

• comfy_get_artifact - Resuelve metadatos seguros para un artefacto de salida sin permitir el path traversal.

• comfy_get_environment_status - Inspecciona los entornos comfy-env configurados/en caché y el estado de ejecución.

• comfy_list_workers - Lista los trabajadores aislados activos, PIDs, entornos y estado de salud.

Recursos MCP

Seis recursos fijos:

• comfy://system/info - Estadísticas del sistema, información de GPU, versión de ComfyUI

• comfy://server/capabilities - Perfil del servidor detectado, versión, versión del frontend, método de autenticación, disponibilidad de WebSocket, versión de OpenAPI, proveedor de caché

• comfy://nodes/catalog - Vista previa del catálogo de nodos (primeros 100 nombres)

• comfy://models/{folder} - Listado de modelos por carpeta (checkpoints, loras, vae, diffusion_models, text_encoders, etc.)

• comfy://embeddings - Embeddings disponibles

• comfy://api/openapi - Ingesta opcional de OpenAPI 3.1 cuando la implementación conectada expone /openapi.json; de lo contrario, devuelve {"error": ...}.

Además, cuatro plantillas de recursos (URI parametrizadas):

• comfy://nodes/catalog/{page} - Catálogo de nodos paginado, 100 nodos por página ({page} = 0, 1, 2, ...)

• comfy://nodes/by-category/{category} - class_types de nodos cuya categoría comienza con el prefijo dado (ej. sampling, loaders/video)

• comfy://templates/catalog - Plantillas de flujo de trabajo anunciadas por el núcleo de ComfyUI + nodos personalizados (a través de /workflow_templates)

• comfy://docs/{node_class} - Markdown incrustado localizado de /docs/<class>/en.md, con respaldos structured-fork y object-info.

Cómo usarlo (Flujo de trabajo práctico)

1. Conecte el cliente MCP a ComfyPilot.

2. Verifique el estado del sistema y el espacio libre de VRAM.

3. Construya un flujo de trabajo (plantilla o JSON de API personalizado).

4. Valide, luego encole el prompt.

5. Observe el progreso hasta que se complete.

6. Recupere la imagen de salida (mostrada en línea en el chat).

7. Enrute a disco/TD/Blender si es necesario. Tome una instantánea en hitos estables.

En qué es bueno

• Construir e iterar sobre flujos de trabajo de ComfyUI mediante conversación.

• Generación consciente de la familia en 11 familias de modelos (SD 1.5, SDXL, SD 3.5, Flux 2, Qwen-Image, Wan 2.2, LTX-2, HunyuanVideo, Hunyuan3D, ACE-Step, Ernie Image) que cubre imágenes, video, mallas 3D y música. Además, 5 intenciones independientes de la familia (superresolución mediante SUPIR, interpolación de fotogramas mediante RIFE/FILM, segmentación mediante SAM 3.1, entrenamiento nativo de LoRA, texto a audio mediante Stable Audio).

• Comenzar desde planos incluidos para cada familia (13 se envían en el repositorio) y personalizar a partir de ahí.

• Validación de flujo de trabajo en 6 pasos (esquema + catálogo + grafo + anti-ciclo + entorno + riesgo de ejecución) que detecta enlaces rotos, ciclos, modelos faltantes, modelos obsoletos, latentes sobredimensionados antes de llegar a ComfyUI.

• Monitorización de recursos de GPU y prevención de situaciones de falta de memoria (OOM) mediante VRAMGuard.

• Devolución de imágenes generadas directamente en el chat (bloques de contenido de imagen).

• Enrutamiento de salida entre aplicaciones a TouchDesigner y Blender con escrituras atómicas + manifiestos sidecar (prompt_id, semillas, referencias de modelo, dimensiones).

• Instantánea/restauración para experimentación no destructiva de flujos de trabajo, ahora opcionalmente persistente entre reinicios.

• Aprendizaje y reproducción de patrones de flujo de trabajo reutilizables mediante la biblioteca de técnicas.

• Barridos de parámetros (encolar N variaciones de un solo valor de widget).

• Importación de un flujo de trabajo desde los metadatos incrustados de un PNG guardado.

• Representación de cualquier flujo de trabajo como Mermaid para una inspección visual rápida.

• Búsqueda directa en HuggingFace y CivitAI de modelos.

En qué no es bueno

• Reemplazar la dirección artística por sí mismo.

• Transmisión de video en tiempo real (instantáneas y sondeos, no fotogramas en vivo).

• "Generación perfecta de un solo disparo" sin refinamiento iterativo.

• Ejecutarse sin una instancia de ComfyUI funcionando en algún lugar (nube o local). Las herramientas de ciclo de vida (comfy_launch_server, comfy_install_node, comfy_install_workflow_deps, comfy_download_model) pueden llevar una instalación local de cero a lista, pero necesitan comfy-cli en PATH — instálelo primero mediante pipx install comfy-cli o uvx --from comfy-cli comfy ....

Familias de modelos

11 familias de modelos de primera clase más 5 anulaciones de intención independientes de la familia. Cada familia tiene una plantilla de construcción (o varias) que emite un flujo de trabajo adaptado a la topología de grafo correcta. La familia se detecta a partir del nombre del archivo de checkpoint; puede anularlo pasando checkpoint= en los parámetros. Las anulaciones de intención omiten por completo la detección de familia y se envían por nombre de intención.

Anulaciones de intención (independientes de la familia; se envían por nombre de intención independientemente de la familia de checkpoint detectada):

Transportes

• stdio (predeterminado) - Mejor para clientes locales como Claude Code, Claude Desktop, Cursor.

• streamable-http - Mejor para implementaciones alojadas/remotas. Habilitar con:

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

Configuración rápida

Opción 1: MCPB (un clic, Claude Desktop)

La más fácil para usuarios de Claude Desktop:

1. Descarga comfypilot-v1.9.0.mcpb desde la última versión.

2. Haz doble clic en el archivo (o arrástralo al panel de Configuración > Extensiones de Claude Desktop).

3. Claude Desktop muestra un formulario para COMFY_URL, COMFY_API_KEY y los demás campos de configuración — completa lo que necesites.

4. Haz clic en Instalar. El reinicio se maneja automáticamente.

MCPB usa el modo de servidor type: "uv", por lo que las dependencias de Python (mcp, httpx, pydantic, websockets) son resueltas por uv en la primera ejecución. Necesitas tener uv instalado en el host — instalar uv.

El paquete incluye manifest.json + pyproject.toml + el paquete completo src/comfy_mcp/ + los 13 planos incluidos. Manifiesto: manifest.json.

Opción 2: Entorno de ejecución de desarrollo local

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

Opción 3: Plugin de Claude Code

claude plugin add /path/to/ComfyPilot

Opción 4: Codex

Instala el checkout y registra su servidor stdio:

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

Codex almacena la configuración MCP en ~/.codex/config.toml; la CLI, la extensión del IDE y la aplicación de escritorio comparten esa configuración. Reinicia Codex después de cambiar los servidores MCP.

Anulación local

Si tu instancia de ComfyUI se encuentra en un lugar diferente a 127.0.0.1:8188 (Tailscale, LAN remota, puerto personalizado), copia .mcp.local.json.example a .mcp.local.json y edítalo. El archivo .mcp.local.json está en gitignore para que las URL y secretos por máquina nunca se confirmen.

Paquete MCP (Estandarizado)

ComfyPilot incluye un paquete MCP estándar en el repositorio:

• mcp/manifest.json

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

Los archivos JSON de perfil incluidos fijan uv run con --directory; reemplaza /path/to/ComfyPilot con la ruta de tu checkout al copiarlos en una configuración de cliente. Si estás iniciando desde dentro de este repositorio, .mcp.json ya usa ${CLAUDE_PLUGIN_ROOT}.

Ejemplo de configuración manual de cliente (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": ""
      }
    }
  }
}

Variables de entorno

Conjunto de pruebas

Ejecuta el conjunto de pruebas:

uv run pytest -v

Ejecuta una categoría específica:

uv run pytest tests/test_builder.py -v

Para una prueba de humo rápida:

uv run pytest -q

Hábito de fiabilidad

Trata esto como obligatorio para cada tarea significativa: antes de las generaciones, verifica la VRAM; antes de los cambios en el flujo de trabajo, toma una instantánea; después de las compilaciones, valida; después de errores, ejecuta comfy_detect_instability.

Licencia

MIT

dreamrec // ComfyPilot // live laugh diffuse