pantin

This page is docs/mcp.md of the repository, as it is on main.

Pantin for an agent: pantin mcp

pantin mcp serves pantin projects by the Model Context Protocol on stdin and stdout. An agent (Claude Code, Claude Desktop, or any client of the protocol) opens a project or makes one, draws its images, rigs and animates it, sees it drawn, undoes and saves, through the same commands and the same history as the application: what the application refuses, the server refuses, and the project is left as it was. It is enough to make a character with no other tool and no script.

The server runs on the machine of the person who starts it and reaches nothing else: no port is opened. A folder that is not there is a new, empty project, written there when it is saved. Nothing is written before save, except the SVG files write_svg writes.

Connecting Claude Code

Claude Code started at the root of the repository finds the server in .mcp.json and asks once whether to use it. The server is then cargo run --release -p pantin-cli -- mcp, with no project: the agent opens one with open. The first start builds the command line, which takes a few minutes: build it once beforehand (cargo build --release -p pantin-cli) so that the start is quick. The tools of a server are read when a session starts: a session that was running when .mcp.json came does not have them.

Elsewhere, add the server by hand, with or without a project to open first:

cargo build --release -p pantin-cli
claude mcp add pantin -- "$PWD/target/release/pantin" mcp
claude mcp add pantin -- "$PWD/target/release/pantin" mcp "$PWD/examples/robot.pantin"

Any other client is given the same command, on stdio.

The tools

