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）**を使用します。

プロジェクト概要

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

仕組み

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

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

ワークフロー図

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

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

前提条件

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
- .envを編集し、 Hugging Face APIトークンと複製したMODEL_SPACEを設定します。詳細は設定をご覧ください。
サーバーを実行します:
- ローカル（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モデル設定

変数	説明	有効範囲/デフォルト
`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
- オクツリー解像度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

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