SkinForge MCP 🎨🔨

Autonomous Model Context Protocol (MCP) Server & Procedural Engine for Minecraft Skins.

SkinForge is an all-in-one professional toolkit designed for both human skin artists and autonomous AI/LLM coding agents (Antigravity, Gemini, Claude, GPT-4o, Cursor, Kilo) to create, sample, inspect, edit, audit, and visually verify Minecraft skins with true 3D dual-layer depth — without requiring ad-hoc Python scripts.

🌟 Key Features

1. 45 Native MCP Tools for AI Agents

• Model Context Protocol (MCP) v3: Enables LLMs to design, recolor, audit, and verify skins directly over stdio.

• Full Skin Assembly & VLM Fine-Tuning (skin_build): Assembles complete 64×64 dual-layer skins in a single atomic call using a global palette and ASCII matrices (~1,200 tokens vs 20,000 for raw pixels), purpose-built for Vision-Language model fine-tuning.

• Direct Reference Sampling (skin_sample_reference): Samples exact colors or extracts dominant palettes from concept art (reference.jpeg) and screenshots without writing Python scripts.

• Multimodal Visual Feedback (skin_render_3d, skin_render_2d): Generates and returns base64 PNG turnaround images directly inside tool results for autonomous visual verification.

2. Real-Time 3D WebGL Viewer with Live Sync (viewer.py)

• Interactive Three.js Player: Orbit rotate (Left Click drag), pan (Right Click drag), zoom (Scroll), and preview walk/run animations.

• Instant Reactive Updates (300ms): The moment an AI agent or developer calls an editing tool, the 3D model in the browser automatically updates its texture with zero lag, preserving camera angles and animation state.

• Live Status Indicator: Header dot pulses violet when updates arrive and returns to emerald green.

3. Dual-Layer 3D Depth Discipline (The 4 Golden Rules)

• Rule 1 (Zero Holes): Strictly enforces 100% opacity on all 36 Base Layer parts (prevents the hollow black skull/torso bug).

• Rule 2 (+0.35 Relief): Restricts Layer 2 exclusively to 3D relief accents (bangs, hood rims, cuffs, pockets, emblems).

• Rule 3 (No Floating Profile Cardboard): hat_front rows 4–7 are kept transparent to prevent detached cardboard planes in 90° profile view.

• Rule 4 (No Floating Crown Planks): hat_top is either solid or transparent, eliminating single detached hovering stripes.

• Autonomous Self-Healing (skin_auto_fix): One-click autonomous healing that plugs holes and strips illegal floating planes.

4. Vectorized HSL / HSV Color Engine

• Pure-NumPy color manipulation running in < 1 millisecond.

• Rotate hue, boost saturation, or adjust brightness across specific parts or the entire skin with optional target color filtering (skin_adjust_hsv, skin_shift_hue).

5. 3D Seam Continuity Auditor & Edge Healer

• 3D Edge Connectivity Matrix: Scans cube fold boundaries (head vertical ring, top crown fold, torso flanks, jacket) to detect texture tears or color misalignments.

• Auto-Healing (skin_align_seams): Harmonizes and blends color jumps along adjacent 3D cube edges.

6. Pixel Typography & Cyber Symbols

• 3×5 Pixel Font Matrix (skin_draw_text): Writes crisp letters (A–Z), numbers (0–9), and punctuation (!, ?, -, :, .) on any face.

• Emblem Library (skin_draw_symbol): Instantly stamps cyber emblems (cyber_s 6×8 crest, heart, star, lightning, skull, cross) without coordinate guesswork.

7. Full Outfits Macro & Model Converter

• Coordinated Outfits (skin_apply_outfit): Applies full-body anatomical outfits (techwear_hoodie, cargo_streetwear, casual_tshirt) across Layer 1 and Layer 2 in a single call.

• Geometry Converter (skin_convert_model): Seamlessly converts between classic Steve (4px arms) and Alex Slim (3px arms) with UV island resampling.

8. Multi-Target Synchronization & Auto-Previews (skin_save)

• Automatically saves to primary destination, synchronizes across canonical project paths, and regenerates 2D composite, 3D turnaround, and bottom-up previews in one atomic tool call.

9. Canvas History, Undo/Redo & Named Checkpoints

• Full undo/redo stack (skin_undo, skin_redo).

• Save milestone snapshots (skin_checkpoint) and instantly roll back (skin_restore_checkpoint).

Related MCP server: VoxelForge

📁 Repository Layout

