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

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

目次

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 モデル空間: さまざまな 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 生成: 環境変数を使用して、推論ステップ、ガイダンス スケール、ターボ モードなどのパラメータをカスタマイズします。

仕組み

ゲーム アセット ジェネレーターは、自動化されたパイプラインを通じてテキスト プロンプトをゲーム対応アセットに変換します。

1. ユーザー入力: テキストプロンプトを送信します (例:「ピクセルアートの剣」または「等角投影の 3D 城」)。
2. MCP サーバー: プロンプトを適切なツール ( generate_2d_assetまたはgenerate_3d_asset ) にルーティングします。
3. 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 )。
4. ファイル出力: アセット (2D の場合は PNG、3D の場合は OBJ/GLB) をassetsディレクトリに保存します。
5. レスポンス: すぐに使用できるリソース URI (例: asset://3d_model/filename.glb ) を返します。

ワークフロー図

プロンプトは、最適な品質を実現するために、「非常に詳細で、オブジェクトが完全で、切り取られておらず、白い単色の背景」で自動的に強化されます。

前提条件

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

クロード・デスクトップ

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

構成

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

必要な設定

• HF_TOKEN : Hugging Face API トークン。
  HF_TOKEN=your_hf_token
• MODEL_SPACE : 複製された 3D モデル空間 (例: your-username/InstantMesh )。
  • 次のいずれかを複製します:
    • インスタントメッシュ
    • フンユアン3D-2
    • フンユアン3D-2ミニターボ```plaintext MODEL_SPACE=your-username/InstantMesh

オプションの3Dモデル設定

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

• インスタントメッシュ:
  • ステップ: 30～75 (デフォルト: 75)
  • シード: デフォルト 42
• フンユアン3D-2 :
  • ステップ: 20～50 (デフォルト: 20)
  • ガイダンススケール: デフォルト 5.5
  • オクツリー解像度512``256 (デフォルト: 256``384
  • シード: デフォルト 1234
• Hunyuan3D-2ミニターボ：
  • ステップ: 1 ～ 100 (デフォルト: Turboの場合は 5、 Fastの場合は 10、 Standardの場合は 20)
  • ガイダンススケール: デフォルト 5.0
  • オクツリー解像度: 16-512 (デフォルト: 256)
  • シード: デフォルト 1234

トランスポート設定

• PORT : SSE トランスポート ポート (デフォルト: 3000)。
  PORT=3000

クロードデスクトップセットアップ

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

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

編集後、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 クォータ処理。

貢献

皆様のご協力をお待ちしております！参加するには：

1. リポジトリをフォークする: GitHub にコピーを作成します。
2. 変更を加える: 機能を追加したり、バグを修正したり、ドキュメントを強化したりします。
3. プル リクエストを送信します。変更内容を詳しく記述します。
4. 未解決の問題: バグを報告したり、改善を提案したりします。

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

ライセンス

MITライセンスに基づいてライセンスされています。詳細についてはLICENSEファイルをご覧ください。