Tool What it does
open Opens the project of a folder, or makes a new one there. Refused over changes that are not saved, unless discard.
describe The whole project as JSON: bones with their setup pose, what they inherit and where they are in the world; slots in the drawing order, with their colour and where each image is on its bone; constraints, springs, animations; whether it changed since it was saved; what undo and redo would do.
describe_animation One animation key by key: the keys of each bone and slot with their curves, and its events.
check What is wrong: images that cannot be read, keys that name an attachment a slot does not have, a rig that cannot be posed.
see A PNG image of the setup pose, or of a time of an animation; bones: true draws the bones over the images.
see_sheet Frames of an animation from its start to its end, in rows, in one PNG image.
add_bone, set_bone, remove_bone, duplicate_bone A bone, under another one or as a root; its setup pose (with its shear), name, parent and what it inherits; taking it away with the bones under it; and a copy of it with its branch, beside it.
write_svg Writes an SVG document in the folder of the project and says its size; one that cannot be drawn is refused.
place_image A PNG or SVG image on a bone, in a slot of its own, where it is said on the bone and at the size it is said.
add_attachment Another image for a slot: an attachment a key of the slot shows, or, in another skin (made when it is not there), the one that skin shows in place of the attachment of the same name.
make_mesh Makes the image of a slot a mesh that looks the same, a grid of cells, each vertex given to the bones near it so that it bends. describe gives where its vertices are.
link_mesh Makes an image of a slot bend as the mesh another slot shows (its vertices, triangles and weights, with its own image), sharing its keys of vertices by default; unlink gives it a copy of its own. describe gives bends_as.
key_deform Keys the vertices of the mesh of a slot at a time: how far each one is moved from where its bones put it.
add_path, add_path_constraint, set_path_constraint, key_path A path on a bone, smooth through its points unless their handles are given; a chain of bones laid along it, its position as a share or a length, its spacing by lengths, shares or proportions, its bones turned by chain, tangent or chain and scale; where along it they are, keyed in an animation.
set_image Moves, turns, sizes an image on its bone, gives it another file, or frames to step through as a flipbook.
add_mask, set_mask A mask on a bone, in a slot of its own behind the others: a polygon that hides what the slots drawn after it show outside it, up to the slot it names.
add_point, set_point A point on a bone, in a slot of its own: a place and a direction a game reads; moving and turning it.
set_slot, remove_slot The colour of a slot, its dark colour, its blend mode (normal, additive, multiply, screen) and its place in the drawing order; taking it away.
add_animation, set_animation, remove_animation An animation with no key; its name, duration and whether it loops; taking it away.
key_bone Keys of a bone at a time: rotation, translation, scale, shear, relative to the setup pose, with the curve to the next key; or a flip (flip_x, flip_y), the bone turned over until its next flip key.
set_keys All the keys of one kind of a bone at once, each with its curve.
remove_keys The keys of a bone at a time, or all of them.
key_slot The colour of a slot, its dark colour, the attachment it shows, or how the frames of its image play, at a time.
set_events The events of an animation, each with its values and maybe a sound: a file of the project, its volume and its balance, which a game plays (pantin plays none).
set_offset Overlap without physics: the bones of a chain each a step after the one before; applied into the keys, or taken away.
set_draw_order The keys of the draw order of an animation: at each, slots in the order they are drawn, those not named after them.
set_markers The markers of an animation: notes of the animator at times of it, which a game is not told.
add_ik, set_ik, remove_ik A constraint on one bone or two that reach for a target; its target, bend and mix, its softness, whether it stretches or compresses to reach, and what the width of its bones does then.
add_transform, set_transform, remove_transform Bones that follow a target bone: its rotation, position, scale and shear, each by a mix; the offset, by default the one that keeps the bone where it is; in the world or in local space, relative, and numbers driven by others with a factor, an offset and limits.
set_solve_order, switch_constraint, duplicate_constraint, copy_constraint_settings, constraint_bone Constraints of any kind as a whole: the order they are solved in, one switched off (kept, not solved), a copy with its keys, the settings of one given to another of its kind, a bone added or taken out. describe gives solve_order and off.
set_skins The skins that have a bone or a constraint: it is there only while one of them is shown (see and see_sheet take a skin). describe gives the skins of a bone and skins_of_constraints.
set_folder, remove_folder Folders that group pieces of one bone, or constraints, in the tree; describe gives folders.
add_slider, set_slider, remove_slider, key_slider An animation held at a time, which poses the character: its time and mix, keyed in another animation, or given by a number of a bone.
key_spring The numbers of the spring of a bone at a time: stiffness, damping, gravity, inertias, mass and mix.
key_ik An IK constraint at a time: its mix and softness, and its bend, stretch and compression, which hold until the next key.
key_transform The mixes of a transform constraint at a time.
set_spring A spring on a bone, its stiffness and damping, the share of gravity it feels, its inertia, its mass and its mix, or none.
set_gravity The gravity of the skeleton, which its springs feel.
rename_project The name of the project, which its exports take.
set_guides The guides of the canvas, which drags snap to in the editor.
add_box, set_box, remove_box The boxes a game tests (hit.json): a polygon or a rectangle on a bone, its kind (hit, hurt, push), numbers for the game, active always or on ranges of animations. describe lists them.
boxes_at The boxes active at a time of an animation, each with its corners in the world.
clean_up_animations Takes out of every animation the keys that change nothing (a key with the value of its neighbours, a lone key at the setup pose, the timelines left empty), the ends of a loop kept; one change, nothing moves.
mirror_pose Mirrors the pose of an animation at a time: each bone whose name says a side (arm_left, LeftHand, leg.L…) takes the pose of the one of the other side, as keys; the pairs of the bones given, or all.
split_bone Cuts a bone in two at a point along it (its middle by default): the part past the cut becomes its child with the children, pieces and mesh weights that lie past it; nothing moves; refused for a bone that IK or a path lays out by its length.
weigh_mesh Works out the weights of a mesh at once: bind (by the bones near each vertex), smooth, prune (under, most), weld; the bones of locked keep their shares; one change.
merge_skin Adds to a skin every image of another that it has not, as one change; those both have stay and are said.
add_parameter, set_state, set_transition, remove_from_graph The graph of states (flow.json): parameters a game sets (number, switch, trigger), states that play animations (placed on the canvas of Flow by at), transitions from a state or from any (*) that wait for conditions on the parameters, the end of the animation, an event or the edge of a box. describe gives it, the transitions with their identifiers.
play_graph The graph played from its entry as a game would, step after step (set, fire, let time pass): the states entered, the events and the edges of boxes, each at its time.
undo, redo The history of the project: each tool that changes something is one undo.
save Writes the project in its folder.

A curve is linear, stepped, ease, ease_in, ease_out, or the control points of a Bézier curve, [x1, y1, x2, y2]. A colour is three or four numbers from 0 to 1.

An argument a tool does not take is refused, with the names it takes, and nothing changes: a misspelt argument is never ignored.

Bones are named by their name or by their identifier, animations by their name. y points up and angles are in degrees, counter-clockwise, as everywhere in Pantin.

The tools are a layer over pantin-project, in the crate pantin-mcp, which has no transport of its own: the same server can later run inside the application, where the changes of an agent would be seen at once and undone with the others.

Made with these tools alone

examples/dominoes.pantin was made by Claude through this server and nothing else: a man seen in profile from the waist up, whose arm reaches by a constraint and whose hand has a bone for each joint of each finger, pushes the first of eight dominoes with his index, and they fall one on the next. Its images are SVG documents the agent wrote with write_svg. The angles of the dominoes come from a simulation, tools/dominoes_physics.py, whose numbers were given to set_keys and key_slot: each domino turns on its front edge under gravity, tips past its balance, strikes the next with its top corner and then leans on it, and the chain behind weighs on the one that leads.

The dominoes falling, rendered by pantin render