comfyui-mcp 0.48.21 → 0.48.23

package/plugin/skills/flux-txt2img/SKILL.md

@@ -30,7 +30,7 @@ Flux is a guidance-distilled diffusion model family from Black Forest Labs. It u
 | Component | Node | Model | Notes |
 |-----------|------|-------|-------|
 | **UNET** | `UNETLoader` | `bigLove_klein1.safetensors` | 17.3GB, Klein 9B variant |
-| **CLIP** | `CLIPLoader` (type=`flux`) | `qwen_3_8b_fp8mixed.safetensors` | Qwen3-8B in text_encoders/ (8.3GB) |
+| **CLIP** | `CLIPLoader` (type=`flux2`) | `qwen_3_8b_fp8mixed.safetensors` | Qwen3-8B in text_encoders/ (8.3GB). Use `flux2`, NOT `flux` — both exist in the enum and `flux` fails at the sampler |
 | **VAE** | `VAELoader` | `flux2-vae.safetensors` | Flux 2 specific VAE (321MB) |
 
 **Klein 9B vs Flux.1 Dev**: Klein uses Qwen3-8B text encoder (not T5XXL + CLIP-L). It has a different VAE (`flux2-vae.safetensors`). 9B distilled runs in 4 steps; 9B base needs ~50 steps at CFG 5.0. Fits in ~20GB VRAM with FP8.
@@ -195,11 +195,11 @@ Bad: "masterpiece, best quality, 1girl, cafe, paris"
 ```json
 {
   "1": { "class_type": "UNETLoader", "inputs": { "unet_name": "bigLove_klein1.safetensors", "weight_dtype": "default" }},
-  "2": { "class_type": "CLIPLoader", "inputs": { "clip_name": "qwen_3_8b_fp8mixed.safetensors", "type": "flux" }},
+  "2": { "class_type": "CLIPLoader", "inputs": { "clip_name": "qwen_3_8b_fp8mixed.safetensors", "type": "flux2" }},
   "3": { "class_type": "VAELoader", "inputs": { "vae_name": "flux2-vae.safetensors" }},
   "4": { "class_type": "CLIPTextEncode", "inputs": { "clip": ["2", 0], "text": "<prompt>" }},
   "5": { "class_type": "ConditioningZeroOut", "inputs": { "conditioning": ["4", 0] }},
-  "6": { "class_type": "EmptyLatentImage", "inputs": { "width": 1024, "height": 1024, "batch_size": 1 }},
+  "6": { "class_type": "EmptyFlux2LatentImage", "inputs": { "width": 1024, "height": 1024, "batch_size": 1 }},
   "7": { "class_type": "KSampler", "inputs": {
     "model": ["1", 0],
     "positive": ["4", 0],
@@ -212,7 +212,12 @@ Bad: "masterpiece, best quality, 1girl, cafe, paris"
 }
 ```
 
-**Klein note**: Uses single `CLIPLoader` (not DualCLIPLoader) with `type: "flux"` and the Qwen3-8B text encoder from `text_encoders/`. The CLIP loader path resolves from `models/text_encoders/`.
+**Klein note**: Uses single `CLIPLoader` (not DualCLIPLoader) with `type: "flux2"` and the Qwen3-8B text encoder from `text_encoders/`. The CLIP loader path resolves from `models/text_encoders/`.
+
+**Two Flux-2-specific gotchas** (both fail at the KSampler, not at the loader, so the error points at the wrong node):
+- `type` must be **`flux2`**, not `flux`. Both values exist in the CLIPLoader enum, so `flux` loads without complaint and then dies during sampling.
+- Use **`EmptyFlux2LatentImage`**, not `EmptyLatentImage` — Flux 2 uses a different latent channel count.
+- Klein **9B** pairs with the **Qwen3-8B** encoder (`qwen_3_8b*` from `Comfy-Org/vae-text-encorder-for-flux-klein-9b`). The similarly-named `qwen_3_4b` ships in the klein-**4b** repo and is for the 4B model. Mismatching them raises `mat1 and mat2 shapes cannot be multiplied (512x7680 and 12288x4096)` — 7680 = 2560x3 (4B hidden size) vs 12288 = 4096x3 (8B) — which reads as a confusing CLIP error rather than a wrong-file error.
 
 ## Complete Workflow: Flux.1 Dev + Turbo LoRA (4-Step)
 

package/plugin/skills/wan-scail-replacement/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: wan-scail-replacement
+description: SCAIL-2 in-video character replacement on WAN 2.1 — WanSCAILToVideo + SCAIL2ColoredMask + SAM3, the reference-image framing→scale rule, and the tuning/compositing pitfalls
+globs:
+  - "**/*.json"
+---
+
+# SCAIL-2 In-Video Character Replacement (WAN 2.1)
+
+SCAIL-2 (zai-org, on WAN 2.1 14B) replaces the person in a driving video with a
+character you supply as a reference image — end-to-end, with no pose maps, and
+with multi-character support. It is the successor to WAN Animate / motion
+transfer for the "swap the subject, keep the motion" job. The official ComfyUI
+template is **`video_wan21_scail2_character_replacement_int8`**, built around
+`WanSCAILToVideo` (+ `SCAIL2ColoredMask`) with a SAM3 mask driving *where* the
+character goes.
+
+This skill documents the non-obvious behaviours that cost a full multi-minute
+render to discover. It is not a from-scratch graph — start from the official
+template and apply the guidance below.
+
+## The one rule that costs a re-render: reference framing controls SCALE
+
+**In `replacement_mode: true`, the reference image's FRAMING controls the output
+character's SIZE — not just its appearance.** The SAM3 mask controls *where* the
+character is placed; the reference image controls *how large*.
+
+Measured on a 720x1280 driving clip where the subject occupied ~30% of frame
+height (subject bbox 363 px):
+
+| Reference framing | Person bbox in output | vs driving subject |
+|---|---|---|
+| Full-bleed portrait (person ~93% of frame) | 621 px | **1.71x oversized** |
+| Reframed (person ~34% of frame) | 364 px | **1.003x — correct** |
+
+After reframing, top/bottom registration matched the driving subject within 1 px
+(the character stands on the same ground plane at the same height). Pose transfer
+was correct in *both* cases — only the scale was wrong, which makes it easy to
+misread as "the model works" until you A/B against the source.
+
+**Guidance — pad/reframe the reference before you render:**
+
+> Pad/reframe the reference image onto a canvas at the working resolution so the
+> person occupies roughly the same fraction of frame height as the subject in the
+> driving video. A full-bleed portrait reference against a wide-shot driving clip
+> renders the character oversized in proportion to the framing mismatch.
+
+Why it's a trap: this isn't stated in the template's on-canvas notes, and it does
+not surface in the popular Civitai motion-transfer workflows — those run
+*animation* mode, where the reference legitimately fills the frame.
+
+## Tuning trade-off: distill LoRA strength / shift leaks driving-subject detail
+
+Running the `lightx2v` distill LoRA at `0.8` with `ModelSamplingSD3 shift 5` (the
+settings the popular Civitai workflow uses) improves colour and detail versus
+`1.0` / `shift 8` — but it also increases adherence to the driving video enough
+that **original-subject details bleed onto the replacement character.** In one
+run the original golfer's neon-yellow shoe appeared on a replacement character
+who wears white shoes in the reference (same seed, same reference, only those two
+params changed). If you see source details you didn't ask for, raise the LoRA
+strength / shift back toward `1.0` / `shift 8`.
+
+## Don't "fix" colour with post-hoc compositing — it's a regression
+
+The raw SCAIL-2 output shows a measurable colour error (background ~-5 per channel
+from the VAE round-trip; the character loses red ~2.4x faster than green, which
+reads as a slight green cast). It is tempting to composite the generated character
+back over the original plate through the SAM3 mask to "correct" it. **Don't** —
+it measures better but looks worse:
+
+- The mask boundary produces an obvious halo.
+- Layering the original plate's props (e.g. a golf club) over generated hands
+  severs the grip relationship the model had solved coherently.
+
+SCAIL-2 resolves colour, edges, grip and occlusion *jointly*; correcting any one
+of them in isolation breaks the others. Leave the raw output alone.
+
+## Models (reference set)
+
+The template's int8 build was exercised with:
+
+- `wan2.1_14B_SCAIL_2_int8_convrot` — SCAIL-2 model
+- `wan2.1_SCAIL_2_DPO_lora_bf16` — DPO LoRA
+- `lightx2v_I2V_14B_480p_cfg_step_distill_rank64_bf16` — distill LoRA (see tuning note)
+- `Wan2_1_VAE_bf16`
+- `umt5_xxl_fp8_e4m3fn_scaled` — text encoder
+- `clip_vision_h`
+- `sam3.1_multiplex_fp16` — SAM3 mask model
+
+VRAM: ~22.2 GB peak at 576x1024 / 81-frame chunks on a 24 GB card.
+
+## See also
+
+- `wan-t2v-video`, `wan-flf-video` — other WAN 2.x video pipelines
+- `director` — multi-shot scene direction for video pipelines

