Plan a project

On the main list

The tools a client sees when it connects.

create_project

Create a project

Your plan laid out exactly, no planner; returns it with ids and the settings it got. Free. Without plan: script/topic via our planner (async). Guide: "The plan".

suggest_plan

Suggest a plan

Optional planner draft: topic or script → draft id; again with draft_id → the plan JSON for create_project {plan, draft_id}. Free.

apply_changes

Apply a changeset

Change structure in one atomic batch (≤40 ops): add/update/delete chapters, blocks, scenes — how you reshape a project after create_project. dry_run first. Free.

list_skills

List skills

The skills Typecut serves: each a whole way of making one kind of video (e.g. history-map: a chibi cast over a living map with one continuous camera) — when to use it, the kits it pins, its latest version. Load one with get_skill. Free.

No inputs.

get_skill

Load a skill

One skill (a whole look or way of making a video). By default its CARD, a few hundred tokens: what it is, when to use it, what must survive, tokens, kits, pacing, checks, and a map of its body with sizes, ending with the one section:"…" read that has what you need to write a scene. A full SKILL.md is 10-66 KB, half of it paste-ready code, so read parts: section:"Rules|Scene stub" (several at once with |); full:true for all of it. slug "history-map" (latest) or "history-map@2". With brief (one line on the beat you are writing), the k nearest worked shots ride along. format:"json" returns the structured record. Free.

Callable by name

Not listed on connect, to keep the list short. Call them directly by name, or find them with tools.

create_chapter

Create a chapter

Create ONE chapter in a project (then grow it with apply_changes add_block / create_scene — a scene with nothing spoken takes create_scene brief + duration, no narration). Omit position and it is placed BEFORE the conclusion / outro wherever that sits, appended when there is none; pass position (1-based) to insert elsewhere. Chapter ids come back for the follow-up calls.

delete_chapter

Delete a chapter

Delete ONE chapter of a project. Refused while the chapter still has scenes unless cascade is true — then its scenes go with it. PERMANENT: confirm with the user before calling. Use it to remove empty or duplicate chapters; ids come from get_storyboard.

estimate_project

Price a project before creating it

What would this cost, and can the user afford it? Creates nothing, spends nothing. Returns the credit estimate with its breakdown, the account balance, and whether the two add up. ALWAYS call this before a create_project that lets Typecut generate the scenes, and show the user the number — creation itself has no undo, and spending someone's credits without telling them first is the fastest way to lose their trust. It prices Typecut composing every scene: when you author the scenes yourself (authoring:"own") creation is free, and resolve_project voice_only dry_run prices the voice. A blank project (create_project blank:true, or with no template, topic or script) and a plan project cost nothing to create: do not price those here.

export_project

Export the project

Export the whole project, the same way the app does. Formats: mp4, webm_alpha, audio, srt, vtt, premiere, resolve, finalcut, nle_package (flag), hyperframes. mp4 / webm_alpha (a transparent-background project) start the film render and return generation_id; premiere, resolve, finalcut and nle_package start an editor package (built from rendered clips; scenes without one are listed in notes). srt / vtt answer with the file text; audio with a hosted mix (options.container m4a|wav|mp3, loudness_lufs); hyperframes with a zip url. Film export is included in the plan. Finished pieces or on request only.

fork_project

Fork a project, or freeze a snapshot of it

Copy a project into a NEW project that continues on its own, and keep the lineage. Use it to try a different cut ("keep this one as it is, fork a version with memes and sound effects"), to iterate on another concept without risking the original, or to snapshot a state you may want back. Everything that makes the film comes along: chapters, script and pauses, scenes and their compositions, music, theme, captions, the bible and characters. Voice and media are shared by URL (a re-voice of the original never changes the fork), and every voice take is kept. History, comments, costs, renders and share links are NOT copied; the fork has to be rendered itself. kind "snapshot" makes a frozen, hidden copy; to restore one, fork the snapshot. The copy counts toward the plan's project limit. workspace_id puts it in another workspace. Free. Returns the new project_id; call get_project_lineage to see how forks relate.

get_project

Get a project

Read one project: name, status, workspace, aspect ratio, and the editorial brief (topic, hook, angle) that drives generation. Read this before changing creative direction — the brief is what the pipeline actually follows. charged_credits is the ledger total linked to this project, net of refunds (credits_charged is the same figure). complete:false means some charges are booked without the project's keys and are NOT in it: unattributed names each kind (voiceover, character, unlinked) with its generation count and quoted credits_estimate. get_account before/after is the receipt for that part.

Status is one of: draft (created, not planned) · planning · generating · review · ready (all scenes resolved, renderable) · rendering · rendered (render_url is populated) · failed.

edit_version is the version of the project-level settings (music cues, tempo, theme, captions, voice, mix, ...): pass it as expected_version to set_tempo / set_theme / set_captions / set_branding / set_project_runtime / set_project_voice / set_music / set_mix / set_groove so a stale write is refused (a conflict with current_version and last_writer) instead of overwriting someone else's change.

get_project_activity

Who is working on the project now

