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, search, and visually verify Minecraft skins with true 3D dual-layer depth — without requiring ad-hoc Python scripts.

🌟 Key Features

1. 55 Native MCP Tools for AI Agents

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

• Craftsmanship & Aesthetic Audit (skin_aesthetic_audit): Full 6-dimensional pixel art evaluation (3D relief, palette harmony, shading depth, cluster coherence, hue shifting, seam continuity) with exact point deductions and actionable pro-tips.

• 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.

• Granular Part Transfer (skin_import_part): Import any individual anatomical UV part (e.g. face, bangs, sleeve emblem) from an external skin or RAG skin ID directly into the active editing session in a single call.

• Autonomous Denoising & Palette Cleaning (skin_denoise_palette): Scans and cleans compression artifacts and isolated noise pixels, harmonizing colors into crisp, authentic pixel-art palettes.

• Direct Reference Sampling (skin_sample_reference): Samples exact colors or extracts dominant palettes from concept art 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. Modular "Lego Constructor" Engine (skin_assemble, skin_part_search)

• Component-Level Search (skin_part_search): Search for individual anatomical components across 900,000+ skins (hair, face, torso, arms, legs, outfit).

• Isolated Component 3D Mannequins: Renders the queried module on a neutral dark mannequin so multimodal models can evaluate hairstyles or jacket folds in isolation.

• Automated Seam Harmonization (skin_assemble): Merges modules from different skins into a cohesive character while automatically blending neck, shoulder, and waist seams and healing 3D geometry rules.

3. Next-Gen Craftsmanship & Aesthetic Engine v2 (compute_aesthetic_score, skin_aesthetic_audit)

• Multi-Dimensional Radar Metrics (0.0 to 1.0): Evaluates authentic pixel art standards across 6 quantitative dimensions:

  • 3D Relief Depth: Optimal Layer 2 coverage (12–45%) without flat planes or over-dense armor bloat.

  • Palette Harmony & Entropy: Rich color ramps (16–70 colors) while rejecting unshaded bucket fills or noisy color fragmentation.

  • Shading Depth & Dynamic Range: Tonal contrast across major anatomical facets.

  • Spatial Cluster Coherence (Anti-Noise): Local autocorrelation ratio distinguishing true clustered pixel art from random TV static / confetti noise.

  • Vectorized Hue Shifting: Rewards natural lighting temperature ramps (warm highlights toward yellow/cyan, cool shadows toward blue/purple) over muddy monochrome brightness dragging.

  • Seam Continuity: Continuity and color gradient alignment across 3D cuboid transitions (head front-to-side, torso front-to-side).

• Pillow Shading & Flaw Detection: Catches classic beginner pillow shading (dark perimeters with bright center) and applies defect deductions for Rule 1 holes, Rule 3 floating cardboard, and Rule 4 planks.

• Search Quality Filtering (skin_search(..., min_quality="medium")): Automatically discards low-effort flat fills, messy noise artifacts, and hollow textures from search results.

4. Visual Concept & Image Search (skin_search_by_image)

• Spatial-Color Pyramid Matching: Converts reference images into a 299-dimensional perceptual pyramid in LAB color space.

• Perceptual Style Similarity: Matches concept art, anime references, or photo textures directly against indexed skins based on global palette, spatial color layout, and contrast.

5. Built-in 900,000+ Skin RAG Search Engine

• Instant Sub-Millisecond Search (skin_search): Queries across 900k+ human-crafted Minecraft skins using SQLite FTS5 (BM25 ranking) in <1ms.

• Visual Reference Generation: Automatically renders 3D turnaround and 2D composite previews for retrieved skins so multimodal LLMs can inspect the design visually.

• Reference Extraction (skin_get_reference): Retrieves full color palettes and ASCII matrices, or loads candidate skins directly into the active editing session.

• Intelligent Remixing (skin_remix): Seamlessly transfers outer layers (jackets, scarves, hoods) and accessories from one reference skin onto another with automatic geometry healing.

6. 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.

• Multi-threaded Architecture (ThreadingHTTPServer): Prevents blocking of status polling during intensive assembly or generation tasks.

• Dynamic Model Synchronization: Auto-detects and updates between classic Steve (4px) and Alex Slim (3px) geometries on-the-fly without refreshing the page.

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

