add_element

Append a single element to an existing project — a TWEAK, e.g. dropping in one more caption or shape. By default it is added at the top level; pass parent_id to add it INTO a group (nested). The element is any valid schema element: video, image, text, shape, audio, group, caption, or particles. To create a composition or add several elements at once, build the JSON and use set_project instead. The new element is validated as part of the project as a whole before being added. Call get_schema(element_type) for the exact per-type fields; unrecognized keys are flagged.

Argument	Type	Description
element*	object	A Clipkit element object. Must include `type`.
parent_id	string	Optional id of a group to add this element INTO (nested). Omit to add at the top level.
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "element"
  ],
  "properties": {
    "element": {
      "type": "object",
      "description": "A Clipkit element object. Must include `type`.",
      "additionalProperties": {}
    },
    "parent_id": {
      "type": "string",
      "minLength": 1,
      "description": "Optional id of a group to add this element INTO (nested). Omit to add at the top level."
    },
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

create_project

Create a new, blank Clipkit project with the given dimensions and duration, and return its project_id. Defaults: 1920×1080, 10 seconds, 30 fps, output_format "mp4". Call this first when starting a new video. Pass an existing project_id to reset that project to blank; omit it to start a fresh project (note the returned id for subsequent tools).

Argument	Type	Description
width	integer	Composition width in pixels. Default 1920.
height	integer	Composition height in pixels. Default 1080.
duration	number	Composition duration in seconds. Default 10.
frame_rate	number	Frame rate. Default 30.
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)
output_dither	any	Anti-banding output dither — DEFAULT ON, leave unset. Pass false for byte-exact undithered output, or { amplitude, pattern } to tune. Stops gradients / soft shadows / blur from showing 8-bit banding; deterministic.
output_format	string	Output container/codec. Default "mp4".

create_promo

Assemble a designed-looking promo/intro/product/data video from the Clipkit pattern library: give an ordered list of SCENES and the words, and it bakes in the camera, glass, lighting, motion blur, timing, and layout, then returns an editor link. This is a FAST option when a conventional promo structure fits — it is NOT the only way to make a video and NOT a default; for anything specific or original, author the JSON yourself and call set_project (the full creative range). When you do use this, MIX scene types to fit the brief and vary the structure — a video can be a single kinetic headline, three title cards, a showcase montage, or a data explainer; you do NOT need a hero or a cta. Scene types: hero (glass-orb logo reveal: wordmark, tagline?), kinetic (letter-fly headline: text, subtitle?), showcase (a screenshot tilted in 3D: screenshot URL), title (full-frame title card: headline, kicker?, subtitle?), cta (closing card with a glass button: wordmark, tagline?, cta), stats (hero numbers: stats[{label,current,previous?}], title?), bars (bar chart: bars[{label,value,previous?}], title?), ranking (top-N list: items[{label,value}], title?), pie (pie cards: cards[{label,value,total,previous?}], title?). The data scenes (stats/bars/ranking/pie) look best with theme "mux".

destructive

Argument	Type	Description
theme	string	Visual theme. Default "cinematic" (dark, serif, premium).
width	integer	Default 1920.
height	integer	Default 1080.
scenes*	array	Ordered scenes; mix types to fit the brief — you do NOT need hero/cta. e.g. a single [{type:"kinetic",text:"…"}], a sequence [{type:"title",headline:"…"},{type:"showcase",screenshot:"…"},{type:"title",headline:"…"}], or a data piece [{type:"ranking",title:"…",items:[…]}]

delete_element

Delete the element with the given id, anywhere in the tree (including one nested inside a group or its mask) — a tweak to an existing composition. (The project must keep at least one top-level element.)

destructive

Argument	Type	Description
id*	string	The id of the element to delete.
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The id of the element to delete."
    },
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

describe_project

Return a compact, human-readable summary of the current project — dimensions, fps, duration, an element breakdown by type, a per-track timeline (paint order low→high), and render-time warnings. Much cheaper to read than get_project's full JSON; use it to orient yourself or sanity-check structure without dumping the whole source.

read-only

Argument	Type	Description
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

edit_element

Change fields on the element with the given id by merging in a partial element — only the keys you include change. The id may be any element ANYWHERE in the tree, including one nested inside a group (or its mask). Pass a whole nested value (e.g. a new `keyframe_animations` array) to replace that key; set a key to null to remove it. This is for TWEAKING an existing composition. To create a composition or change many elements at once, edit the JSON and call set_project instead. The result is re-validated before being accepted.

Argument	Type	Description
id*	string	The id of the element to edit.
patch*	object	Partial element: the fields to change. Omitted keys are left as-is; a key set to null is removed.
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "id",
    "patch"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The id of the element to edit."
    },
    "patch": {
      "type": "object",
      "description": "Partial element: the fields to change. Omitted keys are left as-is; a key set to null is removed.",
      "additionalProperties": {}
    },
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

get_project

Return the full current Clipkit source as JSON. Use this to inspect the project, pass it to a render pipeline, or compose follow-up edits.

read-only

Argument	Type	Description
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

get_schema

Return the authoritative JSON Schema for a Clipkit Source — exact field names, types, and enums, generated from the protocol. Call with no argument for the full Source schema, or with element_type (e.g. "text", "shape", "particles") for just that element's fields (much smaller). Use this when authoring with set_project / add_element so you never guess a field.

read-only

Argument	Type	Description
element_type	string	Limit to one element type's fields (e.g. "text"). Omit for the full Source schema (large).

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "element_type": {
      "enum": [
        "video",
        "image",
        "text",
        "shape",
        "audio",
        "group",
        "caption",
        "particles"
      ],
      "type": "string",
      "description": "Limit to one element type's fields (e.g. \"text\"). Omit for the full Source schema (large)."
    }
  },
  "additionalProperties": false
}

