Skip to main content
Glama
Sign In
UmutFarukDilli

spine-mcp

by UmutFarukDilli
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

spine_set_keyframes

Add or replace keyframes on a Spine animation timeline, creating the animation if missing. Supports bone, slot, constraint, event and drawOrder keys with customizable curves and upsert, append or replace modes.

Instructions

Add or replace keyframes of one timeline (the animation is created if missing).

Timelines and their key fields (written in the Spine 4.x JSON format):

  • rotate (bone) keys: {"time": 0, "value": 15} ("angle" is accepted too)

  • translate (bone) keys: {"time": 0, "x": 10, "y": -4}

  • scale (bone) keys: {"time": 0, "x": 1, "y": 1}

  • shear (bone) keys: {"time": 0, "x": 0, "y": 0}

  • translatex/translatey/scalex/scaley/shearx/sheary (bone) keys: {"time": 0, "value": 3}

  • inherit (bone) keys: {"time": 0, "inherit": "noScale"}

  • attachment(slot) keys: {"time": 0, "name": "eyes-closed"} (null clears)

  • rgba / rgb (slot) keys: {"time": 0, "color": "FFFFFFFF"} (RRGGBB for rgb)

  • rgba2 / rgb2 (slot) keys: {"time": 0, "light": "FFFFFFFF", "dark": "000000"}

  • alpha (slot) keys: {"time": 0, "value": 0.5}

  • event keys: {"time": 0.2, "name": "footstep", "int": 1}

  • drawOrder keys: {"time": 0, "offsets": [{"slot": "arm", "offset": 1}]}

  • ik (constraint) keys: {"time": 0, "mix": 1, "softness": 0, "bendPositive": false}

  • transform (constraint) keys: {"time": 0, "mixRotate": 1, "mixX": 0.5, ...} (mixRotate/mixX/mixY/mixScaleX/mixScaleY/mixShearY; omitted mixes keep the setup value)

  • path.position / path.spacing (constraint) keys: {"time": 0, "value": 0.25}

  • path.mix (constraint) keys: {"time": 0, "mixRotate": 1, "mixX": 1, "mixY": 1}

  • physics.inertia/strength/damping/mass/wind/gravity/mix keys: {"time": 0, "value": 30}

  • physics.reset keys: {"time": 0.5} (physics target "" = every physics constraint)

Curves: every key accepts "curve": "linear" (default), "stepped", a preset ("ease", "ease-in", "ease-out", "ease-in-out", "smooth") or [cx1, cy1, cx2, cy2] normalized to the interval up to the next key (0..1, like CSS cubic-bezier). They are converted to Spine's absolute bezier values automatically and keep their shape when keys are added later. The curve argument is the default for keys that do not specify one.

Args: target: Bone name for bone timelines, slot name for slot timelines, constraint name for ik/transform/path/physics. Ignored for event/drawOrder. mode: upsert (default: merge, new keys win at equal times), append (merge, error on equal times) or replace (the whole timeline).

Input Schema

NameRequiredDescriptionDefault
keysYes
modeNoupsert
curveNo
targetNo
projectYes
timelineYes
animationYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does a lot of it: it discloses implicit creation of the animation, the destructive scope of mode=replace, and that curves are converted to absolute bezier values and survive later key insertions. Left undisclosed are persistence/save semantics, permission or validation requirements, and what happens on invalid timeline names.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and scope are front-loaded in the first sentence, and the long bullet list is reference data an agent genuinely needs rather than prose padding. It is still bulky enough that the per-timeline key shapes could arguably live behind a doc pointer, but almost every line earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with no annotations, the description covers the risky and non-obvious parts — key formats, curve encoding, mode semantics, target resolution — and an output schema exists so return values need not be explained. The remaining gap is surroundings: identity of the project/animation/timeline arguments and save/persist behavior after the edit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does so heavily for the hard parameters: keys is documented per timeline type with concrete JSON examples, and target, mode, and curve all get precise semantics. It falls short only on project, animation, and timeline, which are never explained (presumably project and animation names), leaving the agent to infer them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource+scope: 'Add or replace keyframes of one timeline', plus the important side effect that the animation is created if missing. This clearly separates it from spine_delete_keyframes and spine_add_animation among the siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The mode argument is explained in operational terms (upsert merges with new keys winning, append errors on equal times, replace wipes the whole timeline), which gives real when-to-use guidance. What's absent is routing guidance versus sibling tools — e.g., when to create the animation with spine_add_animation first versus relying on the implicit creation here.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools