Comfyui Topology Viz

Two generation paths (spec 120's fallback pipeline, used when the federated path isn't)

• Structural (preferred, when Flux + a ControlNet are installed): the topology is rendered as a plain geometric box/line diagram, ComfyUI's Canny node extracts edges from it, and Flux paints over those edges — the generated image's structure (which device connects to which) is guaranteed accurate because it comes from deterministic code, not the diffusion model. Real hostname labels are overlaid afterward, also deterministically. Verified end-to-end (2026-08-28): exactly the right devices, exactly the right connections, correct legible labels.
• Plain txt2img (fallback): used only when the ControlNet pipeline's models aren't all installed. Generates from a text-only prompt with no structural guarantee — the diffusion model is free-associating from a description, not reproducing an accurate diagram. Verified working (produces a real image) but visually confirmed by the user to not resemble the actual topology.

Environment Variables

Known Limitations

• Stills only (v1). No video/animation output, no stylized test-result cards — see Overview.
• One job at a time. A second request while one is generating is rejected outright, not queued.
• comfyui-mcp can silently substitute a different ComfyUI instance than the one configured. Found live during implementation: if the configured COMFYUI_URL is unreachable, comfyui-mcp falls back to port-scanning common local ports and connects to whatever ComfyUI it finds there instead of failing — even for a completely non-routable configured host. comfyui_client.py guards against this by verifying the response's comfyuiUrl/discoverySource actually match what was configured, treating a mismatch as backend_unreachable rather than silently generating against the wrong instance. See research.md §8. If you run more than one ComfyUI instance on the same network, double-check COMFYUI_URL is exactly right.
• comfyui-mcp's own npm audit reports 10 vulnerabilities (1 low, 2 moderate, 7 high) in transitive dependencies it bundles for its own internal HTTP/WebSocket handling (hono, path-to-regexp, qs, sharp, ws) — all in libraries used for comfyui-mcp's own internal serving/media-processing, not exposed to this skill's stdio-only, sandboxed usage. Tracked as a non-blocking follow-up, matching the same treatment sketchfab-mcp-server's own audit findings received in spec 046 — do not run npm audit fix --force (it force-upgrades sharp with a breaking change) without testing the server still builds and runs afterward.
• comfyui-mcp's own task tracker (get_task_result/get_task/list_tasks) is unreliable — do not poll it. Live-verified: it got permanently stuck reporting {"status": "working"} for a job ComfyUI itself had already completed successfully ~19 seconds earlier; its WebSocket completion listener silently failed to update. Completion is instead tracked by polling ComfyUI's own /history/{promptId} endpoint directly (comfyui_client.get_prompt_history()), and the finished image is downloaded straight from ComfyUI's own /view endpoint — neither depends on anything comfyui-mcp reports about task status or file location. See research.md §9. get_task_result is kept in comfyui_client.py for diagnostics only.
• A stdio teardown race in our own client, not comfyui-mcp, was also found and fixed: calling run_workflow intermittently raised anyio.BrokenResourceError even though the job had actually submitted and completed successfully every time (confirmed against ComfyUI's own history) — a race between trailing stdio traffic and our client's async with teardown. Fixed by capturing the result before the context managers close (research.md §9).
• Verified end-to-end, plain path (2026-08-27): a real freeform topology produced a genuine 512×512 PNG in ~21.5 seconds using sd_xl_base_1.0.safetensors, correctly attributed in both the returned path and the sidecar JSON — but visually confirmed not to resemble the actual topology (abstract line-art, no real structure).
• sources.from_freeform() mis-parsed connector clauses with inline role declarations. "core1 connects to a switch called sw1" took the article "a" as the device name instead of "sw1" — creating a phantom device and leaving the real one disconnected. Invisible in the plain path (which never exposes exact link structure in its prompt) but exposed immediately once the structural renderer made the parsed graph directly visible. Fixed in sources.py; the identical bug still exists in threejs-network-viz/sources.py (this was ported from there) but was left untouched per FR-014. See research.md §10.
• Canny-edge text reconstruction is unreliable. Baking hostnames into the structure image and relying on Flux to reproduce them through Canny conditioning produced garbled nonsense, not real text. Fixed by never asking the diffusion model to render text at all — see the two generation paths section above and label_overlay.py. See research.md §10.
• Verified end-to-end, structural path (2026-08-28): the same freeform topology produced a genuinely correct diagram in 41.9s — exactly 3 devices, the real core1↔sw1↔fw1 chain, correct legible labels. Remaining imperfections are cosmetic (generic device icons rather than role-specific ones, decorative hallucinated background clutter, thin/dashed rather than "glowing" connection lines) — prompt-tuning opportunities, not correctness bugs.
• ~25GB of Flux/ControlNet models installed on the ComfyUI host for the structural path — see specs/120-comfyui-topology-viz/model-inventory.md for the full list and cleanup guidance if disk space is needed back.

See specs/120-comfyui-topology-viz/tasks.md for the full implementation history and research.md for the technical decisions and live findings behind this skill's design.