内容
# Spine 动作 MCP
用于 [Spine 2D](https://esotericsoftware.com/) 动画的 MCP 服务器 — 通过自然语言编写、预览和导出骨骼动画，支持从 Claude Code 或任何 MCP 客户端访问。
作为**本地 HTTP 服务器**运行，内置**网页仪表盘**：每个用户在其自己的机器上启动服务器，并使用自己的 Claude 账户连接 — 与 Unity MCP 相同的模式。
## 功能
- **以编程方式编写动画**，基于文档化的 [Spine JSON 格式](https://esotericsoftware.com/spine-json-format)：关键帧带有缓动预设（`easeInOut`、`overshoot`、`anticipation`等）— 自动计算贝塞尔曲线。
- **动画模板**，编码动画原理：`idle_breath`、`ui_bounce`、`hit_react`、`walk_cycle`、`attack_swing`、`celebrate`、`death`、`blink` — 参数化，然后使用 `keys_set` 进行微调。
- **渲染为 GIF** (`preview_gif`)：无头 Chrome + 官方 spine-player 渲染任何动画为动态 GIF — 代理**查看**并迭代；用户在聊天中分享。
- **与 Spine 编辑器进行往返**，通过官方 [Spine CLI](https://esotericsoftware.com/spine-command-line-interface)：编写的 JSON → `.spine` 项目艺术家可以打开；`.spine` → 运行时 JSON + 打包的图集。
- **查看结果**：仪表盘嵌入官方 Spine 网页播放器。代理可以截图预览页面（例如使用 Playwright MCP）并对其进行迭代。
- **移动性能检查**：骨骼预算、关键帧密度、变形/剪裁成本、绘制顺序变化、循环弹出。
## 要求
- Node.js ≥ 18
- 仅用于导入/导出工具：**许可的 Spine 编辑器安装**（CLI 随编辑器附带）。编写、检查和预览无需它。
- 仅用于 `preview_gif`：Chrome 系列浏览器（Chrome/Edge/Chromium；自动检测，或设置 `SPINE_MCP_CHROME`）。无需捆绑浏览器下载。
- Spine **4.2.x**（JSON 格式与版本耦合；通过 `SPINE_MCP_EDITOR_VERSION` 固定版本号。嵌入的 spine-player 固定为 4.2.x，原因相同）。
## 快速开始
```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
```
然后连接 Claude Code：
```bash
claude mcp add --transport http spine http://localhost:8734/mcp
```
在 **http://localhost:8734/** 打开仪表盘 — 服务器状态、骨骼浏览器、实时动画预览。
## 配置（环境变量）
| 变量 | 默认值 | 用途 |
|---|---|---|
| `SPINE_MCP_PORT` | `8734` | HTTP 端口（MCP 端点 + 仪表盘） |
| `SPINE_MCP_ROOT` | 当前工作目录 | 骨骼文件根目录（沙箱） |
| `SPINE_MCP_CLI` | 自动检测 | Spine 可执行文件路径 |
| `SPINE_MCP_EDITOR_VERSION` | `4.2` | 传递给 Spine CLI `--update` 的版本号 |
自动检测的 CLI 路径：macOS `/Applications/Spine.app/Contents/MacOS/Spine`，Windows `C:\Program Files\Spine\Spine.com`。
## 工具
| 工具 | 需要 Spine CLI | 用途 |
|---|---|---|
| `spine_status` | – | 健康检查、缓动和模板列表 |
| `skeleton_inspect` | – | 骨骼树、插槽、皮肤、动画 |
| `keys_set` | – | 批量关键帧，带有缓动预设 |
| `template_apply` | – | 从模板生成动画 |
| `loop_smooth` | – | 修复循环连续性弹出 |
| `skeleton_lint` | – | 移动性能和卫生检查 |
| `to_spine_project` | ✅ | 编写的 JSON → `.spine` 项目 |
| `export_runtime` | ✅ | `.spine` → 运行时 JSON + 打包的图集 |
| `preview_url` | – | 渲染动画的仪表盘 URL |
| `preview_gif` | – | 渲染动画为动态 GIF（需要 Chrome） |
## 典型代理工作流程
1. `skeleton_inspect` — 学习骨骼
2. `template_apply`（例如 `idle_breath`）— 坚实的基础
3. `preview_gif` → 查看 GIF → 直观评估运动
4. `keys_set` — 微调时间/缓动；`loop_smooth` 如果它循环
5. `skeleton_lint` — 检查移动预算
6. `to_spine_project` — 移交给艺术家，或 `export_runtime` → 游戏
## 状态
**v0.1 — 早期。** 编写/检查/预览功能正常；CLI 往返标志遵循官方文档，但仍在 Windows 上进行验证（参见 `TESTING.md`）。网格/变形编写和 PSD→骨骼引导程序在路线图中。
## 许可证
MIT。Spine 是 Esoteric Software 的产品；使用 Spine 编辑器/CLI 和运行时需要有效的 Spine 许可证。
