SPINE2D Animation MCP Server

spine2d-mcp

レイヤー構造のPSDキャラクターを、Spine 4.2プロジェクト（スケルトンJSON、テクスチャアトラス、アトラスページPNG）に変換するMCPサーバーです。SpineエディターやUnityにインポートできる形式で出力します。

キャラクターのリギングとインポートにかかる手作業を、数日からおよそ1時間に短縮することを目指しています。

ステータス

フェーズ0（概念実証）： PSD → 正しくインポートできるリグ（アニメーションはまだありません）。

パイプラインは実装済みで、合成フィクスチャを使ったテストも行っています。SpineエディターやUnityで実際のPSDを検証する作業はまだで、次のマイルストーンとなります。アニメーション生成、ヘッドレスプレビュー、Unityへのエクスポートは後続フェーズで予定しています。

現在できること

ボディパーツ（head、body／torso、arm_left、hand_right、leg_left、foot_right、…）の名前が付いたレイヤーを持つPSDを入力すると、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のもとで公開されています。

ソフトウェアの実質的な部分とともに、元の著作権表示およびライセンステキストを含めることを条件として、ソフトウェアの使用、複製、変更、結合、公開、配布、サブライセンス、および販売を行うことができます。

ソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません。ライセンスの全文はLICENSEをご覧ください。