Who is on the project right now: live scene claims, who wrote in the last minutes, and the agent runs touching it (status, last tool, scenes). Presence is not available server-side. Free.

get_project_gist

Project gist — what this project did

What a finished project DID, compact enough to build another one from — the reference you read BEFORE authoring a new project in the same vein. Where get_inventory says what is on screen, this says what it is FOR: the intent of the whole piece and of every section, the DEVICES the project reaches for (the recurring composition moves, each with its purpose and how it is actually built — for hand-written scenes, the dozen lines of the author's own code that build it in its best example), a CODE line (the modules every scene stands on and the preamble each repeats), one line per scene saying what that scene does for its section, the palette and motion grammar as used, and the rules it held to. Bounded: a long project costs about what a short one does, because devices are a vocabulary and not a scene list. text is the form to paste into an authoring prompt. Since v5 it is drawn from EVIDENCE, not only markup: SPEC (scene length, narration pace, whether cuts land on sentence starts, audio, seams — measured from the platform), BUILD (whether scenes are built up in stages or held, read from the renderer as the scene runs), and the LOOK (colours measured from frames' pixels, the style described from the frames), each saying how it is known — a look with no frame behind it is marked unverified. SCENE LENGTH is reported as groups, not one average, and INNER says how much the picture changes inside scenes (measured from frames, so it sees drawn art too). Two PICTURES are attached: the SIGNATURE STRIP (the colour of every moment with the visual change under it, scene boundaries marked) and a contact sheet — they are STYLE reference only; copy the look, never the subject they show (images:false omits them). CAST says whether characters are stored in the project bible (reuse them) or drawn inline. next is where to look closer: frames to open and get_scene_brief calls for each technique's best example scene; gaps names anything that could not be gathered. Cached on the project and redrawn at most every 15 minutes, only when enough scenes changed (stale says when the cached one was served anyway); refresh forces a redraw. A cold draw takes a minute or two: the call holds up to wait_sec (default 50) for it; if it is still drawing it returns status "drawing" (and the previous gist, stale, if any) and keeps drawing — call again and that call waits on the same draw. Free.

get_project_history

Project history: what changed and who did it

Described change history, newest first: each event has who (person, agent, agent run, Director), what in words, and structured per-key changes for tempo, conductor, music, mix, theme, captions, branding, voice and the rest. event_id = one event in full. Filters, paging and the legacy fallback: guide "Debugging a project". Free.

get_project_lineage

Where a project was forked from, and its forks and snapshots

The lineage of a project: its parent (the project it was forked or snapshotted from, if any) and the forks and snapshots made from it, newest first, each with id, name, kind (fork / snapshot), when, and whether it is archived. Read it before choosing which version to continue or restore. Free.

get_storyboard

Get the storyboard

The map of a project: chapters, script blocks (narration/direction), and the scenes anchored to each block, with voiceover status and durations. This is the primary orientation tool — call it before editing anything so you address real scene ids rather than guessing. Each scene carries seamIn — the cut BEFORE it: a transition (slug, length, who set it), an authored hard cut, or undecided. Scene detail (the scene source) is deliberately NOT here; use get_scene.

list_changes

List changesets

A project's change history (newest first) and its current structure_version. changesets are the batches (apply_changes, split/merge/move, undos); edits are what API and MCP callers changed outside a batch (element edits, authored compositions, transitions, cues, music, mix, tempo), one entry per call, each tagged with a domain (timeline / audio / scene / captions / script / structure / project). Every entry carries actor: the key's label and the X-Typecut-Session the caller declared, so you can tell your own work from another session's.

list_projects

List projects

List projects newest-first, with status, workspace, editor_url and render_url. Use to find the project a user is referring to by name ("the Bronze Age one") before acting on it. Returns ids you pass to every other project tool, and links you can hand straight to the user without a second call.

Status is one of: draft (created, not planned) · planning · generating · review · ready (all scenes resolved, renderable) · rendering · rendered (render_url is populated) · failed.

ls

Look at the workspace tree