ingest_asset

Fetch a remote media URL (image/video/audio) and HOST it on Clipkit, returning a stable asset_url to put in an element's `url`. Use this so the project's media survives — the original link may rot, be private, or block hotlinking. Anonymous projects allow up to 5 hosted assets / 100 MB total / 50 MB per file; when the limit is hit, tell the user to open the project (open_in_editor) and sign in to add more. Requires project_id.

Argument	Type	Description
url*	string	A public http(s) URL to an image, video, or audio file.
filename	string	Optional display name for the asset.
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "A public http(s) URL to an image, video, or audio file."
    },
    "filename": {
      "type": "string",
      "description": "Optional display name for the asset."
    },
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

load_project

Import a previously shared project as the current project, by its share id or its editor URL (e.g. https://clipkit.dev/editor?id=…), returning its project_id. Use this to continue working on a project the user opened in the editor or shared earlier — the round-trip for open_in_editor. Pass an existing project_id to load into that project; omit it to load into a new one.

destructive

Argument	Type	Description
id_or_url*	string	A share id, or a clipkit.dev/editor?id=… URL.
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "id_or_url"
  ],
  "properties": {
    "id_or_url": {
      "type": "string",
      "minLength": 1,
      "description": "A share id, or a clipkit.dev/editor?id=… URL."
    },
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

open_in_editor

Validate the current project and create a link that opens it in the Clipkit web editor, where the user can preview and refine it. This shares the PROJECT (nothing is rendered — that's render_video). Use after composing or editing. Returns a URL.

Argument	Type	Description
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

preview_still

Render a single frame of the current project to a PNG and return it as an image you can look at. This is how you check your work — in chat there is no other way to see what a composition actually looks like. Use it liberally: after composing, after edits, and at different times to inspect motion. Stills are FREE (credits are only spent by render_video). Pass `time` (seconds) to choose the frame; defaults to 0.

read-only

Argument	Type	Description
time	number	Composition time in seconds to capture. Default 0 (first frame).
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "time": {
      "type": "number",
      "minimum": 0,
      "description": "Composition time in seconds to capture. Default 0 (first frame)."
    },
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

read_docs

Return a canonical Clipkit doc as text. topic "card" = the ~8KB compact authoring card — the recommended context for authoring; "pattern-lighting" = the shine/neon/glow technique rigs; "pattern-data-viz" / "pattern-cinematic-ui" / "pattern-ui-screencast" / "pattern-promo-teaser" = ~4-5KB pattern cards (proven idioms: count-ups and bar rows; product hero shots with camera rigs; faked app UI with typing/cursor/clicks) — load ONE alongside the card when the brief matches its archetype; "agents" = the full authoring guide (fetch only when the card doesn't cover a need); "protocol" = the formal field spec; "brand" = brand reference. (Same docs offered as MCP resources, exposed as a tool so you can read them directly — resources are not always model-readable.)

read-only

Argument	Type	Description
topic	string	Which doc. Default "agents".

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "topic": {
      "enum": [
        "agents",
        "protocol",
        "brand",
        "card",
        "pattern-data-viz",
        "pattern-cinematic-ui",
        "pattern-ui-screencast",
        "pattern-lighting",
        "pattern-promo-teaser"
      ],
      "type": "string",
      "description": "Which doc. Default \"agents\"."
    }
  },
  "additionalProperties": false
}

set_project

Replace the entire project with the given source JSON, returning its project_id. This is the PRIMARY way to build: use it to create a composition or to add/change many elements at once. (To tweak a single element in an existing project, use edit_element / add_element / delete_element instead.) REVISION RULE: if you are iterating on a video that already exists in this conversation — the user asked for changes, you are fixing your own work — you MUST pass its project_id so the project is updated in place and keeps one editor link and its version history. Omitting project_id creates a NEW, unrelated project and strands the old one; only omit for a genuinely different video. The input is validated against the @clipkit/protocol before being accepted; invalid inputs return an error. Shape: { width, height, duration, frame_rate, output_format, background_color?, defaults? (house easing, e.g. a spring), fonts?, camera?, lights?, elements:[…] }; every element has a `type` plus base fields (id, layer, x, y, width, height, time, duration, opacity, rotation, animations, keyframe_animations) and type-specific fields. CKP/1.1: keyframe easings accept a spring object {type:"spring", duration?, bounce?}; channels take stagger {each, from, ease, split, seed} to spread across text units / set copies / group children; groups take layout {direction, gap, align} (stack — no hand-computed positions); text takes a count-up {expr, format}. For exact field names + types call get_schema (optionally with an element_type) — the runtime ignores unrecognized keys, and this tool flags any it does not recognize.

destructive

Argument	Type	Description
source*	object	A full Clipkit source object.
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

validate_project

Run the @clipkit/protocol validator against the current project AND surface render-time warnings even when the JSON is valid — things that pass the schema but the runtime will silently drop or clip: emoji / non-ASCII text (the runtime font atlas is ASCII-only), elements that run past the composition end, a missing top-level duration. Run it before you share or render the project. For a fuller timeline read-back, use describe_project.

read-only

Argument	Type	Description
project_id	string	Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Which project to act on — the id returned by create_project / set_project / create_promo / load_project. ALWAYS pass it once a project exists in this conversation; omitting it on a build tool creates a brand-new project. (Omit only on the local stdio server working a single project.)"
    }
  },
  "additionalProperties": false
}

Clipkit

Try it

add_element

Clipkit

Try it

add_element

Tools (15)