comfyui-loop-mcp

Un servidor MCP consciente del bucle para tu propio ComfyUI. No solo llama a la API — ejecuta el bucle: construir → ejecutar → mirar → criticar → arreglar, hasta que el resultado cumple realmente el encargo.

Un grafo que se ejecuta sin node_errors es válido, no correcto. Manos deformadas, un fondo desplazado, un borde de mate duro, una costura de mosaico visible — nada de eso aparece en un registro de errores. Solo se ve en los píxeles. Por eso cada descripción de herramienta, cada respuesta de herramienta y las propias instrucciones del servidor empujan al modelo a mirar antes de declarar un grafo como terminado.

La parte que nadie más tiene: el trinquete es una herramienta, no una sugerencia. La mayoría de las herramientas de agente controlan ComfyUI. Esta gestiona el bucle — un bucle largo hace que su contexto se compacte, y en el momento en que eso ocurre, un "mejor hasta ahora" recordado se pierde: el trinquete deja de funcionar silenciosamente, el modelo reintenta cambios que ya rechazó, y puede entregarte una regresión como respuesta final. Así que el mejor grafo y el registro viven en disco, no en la memoria del modelo. Revertir es una llamada a una herramienta, no un acto de memoria.

loop_start ─▶ submit ─▶ get_result ─▶ get_image ─▶ compare_images ─▶ loop_record ─┐
     ▲                                   (LOOK)      (what moved?)    (ratchet)   │
     └───────────────────  revert to best, try something else  ◀─────────────────┘
                                                          ↓ can't name a defect?
                                           loop_finish + loop_report → sign-off

El método se incluye con el servidor. El prompt del bucle y la skill de Claude Code viven en comfy_loop/docs/ y se empaquetan en la wheel, de modo que comfy_loop / comfy_skill / comfy_install los sirven textualmente desde donde esté instalado el servidor — una sola fuente, nada que mantener sincronizado. (Nacieron en comfyui-llm-onboarding-prompt, que ya no se mantiene; este repositorio es donde se conservan ahora).

• Cómo se compara con los propios servidores MCP de Comfy — el local y el de la nube, honestamente

• Posición de diseño: descubrimiento vs. reparación — dónde una herramienta local gana/pierde de verdad, y la estrella del norte

• Las tres primitivas MCP mapeadas al bucle

• Referencia de herramientas

• Ver el bucle funcionando de verdad

• Instalación y conexión

• Apuntando a un ComfyUI remoto

Cómo se compara con los propios servidores MCP de Comfy

ComfyUI incluye dos servidores oficiales, y esto es una tercera cosa construida junto a ellos — de forma independiente, y desde el otro extremo del problema.

