# Higgsfield Director MCP — the Faceless Channel Operating System

**v4.0.** Run this next to Higgsfield's official MCP server and Claude
becomes a complete faceless-video studio: scriptwriter's editor, director,
cinematographer, voice director, caption timer, budget controller and
publishing assistant — for ten proven faceless niches.

One raw script in → **a complete production out**: narration-timed
storyboard, the exact voiceover call, SRT captions, a cost comparison, an
edit checklist, the publishing kit (titles/description/hashtags/thumbnail),
and an **execution manifest of real official Higgsfield MCP calls** — price
checks first, then character stills, then renders — that the agent pipes
straight into the official server.

This layer is **pure intelligence — it makes no network calls of its own.**
No account, no API key, zero dependencies, nothing leaves your machine.
It thinks; the official server renders.

> Higgsfield™ is a trademark of its respective owner. This is an
> independent, unofficial companion tool and is not affiliated with or
> endorsed by Higgsfield AI.

---

## Why it pays for itself

AI video credits are the entire cost of running a faceless channel, and
most of them are wasted on renders that get thrown away. The Director
attacks that from five directions:

1. **Manifests that actually run.** Every call uses the official server's
   real API shape: real catalog model IDs (`veo3_1`, `kling3_0`,
   `minimax_hailuo`, …), the real `params` envelope, durations snapped to
   what each backend truly accepts. No burned credits on malformed or
   improvised calls.
2. **Price checks before renders.** Every manifest opens with
   `get_cost: true` preflight steps that return the true credit price of
   your shots — and a hard STOP until the budget is confirmed.
3. **Image-first economy (default).** A keyframe is generated for every
   shot at *image* prices. You approve or re-roll keyframes for cents,
   then animate only the approved frames. Rerolling a failed idea costs a
   still, not a video.
4. **Audio off when narration covers it.** Models that can render silent
   do, whenever your voiceover is the soundtrack anyway.
5. **A retention analyzer that runs before you spend.** Weak hook, bloated
   beats, dead spots with nothing to shoot — caught and fixed while the
   script is still free to change.

Plus `estimate_production_cost` compares all three render strategies with
the savings spelled out, and `plan_budget` fits your monthly credits to a
posting schedule.

## The niche matrix — 10 faceless formats, fully templated

| Niche | Aspect | The look |
|-------|--------|----------|
| `historical_alt_documentary` | 16:9 | oil-painting realism, god-rays, sweeping cranes |
| `cosmic_horror_creepypasta` | 16:9 | analog-horror VHS texture, chiaroscuro dread |
| `dark_psychology_stoicism` | 9:16 | monochrome marble macro, center-band captions |
| `stickman_3d_documentary` | 16:9 | matte-white 3D mannequin history dioramas |
| `reddit_story` | 9:16 | first-person POV realism, domestic unease |
| `true_crime_documentary` | 16:9 | 90s news-archive grain, evidence macro, no faces |
| `motivation_luxury` | 9:16 | pre-dawn discipline b-roll, deep blacks |
| `finance_money_psychology` | 9:16 | editorial object metaphors on black glass |
| `sleep_scary_stories` | 16:9 | slow-burn cozy-dread ambience, 15s takes |
| `biblical_mythology_stories` | 16:9 | Caravaggio chiaroscuro, monumental scale |

Every niche ships complete: recommended final **and** draft-tier models
(real IDs), camera and shot-size rotations, safe zones, a retention rule,
narration words-per-minute, **voice direction**, **music notes**, **10
tested hooks**, CTA lines, title patterns, hashtags, and topic seeds that
feed the 30-day series planner.

## The tools (27)

**The production line:**

