SPINE2D Animation MCP Server

spine2d-mcp

一个 MCP 服务，可将分层 PSD 角色转换为 Spine 4.2 项目——骨架 JSON、纹理图集和图集页面 PNG 文件，可直接导入 Spine 编辑器和 Unity。

目标是将角色绑定和导入的手动工作从数天缩短到大约一小时。

状态

阶段 0（概念验证）： PSD → 正确且可导入的绑定（暂不包含动画）。

该流程已实现，并通过合成测试素材进行了测试。它尚未在 Spine 编辑器／Unity 中使用真实 PSD 进行验证——这是下一个里程碑。动画生成、无头预览和 Unity 导出计划在后续阶段实现。

当前功能

给定一个图层以身体部位命名的 PSD（head、body/torso、arm_left、hand_right、leg_left、foot_right 等），import_psd_to_spine 工具会生成：

• <name>.json — Spine 4.2 骨架（骨骼、插槽、默认皮肤、区域附件）
• <name>.atlas — libgdx/Spine 纹理图集
• <name>.png — 打包后的图集页面

主要特性：

• 多段骨架（root → hip → torso → chest → neck → head，四肢连接到 chest，腿连接到 hip）；缺失的中间骨骼会作为已定位的虚拟骨骼创建。
• 关节位置准确的轴心点 — 每根骨骼都以其部位的关节边缘（或显式的 <part>[pivot] 标记图层）为轴心点，而非以图像中心为轴心点，因此旋转动作符合人体结构。
• 保留 PSD 绘制顺序作为 Spine 插槽顺序。
• 根据 Spine 4.2 读取器强制执行的不变量，对骨架进行结构验证。

格式的权威来源：reference/SkeletonJson.java（spine-runtimes 4.2）。

要求

• Python 3.11+
• uv

设置

uv sync

运行测试

uv run pytest

运行 MCP 服务

uv run spine2d-mcp

这会启动一个 stdio MCP 服务，并提供一个工具：

import_psd_to_spine(psd_path: str, out_dir: str | None = None)
  -> { project_path, atlas_path, png_paths }

将 MCP 客户端（例如 Claude Desktop / Claude Code）指向此服务，然后让它按路径导入 PSD。

项目结构

src/spine2d_mcp/
  server.py          FastMCP server + import_psd_to_spine tool
  pipeline.py        PSD -> Spine project orchestration
  psd/parser.py      PSD -> flat layer list (+ pivot markers)
  psd/conventions.py bone hierarchy, joint sides, [pivot] tag
  spine/schema.py    Pydantic models for Spine 4.2 JSON
  spine/builder.py   layers -> SpineProject
  spine/writer.py    SpineProject -> JSON
  spine/validator.py structural validation
  atlas/packer.py    rectpack bin packing
  atlas/writer.py    .atlas text + composite PNG
reference/           SkeletonJson.java, spineboy.atlas (format references)
tests/               pytest suite (synthetic PSD fixtures)

许可证

本项目根据 MIT 许可证发布。

您可以使用、复制、修改、合并、发布、分发、再许可和销售本软件的副本，但前提是软件的大部分内容均包含原始版权声明和许可证文本。

本软件按“原样”提供，不附带任何形式的保证。完整许可证文本请参见 LICENSE。