Comfy-Org/comfy-mcp (primer commit 2026-07-01, un día después que este, aunque fue público primero) controla un ComfyUI local a través de comfy-cli: cada herramienta ejecuta el binario comfy y analiza su sobre JSON. Comfy Cloud MCP (https://cloud.comfy.org/mcp) es un servidor HTTP remoto que ejecuta el grafo en las GPU de Comfy. Ambos están construidos y mantenidos por el equipo de ComfyUI.

Este habla HTTP directamente a /prompt y /object_info — sin CLI, sin cuenta, nada que instalar más allá de httpx — y dedica su superficie a la mitad del trabajo que comienza después de que un grafo se ejecuta.

La diferencia real

Su servidor local trata la instalación de ComfyUI como lo que hay que gestionar: iniciarlo, detenerlo, cambiarlo a otra versión, iniciar sesión, gastar créditos en modelos de socios alojados, revisar sus registros, mantener los paquetes actualizados. Esa es una superficie genuinamente más grande que la de este repositorio, y es la superficie que mejor puede poseer un proveedor de plataforma — se mueve cada vez que ComfyUI, comfy-cli o las API de los socios se mueven. Si lo que necesitas es controlar y mantener mi instalación, usa el suyo.

Este trata la salida como lo que hay que gestionar — porque esa es la parte de la que éramos responsables. Salió del propio trabajo de producción de Alienrobot, donde un grafo que se ejecuta es el comienzo del trabajo, no el final. Nada de esto inicia un proceso ni gasta un crédito. En su lugar: devuelve los píxeles al modelo, compara dos pasadas en una imagen donde la deriva no puede esconderse, puntúa lo que el encargo realmente exige, y mantiene el mejor-hasta-ahora en disco para que un contexto compactado no pueda perderlo. Esa es la parte que nadie más tiene — no porque sea difícil llamar a /view, sino porque "haz que el agente mire, y evita que construya sobre una regresión" es una disciplina, no un punto final.

Cuál usar

• Sin GPU → Cloud MCP. Nada local compite con el hardware que no tienes.

• "Instálalo, ejecútalo, mantenlo funcionando" → Comfy-Org/comfy-mcp. Ciclo de vida, modelos de socios, descargas en segundo plano, fijación de versiones.

• "El primer resultado funciona, y un ojo entrenado lo rechaza" → este. Seis dedos, un fondo a la deriva, un borde de mate duro, una costura de tesela visible, un clip que hierve. Eso es un bucle, y este es un servidor construido enteramente en torno a él.

Se complementan: nada te impide ejecutar ambos, y los nombres de las herramientas no chocan. (Los nombres de paquete sí chocaban: este también fue comfy-mcp, brevemente, que es una discusión perdida con la gente que posee el espacio de nombres de ComfyUI. De ahí comfyui-loop-mcp; el paquete de importación es comfy_loop, y ambos pueden instalarse lado a lado.)

Lo que no vamos a añadir

Absorber la lista de funciones de un competidor al por mayor es como se acaba con dos herramientas mediocres. Lo que hay aquí de las suyas es lo que un bucle necesita: comprobación previa, estado del trabajo, seguimiento de registros, margen de VRAM, actualizaciones. Lo que queda fuera, a propósito:

• Cuentas, créditos, modelos de socios alojados. La propuesta es "nada sale de tu máquina, sin registro, sin medidor." Una puerta de créditos la contradice. Si quieres Kling o Veo, su servidor lo hace correctamente, con puertas de consentimiento que este repo no tiene razón para reinventar.

• Iniciar y detener el proceso de ComfyUI. Un cliente HTTP no puede iniciar un servidor que no está en ejecución, y apuntar esto a una máquina en la que no tienes shell es un caso soportado, no uno marginal. restart_comfyui (vía Manager) es el límite honesto — pero "no poder" no es lo mismo que "no ayudar": el agente normalmente sí tiene shell, así que un servidor inalcanzable devuelve los comandos de instalación/inicio para esta máquina y espera que el agente los ejecute. Ni este servidor ni el de Comfy-Org instalan ComfyUI por ti (el suyo te remite a comfy install en una terminal); la diferencia es que aquí las instrucciones vuelven a través de la llamada de herramienta, dirigidas a quien pueda actuar sobre ellas.

• Guardar / compartir / reproducir workflow como servicio. save_workflow te entrega un archivo verificado de ida y vuelta. Dónde viva después es asunto tuyo.

Related MCP server: ComfyPilot

Las tres primitivas de MCP, mapeadas al bucle

Tres cosas lo hacen consciente del bucle en lugar de un simple envoltorio de API:

1. get_image devuelve la salida renderizada al modelo — ese es el paso que hace que «mirar» sea real. El modelo ve literalmente los píxeles.

2. Las respuestas de las herramientas impulsan el bucle. submit_workflow en caso de éxito dice «válido, no correcto — ahora MIRA»; en caso de rechazo dice «no es una iteración — corrige el nodo indicado y vuelve a enviarlo». get_result termina con una directiva: «no te detengas aquí — MIRA, luego cambia un parámetro o declara cumplido el encargo».

3. Las instrucciones del servidor incluyen una política de preferencia por el bucle (ver más abajo) que el cliente inyecta al conectarse.

La política de preferencia por el bucle (instrucciones del servidor)

En el apretón de manos, el servidor le dice al agente cuándo hacer bucle y cuándo no:

• SIEMPRE descubre desde la API en vivo antes de escribir JSON; valida ejecutando; node_errors no son iteraciones — corrige y vuelve a enviar.

• PREFIERE EL BUCLE siempre que un ojo entrenado pudiera rechazar la salida — composición/conteo, parecido, calidad de mate/bordes, upscale/restauración, reiluminación, costuras de textura, estabilidad temporal del vídeo, «haz que se vea bien».

• TRINQUETE — conserva el mejor hasta ahora; mantén un cambio solo si lo supera, si no revierte y prueba algo distinto; pivota parámetro → cableado → modelo en meseta. Aplica un criterio objetivo solo donde el encargo lo tenga; juzga a ojo en caso contrario.

• OMITE el bucle solo para tareas mecánicas (conversión de formato, una consulta de API pura, o cuando el usuario quiere explícitamente solo un grafo ejecutable).

• Cuando dudes, haz al menos una pasada de mirar-y-criticar antes de declarar terminado.

El trinquete/registro/pivote están adaptados del bucle AutoResearch de Karpathy, ajustados para trabajo de imagen subjetivo (criterio objetivo solo donde exista; un punto de control de aprobación humana en lugar de ejecutarse para siempre). Estas líneas de política viven en las instructions del servidor + las respuestas de las herramientas; el método completo está en el prompt comfy_loop, que sirve el documento del bucle del repositorio textualmente.

MCP no puede forzar el comportamiento — expone capacidades y orientación. Esto convierte el bucle en el predeterminado fuerte y bien delimitado que se le dice repetidamente al agente que prefiera. Para una garantía firme en Claude Code, instala el mismo texto como una skill siempre activa:

mkdir -p ~/.claude/skills/comfyui-workflows
cp comfy_loop/docs/SKILL.md ~/.claude/skills/comfyui-workflows/

Skill = disciplina siempre activa, MCP = las herramientas que impulsa. Es el mismo archivo que sirve el prompt comfy_skill, así que no pueden discrepar — y delega en comfy_install para el arranque en lugar de llevar su propia receta obsoleta.

Referencia de herramientas

Descubrir

Verificar — todo lo que se puede saber antes de que la GPU esté involucrada

Construir → Ejecutar → Mirar

El bucle, como estado duradero — el trinquete es una herramienta, no un ejercicio de memoria. Un bucle largo se compacta; si el mejor-hasta-ahora y el registro viven solo en el contexto del modelo, el trinquete deja de funcionar silenciosamente, el modelo reintenta cambios que ya rechazó y puede devolver una regresión como resultado final. Por eso viven en disco.

Entrega

Control

Prompts: comfy_loop (método autónomo completo) y comfy_skill (skill compacta), ambos servidos textualmente desde el markdown del repositorio, más comfy_install — la receta de arranque, generada contra la máquina en la que se ejecuta el servidor: una instalación si ya hay una, el intérprete para construir el venv (el del propio servidor, así que Python nunca es un requisito previo a resolver), si comfy-cli y git están presentes, y la compilación de torch que el acelerador de esta máquina realmente quiere (CUDA / ROCm / MPS / ninguna). El servidor no puede ejecutar nada de esto; el agente sí, y a él va dirigido.

Recursos: comfyui://object_info (volcado completo en vivo), comfyui://loop-method, comfyui://skill.

Observa el bucle en acción

Impulsado enteramente a través de este servidor MCP contra un ComfyUI real (RTX 4090, SD1.5), brief: "a crisp, sharply focused macro studio photo of a single red apple on a warm wooden table, fine skin texture, rich detail." Semilla fijada en 42 para que cada pasada cambie exactamente un parámetro y el efecto sea atribuible. La métrica objetiva es la varianza del laplaciano (una medida estándar de nitidez/enfoque).

La lección sobre la que se construye el bucle, captada en directo: la métrica alcanzó su máximo en el pase 2, pero el pase 2 no es la mejor imagen — su puntuación se vio inflada por la textura del fondo, no por el detalle de la manzana. El ganador (pase 4) se eligió mirando. Un número en verde es válido, no correcto. (example_apple.png es ese resultado del pase 4).

…y la otra mitad: cuando el que se equivoca es el modelo

La manzana demuestra por qué no puedes fiarte a ciegas de la métrica. Esta ejecución demuestra por qué no puedes fiarte a ciegas del modelo — que es exactamente la razón por la que el trinquete es una herramienta y no una nota en un prompt.

Encargo: «una textura de adoquines perfectamente embaldosable — sin costura visible en el borde», con una compuerta objetiva (measure_image → tile_seam). Misma semilla en todo momento, de modo que cada pase cambia exactamente una cosa. Cada textura de abajo está embaldosada 2×2 — una costura no tiene dónde esconderse.

En el pase 3, el modelo le dijo a loop_record que el resultado era "better". No lo era: x_only embaldosa horizontalmente y deja el borde vertical roto — visible en la imagen de la derecha como piedras cortadas a ras contra la unión horizontal. La puntuación objetiva anuló la afirmación, restauró el pase 2 y devolvió el buen grafo.

Ese es el fallo que este servidor existe para prevenir: un agente que quiere terminar llamará mejora a una regresión. Si lo mejor hasta ahora hubiera vivido en el contexto del modelo en lugar de en disco, esa regresión habría sido la respuesta final.

Instalación

La versión corta: pídele a tu agente que lo haga. Pega esto en Claude Code (o en cualquier cliente MCP con shell) y no hagas nada más:

Configura el MCP de bucle de ComfyUI desde https://github.com/huikku/comfyui-loop-mcp — regístralo en mi cliente, e instala y lanza ComfyUI también si no está en ejecución.

Tiene todo lo que necesita para terminar eso sin ti: registrar el servidor es un claude mcp add, y una vez conectado, el prompt comfy_install devuelve el bootstrap para tu máquina — un ComfyUI existente que arrancar, el intérprete con el que construir el venv, la compilación de torch que tu tarjeta realmente quiere, ComfyUI-Manager y dónde poner los modelos. check_comfyui entonces nombra cualquier cosa que aún falte (sin pesos, torch en CPU, sin Manager) como cosas que el agente debe arreglar, no informar.

Si prefieres pegar configuración antes que prosa, esto ejecuta el servidor directamente desde GitHub — nada que clonar, nada que pip install:

{
  "mcpServers": {
    "comfyui": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/huikku/comfyui-loop-mcp", "comfyui-loop-mcp"],
      "env": { "COMFYUI_URL": "http://localhost:8188" }
    }
  }
}

