MCP tool reference

Every tool of the Rigby2D MCP server with its parameters. This page is generated from the server's own tool definitions, so it always matches the version you run. For setup and the tools explained by task, see AI assistants (MCP).

Paths are relative to the first --root folder, and the server never reads or writes outside the root folders. Editing tools save the file in its own format, or a copy when output is given.

The server has 35 tools. Parameters marked required must be given; the others are optional.

#inspect_project

Summarize a Rigby2D project file: format and version, counts of bones, slots, skins, constraints, events and images, the animations with their durations, and any read warnings. Read only.

#describe_rig

List the bone hierarchy with setup-pose transforms (Y up, degrees), the slots in draw order with their attachments, and the attachments of each extra skin. Read only.

#describe_animation

Show one animation: its duration, the key times of every bone, slot, deform, IK and draw-order timeline, its events, and other timelines it holds. Read only.

#sample_pose

Evaluate the skeleton with the Rigby2D runtime: the setup pose, or an animation at a time. Returns world transforms of every bone, the visible attachment of each slot, the draw order, events up to that time and the bounds of everything drawn. Read only.

#validate_project

Check a project for problems: structure, images missing from its work file, atlas or images folder, animations without keys, whether skeleton JSON 4.3 round-trips the data exactly, and whether binary .skel export is possible. Read only.

#convert_project

Write a project as skeleton JSON (format 3.8, 4.2 or 4.3) or binary .skel (4.3). Reads .rigby, .json or .skel. Writes skeleton data only; atlas and images are not repacked. Refuses to replace an existing file unless overwrite is true.

#add_bone

Add a bone as a child of an existing bone, with its setup pose relative to the parent (x, y, rotation in degrees, length). Saves the project.

#set_bone_setup

Change a bone's setup (rest) pose relative to its parent: x, y, rotation, scaleX, scaleY, shearX, shearY (degrees for angles) and length. Only the given fields change. Saves the project.

#add_animation

Add an empty animation. Its duration grows as keys are set later. Saves the project.

#set_bone_key

Set a key on a bone in an animation (replacing a key at the same time). Values are relative to the setup pose: rotate takes value (degrees added); translate and shear take x/y (added); scale takes x/y (multiplied). curve shapes the motion to the next key. The animation grows to include the key. Saves the project.

#delete_bone_key

Delete the key of a bone channel at a time in an animation. Saves the project.

#set_attachment_key

Show an attachment in a slot from a time on in an animation (an image swap), or hide the slot's attachment with hide: true. The attachment must belong to the slot. Saves the project.

#set_event_key

Fire an event at a time in an animation (games receive it during playback). Creates the event definition if it does not exist; int, float and string override its default values. Saves the project.

#batch_edit

Apply many edits in one call, loading and saving the project once, atomically: all of them are saved, or none. Each operation is { op, ...arguments } where op is one of add_bone, set_bone_setup, add_animation, set_bone_key, delete_bone_key, set_attachment_key, set_event_key and the arguments are that tool's (without path, output and overwrite). Operations run in order, so later ones can use what earlier ones created (add_animation, then its keys). Much faster than one call per key for building animations. Curves can be presets or a custom bezier [cx1, cy1, cx2, cy2].

#set_workspace

Set the project's workspace: 'game' (for game engines; skeleton exports) or 'film' (for film and video: output settings, renders, face controls, audio). It only changes which tools the editor shows; animation data is untouched. Saves the work file.

#set_output