| Tool | What it gives you |
|------|-------------------|
| `produce_faceless_video` | **The headline.** Script + niche → narration clock, voiceover call, timed storyboard, SRT captions, cost comparison, edit checklist, publishing kit, and the full execution manifest. Optional `save_as` persists it to disk. |
| `analyze_script_retention` | Score the script's hook, pacing and dead spots against the niche's rules — before credits are spent. |
| `estimate_production_cost` | All-premium vs draft-video vs image-first, with savings spelled out. |
| `plan_budget` | Monthly credits + upload schedule → the model tier that fits. |
| `export_captions` | Narration-timed, valid `.srt`. |
| `plan_shorts_cutdown` | 16:9 master → 9:16 shorts via the official `reframe` tool (a fraction of re-rendering). |
| `plan_series` | 30–90 day calendar: topic + hook + title per episode. |
| `package_for_platform` | 5 titles, paste-ready description, hashtags, thumbnail `generate_image` call. |
| `channel_profile` | Set niche/voice/strategy once — saved to disk, every tool defaults to it. |
| `list_productions` / `load_production` | Saved productions survive restarts; resume rendering any time. |

**The niche toolkit:** `get_viral_niches`, `generate_niche_storyboard`,
`get_viral_hooks`, `apply_retention_framing`, `create_viral_short_clip`,
`render_complete_script`, `assign_character_soul`.

**The director's toolkit:** `build_prompt`, `storyboard`, `apply_style` /
`list_styles` (12 cinematic looks), `character_sheet`, `variations`,
`suggest_preset`, `fix_prompt`, `negative_prompt`.

### Characters that never drift — and never get lost

Write recurring characters as `@Tokens` (`@Hero draws her sword`), register
them once with `assign_character_soul`, and every script renders the same
person. The roster is **saved to disk** and survives restarts — a series
cast, not a session cast. Manifests automatically schedule a reference
still per character (`soul_2` with your Soul ID, or `soul_cast` from text)
and wire its job_id into every shot's identity reference.

### Built-in safety softening

Words that commonly trip generation filters (`blood`, `gun`, `corpse`, and
a full true-crime/horror vocabulary) are swapped locally for visually
equivalent phrasing before they ever reach the official server — the
render queue keeps moving, and every substitution is reported.

---

## New here? Read [QUICKSTART.md](QUICKSTART.md)

Zero-to-first-production in 5 minutes, no coding needed — Claude Desktop
connection steps, paste-ready demo scripts in
[`examples/scripts/`](examples/scripts/), and a troubleshooting table.

## Install

Requires Python 3.10+. **Zero third-party dependencies.**

```bash
pip install .
# or, from a checkout, run without installing:
python -m higgsfield_director --help
```

## Use it with Claude Desktop (alongside the official server)

```json
{
  "mcpServers": {
    "higgsfield": { "url": "https://mcp.higgsfield.ai" },
    "higgsfield-director": {
      "command": "python",
      "args": ["-m", "higgsfield_director", "serve"]
    }
  }
}
```

(Official-server entry shown for illustration — follow Higgsfield's own
connection instructions for your client.)

Restart Claude Desktop, then just talk:

- *"Set my channel profile: niche true crime, image-first drafts."*
- *"Produce this script as a stickman documentary."* (paste the script —
  Claude returns the full production and runs the manifest on the official
  server, price checks first)
- *"Score this script before we render it."*
- *"Plan my next 30 days of reddit stories."*
- *"How many credits will this episode cost on each strategy?"*

## Use it as a CLI

```bash
higgsfield-director niches
higgsfield-director produce "Ten thousand workers haul stone at dawn." --as stickman
higgsfield-director analyze "My roommate was subletting my room." --as reddit
higgsfield-director cost "The lighthouse blinks wrong." --as creepypasta
higgsfield-director budget --credits 3000 --episodes 12 --aspect 16:9
higgsfield-director captions "Marcus wrote his journal at dawn." --as stoicism
higgsfield-director series --as motivation --days 30
higgsfield-director package --as "true crime" --topic "the payphone calls of 1994"
higgsfield-director profile --niche sleep --strategy image_first
```

Every command prints JSON, so it pipes cleanly into other tools.

## Run the tests

```bash
python -m unittest discover -s tests
```

100+ offline tests, no network or API key required.

## License

MIT — see [LICENSE](LICENSE).