Claude Code, una línea:

claude mcp add comfyui -- uvx --from git+https://github.com/huikku/comfyui-loop-mcp comfyui-loop-mcp

Clona el repositorio en su lugar y .mcp.json ya está ahí — Claude Code ofrece el servidor al abrirlo por primera vez, sin ningún comando. Reconecta el cliente después de añadirlo; los servidores MCP se leen en el momento de la conexión.

Desarrollando sobre él:

git clone https://github.com/huikku/comfyui-loop-mcp && cd comfyui-loop-mcp
pip install -e .            # or: uv tool install --editable .

Requiere Python ≥ 3.10 y un ComfyUI accesible. Instala mcp[cli], httpx, anyio, pillow. Funciona tanto con el SDK de MCP 1.x como 2.x — 2.0 renombró FastMCP a MCPServer y movió el helper Image, que el servidor importa de cualquier manera.

¿Lo tenías instalado como comfy-mcp? Ese nombre pertenece al servidor de Comfy-Org en PyPI, así que este ahora es comfyui-loop-mcp (paquete de importación comfy_loop, comando comfyui-loop-mcp). Ejecuta pip uninstall comfy-mcp primero y actualiza la configuración de tu cliente MCP. Las ejecuciones de bucle ya en disco se encuentran automáticamente — el antiguo ~/.comfy-mcp/runs se sigue usando hasta que apuntes COMFY_LOOP_STATE_DIR a otro sitio.

