Game Asset MCP

🚀 Game Asset Management Tool

This game asset generator is a Node.js-based tool that supports generating 2D and 3D assets for games through the MCP protocol. This tool is compatible with MCP clients such as Claude Desktop.

🚀 Quick Start

Installation and Running

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Start the service:

   • By default, logs are recorded in ./logs/server.log, and assets are stored in ./assets.

     node src/index.js
     

   • Specify a custom directory:

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

✨ Features

Core Features

• 2D Asset Generation: Uses the "gokaygokay/Flux-2D-Game-Assets-LoRA" model (50 steps).
• 3D Asset Image Generation: Uses the "gokaygokay/Flux-Game-Assets-LoRA-v2" model (30 steps).
• Multi-model Support:
  • InstantMesh
  • Hunyuan3D-2
  • Hunyuan3D-2mini-Turbo

Runtime Configuration

Configure the following parameters through the .env file:

HF_TOKEN=Your HuggingFace token
MODEL_SPACE=Model space name (e.g., gokaygokay/Flux)
PORT= SSE transmission port, default is 3000

💻 Usage Examples

Command Line Interface

• Start the service:

  node src/index.js
  

• Specify the storage directory:

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

Configuration File

Edit the Claude Desktop configuration file:

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

Add the following content:

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

Restart Claude Desktop for the changes to take effect.

📚 Documentation

File Management

Storage Location

Assets are stored in the ./assets directory and organized according to the following naming rules:

2d_asset_generate_2d_asset_<timestamp>_<unique_id>.png

Resource Access

Use the MCP URI format:

• List resources: asset://2d_asset/
• Access files: asset://2d_asset/filename.png

Advanced Features

API Endpoints

• 2D Asset Generation:

  • Endpoint: POST /generate/2d
  • Parameters: { prompt: "Describe your requirements" }

• 3D Asset Generation:

  • Endpoint: POST /generate/3d
  • Parameters: { prompt: "Describe your requirements" }

Error Handling

• 401 Unauthorized: Missing or invalid HuggingFace token.
• 500 Internal Error: Model inference failed.
• 429 Rate Limit: Exceeded the API call limit.

Security Precautions

• Do not store sensitive information in plain text in the .env file.
• Update the HuggingFace token regularly.
• Configure the firewall to restrict external access.

Project Architecture

Core Modules

• src/index.js: Main service entry.
• src/api/: API route handling.
• src/models/: Model loading and inference.
• src/storage/: Asset storage management.

Technology Selection

• Framework: Express.js
• Model Management: HuggingFace Inference API
• Logging: Outputs to a file by default, supports custom loggers.

Tutorial Examples

Example 1: Generate 2D Assets

curl -X POST http://localhost:3000/generate/2d \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cute kitten"}'

Example 2: Generate 3D Assets

curl -X POST http://localhost:3000/generate/3d \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A panoramic view of a future city"}'

Frequently Asked Questions

• Q: How to improve the generation speed?

• A: Use a higher-performance model or optimize the network bandwidth.

• Q: Where is the resource storage directory?

• A: By default, it is ./assets, which can be specified through startup parameters.

• Q: Which 3D formats are supported?

• A: Currently, common formats such as obj, gltf, and png are supported.

Development Guide

Module Development

1. Add a new 2D generator:

   npm run dev 2d
   

2. Add a new 3D generator:

   npm run dev 3d
   

Contribution Guidelines

• Before submitting code, ensure that all test cases pass.
• Follow the code specifications of eslint and prettier.

📄 License

This project follows the MIT license. Please refer to the LICENSE file for detailed information.