game-asset-mcp

AIエージェントが、参照画像、メッシュ、PBRテクスチャ、来歴まで含めて、ゲーム対応の3Dアセットをエンドツーエンドで生成し、すでに所有しているメッシュのリテクスチャも行えるMCPサーバーです。

ほとんどのアセット生成ツールは「プロンプトを入力してメッシュを取得する」ところで止まります。それは簡単な半分です。実際にプロジェクトを妨げるのは、すでに持っているメッシュです。先週モデリングしたキットバッシュ、アートディレクションに合わないマテリアルのマーケットプレイスプロップ、金曜日までに腐食した鋼鉄のように見せる必要があるグレーボックスなどです。texture_existing_asset は、提供されたメッシュを受け取り、すでに承認したジオメトリを再生成することなく、新しいPBRマテリアルを適用します。

すべてが記録されます。各ジョブは、プロンプト、シード、プロバイダーのモデルバージョン、プロバイダーのタスクID、ダウンロードされたすべてのバイトのSHA-256を保持します。これにより、6か月後でも「このファイルは何から生成されたのか？」という問いに答えられます。

このサーバーは設計上、プロバイダーに依存しません。現在は、3D用にTripo、参照画像用にLeonardo.Aiを、2つの小さなインターフェース（ImageProvider、Model3DProvider）の背後で利用しています。プロバイダーを追加してもツールの表面は変わりません。このように構築された理由については、docs/architecture.mdを参照してください。

要件

• Node.js >= 18.17 — サーバーはグローバルな fetch、FormData、Blob、AbortController を使用します。

• ネイティブモジュール、ビルドツールチェーン、データベースは不要です。Nodeが動作する場所ならどこでも動作します。

• 少なくとも1つのプロバイダーAPIキー（設定を参照）。1つで十分です。遅延検証されます。

インストール

恒久的にインストールせずに実行するには：

npx game-asset-mcp

またはプロジェクトにインストールするには：

npm install game-asset-mcp

またはソースからビルドするには：

git clone https://github.com/<your-account>/game-asset-mcp.git
cd game-asset-mcp
npm install
npm run build     # emits dist/
node dist/server.js

サーバーはstdio上でMCPを話します。ターミナルで直接起動すると、クライアントが話しかけるのを待ってただそこに座っているだけです。これは正しい動作であり、ハングではありません。ログはstderrに出力され、stdoutはプロトコル用です。

設定

.env.example を .env にコピーするか、MCPクライアントの env ブロックに変数を設定します（通常は後者の方が良い選択です。以下のスニペットを参照）。

⚠️ Tripo APIクレジットはTripo Studioサブスクリプションとは別に請求されます

これはほぼ全員が引っかかります。Tripo StudioのWebサブスクリプションはAPI呼び出しの資金にはなりません。 これらは異なる残高を持つ異なる製品です。Studio Webアプリでモデルを生成して満足していたのに、最初の create_3d_asset 呼び出しがクレジット不足で拒否された場合、設定を誤ったわけではありません。開発者プラットフォームでAPIクレジットが必要なのです。Studioアプリではなく、platform.tripo3d.ai で購入してください。

1つのプロバイダーで十分

認証情報は遅延検証され、ツールが必要とした瞬間に検証され、起動時には決して検証されません。TRIPO_API_KEY のみを設定した場合、サーバーは正常に起動し、すべての3Dツールが動作します。画像ツールは、不足している変数を指定した明確な CONFIG_MISSING エラーを返します。逆も同様です。使用したいパイプラインの半分だけを使うために、不要なアカウントを保持することを強制されることはありません。

MCPクライアントのセットアップ

Claude Code / Claude Desktop

MCP設定（claude_desktop_config.json、またはClaude Codeのプロジェクト内の.mcp.json）に追加します：

