Game Asset Generator using MCP and Hugging Face Spaces

This project is an innovative tool that simplifies game asset creation by leveraging AI-powered generation. Whether you're a game developer seeking rapid prototypes or an AI enthusiast exploring generative models, this tool enables you to create 2D and 3D game assets from text prompts effortlessly. It integrates AI models from Hugging Face Spaces—powered by "gokaygokay/Flux-2D-Game-Assets-LoRA", "gokaygokay/Flux-Game-Assets-LoRA-v2", and one of three 3D model generation spaces (InstantMesh, Hunyuan3D-2, or Hunyuan3D-2mini-Turbo, which you must duplicate to your account)—and uses the Model Context Protocol (MCP) for seamless interaction with AI assistants like Claude Desktop.

---

Table of Contents

1. Project Overview
2. Features
3. How It Works
4. Prerequisites
5. Installation
6. Usage
7. Configuration
8. File Management
9. MCP Integration
10. Troubleshooting
11. Advanced
12. Contributing
13. License

---

Project Overview

The Game Asset Generator (version 0.3.0) harnesses AI to streamline the creation of game assets. It supports generating 2D assets (e.g., pixel art sprites) and 3D assets (e.g., OBJ and GLB models) from text prompts, integrating with Hugging Face Spaces and the Model Context Protocol (MCP). This release introduces support for multiple 3D model generation spaces—InstantMesh, Hunyuan3D-2, and Hunyuan3D-2mini-Turbo—offering flexibility and enhanced performance. Built with Node.js and the MCP TypeScript SDK (v1.7.0), it provides a robust, cross-platform solution for asset generation.

---

Features

• 2D Asset Generation: Create pixel art, sprites, or other 2D assets from text prompts (e.g., "pixel art sword").
• 3D Asset Generation: Generate 3D models (OBJ and GLB formats) from text descriptions, with automatic image-to-model conversion.
• Multiple 3D Model Spaces: Supports InstantMesh, Hunyuan3D-2, and Hunyuan3D-2mini-Turbo for varied 3D generation workflows.
• MCP Integration: Seamlessly interact with the tool via MCP-compatible clients like Claude Desktop.
• File Management: Automatically saves and organizes assets in a local assets directory with resource URIs (e.g., asset://{type}/{id}).
• Robust Input Validation: Uses Zod for secure and reliable input processing.
• Multi-Client Support: Handles multiple simultaneous connections via SSE transport.
• Secure Remote Access: Optional HTTPS support for safe remote communication.
• Extensible Backend: Modular design for easy integration of new models or features.
• Cross-Platform: Compatible with Windows, macOS, and Linux using Node.js.
• Configurable 3D Generation: Customize parameters like inference steps, guidance scale, and turbo mode via environment variables.

---

How It Works

The Game Asset Generator transforms text prompts into game-ready assets through an automated pipeline:

1. User Input: Submit a text prompt (e.g., "pixel art sword" or "isometric 3D castle").
2. MCP Server: Routes the prompt to the appropriate tool (generate_2d_asset or generate_3d_asset).
3. AI Model Interaction:
   • 2D Assets: Utilizes the Hugging Face Inference API with "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 steps).
   • 3D Assets:
     • Generates an initial image using "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 steps).
     • Converts the image to a 3D model using one of:
       • InstantMesh: Multi-step process (/preprocess, /generate_mvs, /make3d).
       • Hunyuan3D-2: Single-step process (/generation_all).
       • Hunyuan3D-2mini-Turbo: Single-step process (/generation_all) with configurable turbo modes.
4. File Output: Saves assets (PNG for 2D, OBJ/GLB for 3D) in the assets directory.
5. Response: Returns resource URIs (e.g., asset://3d_model/filename.glb) for immediate use.

Workflow Diagram

User Prompt → MCP Server → AI Model(s) → Local File → Resource URI Response

Prompts are automatically enhanced with "high detailed, complete object, not cut off, white solid background" for optimal quality.

---

Prerequisites

• Node.js: Version 16+ (includes npm).
• Git: For cloning the repository.
• Internet Access: Required for Hugging Face API connectivity.
• Hugging Face Account: Needed for API access; obtain your token from huggingface.co/settings/tokens.
• NPM Packages:
  • @gradio/client: Interacts with Hugging Face Spaces.
  • @huggingface/inference: For direct model inference.
  • @modelcontextprotocol/sdk: Implements the MCP server.
  • dotenv: Loads environment variables.
  • express: Enables SSE transport.
  • zod: Ensures input validation.
  • sharp: Handles image processing.
• Optional: Claude Desktop (or another MCP client) for enhanced interaction.

---

Installation

1. Clone the Repository:

   git clone https://github.com/yourusername/game-asset-mcp.git
   cd game-asset-mcp
   

2. Install Dependencies:

   npm install
   

3. Configure Environment:

   • Copy the example .env file:

     cp .env.example .env
     

   • Edit .env with your Hugging Face API token and duplicated MODEL_SPACE. See Configuration for details.

4. Run the Server:

   • Local (stdio transport):

     npm start
     

   • Custom Working Directory:

     node src/index.js /path/to/directory
     

   • Remote (SSE transport):

     node src/index.js --sse
     

   • Remote with HTTPS:

     node src/index.js --sse --https
     

     Requires ssl/key.pem and ssl/cert.pem (see ssl/README.md).

Note: Uses ES modules ("type": "module" in package.json). Ensure Node.js 16+ is installed (node --version).

---

Usage

Interact with the server via an MCP client (e.g., Claude Desktop) or programmatically:

• Generate a 2D Asset:

  • Command: generate_2d_asset prompt:"pixel art sword"
  • Output: Saves a PNG file (e.g., 2d_asset_generate_2d_asset_1698765432.png) and returns its URI.

• Generate a 3D Asset:

  • Command: generate_3d_asset prompt:"isometric 3D castle"
  • Output: Saves OBJ/GLB files and intermediate images, returning their URIs. Provides an operation ID for long-running tasks.

Prompt Examples

• Natural Interaction:
  • generate_2d_sprite prompt:"pixel art sword"
  • generate_3d_model prompt:"isometric 3D castle"

With Claude Desktop

After configuring (see Configuration), type commands directly in the interface.

---

Configuration

Customize the server via the .env file:

Required Settings

• HF_TOKEN: Hugging Face API token.

  HF_TOKEN=your_hf_token
  

• MODEL_SPACE: Your duplicated 3D model space (e.g., your-username/InstantMesh).
  • Duplicate one of:
    • InstantMesh
    • Hunyuan3D-2
    • Hunyuan3D-2mini-Turbo

  MODEL_SPACE=your-username/InstantMesh
  

Optional 3D Model Settings

Variable	Description	Valid Range/Default
MODEL_3D_STEPS	Inference steps	Varies by space (see below)
MODEL_3D_GUIDANCE_SCALE	How closely the model follows the prompt	0.0-100.0 (default: 5.0-5.5)
MODEL_3D_OCTREE_RESOLUTION	Detail level of the 3D model	Varies by space (see below)
MODEL_3D_SEED	Randomness control	0-10000000 (default: varies)
MODEL_3D_REMOVE_BACKGROUND	Remove image background	true/false (default: true)
MODEL_3D_TURBO_MODE	Generation mode (Hunyuan3D-2mini-Turbo only)	Turbo, Fast, Standard (default: Turbo)
MODEL_SPACE_TYPE	Override space type detection	instantmesh, hunyuan3d, hunyuan3d_mini_turbo

Space-Specific Defaults

• InstantMesh:
  • Steps: 30-75 (default: 75)
  • Seed: Default 42
• Hunyuan3D-2:
  • Steps: 20-50 (default: 20)
  • Guidance Scale: Default 5.5
  • Octree Resolution: 256, 384, 512 (default: 256)
  • Seed: Default 1234
• Hunyuan3D-2mini-Turbo:
  • Steps: 1-100 (default: 5 for Turbo, 10 for Fast, 20 for Standard)
  • Guidance Scale: Default 5.0
  • Octree Resolution: 16-512 (default: 256)
  • Seed: Default 1234

Transport Settings

• PORT: SSE transport port (default: 3000).

  PORT=3000
  

Claude Desktop Setup

Edit the config file:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "game-asset-generator": {
      "command": "node",
      "args": ["/full/path/to/game-asset-mcp/src/index.js"]
    }
  }
}

