# Spine Motion MCP

MCP server for [Spine 2D](https://esotericsoftware.com/) animation — author, preview
and export skeletal animations via natural language, from Claude Code or any MCP client.

Runs as a **local HTTP server** with a built-in **web dashboard**: each user starts the
server on their own machine and connects with their own Claude account — same model as
Unity MCP.

## What it does

- **Author animations programmatically** on the documented [Spine JSON format](https://esotericsoftware.com/spine-json-format):
  keyframes with easing presets (`easeInOut`, `overshoot`, `anticipation`, …) — bezier
  handles are computed for you.
- **Animation templates** that encode animation principles: `idle_breath`, `ui_bounce`,
  `hit_react`, `walk_cycle`, `attack_swing`, `celebrate`, `death`, `blink` — parametric,
  then refine with `keys_set`.
- **Render to GIF** (`preview_gif`): headless Chrome + the official spine-player render
  any animation to an animated GIF — the agent *looks at it* and iterates; humans share
  it in chat.
- **Round-trip with the Spine editor** via the official [Spine CLI](https://esotericsoftware.com/spine-command-line-interface):
  authored JSON → `.spine` project artists can open; `.spine` → runtime JSON + packed atlas.
- **See the result**: the dashboard embeds the official Spine web player. An agent can
  screenshot the preview page (e.g. with Playwright MCP) and iterate on what it sees.
- **Mobile performance lint**: bone budgets, key density, deform/clipping cost,
  draw-order churn, loop pops.

## Requirements

- Node.js ≥ 18
- For import/export tools only: a **licensed Spine editor install** (the CLI ships with
  the editor). Authoring, lint and preview work without it.
- For `preview_gif` only: a Chrome-family browser (Chrome/Edge/Chromium; auto-detected,
  or set `SPINE_MCP_CHROME`). No bundled browser download.
- Spine **4.2.x** (JSON format is version-coupled; pin via `SPINE_MCP_EDITOR_VERSION`.
  The embedded spine-player is pinned to 4.2.x for the same reason).

## Quick start

```bash
git clone https://github.com/nihatcagri44/spine-motion-mcp.git
cd spine-motion-mcp
npm install
npm run build
SPINE_MCP_ROOT=/path/to/your/spine/assets npm start
```

Then connect Claude Code:

```bash
claude mcp add --transport http spine http://localhost:8734/mcp
```

Open the dashboard at **http://localhost:8734/** — server status, skeleton browser,
live animation preview.

## Configuration (env vars)

| Variable | Default | Purpose |
|---|---|---|
| `SPINE_MCP_PORT` | `8734` | HTTP port (MCP endpoint + dashboard) |
| `SPINE_MCP_ROOT` | cwd | Root directory for skeleton files (sandbox) |
| `SPINE_MCP_CLI` | auto-detect | Path to the Spine executable |
| `SPINE_MCP_EDITOR_VERSION` | `4.2` | Version passed to Spine CLI `--update` |

Auto-detected CLI paths: macOS `/Applications/Spine.app/Contents/MacOS/Spine`,
Windows `C:\Program Files\Spine\Spine.com`.

## Tools

| Tool | Needs Spine CLI | Purpose |
|---|---|---|
| `spine_status` | – | Health check, easings & templates list |
| `skeleton_inspect` | – | Bone tree, slots, skins, animations |
| `keys_set` | – | Batch keyframes with easing presets |
| `template_apply` | – | Generate an animation from a template |
| `loop_smooth` | – | Fix loop continuity pops |
| `skeleton_lint` | – | Mobile perf & hygiene checks |
| `to_spine_project` | ✅ | Authored JSON → `.spine` project |
| `export_runtime` | ✅ | `.spine` → runtime JSON + packed atlas |
| `preview_url` | – | Dashboard URL rendering the animation |
| `preview_gif` | – | Render an animation to an animated GIF (needs Chrome) |

## Typical agent workflow

1. `skeleton_inspect` — learn the rig
2. `template_apply` (e.g. `idle_breath`) — solid base
3. `preview_gif` → look at the GIF → evaluate motion visually
4. `keys_set` — refine timing/easing; `loop_smooth` if it loops
5. `skeleton_lint` — check mobile budgets
6. `to_spine_project` — hand off to an artist, or `export_runtime` → game

## Status

**v0.1 — early.** Authoring/lint/preview are functional; CLI round-trip flags follow
the official docs but are still being validated on Windows (see `TESTING.md`).
Mesh/deform authoring and PSD→rig bootstrap are on the roadmap.

## License

MIT. Spine is a product of Esoteric Software; using the Spine editor/CLI and runtimes
requires a valid Spine license.