MCP와 Hugging Face Spaces를 활용한 게임 자산 생성기

이 프로젝트는 AI 기반 생성 기능을 활용하여 게임 에셋 제작을 간소화하는 혁신적인 도구입니다. 신속한 프로토타입을 원하는 게임 개발자든, 생성 모델을 탐구하는 AI 애호가든, 이 도구를 사용하면 텍스트 프롬프트에서 2D 및 3D 게임 에셋을 손쉽게 제작할 수 있습니다. "gokaygokay/Flux-2D-Game-Assets-LoRA" , "gokaygokay/Flux-Game-Assets-LoRA-v2" , 그리고 세 가지 3D 모델 생성 공간 ( InstantMesh , Hunyuan3D-2 또는 Hunyuan3D-2mini-Turbo , 계정으로 복제해야 함) 중 하나를 기반으로 하는 Hugging Face Spaces의 AI 모델을 통합하고, Claude Desktop 과 같은 AI 도우미와의 원활한 상호작용을 위해 모델 컨텍스트 프로토콜(MCP)을 사용합니다.

프로젝트 개요

게임 에셋 생성기 (버전 0.3.0 )는 AI를 활용하여 게임 에셋 생성을 간소화합니다. 텍스트 프롬프트에서 2D 에셋 (예: 픽셀 아트 스프라이트)과 3D 에셋 (예: OBJ 및 GLB 모델)을 생성할 수 있으며, Hugging Face Spaces 및 Model Context Protocol(MCP) 과 통합됩니다. 이번 릴리스에서는 InstantMesh , Hunyuan3D-2 , Hunyuan3D-2mini-Turbo 등 다양한 3D 모델 생성 공간을 지원하여 유연성과 향상된 성능을 제공합니다. Node.js 와 MCP TypeScript SDK(v1.7.0) 로 구축된 이 제품은 에셋 생성을 위한 강력한 크로스 플랫폼 솔루션을 제공합니다.

특징