{
  "mcpServers": {
    "game-asset": {
      "command": "node",
      "args": ["/absolute/path/to/game-asset-mcp/dist/server.js"],
      "env": {
        "TRIPO_API_KEY": "tsk_...",
        "LEONARDO_API_KEY": "...",
        "ASSET_OUTPUT_DIR": "/absolute/path/to/your/project/assets/generated",
        "ASSET_LOG_LEVEL": "info"
      }
    }
  }
}

args と ASSET_OUTPUT_DIR には絶対パスを使用してください。MCPクライアントの作業ディレクトリは、あなたが思っているものとは異なります。相対出力ディレクトリを使用すると、アセットが予期しない場所に散らばります。

その他のMCPクライアント

同じサーバーを汎用的に記述したもの — stdio子プロセス：

{
  "name": "game-asset",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "game-asset-mcp"],
  "env": {
    "TRIPO_API_KEY": "tsk_...",
    "LEONARDO_API_KEY": "...",
    "ASSET_OUTPUT_DIR": "/absolute/path/to/assets/generated"
  }
}

利用可能なツール

お金がかかるツールは5つだけで、それぞれの説明にその旨が記載されています。

ワークフロー例

フルパイプライン：アイデアから検査済みアセットまで

1. generate_asset_reference   → spends image credits, returns assetJobId + N candidates
2. (inspect the images)       → look at the returned reference images and choose one
3. select_reference           → free; records which candidate wins
4. create_3d_asset            → spends 3D credits, returns a task to poll
5. get_asset_job              → free; poll until status is "ready" (or "failed")
6. download_asset             → free; pulls model + textures + previews into the workspace
7. inspect_asset              → free; confirms what actually landed on disk

ステップ2は飾りではありません。3Dクレジットを使う前に参照を選ぶことが、パイプラインがここで分割されている理由のすべてです。悪い参照は溶けたメッシュを生み出し、その発見は再構築の支払い後にしかできません。

リテクスチャ：より短く、より安く、ほとんどのツールにはないフロー

メッシュはすでにあります。参照するものも、選択するものも、再構築するものもありません：

1. texture_existing_asset     → spends texturing credits on a mesh you supply
2. get_asset_job              → free; poll until ready
3. download_asset             → free
4. inspect_asset              → free

2回の代わりに1回の有料呼び出しで、すでに承認したジオメトリは変更されずに戻ってきます。

コストと副作用

プロバイダークレジットを消費する呼び出し： generate_asset_reference、generate_reference_variations、create_3d_asset、texture_existing_asset、および create_game_prop 内の画像生成ステップ。このサーバーで課金されるものは他にありません。

無料の呼び出し： select_reference、get_asset_job、download_asset、inspect_asset、list_asset_jobs。ポーリングとダウンロードは何度でも行えます。

クレジットを消費するPOSTは自動的に再試行されません。 これは意図的で重要なルールであり、各呼び出しサイトではなくHTTPレイヤーに存在します。生成タスクを作成するリクエストが失敗した場合（タイムアウト、ソケットリセット、502）、クライアントは接続が切れる前にプロバイダーがそれを受け入れたかどうかを知ることはできません。再試行は無料かもしれませんが、受け取らないメッシュに対して二重に請求される可能性もあります。そのため再試行は行われず、エラーが直接返され、再試行するかどうかの決定はあなたに委ねられます。冪等な読み取り（ステータスポーリング、ファイルダウンロード）は、繰り返してもコストがかからないため、バックオフ付きで自由に再試行されます。

知っておくべきその他の副作用：

• ファイルはディスクに書き込まれます。 すべては ASSET_OUTPUT_DIR の下に置かれます。その外には何も書き込まれません。パスは解決され、ワークスペースルートから外れるものは拒否されます。

• 何も黙って上書きされません。 アセット名が衝突した場合は、すでにレビューした結果を破壊するのではなく、数値サフィックス（crate、crate_2、…）が付けられます。

• ダウンロードは上限 ASSET_MAX_DOWNLOAD_BYTES で制限され、上限はストリーミング中に強制されます。Content-Length ヘッダーからではありません。サイズについて嘘をつくサーバーでもメモリを枯渇させることはできません。

