game-asset-mcp

Ein MCP-Server, der es einem KI-Agenten ermöglicht, spielfertige 3D-Assets Ende-zu-Ende zu erstellen – Referenzbild, Mesh, PBR-Texturen, Herkunft – und Meshes neu zu texturieren, die du bereits besitzt.

Die meisten Asset-Generierungstools enden bei „Prompt eingeben, Mesh erhalten“. Das ist die einfache Hälfte. Die Hälfte, die ein Projekt tatsächlich blockiert, ist das Mesh, das du bereits hast: das Kitbash, das du letzte Woche modelliert hast, das Marktplatz-Prop, dessen Materialien nicht zu deiner Art Direction passen, der Greybox, der bis Freitag wie korrodierter Stahl aussehen muss. texture_existing_asset nimmt ein Mesh, das du lieferst, und gibt ihm neue PBR-Materialien, ohne die Geometrie neu zu generieren, die du bereits freigegeben hast.

Alles wird protokolliert. Jeder Job behält den Prompt, den Seed, die Provider-Modellversion, die Provider-Task-ID und einen SHA-256-Hash für jedes heruntergeladene Byte – damit du sechs Monate später noch beantworten kannst: „Was hat diese Datei erzeugt?“

Der Server ist von Natur aus provider-agnostisch. Heute steuert er Tripo für 3D und Leonardo.Ai für Referenzbilder, hinter zwei kleinen Schnittstellen (ImageProvider, Model3DProvider). Das Hinzufügen eines Providers ändert die Tool-Oberfläche nicht. Siehe docs/architecture.md für die Gründe, warum es so aufgebaut ist.

Anforderungen

• Node.js >= 18.17 – der Server verwendet globales fetch, FormData, Blob und AbortController.

• Keine nativen Module, keine Build-Toolchain, keine Datenbank. Er läuft überall, wo Node läuft.

• Mindestens ein Provider-API-Schlüssel (siehe Konfiguration). Einer reicht – sie werden lazy validiert.

Installation

Führe es aus, ohne etwas dauerhaft zu installieren:

npx game-asset-mcp

Oder installiere es in ein Projekt:

npm install game-asset-mcp

Oder baue es aus dem Quellcode:

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

Der Server spricht MCP über stdio. Direkt in einem Terminal gestartet, wartet er einfach darauf, dass ein Client mit ihm spricht – das ist korrektes Verhalten, kein Hänger. Logs gehen an stderr; stdout gehört zum Protokoll.

Konfiguration

Kopiere .env.example in .env oder setze die Variablen im env-Block deines MCP-Clients (was meist die bessere Option ist – siehe die Snippets unten).

⚠️ Tripo-API-Guthaben wird getrennt von einem Tripo-Studio-Abonnement abgerechnet

Das erwischt fast jeden. Ein Tripo-Studio-Web-Abonnement finanziert keine API-Aufrufe. Es sind zwei verschiedene Produkte mit zwei verschiedenen Kontoständen. Wenn du fröhlich Modelle in der Studio-Web-App generiert hast und dein allererster create_3d_asset-Aufruf wegen unzureichendem Guthaben abgelehnt wird, hast du nichts falsch konfiguriert – du brauchst API-Guthaben auf der Entwicklerplattform. Kaufe es unter platform.tripo3d.ai, nicht in der Studio-App.

Ein Provider reicht

Anmeldedaten werden lazy validiert, erst wenn ein Tool sie benötigt, niemals beim Start. Wenn du nur TRIPO_API_KEY setzt, startet der Server einwandfrei und alle 3D-Tools funktionieren; die Bild-Tools geben einen klaren CONFIG_MISSING-Fehler zurück, der die fehlende Variable benennt. Das Gegenteil gilt ebenfalls. Du bist nie gezwungen, ein Konto zu haben, das du nicht willst, nur um die Hälfte der Pipeline zu nutzen, die du willst.

MCP-Client-Einrichtung

Claude Code / Claude Desktop

Füge zu deiner MCP-Konfiguration hinzu (claude_desktop_config.json oder .mcp.json in einem Projekt für Claude Code):

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

Verwende einen absoluten Pfad für args und für ASSET_OUTPUT_DIR. Das Arbeitsverzeichnis eines MCP-Clients ist nicht das, das du denkst, und ein relatives Ausgabeverzeichnis verteilt Assets an einem überraschenden Ort.