Restart Claude Desktop after editing.

---

File Management

• Storage Location: Assets are saved in ./assets within the working directory.
• Naming Convention: Files use a prefix, tool name, timestamp, and unique ID (e.g., 2d_asset_generate_2d_asset_1698765432_abcd1234.png).
• Customization: Set a custom directory:

  node src/index.js /path/to/custom/directory
  

• Resource Access: Use MCP URIs (e.g., asset://2d_asset/filename.png) to list or read assets.

---

MCP Integration

The Model Context Protocol (MCP) enables this tool to serve AI clients securely:

• Tools: generate_2d_asset, generate_3d_asset.
• Resources: Managed via asset:// URIs.
• Prompts: generate_2d_sprite, generate_3d_model.
• Compatibility: Works with Claude Desktop and other MCP clients.

---

Troubleshooting

• API Errors: Check network connectivity or rate limits; review ./logs/server.log.
• Authentication Issues: Verify HF_TOKEN and MODEL_SPACE in .env.
• ES Modules Error: Ensure Node.js 16+ (node --version).
• Logs: Inspect detailed logs:

  tail -f ./logs/server.log
  

---

Advanced

API Endpoints and Integration

• 2D Asset Generation: Uses "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 steps).
• 3D Asset Image Generation: Uses "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 steps).
• 3D Model Conversion:
  • InstantMesh: Multi-step (/check_input_image, /preprocess, /generate_mvs, /make3d).
  • Hunyuan3D-2: Single-step (/generation_all).
  • Hunyuan3D-2mini-Turbo: Single-step (/generation_all) with turbo modes.

Versioning

• Current Version: 0.3.0 (Added Hunyuan3D-2mini-Turbo support).
• MCP SDK Version: 1.7.0.
• Format: MAJOR.MINOR.PATCH (SemVer).

Backend Architecture

• Core File: src/index.js.
• Dependencies: See package.json.
• Security: Zod validation, path traversal prevention, HTTPS support, rate limiting.
• Performance: Async processing, retry with backoff, GPU quota handling.

---

Contributing

We welcome contributions! To participate:

1. Fork the Repository: Create your copy on GitHub.
2. Make Changes: Add features, fix bugs, or enhance docs.
3. Submit a Pull Request: Detail your changes.
4. Open Issues: Report bugs or suggest improvements.

Follow standard coding conventions and include tests where applicable.

---

License

Licensed under the MIT License. See the LICENSE file for details.