io.github.ODU33104/rive-mcp

Render the same artboard/animation/state-machine from two .riv files under identical conditions and composite them side by side (horizontal or vertical) into a single GIF/APNG for human review — e.g. a rig before/after an edit, or two design variants. 'A: <file>' / 'B: <file>' labels are burned into each frame by default. If the two files' animation lengths differ, the shorter one holds on its final frame once it ends. Different from riv_visual_diff: that tool computes a per-pixel numeric diff of the SAME thing rendered two ways (for regression testing); this tool is for eyeballing two DIFFERENT things playing side by side (for design review), not measuring a delta.

Search Iconify's ~200k professionally designed open-source icons and convert one directly into Rive shapes. Two modes: query-only returns matching icon names; icon+outSpec downloads the SVG and imports it (same output as riv_import_svg). Requires network access to api.iconify.design.

Render a list of jobs — each a single .riv (rivPath) or a glob of .riv files (glob) — to png/gif/apng/webm/sprites, sequentially reusing the same headless Chromium page (no parallel pages). Built for CI/scripts: call this tool repeatedly from your pipeline instead of expecting a live watch mode — none is provided, since MCP's request/response model doesn't fit a background file watcher. 'defaults' holds options shared across every job; each job's own fields override them. Every job needs a format (in the job or in defaults), or that job fails. One job's failure does not stop the batch — every job (and every file a glob expands to) gets its own success/error/outPath/durationMs entry in the returned report.