package/scripts/sync-agents.mjs

@@ -57,9 +57,25 @@ ${body.trim()}`;
 const skillsDir = path.join(PLUGIN_DIR, 'skills');
 if (fs.existsSync(skillsDir)) {
   for (const skillName of fs.readdirSync(skillsDir)) {
-    const srcPath = path.join(skillsDir, skillName, 'SKILL.md');
-    const destPath = path.join(AGENTS_DIR, 'skills', skillName, 'SKILL.md');
+    const skillSrcDir = path.join(skillsDir, skillName);
+    if (!fs.statSync(skillSrcDir).isDirectory()) continue;
+    const srcPath = path.join(skillSrcDir, 'SKILL.md');
+    const destSkillDir = path.join(AGENTS_DIR, 'skills', skillName);
+    const destPath = path.join(destSkillDir, 'SKILL.md');
     processSkillOrAgent(srcPath, destPath, skillName, false);
+
+    // Also copy sibling asset folders the SKILL.md links to (references/, docs/).
+    // Without this the synced bundle keeps the SKILL.md but drops the docs it
+    // points at, leaving dangling relative-doc links in .agents/skills/<name>/
+    // (the class of breakage reported in #552).
+    for (const sub of ['references', 'docs']) {
+      const subSrc = path.join(skillSrcDir, sub);
+      if (fs.existsSync(subSrc) && fs.statSync(subSrc).isDirectory()) {
+        const subDest = path.join(destSkillDir, sub);
+        fs.cpSync(subSrc, subDest, { recursive: true });
+        console.log(`Synced ${subSrc} -> ${subDest}`);
+      }
+    }
   }
 }
 
@@ -129,12 +145,6 @@ const mcpConfig = {
         CIVITAI_API_TOKEN: ""
       }
     },
-    civitai: {
-      url: "https://mcp.civitai.com/mcp",
-      headers: {
-        Authorization: "Bearer ${CIVITAI_API_TOKEN:-}"
-      }
-    },
     huggingface: {
       url: "https://huggingface.co/mcp",
       headers: {

package/scripts/test-packs.sh

@@ -43,9 +43,14 @@ for dir in "$PACKS"/*/; do
   ( cd "$root" && PATH="$BIN:$PATH" bash "$sh" ) > "$WORK/r1.log" 2>&1
   nodes=$(find "$root/custom_nodes" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')
   models=$(find "$root/models" -type f | wc -l | tr -d ' ')
-  echo "   nodes=$nodes models=$models"
-  if [ "$nodes" -lt 1 ] || [ "$models" -lt 1 ]; then
-    echo "   [FAIL] expected >=1 node and >=1 model staged"; fail=1
+  # Expected node count is derived from the generated installer itself (one
+  # `clone` invocation per custom_nodes entry). A pack may legitimately declare
+  # zero custom nodes (all nodes native to core ComfyUI) — assert the installer
+  # staged exactly what it declares rather than a blanket >=1.
+  want_nodes=$(grep -cE '^clone ' "$sh" || true)
+  echo "   nodes=$nodes/$want_nodes models=$models"
+  if [ "$nodes" -ne "$want_nodes" ] || [ "$models" -lt 1 ]; then
+    echo "   [FAIL] expected $want_nodes node(s) and >=1 model staged"; fail=1
   fi
 
   echo "== $name: second run (idempotency) =="