# Hermes ComfyUI MCP

This connector gives Hermes product-level ComfyUI tools instead of exposing raw `/prompt` JSON.

Tools:

- `comfyui_health_check`
- `comfyui_generate_image`
- `comfyui_generate_poster`
- `comfyui_generate_video`
- `basic_video_generate`

Current capability:

- Text-to-image: supported with DreamShaper 6.2 + SD1.5 LCM LoRA as a low-end fallback profile.
- Image profiles: configurable local model tiers. The connector can auto-select ready profiles without opening the ComfyUI UI.
- Chinese poster/cover/banner: supported through `comfyui_generate_poster`. ComfyUI generates a no-text background, then the connector overlays real Chinese text with local Windows fonts and ffmpeg.
- High-quality ComfyUI text-to-video: reserved for high-end GPU machines. It returns `not_configured` until video nodes, a motion model, an API workflow, and ffmpeg are ready.
- CPU basic video: planned as a fallback path. It uses title/script/images/motion/subtitles/MP4 and should be used when GPU or video models are missing.
- CPU basic video execution now supports:
  - no-image fallback background + Chinese subtitles + MP4
  - multiple image segments joined into one vertical MP4
  - optional Windows SAPI voiceover, with automatic silent-video fallback when SAPI blocks or is unavailable
  - optional ComfyUI still-cover generation before MP4 composition

Important image rule:

- Do not ask SD1.5/DreamShaper to draw exact Chinese titles. It will often create fake character-like patterns.
- For Chinese text, dates, brand names, prices, and poster copy, Hermes should call `comfyui_generate_poster`.
- Optional high-end local profiles are registered in `config\comfyui.config.json`:
  - `qwen_image_cn_poster`
  - `kolors_cn_visual`
  - `flux_schnell_visual`
- These profiles are disabled until the matching model/custom nodes/API workflow are installed.
- Normal users do not need to open ComfyUI to choose models. Hermes reads the config and auto-selects the best ready profile. ComfyUI is only needed for installing/debugging advanced workflows.

Image profile documentation:

```text
F:\Agent\Hermes-MCP-Connectors\connectors\comfyui-mcp\README-ComfyUI-Image-Profiles.md
```

Video runtime source:

```text
F:\Agent\Hermes-MCP-Connectors\runtimes\comfyui-video
```

Current video blockers on this machine:

- `models/animatediff_models/mm_sd_v15_v2.safetensors` is not installed.
- ComfyUI currently does not expose `AnimateDiffLoader` or `EmptyLatentVideo`.
- Bundled ffmpeg is now a full build and supports image sequence input, drawtext subtitles, concat, libx264 MP4, and AAC audio.

High-end GPU text-to-video route:

- Tool: `comfyui_generate_video`
- Default state: disabled by `video.enabled=false`
- Required ComfyUI custom nodes:
  - `AnimateDiffLoader`
  - `EmptyLatentVideo`
- Required motion model:
  - `mm_sd_v15_v2.safetensors`
  - Put it under `F:\Agent\Hermes-MCP-Connectors\runtimes\comfyui-video\models\animatediff_models`
  - Also put/copy it under the user's ComfyUI folder: `ComfyUI\models\animatediff_models`
- Required workflow files:
  - UI reference workflow: `runtimes\comfyui-video\workflows\text-to-video.json`
  - API workflow for Hermes: `runtimes\comfyui-video\workflows\text-to-video-api.json`

Enable high-end text-to-video only after the readiness check passes:

```powershell
powershell -ExecutionPolicy Bypass -File F:\Agent\Hermes-MCP-Connectors\runtimes\comfyui-video\scripts\Test-ComfyUI-VideoRuntime.ps1
```

Then set this in `config\comfyui.config.json`:

```json
"video": {
  "enabled": true
}
```

If the readiness check fails, Hermes should use `basic_video_generate` instead. That fallback produces a normal MP4 from script, images, subtitles, optional voiceover, and optional still cover generation without forcing CPU to run a heavy video diffusion model.

Validation outputs on the development machine:

- `F:\Agent\Hermes-MCP-Connectors\outputs\basic-video\basic-video-20260619-001216.mp4`
  - background + Chinese subtitles + Windows SAPI voiceover
- `F:\Agent\Hermes-MCP-Connectors\outputs\basic-video\basic-video-20260619-001708.mp4`
  - ComfyUI still cover + Chinese subtitles + MP4
- `F:\Agent\Hermes-MCP-Connectors\outputs\basic-video\basic-video-20260619-002657.mp4`
  - two image segments + Chinese subtitles + MP4

Start ComfyUI with auto device selection:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\Start-ComfyUI-Auto.ps1
```

The launcher does not force CPU by default. It first reuses an already running ComfyUI service. If ComfyUI is not running, it tries the normal GPU/accelerator path first and only falls back to `--cpu` when startup fails. NVIDIA users should normally run without `--cpu`.

Health test:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\Test-Hermes-ComfyUI-MCP.ps1
```

Video runtime readiness test:

```powershell
powershell -ExecutionPolicy Bypass -File F:\Agent\Hermes-MCP-Connectors\runtimes\comfyui-video\scripts\Test-ComfyUI-VideoRuntime.ps1
```

Hermes MCP settings:

Server name:

```text
comfyui
```

Command:

```text
<Hermes install folder>\resources\native-runtime\python\python.exe
```

Arguments:

```text
-B
D:\Hermes-MCP-Connectors\connectors\comfyui-mcp\run_server.py
```

Environment:

```text
PYTHONPATH=D:\Hermes-MCP-Connectors\connectors\comfyui-mcp\src
PYTHONIOENCODING=utf-8
COMFYUI_MCP_CONFIG_PATH=D:\Hermes-MCP-Connectors\connectors\comfyui-mcp\config\comfyui.config.json
```

Working directory:

```text
D:\Hermes-MCP-Connectors\connectors\comfyui-mcp
```

Timeout seconds:

```text
600
```