7. 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.

8. 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).

9. 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.

10. 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.

11. Full Outfits Macro & Model Converter (Steve 4px ⟷ Alex 3px Slim)

• 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.

• Complete Alex Slim (3px) Geometry & UV Engine (skin_convert_model): Seamless bidirectional conversion between Steve (4px) and Alex Slim (3px) with official Minecraft UV island resampling (MINECRAFT_UV_MAP_SLIM). Full support for export, loading, validation, and 3D software rendering.

12. 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.

13. 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).

14. 100% Portable & Zero Hardcoded Paths

• Fully portable across any Linux, macOS, or Windows environment using dynamic relative paths and environment variable overrides (SKINFORGE_DEFAULT_SKIN, SKINFORGE_DB_PATH, SKINFORGE_VIEWER_PORT, SKINFORGE_LIVE_SKIN, SKINFORGE_EXPORT_DIR).

Related MCP server: Blockbench MCP Bridge

📁 Repository Layout

SkinForge/
├── instructions.md            # System instructions & architectural guide for AI models / MCP clients
├── pyproject.toml             # Standard Python packaging metadata (v1.0.0)
├── 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 (v1.0.0)
│   ├── mcp_server.py          # MCPServer implementation (54 tools, 4 resources, 2 prompts)
│   ├── canvas.py              # SkinCanvas, 72 UV parts, undo/redo, HSV adjustments
│   ├── modular.py             # Lego Constructor: assembly & isolated module mannequin preview
│   ├── vision.py              # Spatial-color pyramid visual concept & image search
│   ├── validator.py           # Quality auditor & aesthetic craftsmanship scorer
│   ├── rag.py                 # 900k+ skin FTS5 search engine, part search & remix
│   ├── 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 & vectorized color normalization
│   ├── templates.py           # Solid humanoid template generator (0 holes)
│   ├── renderer.py            # Software 3D rasterizer, 2D composite, turntable GIF
│   ├── 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     # Base MCP unit tests
│   ├── test_rag.py            # RAG engine and FTS5 search tests
│   └── test_v1.py             # v1.0.0 Lego constructor, aesthetic scoring & vision 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 https://github.com/Syntren/SkinForge-MCP.git
cd SkinForge-MCP

# 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-MCP",
      "env": {
        "PYTHONPATH": "/path/to/SkinForge-MCP"
      }
    }
  }
}

Now any LLM (Claude, Gemini, Antigravity, GPT-4o) can autonomously design, assemble, 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 Examples

A. Modular Lego Assembly with Automatic Seam Blending

from skinforge import SkinCanvas, assemble_skin, render_3d_turnaround

# Assemble modular parts from different skin files
target_canvas, summary = assemble_skin(
    sources={
        "hair": "skins/hair_reference.png",
        "torso": "skins/tuxedo_torso.png",
        "legs": "skins/tailored_pants.png"
    },
    auto_blend_seams=True,
    auto_fix=True
)

print(f"Aesthetic score: {summary['aesthetic_score']} ({summary['aesthetic_tier']})")
target_canvas.export_png("assembled_character.png")
render_3d_turnaround("assembled_character.png", "preview_assembled.png")

B. Quality Auditing & Aesthetic Scoring

from skinforge import SkinValidator, compute_aesthetic_score

# 1. Audit Minecraft rules (holes, floating cardboard planes)
validator = SkinValidator("skin_syntren.png")
valid, report = validator.validate()
print(report)

# 2. Compute aesthetic craftsmanship metrics
score_info = compute_aesthetic_score("skin_syntren.png")
print(f"Quality Tier: {score_info['tier']} (Score: {score_info['score']})")
print(f"Layer 2 Relief Ratio: {score_info['layer2_ratio']}")
print(f"Unique Colors: {score_info['unique_colors']}")
print(f"Radar Metrics: {score_info['metrics']}")
print(f"Recommendations: {score_info['recommendations']}")

🧪 Testing

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

PYTHONPATH=. python3 -m unittest discover -s tests -p "test_*.py"

..............................
----------------------------------------------------------------------
Ran 30 tests in 9.348s

OK

📜 License

MIT License. Free for personal and commercial use.