• HTTPSのみ。 HTTPS以外のURLは、プロバイダーの応答内に含まれるものも含めて、完全に拒否されます。

• APIキーはログから一元的に編集されます。そのため、個々のログ呼び出しサイトがキーを漏らすことはありません。

ワークスペースのレイアウト

すべてのアセットは自己完結型のディレクトリを取得します。6か月後にファイルブラウザで開いても、それ自体が説明します：

assets/generated/
├── .jobs/                          job records, one JSON file per job
│   └── asset_<uuid>.json
└── <asset_name>/
    ├── asset.json                  complete provenance: spec, prompt, seed,
    │                               model version, provider ids, file hashes
    ├── source/                     the reference image(s) the mesh was built from
    ├── model/                      the mesh (GLB by default)
    ├── textures/                   extracted PBR maps
    ├── previews/                   provider-rendered turnarounds
    └── metadata/                   raw provider payloads, kept for debugging

<asset_name> はスペックの名前をサニタイズしたものです。小文字化され、英数字以外はアンダースコアに変換されます。.jobs ディレクトリは意図的にドットディレクトリになっています。アセットワークスペースを閲覧するとき、帳簿ではなくアセットが表示されるべきだからです。

トラブルシューティング

すべてのエラーには、機械可読な code と retryable フラグが含まれているため、エージェントは散文を解析することなく次に何をすべきかを決定できます。

CONFIG_MISSING — 認証情報がありません。 呼び出したツールには、設定していないプロバイダーが必要です。メッセージには正確な環境変数が示されています。MCPクライアントの env ブロックに設定してクライアントを再起動してください。.env ファイルは、サーバーの作業ディレクトリがあなたが思っている場所にある場合にのみ読み取られますが、MCPクライアントの下では通常そうではありません。

PROVIDER_HTTP ステータス401/403 — APIキーが無効です。 キーが間違っているか、失効しているか、別のプロバイダーのものです。特に2つの落とし穴があります：LeonardoキーはアカウントでAPIアクセスを有効にする必要があります（Webログインだけでは付与されません）。また、APIクレジット残高がないTripoキーは、キー自体は有効でも最初の有料呼び出しで失敗する可能性があります。上記のクレジット警告を参照してください。

RATE_LIMITED — HTTP 429。 再試行可能とマークされています。ポーリングとダウンロードはバックオフして自動的に再試行します（400 ms、800 ms、1600 ms、最大8秒）。生成リクエストは再試行されません。ウィンドウが空いたら、コストがかかるため、意図的に自分で再試行してください。

PROVIDER_TASK_FAILED — タスクがプロバイダー側で失敗しました。 HTTP呼び出しは成功しましたが、生成は行われませんでした。プロバイダーのメッセージ自体はエラー詳細に保持されます。モデレーション拒否もここに該当します。そのまま再試行するのではなく、プロンプトを書き直してください。Tripoのレスポンスは、HTTP 200でエンベロープのcodeが非ゼロになる場合があることに注意してください。それは失敗であり、このサーバーはそれを幻の成功として報告するのではなく、失敗として扱います。

ダウンロードがPROVIDER_HTTP 403/404で失敗 — URLが期限切れです。 これは最も一般的な驚きです。プロバイダーのモデルおよびプレビューURLは短命です。 署名付きで、期限が切れます。20分前に機能したURLは現在は無効です。修正方法は同じURLを再試行することではありません。get_asset_jobを再度呼び出してプロバイダーから新しいURLを再ポーリングし、すぐにdownload_assetを呼び出してください。習慣として、ジョブがreadyを報告したらすぐにダウンロードし、長いセッションの最後にダウンロードしないでください。

INVALID_INPUT — サポートされていない画像形式です。 参照画像は標準的なWebセーフなラスター形式（PNG、JPEG、WebP）である必要があります。HDR、EXR、レイヤー付きPSD、SVG、マルチページTIFFは再構築可能な入力ではありません。texture_existing_assetの場合、メッシュはGLB、GLTF、FBX、OBJ、STLのいずれかである必要があります。最初に変換してください。プロバイダーは変換してくれません。