2D 자산 생성 : 텍스트 프롬프트에서 픽셀 아트, 스프라이트 또는 기타 2D 자산을 생성합니다(예: "픽셀 아트 검").
3D 자산 생성 : 텍스트 설명에서 3D 모델(OBJ 및 GLB 형식)을 생성하고, 이미지를 자동으로 모델로 변환합니다.
다중 3D 모델 공간 : 다양한 3D 생성 워크플로를 위해 InstantMesh , Hunyuan3D-2 , Hunyuan3D-2mini-Turbo 지원합니다.
MCP 통합 : Claude Desktop 과 같은 MCP 호환 클라이언트를 통해 도구와 원활하게 상호 작용합니다.
파일 관리 : 리소스 URI(예: asset://{type}/{id} )를 사용하여 로컬 assets 디렉토리에 자산을 자동으로 저장하고 구성합니다.
강력한 입력 검증 : 안전하고 안정적인 입력 처리를 위해 Zod를 사용합니다.
다중 클라이언트 지원 : SSE 전송을 통해 여러 개의 동시 연결을 처리합니다.
보안 원격 액세스 : 안전한 원격 통신을 위한 선택적 HTTPS 지원.
확장 가능한 백엔드 : 새로운 모델이나 기능을 쉽게 통합할 수 있는 모듈식 디자인.
크로스 플랫폼 : Node.js를 사용하여 Windows, macOS, Linux와 호환됩니다.
구성 가능한 3D 생성 : 환경 변수를 통해 추론 단계, 안내 척도, 터보 모드와 같은 매개변수를 사용자 정의합니다.

작동 원리

게임 자산 생성기는 자동화된 파이프라인을 통해 텍스트 프롬프트를 게임에 사용할 수 있는 자산으로 변환합니다.

사용자 입력 : 텍스트 프롬프트를 제출하세요(예: "픽셀 아트 검" 또는 "아이소메트릭 3D 성").
MCP 서버 : 프롬프트를 적절한 도구( generate_2d_asset 또는 generate_3d_asset )로 라우팅합니다.
AI 모델 상호작용 :
- 2D 자산 : "gokaygokay/Flux-2D-Game-Assets-LoRA" 사용한 Hugging Face Inference API를 활용합니다(50단계).
- 3D 자산 :
  - "gokaygokay/Flux-Game-Assets-LoRA-v2" 사용하여 초기 이미지를 생성합니다(30단계).
  - 다음 중 하나를 사용하여 이미지를 3D 모델로 변환합니다.
    - InstantMesh : 다단계 프로세스( /preprocess , /generate_mvs , /make3d ).
    - Hunyuan3D-2 : 단일 단계 프로세스( /generation_all ).
    - Hunyuan3D-2mini-Turbo : 구성 가능한 터보 모드를 갖춘 단일 단계 프로세스( /generation_all ).
파일 출력 : assets 디렉토리에 자산(2D의 경우 PNG, 3D의 경우 OBJ/GLB)을 저장합니다.
응답 : 즉시 사용할 수 있는 리소스 URI(예: asset://3d_model/filename.glb )를 반환합니다.

워크플로 다이어그램

지엑스피1

최적의 품질을 위해 프롬프트는 자동으로 "매우 자세하고 완전한 객체이며 잘리지 않았으며 흰색 단색 배경"으로 향상됩니다.

필수 조건

Node.js : 버전 16 이상( npm 포함).
Git : 저장소를 복제합니다.
인터넷 접속 : Hugging Face API 연결에 필요합니다.
Hugging Face 계정 : API 접근에 필요합니다. huggingface.co/settings/tokens 에서 토큰을 받으세요.
NPM 패키지 :
- @gradio/client : Hugging Face Spaces와 상호작용합니다.
- @huggingface/inference : 직접적인 모델 추론을 위해.
- @modelcontextprotocol/sdk : MCP 서버를 구현합니다.
- dotenv : 환경 변수를 로드합니다.
- express : SSE 전송을 활성화합니다.
- zod : 입력 검증을 보장합니다.
- sharp : 이미지 처리를 처리합니다.
선택 사항 : 향상된 상호작용을 위해 Claude Desktop (또는 다른 MCP 클라이언트)을 사용합니다.

설치

저장소 복제 :
git clone https://github.com/yourusername/game-asset-mcp.git cd game-asset-mcp
종속성 설치 :
npm install
환경 구성 :
- 예제 .env 파일을 복사하세요.
  cp .env.example .env
- Hugging Face API 토큰 과 복제된 MODEL_SPACE를 사용하여 .env 편집하세요. 자세한 내용은 구성을 참조하세요.
서버 실행 :
- 로컬(stdio 전송) :
  npm start
- 사용자 정의 작업 디렉토리 :
  node src/index.js /path/to/directory
- 원격(SSE 전송) :
  node src/index.js --sse
- HTTPS를 통한 원격 :
  node src/index.js --sse --https
  ssl/key.pem 및 ssl/cert.pem 필요합니다( ssl/README.md 참조).

참고 : ES 모듈을 사용합니다( package.json 에 "type": "module" ). Node.js 16 이상이 설치되어 있는지 확인하세요( node --version ).

용법

MCP 클라이언트 (예: Claude Desktop)를 통해 또는 프로그래밍 방식으로 서버와 상호 작용합니다.

2D 자산 생성 :
- 명령어 : generate_2d_asset prompt:"pixel art sword"
- 출력 : PNG 파일(예: 2d_asset_generate_2d_asset_1698765432.png )을 저장하고 해당 URI를 반환합니다.
3D 자산 생성 :
- 명령어 : generate_3d_asset prompt:"isometric 3D castle"
- 출력 : OBJ/GLB 파일과 중간 이미지를 저장하고 해당 URI를 반환합니다. 장기 실행 작업에 대한 작업 ID를 제공합니다.

프롬프트 예제

자연스러운 상호작용 :
- generate_2d_sprite prompt:"pixel art sword"
- generate_3d_model prompt:"isometric 3D castle"

클로드 데스크톱과 함께

구성 후( 구성 참조) 인터페이스에 직접 명령을 입력합니다.

구성

.env 파일을 통해 서버를 사용자 정의합니다.

필수 설정

HF_TOKEN : Hugging Face API 토큰.
HF_TOKEN=your_hf_token
MODEL_SPACE : 복제된 3D 모델 공간(예: your-username/InstantMesh ).
- 다음 중 하나를 복제하세요.

선택적 3D 모델 설정

변하기 쉬운	설명	유효 범위/기본값
`MODEL_3D_STEPS`	추론 단계	공간에 따라 다름(아래 참조)
`MODEL_3D_GUIDANCE_SCALE`	모델이 프롬프트를 얼마나 밀접하게 따르는가	0.0-100.0 (기본값: 5.0-5.5)
`MODEL_3D_OCTREE_RESOLUTION`	3D 모델의 세부 수준	공간에 따라 다름(아래 참조)
`MODEL_3D_SEED`	무작위성 제어	0-10000000 (기본값: 다양함)
`MODEL_3D_REMOVE_BACKGROUND`	이미지 배경 제거	`true` / `false` (기본값: `true` )
`MODEL_3D_TURBO_MODE`	생성 모드(Hunyuan3D-2mini-Turbo 전용)	`Turbo` , `Fast` , `Standard` (기본값: `Turbo` )
`MODEL_SPACE_TYPE`	공간 유형 감지 재정의	`instantmesh` , `hunyuan3d` , `hunyuan3d_mini_turbo`

공간별 기본값

인스턴트메시 :
- 단계: 30-75 (기본값: 75)
- 시드: 기본 42
헌원3D-2 :
- 단계: 20-50 (기본값: 20)
- 안내 척도: 기본 5.5
- Octree 해상도: 256 , 384 , 512 (기본값: 256 )
- 시드: 기본 1234
Hunyuan3D-2mini-Turbo :
- 단계: 1-100(기본값: Turbo 의 경우 5, Fast 의 경우 10, Standard 의 경우 20)
- 지침 척도: 기본 5.0
- Octree 해상도: 16-512(기본값: 256)
- 시드: 기본 1234

전송 설정

PORT : SSE 전송 포트(기본값: 3000).
PORT=3000

클로드 데스크탑 설정

구성 파일을 편집하세요:

MacOS : ~/Library/Application Support/Claude/claude_desktop_config.json
윈도우 : %APPDATA%\Claude\claude_desktop_config.json

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

편집 후 Claude Desktop을 다시 시작하세요.

파일 관리

저장 위치 : 자산은 작업 디렉토리 내의 ./assets 에 저장됩니다.
명명 규칙 : 파일은 접두사, 도구 이름, 타임스탬프 및 고유 ID를 사용합니다(예: 2d_asset_generate_2d_asset_1698765432_abcd1234.png ).
사용자 정의 : 사용자 정의 디렉토리 설정:
node src/index.js /path/to/custom/directory
리소스 액세스 : MCP URI(예: asset://2d_asset/filename.png )를 사용하여 자산을 나열하거나 읽습니다.

MCP 통합

MCP(모델 컨텍스트 프로토콜)를 통해 이 도구는 AI 클라이언트에게 안전하게 서비스를 제공할 수 있습니다.

도구 : generate_2d_asset , generate_3d_asset .
리소스 : asset:// URI를 통해 관리됩니다.
프롬프트 : generate_2d_sprite , generate_3d_model .
호환성 : Claude Desktop 및 기타 MCP 클라이언트와 호환됩니다.

문제 해결

API 오류 : 네트워크 연결이나 속도 제한을 확인하세요. ./logs/server.log 를 검토하세요.
인증 문제 : .env 에서 HF_TOKEN 및 MODEL_SPACE 확인하세요.
ES 모듈 오류 : Node.js 16 이상을 확인하세요( node --version ).
로그 : 자세한 로그를 검사합니다.
tail -f ./logs/server.log

고급의

API 엔드포인트 및 통합

2D 자산 생성 : "gokaygokay/Flux-2D-Game-Assets-LoRA" 사용합니다(50단계).
3D 자산 이미지 생성 : "gokaygokay/Flux-Game-Assets-LoRA-v2" 사용합니다(30단계).
3D 모델 변환 :
- InstantMesh : 다단계( /check_input_image , /preprocess , /generate_mvs , /make3d ).
- Hunyuan3D-2 : 단일 단계( /generation_all ).
- Hunyuan3D-2mini-Turbo : 터보 모드가 있는 단일 단계( /generation_all ).

버전 관리

현재 버전 : 0.3.0(Hunyuan3D-2mini-Turbo 지원 추가).
MCP SDK 버전 : 1.7.0.
형식 : MAJOR.MINOR.PATCH(SemVer).

백엔드 아키텍처

코어 파일 : src/index.js .
종속성 : package.json 참조하세요.
보안 : Zod 검증, 경로 횡단 방지, HTTPS 지원, 속도 제한.
성능 : 비동기 처리, 백오프를 통한 재시도, GPU 할당량 처리.

기여하다

여러분의 참여를 환영합니다! 참여 방법:

저장소 포크 : GitHub에 사본을 만듭니다.
변경하기 : 기능을 추가하고, 버그를 수정하고, 문서를 개선합니다.
풀 리퀘스트 제출 : 변경 사항을 자세히 설명하세요.
열린 문제 : 버그를 보고하거나 개선 사항을 제안하세요.

표준 코딩 규칙을 따르고 해당되는 경우 테스트를 포함합니다.

특허

MIT 라이선스 에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.

Game Asset Generator

Integrations