Disciplina siempre activa (Claude Code)

El método también se instala como skill, de modo que se carga con las palabras de activación en lugar de esperar a que se lo pidan — pídele al agente que haga esto también, o:

mkdir -p ~/.claude/skills/comfyui-workflows
cp comfy_loop/docs/SKILL.md ~/.claude/skills/comfyui-workflows/

El mismo archivo que sirve el prompt comfy_skill, de modo que el skill y el servidor no pueden divergir.

Configuración

Apuntando a un ComfyUI remoto

ComfyUI normalmente se vincula a 127.0.0.1, así que un ComfyUI en otra máquina no es accesible a través de la red por defecto. Dos opciones:

• Túnel SSH (lo más simple, mantiene ComfyUI privado): reenvía el puerto y deja COMFYUI_URL en localhost:

  ssh -N -L 8188:localhost:8188 your-remote-host
  # COMFYUI_URL stays http://localhost:8188

• Vincula ComfyUI a la red y apunta directamente a él (solo en una red de confianza — esto expone una API sin autenticación):

  python main.py --listen 0.0.0.0 --port 8188
  # COMFYUI_URL=http://<remote-ip>:8188

Úsalo

1. En tu agente, carga el prompt comfy_loop (o deja que lea el recurso comfyui://loop-method) para incorporar el método completo. Si tu cliente inyecta las instrucciones del servidor, la política de preferir el bucle ya está activa.

2. Dale un objetivo. Hará check_comfyui → list_nodes / get_node / list_models → construirá JSON en formato API → submit_workflow → get_result → get_image, y luego criticará e iterará — un cambio por pase — hasta que no pueda nombrar un defecto, y entonces presentará el resultado para su aprobación.

Solución de problemas

• «ComfyUI no es accesible» — la respuesta es un conjunto de instrucciones, no una queja, y van dirigidas al agente, que tiene un shell del que este servidor carece: busca un ComfyUI en esta máquina ($COMFYUI_PATH, el espacio de trabajo de comfy-cli, ~/ComfyUI, ~/comfy, ~/code, ~/github, /opt) y o bien devuelve el comando de arranque usando el python del venv propio de esa instalación, o la secuencia de clonado + venv + Manager + lanzamiento si no hay ninguno. Si COMFYUI_URL es remoto, deliberadamente no ofrece instalar en local — eso solo dejaría un segundo ComfyUI sin usar en la máquina equivocada — y te da el túnel SSH en su lugar. Cada herramienta devuelve esto, no solo check_comfyui; el consejo va adjunto en el transporte.

• Node/modelo no encontrado — instala el paquete/modelo en el lado de ComfyUI y luego reinicia ComfyUI para que /object_info lo refleje (la API está obsoleta hasta entonces).

• get_image no devuelve nada — asegúrate de que el grafo tenga un nodo SaveImage / PreviewImage; get_result enumera lo que se produjo realmente.

• install_node_pack bloqueado / sin efecto — las herramientas de instalación necesitan ComfyUI-Manager en el host, y el nivel de seguridad de Manager debe permitir instalaciones por API. Después de instalar, se requiere restart_comfyui antes de que /object_info muestre los nuevos nodos.

• find_missing_nodes elige el paquete «equivocado» — varios paquetes pueden exportar un nodo con el mismo nombre; la resolución toma la primera coincidencia del registro. Si una instalación no proporciona la clase, comprueba el paquete indicado e instala el correcto explícitamente.

Licencia

MIT.