SkinForge/
├── instructions.md            # System instructions & architectural guide for AI models / MCP clients
├── pyproject.toml             # Standard Python packaging metadata
├── README.md                  # Project overview & documentation
├── cli.py                     # Command-line interface
├── mcp_server.py              # Stdio MCP server entry point
├── viewer.py                  # Interactive 3D WebGL viewer server (port 8080)
├── skinforge/                 # Core library
│   ├── __init__.py            # Public exports
│   ├── mcp_server.py          # MCPServer implementation (44 tools, 4 resources, 2 prompts)
│   ├── canvas.py              # SkinCanvas, 72 UV parts, undo/redo, HSV adjustments
│   ├── seams.py               # 3D wrap-around seam auditing and edge blending
│   ├── typography.py          # 3x5 pixel font matrix & cyber symbols
│   ├── outfits.py             # Full anatomical outfit macros
│   ├── converter.py           # Steve 4px <-> Alex 3px slim model converter
│   ├── ascii_codec.py         # ASCII reverse-engineering & color normalization
│   ├── templates.py           # Solid humanoid template generator (0 holes)
│   ├── renderer.py            # Software 3D rasterizer, 2D composite, turntable GIF
│   ├── validator.py           # Quality auditor & layer rule enforcement
│   ├── palettes.py            # Color palettes & 5-step shading ramps
│   ├── presets.py             # Anatomical presets (eyes, drawstrings, cargo pockets)
│   └── sampler.py             # Reference art sampler & dominant palette extractor
├── tests/
│   └── test_mcp_server.py     # Comprehensive unit test suite (16 tests)
├── examples/
│   └── build_syntren.py       # Reference script building the Syntren skin
├── skins/
│   └── skin_syntren.png       # 64x64 RGBA canonical skin
├── previews/
│   ├── 3d_turnaround.png      # 4-angle 3D rasterized turnaround
│   ├── 2d_composite.png       # 2D front/back composite
│   └── turntable_360.gif      # 360-degree turntable animated GIF
└── static/
    └── skinview3d.bundle.js   # Offline Three.js WebGL skinview3d bundle

🚀 Quick Start

1. Installation

# Clone the repository
git clone <repo-url>
cd SkinForge

# Install in editable mode
pip install -e .

Dependencies: python>=3.9, numpy, pillow, mcp.

2. Using with AI / LLMs (Model Context Protocol)

Add SkinForge to your IDE or agent config (mcp_config.json or .mcp.json):

{
  "mcpServers": {
    "skinforge": {
      "command": "python3",
      "args": ["-m", "skinforge.mcp_server"],
      "cwd": "/path/to/SkinForge",
      "env": {
        "PYTHONPATH": "/path/to/SkinForge"
      }
    }
  }
}

Now any LLM (Claude, Gemini, Antigravity, GPT-4o) can autonomously design, edit, audit, and view skins!

3. Interactive 3D Web Viewer

# Launch viewer
python3 viewer.py
# Or via CLI
skinforge view

Open http://localhost:8080 in your browser:

• Left Click Drag: Orbit rotate around character.

• Right Click Drag: Pan camera horizontally and vertically.

• Scroll Wheel: Zoom in/out.

• Animations: Toggle Idle, Walking, Running, and Auto-Spin.

• Layer Toggles: Individually toggle Head, Torso, Arms, Legs, and Outer 3D overlays.

• Live Sync: Edits made via MCP server appear instantly in 300ms!

4. CLI Tools

# Render 3D turnaround and 2D composite
skinforge render skins/skin_syntren.png --out3d previews/3d.png --out2d previews/2d.png

# Generate 360-degree animated turntable GIF
skinforge gif skins/skin_syntren.png --frames 16 --out previews/turntable.gif

# Run quality audit on a skin PNG
skinforge inspect skins/skin_syntren.png

# Mirror right arm to left arm
skinforge mirror skins/skin_syntren.png --from-limb right_arm --to-limb left_arm

5. Python API Example

from skinforge import (
    SkinCanvas,
    SkinValidator,
    render_3d_turnaround,
    render_composite_2d,
    TECHWEAR_CYBERPUNK,
    apply_outfit,
    draw_symbol,
)

# 1. Initialize canvas and apply full techwear outfit
canvas = SkinCanvas()
apply_outfit(canvas, style="techwear_hoodie", accent_color="#af36f8")

# 2. Add custom cyber emblem to jacket back
draw_symbol(canvas, "jacket_back", "cyber_s", x=1, y=2, color="#af36f8")

# 3. Export to 64x64 PNG
canvas.export_png("my_skin.png")

# 4. Audit quality
validator = SkinValidator("my_skin.png")
valid, report = validator.validate()
print(report)

# 5. Render previews
render_3d_turnaround("my_skin.png", "turnaround.png")
render_composite_2d("my_skin.png", "composite.png")

🧪 Testing

SkinForge includes a comprehensive unit test suite covering session state, ASCII reverse-engineering, multimodal rendering, checkpoints, HSV adjustments, seam healing, typography, outfits, and converter:

python3 -m unittest tests/test_mcp_server.py

Ran 16 tests in 1.112s
OK

📜 License

MIT License. Free for personal and commercial use.