Game Asset Generator using MCP and Hugging Face Spaces

プロジェクトのオーナーが近いうちにこのリポジトリを確認する予定です。2026年6月の更新をお待ちください。

MCP と Hugging Face Spaces を使用したゲームアセットジェネレーター

このプロジェクトは、AI による生成を活用してゲームアセットの作成を簡素化する革新的なツールです。迅速なプロトタイプを必要とするゲーム開発者にも、生成モデルを探求する AI 愛好家にも、このツールを使えばテキストプロンプトから2Dおよび3D ゲームアセットを簡単に作成できます。"gokaygokay/Flux-2D-Game-Assets-LoRA"、"gokaygokay/Flux-Game-Assets-LoRA-v2"、および3つの3Dモデル生成スペース（InstantMesh、Hunyuan3D-2、Hunyuan3D-2mini-Turboのいずれか。これらは自分のアカウントに複製する必要があります）を利用するHugging Face Spacesの AI モデルと連携し、Model Context Protocol (MCP) を使用してClaude Desktopなどの AI アシスタントとシームレスにやり取りできます。

---

目次

1. プロジェクト概要
2. 機能
3. 仕組み
4. 前提条件
5. インストール
6. 使い方
7. 設定
8. ファイル管理
9. MCP 連携
10. トラブルシューティング
11. 上級者向け
12. コントリビューション
13. ライセンス

---

プロジェクト概要

Game Asset Generator（バージョン 0.3.0）は、AI を活用してゲームアセットの作成を効率化します。テキストプロンプトから2D アセット（ピクセルアートのスプライトなど）と3D アセット（OBJ や GLB モデルなど）を生成でき、Hugging Face SpacesおよびModel Context Protocol (MCP) と連携します。このリリースでは、複数の3Dモデル生成スペース（InstantMesh、Hunyuan3D-2、Hunyuan3D-2mini-Turbo）への対応が導入され、柔軟性とパフォーマンスが向上しています。Node.jsと**MCP TypeScript SDK (v1.7.0)**で構築されており、堅牢なクロスプラットフォーム対応のアセット生成ソリューションを提供します。

---

機能

• 2D アセット生成：テキストプロンプト（例：「ピクセルアートの剣」）からピクセルアート、スプライト、その他の2Dアセットを作成します。
• 3D アセット生成：テキストの説明から3Dモデル（OBJ および GLB 形式）を生成し、画像からモデルへの変換も自動で行います。
• 複数の3Dモデルスペース：InstantMesh、Hunyuan3D-2、Hunyuan3D-2mini-Turboに対応し、さまざまな3D生成ワークフローを利用できます。
• MCP 連携：Claude Desktopなどの MCP 対応クライアントを通じて、ツールとシームレスにやり取りできます。
• ファイル管理：リソース URI（例：asset://{type}/{id}）を使用して、アセットをローカルのassetsディレクトリに自動で保存し、整理します。
• 堅牢な入力検証：Zodを使用して、安全で信頼性の高い入力処理を実現します。
• 複数クライアント対応：SSE transportを介して、複数の同時接続を処理します。
• 安全なリモートアクセス：安全なリモート通信のために、オプションでHTTPSを利用できます。
• 拡張可能なバックエンド：新しいモデルや機能を簡単に統合できるモジュール設計です。
• クロスプラットフォーム対応：Node.jsを使用し、Windows、macOS、Linux と互換性があります。
• 設定可能な3D生成：環境変数を使って、推論ステップ、ガイダンススケール、ターボモードなどのパラメーターをカスタマイズできます。

---

動作の仕組み

Game Asset Generator は、自動化されたパイプラインを通じて、テキストプロンプトをゲームですぐに使えるアセットに変換します。

1. ユーザー入力：テキストプロンプト（例：「ピクセルアートの剣」や「アイソメトリックな3Dの城」）を送信します。
2. MCP サーバー：プロンプトを適切なツール（generate_2d_asset または generate_3d_asset）にルーティングします。
3. AI モデルとの連携：
   • 2D アセット："gokaygokay/Flux-2D-Game-Assets-LoRA"（50ステップ）で Hugging Face Inference API を使用します。
   • 3D アセット：
     • "gokaygokay/Flux-Game-Assets-LoRA-v2"（30ステップ）を使用して初期画像を生成します。
     • 次のいずれかを使用して、画像を3Dモデルに変換します。
       • InstantMesh：複数ステップの処理（/preprocess、/generate_mvs、/make3d）。
       • Hunyuan3D-2：単一ステップの処理（/generation_all）。
       • Hunyuan3D-2mini-Turbo：設定可能なターボモードを備えた単一ステップの処理（/generation_all）。
4. ファイル出力：アセット（2DはPNG、3DはOBJ/GLB）をassetsディレクトリに保存します。
5. レスポンス：すぐに使用できるリソース URI（例：asset://3d_model/filename.glb）を返します。

ワークフロー図

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

最適な品質を得るため、プロンプトには「high detailed, complete object, not cut off, white solid background」が自動的に追加されます。

---

前提条件

• 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クライアント）を使用します。

---

インストール

1. リポジトリをクローンする：

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

2. 依存関係をインストールする：

   npm install
   

3. 環境を設定する：

   • サンプルの.envファイルをコピーします。

     cp .env.example .env
     

   • .envを編集し、Hugging Face APIトークンと複製したMODEL_SPACEを設定します。詳しくは設定を参照してください。

4. サーバーを起動する：

   • ローカル（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"

Claude Desktopを使用する場合

設定後（設定を参照）、インターフェースにコマンドを直接入力します。

---

設定

.envファイルを使用してサーバーをカスタマイズします。

必須設定

• HF_TOKEN：Hugging Face API トークン。

  HF_TOKEN=your_hf_token
  

• MODEL_SPACE：複製した 3D モデルスペース（例：your-username/InstantMesh）。
  • 次のいずれかを複製します：
    • InstantMesh
    • Hunyuan3D-2
    • Hunyuan3D-2mini-Turbo

  MODEL_SPACE=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

スペース固有のデフォルト

• InstantMesh：
  • ステップ数：30-75（デフォルト：75）
  • シード：デフォルトは 42
• Hunyuan3D-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
  

Claude Desktop の設定

設定ファイルを編集します：

• 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"]
    }
  }
}

編集後、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 統合

Model Context Protocol（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 クォータの処理。

---

コントリビューション

コントリビューションを歓迎します！参加するには、以下の手順に従ってください。

1. リポジトリをフォークする：GitHub で自分のコピーを作成します。
2. 変更を加える：機能の追加、バグの修正、ドキュメントの改善を行います。
3. プルリクエストを送信する：変更内容を詳しく記載します。
4. イシューを作成する：バグを報告するか、改善案を提案します。

標準的なコーディング規約に従い、該当する場合はテストを含めてください。

---

ライセンス

MIT Licenseの下でライセンスされています。詳細はLICENSEファイルを参照してください。