hyperframes-mcp

This server fronts the HTML-first half of the Video studio — the HyperFrames engine, where a video is authored as web pages and animation timelines rather than typed compositions. Its 19 hf_* tools cover brief lifecycle, the three staged authoring passes, website capture, the block catalog and saved templates, rendering, and the engine's built-in quality checks. It is a thin front over the automation daemon, which dispatches the authoring agents and runs the renders.

Two capabilities give this engine its character. Site capture (hf_capture_site) snapshots a real website so the pipeline can build a video from it — the shortest path from "here is my landing page" to a finished promo. And the staged authoring surface mirrors the pipeline's three agents exactly: hf_author_brief refines your direction, hf_author_plan produces the storyboard with exact block picks, and hf_author_html writes the compositions — with hf_run_pipeline chaining all three when you want one dispatch instead of three gates.

How your agents use it

• "Turn this landing page into a 40-second promo." — hf_create_brief with the URL as a reference, hf_capture_site to snapshot it, then hf_run_pipeline for the full brief → storyboard → HTML pass, and hf_render when you approve.
• "Check the composition before we spend a render." — hf_lint and hf_inspect run the engine's structural checks and report findings the authoring agent then fixes.
• "What blocks and caption styles are available?" — hf_get_catalog lists the installable registry; hf_list_templates and hf_save_template manage your reusable starting points.

Prerequisites

The automation daemon must be running (Dashboard ▸ Platform Health); the authoring stages run on your Claude subscription, and rendering runs locally. Daemon settings live in the configuration reference.

Tool reference

Tool	Parameters	What it does
hf_health	—	Get Hyperframes engine health status (daemon online + hyperframes doctor + brief count + cached catalog size). No args.
hf_get_catalog	type: string, tag: string	List registry items (64 blocks + 20 components, 16 of which are caption styles) available via `npx hyperframes add <name>`. Filterable by type ('hyperframes:block' | 'hyperframes:component' | 'hyperframes:example') and tag. Cached for 5 min daemon-side.
hf_list_briefs	status: string, limit: integer	List Hyperframes briefs (paginated, status-filterable). Returns brief metadata for each.
hf_get_brief	brief_id*: string	Get full detail for one Hyperframes brief, including its current revision metadata.
hf_create_brief	name*: string, brief*: string, brand_preset_id: string, capture_source_url: string, auto_flow: boolean, consumer_tag: string, hints: object, assets: array, references: array	Create a new Hyperframes brief. The `brief` field carries the operator's creative direction — the single editorial source of truth the planner reads + the brief-author refines in-place. Optional capture_source_url triggers `npx hyperframes capture` automatically. auto_flow=true chains all 3 agents back-to-back without HITL pauses between stages.
hf_update_brief	brief_id*: string, patch*: object	Patch fields on an existing brief. Allowed: name, brief, assets, references, hints, brand_preset_id, consumer_tag, capture_source_url, auto_flow, status.
hf_archive_brief	brief_id*: string	Soft-delete a brief (status='cancelled', disk artifacts retained). For hard delete use the CC UI (HITL gate).
hf_save_template	brief_id*: string, name: string	Save the brief's current revision as a project template (brief.md + STORYBOARD.md + index.html + compositions/*.html — text artifacts only, partial saves valid). Returns the template manifest incl. which artifacts were captured.
hf_list_templates	—	List saved HF project templates (newest first). Attach one to a brief by setting hints.template_id via hf_update_brief or at hf_create_brief — agents then receive their template slice as guidance.
hf_author_brief	brief_id*: string, edit_instructions: string, auto_chain: boolean, timeout_sec: integer	Dispatch hyperframes-brief-author (hba) agent. On every dispatch, the agent reads the CURRENT brief in full (DB column `prompt`, operator-facing 'brief') + DESIGN.md + hf_capabilities_overview.md + EVERY operator-supplied reference (URLs fetched via WebFetch, file paths read via Read). Writes the refined brief to `_brief.md` (revision-scoped staging file, markdown) + `_brief_output.json` sidecar. Daemon commits the refined brief back to the DB column IN-PLACE — there is no separate 'initial vs refined' distinction; there is just THE BRIEF. Status flips drafted → authoring → brief_ready. Set auto_chain=true to cascade through planner + html-author (full 3-stage). Daemon validates brief depth post-exit and fails with error_class='brief_depth_insufficient' if below the bar.
hf_author_plan	brief_id*: string, edit_instructions: string, auto_chain: boolean, timeout_sec: integer	Dispatch hyperframes-planner (hpl) agent. Reads the brief (DB column `prompt`, operator-facing 'brief' — carries the refined version when brief-author has run; raw operator sketch otherwise) + DESIGN.md + hf_blocks_catalog.md, writes STORYBOARD.md (per-beat creative direction + asset audit) + _planner_output.json sidecar (skill_overrides + beat_picks + blocks_to_install). Status flips brief_ready → authoring → plan_ready. Set auto_chain=true to continue into html-author. Daemon validates STORYBOARD.md depth post-exit and fails with error_class='storyboard_depth_insufficient' if below the bar.
hf_author_html	brief_id*: string, blocks_to_install: array, edit_instructions: string, timeout_sec: integer	Dispatch hyperframes-html-author (hha) agent. Reads STORYBOARD.md + _planner_output.json sidecar, runs `npx hyperframes add` for each registry block in planner's install list, authors index.html + compositions/*.html with GSAP timelines, runs lint+inspect. Status flips plan_ready → authoring → ready (if lint pass).
hf_run_pipeline	brief_id*: string, edit_instructions: string	Chain all 3 agents back-to-back (auto_flow=true). Equivalent to hf_author_brief with auto_chain=true → cascade through planner + html-author.
hf_render	brief_id*: string, revision_id: integer, format: string, fps: integer, quality: string, use_docker: boolean, workers: integer, variables: object	Kick off a Hyperframes render (`npx hyperframes render`). Requires brief status in {authored, ready, rendered, failed}. Returns render_id for polling.
hf_get_render	render_id*: string	Get render status + progress + output path. Poll this after hf_render.
hf_lint	brief_id*: string, revision_id*: integer	Run `npx hyperframes lint --json` on a revision. Returns error/warning/info counts + findings.
hf_inspect	brief_id*: string, revision_id*: integer, samples: integer, at_seconds: array	Run `npx hyperframes inspect --json` on a revision. Catches text overflow + clipped containers across timeline samples.
hf_capture_site	url*: string, engine: string, brief_id: string, revision_id: integer, max_screenshots: integer, skip_assets: boolean, timeout_sec: integer	Dispatch `npx hyperframes capture <url>` for a brief. Writes screenshots, palette, fonts, assets, visible-text to the brief's captures/ dir. Engine param routes the output: 'hyperframes' writes to HF revision dir; 'remotion' writes to Remotion brief's captures/ + patches brief.assets[] + brief.hints.brand_palette.
hf_get_capture_job	capture_job_id*: string	Poll a site capture job's status + output. Returns palette, screenshot count, asset count, summary path.

Where to go next

• Video — the production studio — briefs, gates, and both engines in the app
• remotion-mcp — the code-driven sibling engine
• footage-mcp — preparing raw recordings for either engine