Create a working .riv animation file from scratch (no Rive editor needed) and validate it with the official runtime. Returns a rendered preview frame. For polished results (gradients, organic bezier curves, easing, springy motion), read the "rive-design-guidelines" prompt this server exposes before designing a non-trivial scene. Scene spec example: { "artboard": {"name":"Demo","width":400,"height":300}, "backgroundColor": "#1a1a2e", "shapes": [ {"id":"box","type":"rect","x":120,"y":150,"width":80,"height":80,"cornerRadius":12,"rotation":0,"opacity":1, "fill":{"color":"#e94560"},"stroke":{"color":"#fff","thickness":3}}, {"id":"ball","type":"ellipse","x":280,"y":150,"width":70,"height":70, "fill":{"gradient":{"type":"linear","stops":[{"color":"#00d9ff"},{"color":"#0066ff"}]}}}, {"id":"tri","type":"polygon","x":200,"y":100,"points":[{"x":0,"y":-40},{"x":35,"y":20},{"x":-35,"y":20}],"fill":{"color":"#ffd700"}} ], "animations": [ {"name":"spin","fps":60,"duration":60,"loop":"loop","tracks":[ {"target":"box","property":"rotation","keyframes":[{"frame":0,"value":0},{"frame":60,"value":360,"easing":"linear"}]}, {"target":"ball","property":"y","keyframes":[{"frame":0,"value":150},{"frame":30,"value":80,"easing":"ease-out"},{"frame":60,"value":150,"easing":"ease-in"}]} ]} ], "stateMachine": {"name":"SM","inputs":[{"name":"go","type":"bool"}], "states":[{"name":"spinning","animation":"spin"}], "transitions":[{"from":"entry","to":"spinning","condition":{"input":"go"}}]} } Character animation (images/groups/mesh): { "groups": [{"id":"rig","x":300,"y":200}], "images": [{"id":"chara","pngPath":"./cat.png","x":0,"y":0,"scale":0.25,"parent":"rig", "mesh":{"columns":6,"rows":6}}], "animations": [{"name":"idle","duration":240,"loop":"loop","tracks":[ {"target":"rig","property":"y","keyframes":[{"frame":0,"value":200},{"frame":120,"value":195,"easing":"ease-in-out"},{"frame":240,"value":200,"easing":"ease-in…

One-call review bundle for the render→critique→revise loop. Returns (1) a FILMSTRIP image — N frames left→right across the duration, so motion is readable as a sequence, (2) an ONION-SKIN image — all frames ghost-overlaid so every mover leaves a visible trail (use it to check trajectories and travel direction vs the artwork's facing), (3) a MOTION REPORT — net displacement/rotation vector per animated object computed from the file data, (4) objective design metrics + lint findings, and (5) a fixed 7-axis scoring checklist (incl. spatial/directional coherence). LOOK at the images, score each axis 1-5, fix anything below 4 (riv_edit / regenerate), then re-run. Iterate at least twice before delivering any non-trivial scene.

Reverse a .riv file into a riv_create scene spec (shapes with bezier vertices, solid/gradient fills incl. gradient opacity, blend modes, artboard background, groups/solos, trim paths, clipping, animations with named easings, loop modes). Paint objects are resolved by parentId, so editor-authored files (paints deferred to the stream tail) decompile correctly. Use it to study professional files as few-shot examples, or to remix them — art AND hand-tuned animation tracks — into new scenes (decompile → edit spec → riv_create; see samples/night-delivery). Object types outside the writer's coverage are counted in 'skipped', not silently dropped. Note: community/marketplace files are CC BY 4.0 — keep attribution.

Deterministically generate professional design tokens for a scene BEFORE calling riv_create: an OKLCH-harmonized palette (with WCAG contrast ratios), gradient pairs, Material-Motion-derived durations & easing roles, spacing/radius/stroke scales and a type scale. Call this first, then use ONLY the returned values in the scene spec — never invent raw hex colors or ad-hoc durations. Inputs: optional seed color, mood (calm|playful|elegant|tech|warm|natural), scheme (dark|light).

Structural diff between two .riv files: type count changes and per-object property differences.

Low-level dump of a .riv file's object stream (typeKeys, property values, hierarchy). Useful for debugging and format research. Large files return a summary unless full=true.

Modify an existing .riv (lossless roundtrip): set any property, change named text runs, delete objects (with automatic subtree + reference remapping), or edit keyframes on an existing animation (op=setKeyframes). Use riv_dump to find object indices/names. Renders a preview of the result. setKeyframes: target an animated object via index/name(+type), give 'animation' (LinearAnimation name) and 'property' (x/y/rotation/scaleX/scaleY/opacity/width/height — rotation in degrees), then 'keyframes' (array of {frame,value,easing}). 'mode': replace (default, swaps the whole track) | add (appends keyframes, creating the track if absent) | remove (deletes keyframes matching the given frame numbers; keyframes[].value/easing are ignored).

Export one .riv animation to Lottie JSON. Reports unsupported and approximated features, and indicates whether pixel comparison was available.

Extract embedded image/font/audio asset binary contents (ImageAsset/FontAsset/AudioAsset + FileAssetContents pairs) from a .riv file to disk, with the file extension inferred from magic bytes (PNG/JPEG/WEBP/TTF/OTF/WOFF/WOFF2/GIF). Externally-referenced (non-embedded) assets are skipped.

Generate ready-to-use integration code (React/Vue/Svelte/plain JS/Flutter) for a .riv file, using its real artboard, state machine and input names.

Convert an SVG file (Figma/Illustrator export, icon, illustration) into Rive bezier path shapes — the professional way to get high-quality artwork instead of drawing with primitives. Writes a scene-fragment JSON (shapes with full cubic vertices, gradients, strokes) and returns a rendered preview. Use the fragment in riv_create via "imports". Supports path/rect/circle/ellipse/polygon/polyline/line, nested transforms, style attrs, linear/radial gradients. Not imported: <text> (use texts[] with a font), <image>, filters, masks.

Extract full metadata from a .riv file: artboards, animations (duration/fps/loop), state machines and their inputs (name/type/initial value). Uses the official Rive runtime. Also decodes Data Binding (ViewModel) structure when present — ViewModel definitions and their properties, ViewModelInstances with resolved property values (including enum/nested-viewmodel/list references), enums, converters, and DataBind wiring (which target object/property each bind writes to) — via direct binary parsing (returned as `dataBinding`, omitted when the file has none).

Static diagnostic pass over a .riv file: broken/out-of-range references, oversized embedded assets, state-machine states unreachable by any transition, unconditional self-transitions (infinite-loop risk), unused state-machine inputs, keyframe easing silently discarded on a track's last keyframe, plus motion-quality rules (all-linear robotic movement, teleporting objects, missing stagger on simultaneous fade-ins, one-sided scale animation). Complements riv_dump (which shows raw structure but doesn't judge it).

Recursively find .riv files under a directory and report size and format version for each.

Convert a Lottie (bodymovin, .json) animation — the format of LottieFiles' free animation library — into a riv_create scene fragment. Unlike riv_import_svg (shapes only), this keeps the keyframed timing: position, rotation, scale and opacity with their exact bezier easing (not mapped to a named preset), shape/null/precomp layer hierarchy, solid layers, gradient fills, stroke trim-path animation, and layer in/out visibility windows. Writes a scene-fragment JSON with {groups,shapes,animations} plus a rendered preview and a coverage/warnings summary. Since the fragment includes animations (which riv_create's "imports" mechanism does not merge), splice its groups/shapes/animations arrays directly into your riv_create scene spec instead of using "imports". Supported: shape layers (path/ellipse/rect/star/polygon/fill/stroke/gradient/trim/nested groups), null layers, solid layers, one level of precomp inlining, parented layers, hold and bezier easing. Not imported (counted in coverage.skipped, not silently dropped): text layers, masks, track mattes, repeaters, merge-paths, path/gradient-position keyframe morphing (frozen to first frame + warning), time-remapped precomps, expressions.

Shrink a .riv without changing its visual output: remove unreferenced objects (dangling easing interpolators, fired-events nothing points to, empty keyframe tracks left over from prior edits) and thin redundant keyframes on strictly-linear-interpolation runs within a tolerance. Only runs where every segment is linear are touched — any run touching hold/cubic easing is left alone, so no easing gets shifted (see keyed_property.cpp semantics: a KeyFrame's interpolationType applies to the segment going INTO the next frame). Colors and id-keyframes (soloActive) are never thinned, only numeric (KeyFrameDouble) tracks. Each step is a boolean that is on by default (set it to false to skip that step), and the run is idempotent/safe to repeat. Use dryRun=true to see the removal/thinning plan without writing anything. Run riv_lint afterwards if in doubt.

Run a .riv state machine step by step: set/fire inputs, advance time, observe state transitions, and optionally capture frames. Returns a transition report.

Detect .riv features and compare optional target runtime versions with documented minimums. Report unsupported, conditional, or unverified support, and inspect the file with bundled official WASM.

Render a .riv animation (or state machine playback) to an animated PNG (APNG). Unlike GIF this supports 24-bit color plus full alpha transparency, and GitHub READMEs animate it like a regular image. Frames are rendered with a transparent background by default.

Render one frame of a .riv animation or state machine to PNG. Returns the image inline and saves it to disk.

Render a .riv animation (or state machine idle playback) to an animated GIF file for preview.

Render N evenly-spaced frames of a .riv animation/state machine into a single grid sprite sheet PNG (columns = ceil(sqrt(N))). Writes the PNG plus a JSON metadata file (cellW/cellH/cols/rows/count/fps) alongside.

Render a .riv animation (or state machine) to a real-time WebM video using canvas.captureStream() + MediaRecorder (VP9, falls back to VP8/generic webm). Default duration is one loop of the animation (2s for a bare state machine or when the animation's length can't be determined).

Repair lint findings one change at a time. Compare pixels for each candidate, skip visual changes with reasons, and validate the final result before writing. dryRun never writes.

One call: character PNG -> fully rigged .riv with cutout parts (ears/tail via polygons), 2-bone head-tilt mesh (seamless), vector eyelid blink, idle + happy animations, and a state machine with a 'happy' trigger. Returns a preview. Fine-tune afterwards with riv_edit or riv_studio.

One-time setup: copies the bundled `rive-design-guidelines` skill (the mandatory tokens → pro-asset ingestion → presets → critique workflow, asset-source registry, icon-animation recipes and craft rules) into the client's skills directory so it auto-triggers on future Rive work — .claude/skills/ in the current project (scope=project, default) or ~/.claude/skills/ for all projects (scope=user). Idempotent: re-running updates the skill to this server version's copy. Recommended on first use of this server in a new environment; clients without skill support can read the same content via the rive-design-guidelines MCP prompt instead.

Cut polygon regions out of a character PNG for parts-based rigging (cutout animation). Writes each part as <name>.png plus base.png (source with parts erased) into outDir, and returns each part's bbox for placement. Use with riv_create: images per part + groups as pivots.

Start a local web UI (Rive-editor-like 3-pane layout) for live-previewing and editing a .riv file: hierarchy tree + click/drag selection on canvas + inspector (position/size/color/text edits apply live), timeline with keyframe markers, hot reload on file change, auto-generated state machine input controls, event log, and (with scenePath) direct scene-JSON editing. The UI also has an 'Instructions for AI' box — fetch those with riv_studio_notes. Re-running riv_create/riv_edit on the watched file updates the browser instantly. Only one studio runs at a time.

Read the Studio web UI's Agent chat and reply into it. 1) READ: call with no `reply` to fetch the messages the user typed (consumes the queue; the Studio shows them as picked up). Trigger on 'check the studio notes' / 「スタジオの指示を確認して」, or after opening riv_studio when the user mentions they left notes. Act on each instruction — usually riv_edit or riv_create on the watched file, which hot-reloads the browser. 2) REPLY: after doing the work, call again with `reply` set to a short summary of what you changed (and anything you could not do). It appears as your message in the same chat. Always reply: without a reply the user cannot tell whether you acted. Both can be done in one call: pass `reply` together with the read to answer and pick up anything new at the same time.

Find the rectangles, text runs and images in a UI screenshot or design comp. Returns a nested element tree with rects, corner radii and fill colours, plus a numbered overlay PNG. Coordinates are in source pixels (accurate to about 1-2 px); corner radii to about 1 px. Each element carries renderMode ("vector-panel" | "raster" — how it would be reconstructed; flat fills are test-rendered and turned into crops when more than 2% of their visible pixels would differ, the measured share is returned as renderRisk) and semanticHint ("panel" | "text" | "image" | "line" — what it looks like) as independent fields. Next, give each element a role and pass the result to riv_ui_prototype. This is geometry only: it does not know a button from a card. If you have the vector source, pass svgPath instead of imagePath: nothing is estimated, the element tree is the SVG's own group nesting, non-rectangular artwork comes through as "vector-shape" with its real bezier vertices, <text> becomes "vector-text" (editable Rive text — the bundled Inter is substituted unless you pass fonts, and a run whose glyphs are missing is baked as a picture instead, always with a warning), embedded <image> data comes through as its own pixels, and Figma layer names arrive as roleHint.

Take the elements from riv_ui_detect, assign each one a role, and get back a working .riv: every element becomes a shape or an image asset, each gets an entrance appropriate to its role, and buttons and cards get hover and press states. Roles: background, nav, header, card, panel, button, fab, text, icon, image, chart, list-item, badge, divider, avatar, input. Elements you leave unassigned animate as a generic panel. Pass exactly one of imagePath, svgPath or figmaUrl, the same one you gave riv_ui_detect. If you changed minArea or maxElements there, pass the same values here so the ids match. With svgPath no screenshot is embedded, every element stays editable, and the file reproduces the SVG; its <text> becomes real Rive text you can re-type at runtime, and its embedded <image> data becomes an image asset. figmaUrl fetches the same thing straight from Figma, and needs FIGMA_TOKEN.

Render the same artboard/animation/time from two .riv files under identical conditions (forced to the same output size) and compute a thresholded per-pixel visual diff. Returns match rate, differing pixel count, and a diff visualization PNG (differing pixels in red, matching pixels dimmed).