Jeder andere MCP-Client

Derselbe Server, generisch beschrieben – ein stdio-Unterprozess:

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

Verfügbare Tools

Nur fünf Tools können Geld kosten, und jedes sagt das in seiner Beschreibung, bevor es aufgerufen wird.

Beispiel-Workflow

Vollständige Pipeline: von der Idee zum inspizierten Asset

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

Schritt 2 ist keine Dekoration. Die Referenz auszuwählen, bevor 3D-Guthaben ausgegeben wird, ist der ganze Grund, warum die Pipeline hier geteilt ist: Eine schlechte Referenz erzeugt ein geschmolzenes Mesh, und das entdeckst du erst nachdem du für die Rekonstruktion bezahlt hast.

Retexturierung: kürzer, billiger und der Ablauf, den die meisten Tools nicht haben

Du hast das Mesh bereits. Es gibt nichts zu referenzieren, nichts auszuwählen, nichts zu rekonstruieren:

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

Ein bezahlter Aufruf statt zwei, und die Geometrie, die du bereits freigegeben hast, kommt unverändert zurück.

Kosten und Nebenwirkungen

Aufrufe, die Provider-Guthaben verbrauchen: generate_asset_reference, generate_reference_variations, create_3d_asset, texture_existing_asset und der Bildgenerierungsschritt innerhalb von create_game_prop. Nichts anderes auf diesem Server kann in Rechnung gestellt werden.

Aufrufe, die kostenlos sind: select_reference, get_asset_job, download_asset, inspect_asset, list_asset_jobs. Frage ab und lade herunter, so oft du willst.

Ein guthabenverbrauchender POST wird niemals automatisch wiederholt. Dies ist eine bewusste, tragende Regel und sie lebt in der HTTP-Schicht, nicht an jedem Aufrufort. Wenn eine Anfrage, die eine Generierungsaufgabe erstellt, fehlschlägt – Timeout, Socket-Reset, 502 – kann der Client nicht erkennen, ob der Provider sie akzeptiert hat, bevor die Verbindung abbrach. Ein erneuter Versuch könnte kostenlos sein; er könnte dich auch doppelt für ein Mesh belasten, das du nie erhältst. Also wird nicht wiederholt, der Fehler kommt direkt zurück, und die Entscheidung, es erneut zu versuchen, liegt bei dir. Idempotente Lesevorgänge – Statusabfragen, Dateidownloads – werden frei mit Backoff wiederholt, weil sie nichts kosten, wenn sie wiederholt werden.

Andere Nebenwirkungen, die du kennen solltest:

• Dateien werden auf die Festplatte geschrieben. Alles landet unter ASSET_OUTPUT_DIR. Nichts wird außerhalb geschrieben: Pfade werden aufgelöst und jeder, der die Workspace-Wurzel verlässt, wird abgelehnt.

• Nichts wird stillschweigend überschrieben. Ein kollidierender Asset-Name erhält ein numerisches Suffix (crate, crate_2, …), anstatt ein Ergebnis zu zerstören, das du möglicherweise bereits geprüft hast.

• Downloads sind begrenzt auf ASSET_MAX_DOWNLOAD_BYTES, und die Grenze wird während des Streamings durchgesetzt, nicht anhand des Content-Length-Headers – ein Server, der über die Größe lügt, kann deinen Speicher nicht erschöpfen.

• Nur HTTPS. Nicht-HTTPS-URLs werden rundweg abgelehnt, einschließlich solcher, die in einer Provider-Antwort ankommen.

• API-Schlüssel werden zentral aus Logs entfernt, sodass keine einzelne Log-Aufrufstelle einen durchsickern lassen kann.

Workspace-Layout

Jedes Asset erhält ein eigenständiges Verzeichnis. Öffne es sechs Monate später in einem Dateibrowser, und es erklärt sich immer noch selbst:

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> ist der Name deiner Spezifikation, bereinigt: kleingeschrieben, Nicht-Alphanumerisches zu Unterstrichen zusammengezogen. Das .jobs-Verzeichnis ist absichtlich ein Punktverzeichnis – das Durchsuchen deines Asset-Workspaces sollte Assets zeigen, keine Buchhaltung.

