​

Graph-health heuristics in workflow analysis

Prior art: filliptm/ComfyUI_FL-MCP workflow_overview (web/js/query_executor.js) reports node-type histograms, disconnected nodes, and missing required inputs — but client-side with slot-name heuristics, because the live canvas lacks schema data. We run server-side with real /object_info required/optional data, keeping their heuristics only as a fallback for uninstalled node types.

​

Relationship to graph query (#169)

​

Motivation

​

Placement: create_workflow (action:"validate") (primary), get_workflow (action:"analyze") view:"health" (secondary)

• create_workflow (action:"validate") takes raw workflow JSON — the shape agents hold while authoring; health findings are a validation concern (severity-tagged issues) and compose with ValidationResult.issues.
• get_workflow (action:"analyze") takes a library filename; extending its view enum with "health" reuses loadWorkflowApi() (which already converts UI→API via convertUiToApi) for near-zero extra code.

​

Tool API

health: z.boolean().optional().default(true)
  .describe("Include graph-health heuristics (disconnected nodes, duplicate model loads, orphaned branches, muted/bypassed nodes) as info/warning issues plus a structured health section.")

​

New service: src/services/workflow-health.ts

export interface HealthFinding {
  kind: "disconnected" | "missing_required_input" | "duplicate_model_load"
      | "orphaned_branch" | "muted_or_bypassed" | "no_output_reachable";
  severity: "warning" | "info";
  node_ids: string[];
  node_type?: string;
  detail: string;        // e.g. `CheckpointLoaderSimple loads "sd_xl_base.safetensors" in nodes 4 and 17`
  heuristic?: boolean;   // true when object_info lacked the node and slot-name heuristics were used
}

export interface GraphHealth {
  total_nodes: number;
  node_type_histogram: Record<string, number>;
  findings: HealthFinding[];
  summary: string;
}

export function analyzeGraphHealth(workflow: WorkflowJSON, objectInfo: ObjectInfo): GraphHealth

​

Checks (API-format WorkflowJSON)

1. Disconnected nodes (warning): build in/out adjacency from [nodeId, outIdx] input tuples; a node with no inbound links, no consumers, and not an output_node per object_info is isolated.
2. Missing required inputs (warning): primary source objectInfo[class_type].input.required. Fallback heuristic only when the class is absent from object_info (uninstalled custom node): FL-MCP’s isInputSlotRequired rules — known-optional slot-name list; Loader/Load families require *name*/*path*/*ckpt*; Sampler families require model/positive/negative/latent_image; VAE families require samples/images/vae; default required. Tagged heuristic: true.
3. Duplicate model loads (warning): group nodes by (class_type, model-file widget value) where class_type matches /Loader|Load/ and the value matches the model-file regex already in workflow-validator.ts:213 (/\.(safetensors|gguf|ckpt|pt|pth|bin|sft)$/i). ≥2 nodes on the same file → one finding listing all node ids.
4. Orphaned branches / no output reachable (warning): reverse-BFS from every output node (objectInfo[ct].output_node === true plus the hardcoded SaveImage/PreviewImage/SaveAnimated* list at workflow-validator.ts:137-146). Unreached non-output nodes are “computed but never saved” — reported as one finding per connected component (avoids 40 line items on big graphs). The existing zero-output validator check stays as-is.
5. Muted/bypassed (info): via _meta.mode where present. Known limitation, documented: convertUiToApi drops mode-2/4 nodes (comment at workflow-converter.ts:731; the _meta.mode: "muted"|"bypassed" mapping lives at 932-942), so for get_workflow (action:"analyze") we surface the converter’s existing warnings instead; raw API JSON handed to create_workflow (action:"validate") is checked directly, and silently skipped when _meta is absent.

​

Output composition

### Graph health
- 24 nodes, 14 types (top: KSampler x2, LoadImage x3, ...)
- [warning] Duplicate model load: CheckpointLoaderSimple "sd_xl_base.safetensors" in nodes 4, 17 — merge into one loader to save VRAM
- [warning] Orphaned branch: nodes 22, 23, 24 (UpscaleModelLoader → ImageUpscaleWithModel) never reach a save/preview node
- [info] Node 9 (KSampler) is bypassed (_meta.mode)

​

Implementation plan

1. src/services/workflow-health.ts — analyzeGraphHealth (~180 lines, pure). Types imported from src/comfyui/types.ts.
2. src/services/workflow-validator.ts — widen ValidationIssue.severity; call analyzeGraphHealth after existing step 4 (objectInfo already in hand); merge findings; return health.
3. src/tools/workflow-validate.ts — health param; render the section incl. the info bucket.
4. src/tools/workflow-library.ts — add "health" to get_workflow (action:"analyze")’s view enum; handler calls analyzeGraphHealth(workflow, objectInfo) (both in scope at lines 443-444) and renders.

​

Test plan (vitest)

​

Rollout / compat