Spine2d Animation MCP

🚀 MCP Server for Creating SPINE2D Animations from PSD Files

This Model Context Protocol (MCP) server provides tools for creating SPINE2D animations from PSD character files using natural language descriptions.

🚀 Quick Start

✨ Features

The SPINE2D Animation MCP Server allows you to:

1. Import PSD character files
2. Automatically rig characters
3. Generate animations using natural language descriptions
4. Preview animations
5. Export animations in various formats

📦 Installation

Prerequisites

• Python 3.6+
• Required Python packages (installed automatically):
  • Flask
  • Pydantic
  • Pillow
  • PSD-Tools
  • OpenAI (for natural language processing)
  • Requests
  • Python-dotenv

Steps

1. Clone this repository.
2. Run the installation script:

./install.sh

The installation script will:

• Create necessary storage directories.
• Install Python dependencies.
• Configure MCP settings for VS Code.
• Optionally configure MCP settings for Claude Desktop.

💻 Usage Examples

Basic Usage

After installation, restart VS Code and/or Claude. Then you can use the following tools through the MCP server:

Import PSD Character

Upload and process a PSD file:

Usage: "Import my character from character.psd"

Parameters:

• file_path: Path to the PSD file

Set Up Character

Automatically rig the imported character:

Usage: "Set up rigs for my character"

Parameters:

• character_id: Character ID obtained from import_psd

Generate Animation

Create an animation based on a text description:

Usage: "Create a happy waving animation for my character"
Usage: "Make my character jump excitedly"
Usage: "Scare my character away with a blinking effect"

Parameters:

• character_id: Character ID
• description: Animation description (e.g., "waving")

Preview Animation

Get a preview of the animation:

Usage: "Show me a preview of the waving animation"

Parameters:

• character_id: Character ID
• animation_id: Animation ID

Export Animation

Export the final animation:

Usage: "Export the jumping animation as a GIF"

Parameters:

• character_id: Character ID
• animation_id: Animation ID
• format: Export format (json, png, gif)

🔧 Technical Details

Project Structure

spine2d-animation-mcp/
├── README.md             # This file
├── requirements.txt      # Python dependencies
├── install.sh            # Installation script
├── src/
│   ├── main.py           # Entry point
│   ├── server.py         # MCP server implementation
│   ├── psd_parser.py     # PSD parsing module
│   ├── animation_generator.py  # Animation generation module
│   └── spine2d_integration.py  # SPINE2D integration module
└── storage/              # Created during installation
    ├── characters/       # Imported character data
    ├── animations/       # Generated animations
    ├── rigs/             # Character rigs
    └── exports/          # Exported animations

How It Works

1. PSD Import: The server parses the PSD file, extracts layers, and organizes them into a character structure.
2. Character Rigging: The server analyzes the character structure and automatically creates bones, IK constraints, and skin attachments.
3. Animation Generation: Natural language descriptions are parsed to extract animation type, mood, and intensity. This information is then applied to animation templates.
4. Animation Preview: The server generates a GIF preview of the animation.
5. Animation Export: The server exports the animation in the requested format (JSON, PNG, or GIF).

Limitations

1. The automatic rigging system is based on layer names and structures, and may require specific naming conventions for optimal results.
2. Animation templates are predefined, so complex custom animations may require manual adjustment.
3. The natural language processing in this implementation is simplified and may not capture all nuances of complex descriptions.

Future Improvements

1. Integrate more advanced LLMs to improve natural language understanding.
2. Implement more complex automatic rigging with bone placement based on image analysis.
3. Expand the animation template library.
4. Enable real-time preview rendering.
5. Provide more export formats and options.

📚 Documentation

• Animation Creation Guide - A complete guide to creating animations from scratch using only PSD files.
• SPINE2D Integration Guide - Settings for configuring and using SPINE2D.