Fehlerbehebung

Jeder Fehler trägt einen maschinenlesbaren code und ein retryable-Flag, sodass ein Agent entscheiden kann, was als Nächstes zu tun ist, ohne Prosa zu parsen.

CONFIG_MISSING – fehlende Anmeldedaten. Das aufgerufene Tool benötigt einen Provider, den du nicht konfiguriert hast. Die Meldung nennt die genaue Umgebungsvariable. Setze sie im env-Block deines MCP-Clients und starte den Client neu – eine .env-Datei wird nur gelesen, wenn das Arbeitsverzeichnis des Servers das ist, das du denkst, was unter einem MCP-Client normalerweise nicht der Fall ist.

PROVIDER_HTTP mit Status 401/403 – ungültiger API-Schlüssel. Der Schlüssel ist falsch, widerrufen oder gehört zum falschen Provider. Zwei spezifische Fallen: Leonardo-Schlüssel benötigen API-Zugriff auf dem Konto (ein Web-Login allein gewährt ihn nicht), und ein Tripo-Schlüssel ohne API-Guthaben kann beim ersten bezahlten Aufruf fehlschlagen, obwohl der Schlüssel selbst gültig ist. Siehe die Guthaben-Warnung oben.

RATE_LIMITED — HTTP 429. Als wiederholbar markiert. Abfragen und Downloads führen einen Backoff durch und wiederholen automatisch (400 ms, 800 ms, 1600 ms, begrenzt auf 8 s). Generierungsanfragen tun das nicht – wiederholen Sie diese selbst, sobald das Fenster frei ist, bewusst, weil sie Geld kosten.

PROVIDER_TASK_FAILED — die Aufgabe ist auf Anbieterseite fehlgeschlagen. Der HTTP-Aufruf war erfolgreich, die Generierung jedoch nicht. Die eigene Nachricht des Anbieters bleibt in den Fehlerdetails erhalten. Auch eine Moderation-Ablehnung landet hier: Formulieren Sie den Prompt um, anstatt ihn unverändert erneut zu versuchen. Beachten Sie, dass eine Tripo-Antwort HTTP 200 mit einem von Null verschiedenen Envelope-code tragen kann; das ist ein Fehler, und dieser Server behandelt ihn als solchen, anstatt einen Phantom-Erfolg zu melden.

Download schlägt mit PROVIDER_HTTP 403/404 fehl — die URL ist abgelaufen. Das ist die mit Abstand häufigste Überraschung. Provider-Modell- und Vorschau-URLs sind kurzlebig. Sie sind signiert, laufen ab, und eine URL, die vor zwanzig Minuten funktioniert hat, ist jetzt tot. Die Lösung ist nicht, dieselbe URL erneut zu versuchen – rufen Sie get_asset_job erneut auf, um den Anbieter nach frischen URLs zu befragen, und führen Sie dann sofort download_asset aus. Als Gewohnheit: Laden Sie herunter, sobald ein Auftrag ready meldet, nicht am Ende einer langen Sitzung.

INVALID_INPUT — nicht unterstütztes Bildformat. Referenzbilder sollten standardmäßige websichere Rasterformate sein (PNG, JPEG, WebP). HDR, EXR, mehrschichtige PSD, SVG und mehrseitige TIFF sind keine rekonstruierbaren Eingaben. Für texture_existing_asset müssen Meshes GLB, GLTF, FBX, OBJ oder STL sein. Konvertieren Sie zuerst; der Anbieter wird das nicht für Sie tun.

PROVIDER_MALFORMED_RESPONSE — der Anbieter hat etwas Unerwartetes zurückgegeben. Nicht-JSON-Body, ein leerer Envelope, ein Erfolg ohne Daten oder ein Upload ohne zurückgegebenes Datei-Token. Das bedeutet normalerweise einen anbieterseitigen Vorfall oder eine Abweichung der API-Version. Setzen Sie ASSET_LOG_LEVEL=debug, um die Anfrageform zu sehen (Schlüssel sind redigiert), und prüfen Sie die Statusseite des Anbieters, bevor Sie annehmen, dass der Fehler lokal ist.