PROVIDER_MALFORMED_RESPONSE — プロバイダーが予期しないものを返しました。 非JSONボディ、空のエンベロープ、データなしの成功、またはファイルトークンを返さないアップロード。通常はプロバイダー側のインシデントまたはAPIバージョンのずれを意味します。ASSET_LOG_LEVEL=debugを設定してリクエストの形状を確認し（キーは編集されます）、バグがローカルにあると想定する前にプロバイダーのステータスページを確認してください。

DOWNLOAD_TOO_LARGE。 ファイルがASSET_MAX_DOWNLOAD_BYTESを超えました。高品質のPBR GLBは大きくなる可能性があります。本当にファイルが必要な場合は制限を引き上げてください。

PATH_ESCAPE。 プロバイダーが提供したファイル名がワークスペースの外に解決しようとしました。書き込みは拒否されました。通常の操作では発生しないはずです。発生した場合は問題を開いてください。

ステータス

これは初期のソフトウェアであり、変更される可能性が最も高い部分は、静かに想定されるのではなく、そのようにマークされています。

Tripoのv3エンドポイントパスは、正確に1つのモジュール（src/providers/model3d/tripo.ts）に固定され、その先頭のコメントに文書化されています。Tripoの公開ドキュメントはv3のサーフェスを2つの異なる方法で説明しています。一般的なタスクエンドポイントと操作ごとのパスです。両方が現在のドキュメントに存在します。このクライアントはタスク形式を実装しており、これはすべての生成がtask_idを返してポーリングするという観察可能な動作と一致し、コードを編集せずに再ターゲットできるようにTRIPO_BASE_URLを公開しています。パスはライブスモークテストが最初にチェックするものです。間違ったパスは、不正なAPIキーとまったく同じように見える404を返すためです。

ライブプロバイダーAPIへの呼び出しは一度も行われていません。 これがここで最も重要な注意事項であるため、埋もれずに明確に述べられています。165のテストはすべてモックまたはローカルファイルシステムに対して実行されます。プロンプト構築、ステータスマッピング、パス安全性、ジョブストア、HTTPレイヤーの再試行とリダイレクトルール、実際のファイルに対するglTF検査をカバーしていますが、グリーンスイートはLeonardoとTripoがこのクライアントが想定するように動作することを何も保証しません。

具体的には、これらは未検証のままです：

• 上記のTripo v3エンドポイントパス。

• texture_modelがアップロードされたメッシュ（file_token）を受け入れるか、以前のTripoタスク（original_model_task_id）によって生成されたメッシュのみを受け入れるか。これは、すでに所有しているモデルを再テクスチャリングできるかどうかを決定します。これはこのサーバーが存在する機能です。解決にはHDテクスチャ呼び出しが1回かかります。

• src/providers/image/leonardo.tsのLeonardoモデルID。公開ドキュメントから転記されました。GET /platformModelsと照合してください。古いIDは、不正なリクエストボディのように見えるHTTP 400として失敗します。LEONARDO_MODEL_IDと呼び出しごとのmodelIdの両方がエスケープハッチとして存在します。

実際のキーでこれを実行する最初の人物である場合は、エンドポイントパスを修正することを期待し、見つけた内容で問題を開いてください。

検証済みのもの： npm run verifyはサーバーをビルドし、実際のMCPクライアントでstdioを介して起動し、ハンドシェイクを完了し、11のツールすべてが登録されることをアサートします。これはプロトコルのラウンドトリップであり、バージョン文字列ではありません。ツールの登録に失敗したサーバーでも、問題なく起動します。

貢献

問題とプルリクエストを歓迎します。プロバイダーを追加する場合は、ImageProviderまたはModel3DProviderを実装し、他は変更しないでください。新しいプロバイダーがツールサーフェスの変更を強制する場合、抽象化が間違っており、それが最初に議論する価値のあるバグです。

ライセンス

MIT © 2026 Ben Haire。 LICENSEを参照してください。