Look at where work lives: workspaces, folders, projects, and inside a project its chapters and scenes. No at lists the workspaces. at is a path like tc:/development/eng-music/clock-fixes (a chapter or scene is #c2.s5) or the id of a workspace, folder or project. Returns the node, compact children with their id and path (either works as input anywhere), and notes: the short markdown notes of the folders on the way down, which say how that place is used. q searches project names under the node. Paged by cursor. since (30m, 48h, 7d, 2w or an ISO date) lists only projects edited since, newest first, across everything under at; add scenes:true and each also carries scenes_since: the scenes touched in that window, each with a one-line gist, duration and a thumbnail_url, so "what did we work on this week" is one call. Opening a project (at a project) gives every scene the same gist/duration/thumbnail. Free, read-only. Replaces browsing with list_workspaces + list_projects.

merge_from_fork

Pull a fork's changes back into its parent

Pull a fork's changes back into the project it was forked from. Scenes are matched by lineage (forked_from, or copied_from), or by a composition url that is unique on both sides, as project_diff matches them. Their composition, title and length are written into the parent scene. Narration, scenes only the fork has (copy those with copy_scenes) and scenes only the parent has are reported, not changed. Nothing is deleted. dry_run:true returns the plan and writes nothing. Free.

open_project_wizard

Open the project wizard

Show the user a form to set up a video — workspace, template, brief, length, voice and look, with the palettes visible — then price it and create it. Free to open; creating from it spends credits, and the form shows the cost against their balance before the commit button appears.

Prefer this over interrogating the user one question at a time when they want a video and have not specified much: five choices are faster to make by looking than by describing. If they have ALREADY told you what they want, just call create_project — do not make them fill in a form to repeat themselves.

Only useful in a client that renders MCP Apps. Elsewhere this returns the same options as data, and you should ask in conversation instead.

No inputs.

organize

Organize workspaces, folders and projects

Change where things live. op: mkdir {workspace_id, parent_id?, name, note?} (folders nest 3 deep) · rename {id, name} (folder or project) · note {folder_id, note} (short markdown that ls returns to anyone working in that folder: what the place is for, naming, what not to do) · mv {id, to_folder_id|null} (a project or folder; null = workspace root; inside one workspace) · dup {project_id, name?, to_folder_id?, workspace_id?} (a copy of a project, filed where you say; counts toward the plan cap) · archive {id, archived?} (project, or an empty folder) · chapter_copy / chapter_move {chapter_id, to_project_id, position?} (a whole chapter into another project WITH its narration, audio and scenes; a move archives the source after the copy is in place, nothing is hard-deleted) · restore {archive_id} (undo a chapter or scene move: the move returned archive_id) · workspace_rename / workspace_archive {workspace_id}. Folders only decide where a project is listed; contents, media and sources are untouched. dry_run:true says what would change. Find ids and paths with ls. Single scenes: copy_scenes copies them into another project by reference, with their narration and voice when every scene of a script block goes (move:true moves them: sources soft-deleted, emptied narration blocks archived, undo with restore); move_scene moves one between chapters of a project.

project_deps

What a project stands on

Read before you change a scene in a project you did not build: what it is tied to. Live, a second or two, no model. The clock (fps, tempo, music, voice); the RUNTIME and SKILLS every scene lands with; the CAST; which scenes link which shared module version (\<script data-tc-module\>), and which are BEHIND the runtime; the SOUNDS the project already uses (its own kit: reuse before adding new); a line per scene. With scene_id: that scene in depth (its modules with their API, the scenes either side, its continuity rows, its sound cues, and what to KEEP), so you call the modules instead of rewriting them inline. get_project_gist is the other read: the style of a finished piece, for making one like it. Free.

project_diff

Compare two projects scene by scene

Compare two projects scene by scene, read only: which scenes match (by id, by copy lineage, or by a shared composition, as a fork matches its parent), which changed (composition, title, length, narration), which moved chapter or position, and which are only in one project. Use it before merging work between projects or to see what another agent changed in a fork. Free; writes nothing.

reorder_chapters

Reorder chapters

Set a project's chapter order. Either pass order (EVERY chapter id exactly once, from get_storyboard) or move ONE chapter with chapter_id + position (1-based). Use it when a chapter sits in the wrong place — e.g. after the conclusion. Returns the full new order with chapter numbers.

resolve_project

Generate unresolved work

Generate everything still missing — voiceover, then scene compositions, correctly sequenced. SPENDS CREDITS. Scope it to the whole project, one chapter, or one block. Authoring the HTML yourself? Pass voice_only:true — voiceover and word timings only, the composer never runs. ALWAYS run with dry_run true first and show the user the cost before running it for real; that is the difference between a helpful agent and an expensive one. Returns immediately — poll get_project_status. voice_timing reports voiced vs target seconds; warnings says when the finished voice is more than 10% off the target length.

set_project_runtime

Declare the shared modules a project runs on

List the hosted modules (put_module) every scene of a project — or of one chapter — runs on, ONCE, instead of pinning them in every scene: {modules: ["kit3d@11", "rig:kaykit@1"]}. Each authored land then gets those pins in front of its own scripts (vendored, hash-checked and linked like a pin you wrote), so a scene carries only what differs, and moving to a new kit version is one call plus a re-land (repin_modules does the re-landing). chapter_id (a chapter id from get_project / get_storyboard) sets that chapter's own list, which ADDS to the project's there (the chapter's entry for a module wins, so a chapter can hold another version); modules: [] with chapter_id means NO shared modules in that chapter (a DOM chapter in a 3D film); modules: null with chapter_id makes the chapter inherit again, without it clears the project list. A scene that pins a module itself keeps its own version; data-tc-runtime="none" on any element opts a scene out. Applies at land: scenes landed earlier keep what they were landed with until re-landed. Returns the whole runtime. Free.

transpose_project

Transpose a project

Make a NEW project about a NEW topic on an existing project's skeleton: same chapter count and roles, word weight per chapter, block counts and scenes-per-block rhythm, theme / template / voice / music / duration (each overridable). dry_run:true returns the structure brief that will be mirrored — show it, confirm, then run. Planning is free; the new project rests at draft (poll get_project_status). Then link_transposed_references to carry the source designs over, and resolve_project (dry_run first) to generate. Exactly one of topic / script.