Set the film output: frame rate (presets: 12, 15, 23.976, 24, 25, 29.97, 30, 48, 50, 60; any rate up to 240), size in pixels, background ('transparent' or a #rrggbb color), and framing: 'auto' (fit the animation), 'fixed' (center frame_x, frame_y and frame_scale world units per pixel), or 'camera' (follow a bone named 'camera', created if missing). Only the given fields change. Saves the work file.

#save_pose

Save a pose to the pose library: the local transforms of the given bones (default: every bone) and the attachments their slots show (mouth shapes, eyes). Taken from the setup pose, or from an animation at a time. Replaces a pose with the same name only with replace: true. Saves the work file.

#apply_pose

Apply a saved pose at an amount (0 to 1; image swaps switch at 0.5). Without an animation it changes the setup pose; with one it sets keys at the time (all transform channels of the pose's bones, attachment keys for its slots). Saves the work file.

#delete_pose

Delete a pose from the pose library. Face controls that use it are deleted too. Saves the work file.

#add_face_control

Add a face control: a slider from 0 to 1 that blends from one pose ('from', default the setup pose) to another ('to'), such as brows up, eyes closed or mouth open. Saves the work file.

#set_face_control

Set a face control to a value (0 to 1). Without an animation it changes the setup pose; with one it keys the face at the time, like dragging the slider in Animate mode. Saves the work file.

#delete_face_control

Delete a face control (its poses stay in the library). Saves the work file.

#add_audio_track

Add a sound file (.wav, .mp3, .ogg, .m4a, .aac, .flac) as an audio track of an animation, starting at 'offset' seconds. The file is stored inside the work file; it plays with the timeline, drives lip-sync, and is mixed into renders. Saves the work file.

#set_audio_track

Change an audio track's start time (offset, seconds) or volume. Saves the work file.

#remove_audio_track

Remove an audio track from an animation. The sound file is removed from the work file when no other track uses it. Saves the work file.

#lip_sync

Lip-sync an animation to one of its audio tracks. With text (the words spoken) or timing_file (ElevenLabs timestamps or Whisper/word-timing JSON, Rhubarb Lip Sync .tsv/.json, Papagayo .dat), keys mouth shapes (visemes A, E, I, O, U, MBP, FV, L and rest) as image swaps on a mouth slot, each landing a little before its sound; the slot and the shape-to-image mapping are found from image names unless given. Without them, keys a face control (such as 'mouth open') from the loudness of the track instead. Reading the audio (text or loudness) needs a WAV track; a timing file does not. Saves the work file.

#rename_bone

Rename a bone. Poses that store the bone follow the new name. Saves the project.

#rename_animation

Rename an animation. Its audio tracks follow. Saves the project.

#delete_animation

Delete an animation and its audio tracks. Saves the project.

#set_slot

Change a slot's setup: the attachment it shows (or hide: true to show none) and its color (#rrggbb or #rrggbbaa). Saves the project.

#detect_parts

Preview Rigby AutoRig on layered artwork: which body part each layer is (head, torso, upperarm, forearm, hand, arm, thigh, shin, foot, leg, eye, mouth, hair, tail, ...), its side and whether that came from the layer name or its position. Nothing is saved. Use the roles and sides arguments of autorig to correct it. Read only.

#autorig

Rigby AutoRig: rig layered artwork in one step. Identifies body parts from layer names (or positions), places joints where parts meet, builds the skeleton (hip, chest, neck, head, arms, legs, face, hair, ears, tail, wings), attaches every layer to its bone, turns parts that bend across bones into weighted meshes (a single arm layer gets an elbow) and adds IK for arms and legs. From psd_file it writes a new .rigby work file to 'output'; from path it rigs an unrigged .rigby work file. The result is ordinary, editable rig data.

#map_bones

Preview how retarget_animation matches the bones of a source character to a target character: by name, similar name ("L_Arm" and "arm.l"), body part ("UpperArm_Left" and "upperarm_l") or your mapping. Lists unmatched bones. Read only.

#retarget_animation

Copy animations from one character to another (any format): bones are matched automatically (see map_bones; override with mapping), movement is scaled to the target's size (scale 'auto') and rotated into its bones' frames, curves are kept, and slot, event and IK keys follow by name. mode 'relative' (default) keeps the target's own rest pose; 'world' makes bones point the way the source's do, compensating for different rest poses. Saves the target.

#run_script

Run a Python script against a project with the Rigby2D scripting API (import rigby: bones, slots, animations, keys, selection, time; see docs/scripting.md), then save the project. The script runs in a sandbox (CPython 3.14 on Pyodide, standard library only). print() output is returned. If the script raises, nothing is saved and the traceback is returned. dry_run: true runs it without saving (for queries). 'animation' and 'time' set what rigby.current_animation() and rigby.time() return; 'selection' sets rigby.selected_bones().