DOWNLOAD_TOO_LARGE. Die Datei hat ASSET_MAX_DOWNLOAD_BYTES überschritten. Ein hochwertiges PBR-GLB kann groß sein; erhöhen Sie das Limit, wenn Sie die Datei wirklich möchten.

PATH_ESCAPE. Ein vom Anbieter gelieferter Dateiname versuchte, außerhalb Ihres Arbeitsbereichs aufzulösen. Der Schreibvorgang wurde verweigert. Das sollte im normalen Betrieb nie passieren – bitte öffnen Sie ein Issue, falls es doch passiert.

Status

Dies ist frühe Software, und die Teile, die am wahrscheinlichsten abweichen, sind als solche markiert, anstatt stillschweigend angenommen zu werden.

Tripos v3-Endpunktpfade sind in genau einem Modul festgelegt (src/providers/model3d/tripo.ts) und in einem Kommentar am Anfang davon dokumentiert. Tripos öffentliche Dokumentation beschreibt die v3-Oberfläche auf zwei verschiedene Arten – einen generischen Aufgaben-Endpunkt und pro-Operation-Pfade – und beide erscheinen in der aktuellen Dokumentation. Dieser Client implementiert die Aufgabenform, die dem beobachtbaren Verhalten entspricht, dass jede Generierung eine task_id zum Abfragen zurückgibt, und stellt TRIPO_BASE_URL bereit, sodass Sie ohne Codeänderung umzielen können. Die Pfade sind das erste, was der Live-Smoke-Test prüft, denn ein falscher Pfad gibt einen 404 zurück, der genau wie ein falscher API-Schlüssel aussieht.

Es wurde noch nie ein Aufruf an eine Live-Provider-API gemacht. Das ist der wichtigste Vorbehalt hier, daher wird er klar ausgesprochen und nicht versteckt. Jeder der 165 Tests läuft gegen Mocks oder das lokale Dateisystem. Sie decken Prompt-Konstruktion, Statuszuordnung, Pfadsicherheit, den Auftragsspeicher, die Wiederholungs- und Weiterleitungsregeln der HTTP-Schicht und die glTF-Inspektion anhand echter Dateien ab – aber eine grüne Testsuite sagt nichts darüber aus, ob sich Leonardo und Tripo so verhalten, wie dieser Client annimmt.

Konkret bleiben diese unverifiziert:

• Die oben beschriebenen Tripo-v3-Endpunktpfade.

• Ob texture_model ein hochgeladenes Mesh (file_token) akzeptiert oder nur ein Mesh, das von einer früheren Tripo-Aufgabe erzeugt wurde (original_model_task_id). Das entscheidet, ob Sie ein Modell, das Sie bereits besitzen, neu texturieren können – das ist die Funktion, für die dieser Server existiert. Die Auflösung kostet einen HD-Texturaufruf.

• Die Leonardo-Modell-IDs in src/providers/image/leonardo.ts, die aus veröffentlichter Dokumentation transkribiert wurden. Prüfen Sie sie gegen GET /platformModels; eine veraltete ID schlägt als HTTP 400 fehl, das wie ein fehlerhafter Anforderungstext aussieht. Sowohl LEONARDO_MODEL_ID als auch ein modelId pro Aufruf existieren als Notluken.

Wenn Sie die erste Person sind, die dies mit echten Schlüsseln ausführt, rechnen Sie damit, einen Endpunktpfad zu korrigieren, und öffnen Sie bitte ein Issue mit dem, was Sie gefunden haben.

Was ist verifiziert: npm run verify baut den Server, startet ihn über stdio mit einem echten MCP-Client, führt den Handshake durch und stellt fest, dass alle elf Tools registriert sind. Das ist ein Protokoll-Roundtrip, keine Versionszeichenkette – ein Server, der seine Tools nicht registriert, startet trotzdem problemlos.

Mitwirken

Issues und Pull-Requests sind willkommen. Wenn Sie einen Provider hinzufügen, implementieren Sie ImageProvider oder Model3DProvider und ändern Sie sonst nichts – wenn ein neuer Provider eine Änderung an der Tool-Oberfläche erzwingt, ist die Abstraktion falsch, und das ist der Fehler, der zuerst besprochen werden sollte.

Lizenz

MIT © 2026 Ben Haire. Siehe LICENSE.