MCP tools and REST endpoints

ReelForge has one tool registry (packages/studio/src/tools/, ADR-014) served three ways: MCP over stdio (reelforge mcp), MCP Streamable HTTP at /mcp and REST at /api/v1 on the dashboard (reelforge studio, default http://127.0.0.1:4310). This page is generated from that registry: 24 tools. Tool names and arguments follow semantic versioning. See AI integration for setup and security.

REST endpoints

Method and path	Returns
GET /api/v1/health	Server name, version, number of tools, MCP and OpenAPI URLs, whether a token is required
GET /api/v1/tools	Every tool with its input schema (?format=openai returns OpenAI function definitions)
POST /api/v1/tools/<name>	Runs one tool; the body is the arguments as JSON. Answer: { ok, result, text, error, images }
GET /api/v1/openapi.json	OpenAPI 3.1 document, one operation per tool (GPT Actions, function calling)
POST /mcp	MCP Streamable HTTP (JSON-RPC 2.0)
GET /.well-known/mcp.json	Server card: transports, toolsets, tools, auth
GET /llms.txt, /llms-full.txt	Documentation index and full documentation for models

Add ?toolsets=basic,design to /mcp, /api/v1/tools and /api/v1/openapi.json to serve fewer tools. When the server requires a token, send Authorization: Bearer <token> to /mcp and /api/v1.

Toolsets

Toolset	Tools
basic	list_episodes, get_episode, create_episode, validate_episode, preview_frames, suggest_scene, set_cues, draft_cues, align_cues, get_render_status, get_guide, list_templates, create_from_template, list_blueprints, add_scene, suggest_scenes
design	get_episode, edit_episode, write_episode_yaml, list_components, get_component_schema, suggest_scene, get_guide, list_blueprints, add_scene, suggest_scenes
render	render_episode, get_render_status, cancel_render, open_editor, doctor, get_guide
all	every tool

Tools

Tool	Toolsets	Kind	Title
list_episodes	basic	read-only	List episodes
get_episode	basic, design	read-only	Read an episode
create_episode	basic	writes	Create an episode
edit_episode	design	writes	Edit an episode (structured)
write_episode_yaml	design	destructive	Replace episode.yaml
validate_episode	basic	read-only	Validate an episode
preview_frames	basic	read-only	Preview frames
list_components	design	read-only	List components
get_component_schema	design	read-only	Component props schema
suggest_scene	basic, design	read-only	Suggest elements for a line
set_cues	basic	writes	Set cues
draft_cues	basic	writes	Draft cues
align_cues	basic	writes	Align cues to the recording
render_episode	render	writes	Render an episode
get_render_status	basic, render	read-only	Render status
cancel_render	render	writes	Cancel the render
open_editor	render	writes	Open the visual editor
doctor	render	read-only	Check the environment
get_guide	basic, design, render	read-only	Read a guide
list_templates	basic	read-only	List episode templates
create_from_template	basic	writes	Create an episode from a template
list_blueprints	basic, design	read-only	List scene blueprints
add_scene	basic, design	writes	Add a scene from a blueprint
suggest_scenes	basic, design	read-only	Suggest a plan for every line

list_episodes

List episodes · toolsets: basic · read-only · POST /api/v1/tools/list_episodes

List every episode in the project (episodes/ and examples/) with title, language, duration, voice/cue status and error count.

No arguments.

get_episode

Read an episode · toolsets: basic, design · read-only · POST /api/v1/tools/get_episode

Return the full episode.yaml text plus a compiled outline: script lines with ids, start times and words; scenes and elements with their YAML paths, resolved times and boxes; voice/cue status and lint issues. Read this before editing.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")

create_episode

Create an episode · toolsets: basic · writes · POST /api/v1/tools/create_episode

Create episodes/<id>/episode.yaml from the commented template. Optionally give the script (one spoken sentence per entry) to replace the template lines; estimated (draft) cues are written so the episode previews immediately. Then design scenes with edit_episode or write_episode_yaml.

Argument	Type	Required	Default	Description
id	string	yes		Slug, e.g. "ep10"
title	string
series	string			Series name shown in the header
lang	en | ar			Language of the voice-over (default en)
script	string[]			Spoken sentences, one per line

edit_episode

Edit an episode (structured) · toolsets: design · writes · POST /api/v1/tools/edit_episode

Apply structured edits to episode.yaml. Comments and formatting of untouched parts are kept. Operations (applied in order):

• {"op":"set","path":[...],"value":...} sets a value (missing parents are created);
• {"op":"delete","path":[...]} removes a key or list item;
• {"op":"insert","path":[...list],"index":n?,"value":...} inserts into a list (appends without index);
• {"op":"move","path":[...list],"from":i,"to":j} reorders a list. Paths are arrays of keys and 0-based indexes, e.g. ["scenes",0,"elements",2,"props","text"] or ["scenes",1,"elements"] to add an element. Get paths from get_episode. Returns the compile result (errors/warnings) with fix hints and the next step.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
ops	object[]	yes

write_episode_yaml

Replace episode.yaml · toolsets: design · destructive · POST /api/v1/tools/write_episode_yaml

Replace the whole episode.yaml with new YAML text (use for large rewrites; prefer edit_episode for small changes). The file is only written when it parses and has no schema errors, unless force is true.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
yaml	string	yes
force	boolean		false

validate_episode

Validate an episode · toolsets: basic · read-only · POST /api/v1/tools/validate_episode

Run every check (V-1…V-14: schema, cues, timing, pacing, overlaps, off-screen elements, platform safe zones, text overflow measured in the real browser, caption length). Each issue has a line, time and fix hint.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
measure	boolean		true	Measure text overflow headless (slower)

preview_frames

Preview frames · toolsets: basic · read-only · POST /api/v1/tools/preview_frames

Render still frames of the episode and return them as images so you can see the result, each with a text layout description (visible elements and their canvas boxes, layers, overlaps between base elements, platform UI zones they touch). Times: seconds (12.5), line ids ("l7" = when line 7 starts), words ("l7:'Idempotency'"), or offsets ("l7+0.8"). Tip: check a moment shortly after elements enter.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
times	string | number[]	yes
width	integer		360	Image width in pixels (height is 16/9 × width; frames are 9:16)

list_components

List components · toolsets: design · read-only · POST /api/v1/tools/list_components

Every animated component (name, description, default size). Use get_component_schema for the props of one component.

No arguments.

get_component_schema

Component props schema · toolsets: design · read-only · POST /api/v1/tools/get_component_schema

JSON Schema of a component's props (types, enums, defaults, required fields).

Argument	Type	Required	Default	Description
name	icon name (list)	yes

suggest_scene

Suggest elements for a line · toolsets: basic, design · read-only · POST /api/v1/tools/suggest_scene

Suggest on-screen elements for one script line: component, valid props and an enter time on the word that names it (e.g. "race" → lanes, "token bucket" → bucket, numbers → counter). Instant keyword dictionary by default; llm: true asks the configured language model (local or cloud, REELFORGELLM*; optional). Insert a suggestion with edit_episode (op insert into ["scenes", i, "elements"]).

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
line	string	yes		Script line id, e.g. "l3"
llm	boolean		false

set_cues

Set cues · toolsets: basic · writes · POST /api/v1/tools/set_cues

Set the start time (seconds in the voice recording) of script lines, e.g. {"l1": 0.2, "l2": 3.4}. Normally a person marks cues by ear in the studio; use this to apply known timings. Use draft_cues for estimates. Without a recording (silent videos), duration sets the total length; otherwise it grows to fit the last line.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
cues	map	yes
duration	number			Total length in seconds. Only used when there is no voice recording.

draft_cues

Draft cues · toolsets: basic · writes · POST /api/v1/tools/draft_cues

Write estimated cues (from the text length, scaled to the voice recording if there is one) so the episode can be previewed and rendered before cues are marked by ear.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
overwrite	boolean		false

align_cues

Align cues to the recording · toolsets: basic · writes · POST /api/v1/tools/align_cues

Mark cues automatically from the voice recording: every line start and every word (cues.json, flagged auto). Engine "auto" uses Whisper word timings matched to the known script when the optional speech models are installed (reelforge align --setup), otherwise pause detection (fast, no model). Lines with confidence < 0.5 deserve a listen. Refuses to replace cues marked by hand unless force: true.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
engine	auto | dsp | whisper		"auto"
words	boolean		true	Also place every word
force	boolean		false	Replace cues marked by hand

render_episode

Render an episode · toolsets: render · writes · POST /api/v1/tools/render_episode

Start rendering the final videos (master MP4, share MP4, SRT, contact sheet, publish.md in <episode>/out/). Rendering takes minutes: it runs in the background; poll get_render_status. Use silent: true when there is no voice recording.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
preset	string			Platform preset: tiktok, reels, shorts or a preset in presets/ (default: meta.preset)
silent	boolean		false
fast	boolean		false	Quick lower-quality draft
shareMb	number
sfx	boolean		true
denoise	boolean			Remove background noise from the voice (default: audio.denoise in episode.yaml)

get_render_status

Render status · toolsets: basic, render · read-only · POST /api/v1/tools/get_render_status

Progress of the current/last render, and the files in the episode's out/ folder.

Argument	Type	Required	Default	Description
episode	string			Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")

cancel_render

Cancel the render · toolsets: render · writes · POST /api/v1/tools/cancel_render

Cancel the running render.

No arguments.

open_editor

Open the visual editor · toolsets: render · writes · POST /api/v1/tools/open_editor

Start the ReelForge visual editor for an episode on 127.0.0.1 and return its URL, so a person can review or fine-tune what you made (and mark cues by ear).

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")

doctor

Check the environment · toolsets: render · read-only · POST /api/v1/tools/doctor

Check Node.js, FFmpeg, the rendering Chromium and fonts.

No arguments.

get_guide

Read a guide · toolsets: basic, design, render · read-only · POST /api/v1/tools/get_guide

Task guides for working with ReelForge (writing scripts, designing scenes, layout, cues, rendering…). detail false (default) gives the short version: what the guide is for and its first section or checklist; detail true gives the whole guide and lists its references ("<topic>/<reference>" reads one). Call without a topic (or with an unknown one) to list the topics.

Argument	Type	Required	Default	Description
topic	string			Guide name, e.g. "make-video"; "<topic>/<reference>" for a reference
detail	boolean		false	Return the full guide instead of the summary

list_templates

List episode templates · toolsets: basic · read-only · POST /api/v1/tools/list_templates

Ready-made episodes by industry (healthcare, real estate, ports, education, finance…). Each template has a few slots (short texts and numbers). Pick one, then call create_from_template with the slot values: the easiest way to make a good video.

Argument	Type	Required	Default	Description
pack	string			Only this pack (industry id)
lang	en | ar		"en"	Language of the episode (en or ar)

create_from_template

Create an episode from a template · toolsets: basic · writes · POST /api/v1/tools/create_from_template

Create episodes/<id>/ from an industry template by filling its slots (a flat object of short texts, numbers or colors; see list_templates). Missing slots keep their defaults. Draft cues are written so it previews immediately.

Argument	Type	Required	Default	Description
id	string	yes
pack	string	yes
template	string	yes
lang	en | ar		"en"	Language of the episode (en or ar)
slots	map		{}	Slot values by name, e.g.

list_blueprints

List scene blueprints · toolsets: basic, design · read-only · POST /api/v1/tools/list_blueprints

Named scene designs (hook, problem-solution, stat-reveal, comparison, process-steps, timeline, before-after, quote, cta…) with their parameters and an example. Use one with add_scene.

Argument	Type	Required	Default	Description
name	string			Only this blueprint, with its full schema

add_scene

Add a scene from a blueprint · toolsets: basic, design · writes · POST /api/v1/tools/add_scene

Add a complete scene to an episode from a named blueprint (see list_blueprints) and a few parameters. params.line is the script line the scene starts on; the scene is placed in time order and replaces an existing scene on the same line when replace is true.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")
blueprint	string	yes
params	map	yes		Blueprint parameters, including "line" (e.g. "l3")
replace	boolean		false	Replace a scene that starts on the same line

suggest_scenes

Suggest a plan for every line · toolsets: basic, design · read-only · POST /api/v1/tools/suggest_scenes

A deterministic scene plan for the whole script (no model needed): for each line, a fitting blueprint for add_scene and the best single element for edit_episode. Good first step after create_episode.

Argument	Type	Required	Default	Description
episode	string	yes		Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02")