MCP reference

This page is built from the server's own list of tools, the same one the MCP page shows, so it cannot drift from the server. The desktop app serves them over HTTP, at the address in Settings, Model. From a clone, the server speaks MCP over stdio: run it with npm run mcp. See Using your model to connect either.

list_projects

List the projects in this studio: id, name and how many patterns each has. Start here when you do not know a project id.

Takes no parameters.

create_project

Create a project. starter: social gives it five ready patterns (Story, Post, Square, Landscape, Banner) with a headline slot each; blank gives one empty pattern.

get_project

A project's patterns, how much Yarn it has, and its brand (colours, fonts and voice).

set_project_picture

Show one of a project's images or videos (from its Yarn) on the project's card in the studio, so the person knows it at a glance. A logo or a key photo works well. Leave out yarnId to take the picture away.

list_yarn

List the files (Yarn) in a project: images, video, audio, fonts and saved copy. Filter by kind, tag or a search word. Use a Yarn name or id when filling an image slot.

import_yarn

Add a file to a project's Yarn from a public web address: an image, a video, a sound, a font (to use it in a swatch) or a text file. Or save a piece of text as reusable copy. Local files are not accepted here; ask the person to upload them in the studio.

tag_yarn

Set the tags on a piece of Yarn. Tags let a batch pick from a group, like tag:product.

rename

Rename a pattern or a piece of Yarn: give its patternId or its yarnId, and the new name. Use it to label a draft of your own, like "Draft: spring post"; only a person deletes, in the studio.

get_brand_guidelines

The brand's colours, fonts and how it writes (voice, do and do-not lists, examples). Read this before writing any copy.

propose_swatch

Propose a brand (a swatch) for the person to review: read it from the brand's website (url), give it yourself (colors, fonts, voice), or both, and what you give wins over what the site says. It is saved as a NEW swatch and never made the project's: the person looks it over in the Swatch tab and presses Use for this project. Fonts are matched to the bundled ones and to font files in the project's Yarn, so import_yarn a brand's font file first to use it. A swatch needs a primary, a text and a background colour.

list_patterns

The patterns in a project.

get_pattern

A pattern as data: every stitch, with slot names, locked or free, and coordinates as fractions of the frame. Large; prefer describe_pattern.

describe_pattern

A short text summary of a pattern: what slots it has, which are locked by the brand and which you may fill, what it says now, any animation, and the brand's voice. The cheapest way to understand a pattern.

create_pattern

Add an empty pattern to a project. Sizes: Story 1080x1920, Post 1080x1350, Square 1080x1080, Landscape 1920x1080, Banner 1456x816.

duplicate_pattern

Copy a pattern, locks and all.

fill_slots

Write into a pattern's named slots. A text slot takes text. An image or video slot takes a Yarn name or id from list_yarn, or tag:product for the first file with that tag. A slot inside a part is addressed part.slot, like lower_third.name. Locked slots are REFUSED and reported: if you are refused, tell the person, do not look for another way around it. Returns what was filled and what was refused with the reason.

Example call:

{ "projectId": "pj_sample", "patternId": "pt_launch_story",
  "slots": { "headline": "Make it knitted.", "eyebrow": "Big news" } }

Example result:

{
  "filled": ["headline"],
  "refused": [
    { "slot": "eyebrow", "why": "locked by the pattern; unlock it in the studio first" }
  ]
}

add_stitch

Add a stitch. Coordinates are fractions of the frame (0 to 1). kind: text, image, shape. Give it a slot name so it can be filled later. Text sizes in style.fontSize are fractions of the frame WIDTH (0.05 is a modest body size, 0.1 a headline).

update_stitch

Change a stitch's text, position, size, image or style. Address it by slot name.

remove_stitch

Remove a stitch. Locked stitches are refused.

set_size

Change a pattern's size. Everything is stored as fractions, so it re-lays out. Check the result with preview_pattern.

apply_batch

Apply several edit commands as ONE step, so a person can undo it as one. atomic: true applies all or nothing. Each command is {type, ...}: addStitch {stitch}, updateStitch {id, patch}, removeStitch {id}, reorder {id, toIndex}, setSize {size}, fillSlot {slot, content} (text slots only; set an image with updateStitch and a yarnId), setMeta {name, durationMs}, setMotion {stitchId, clips}, setAudio {audio}. setLocked is refused: only a person locks or unlocks.

list_parts

Reusable parts you can insert: lower thirds, quotes, price tags and the project's own. Each lists its slots.

insert_part

Put a part into a pattern. Then fill its slots with fill_slots using instance.slot.

list_presets

The animation presets available to set_motion.

Takes no parameters.

set_motion

Animate a stitch: give it clips, each {preset, startMs, endMs}. Replaces that stitch's clips. Also set the pattern's length with durationMs if the animation runs past it. Keep text on screen long enough to read (about 3 words a second).

list_voices

The voices available for voiceover, and whether the configured voice works right now.

Takes no parameters.

synthesize_voiceover

Speak lines and put them on the pattern's timeline as sound, optionally with timed captions. Returns a job id: check it with get_job. The pattern becomes a video long enough for the speech.

preview_pattern

Render the pattern and SEE it: returns a PNG. Use it after layout changes to check your own work. time is milliseconds for animated patterns.

check_pattern

Run the same quality checks Knit runs, without drawing anything: missing files, low contrast, text that will not fit, animation that is too busy. Fix errors before knitting.

knit_pattern

Make real files (PNG, JPEG, WebP or MP4) from a pattern, through the same job the studio's Knit button uses, with the same checks. params: sizes (array of {name,w,h}), format, scale (1 or 2), rows (an array of objects of slot values, one per post, to make many). A row may only fill free slots. Returns file paths and any issues, or a jobId when wait is false.

get_job

Check on a job: a knit or a voiceover.

cancel_job

Stop a running job.

list_knits

What has been knitted in a project, newest first.

Errors

A tool that cannot do its job replies with a plain message saying what happened. For example, knit_pattern explains how to install Playwright if it is missing.