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, Provenienz – und Meshes neu zu texturieren, die du bereits besitzt.

Die meisten Asset-Generierungs-Tools hören bei „Prompt eingeben, Mesh erhalten" auf. 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 Auftrag speichert den Prompt, den Seed, die Provider-Modellversion, die Provider-Task-ID und einen SHA-256 für jedes heruntergeladene Byte – so kannst du sechs Monate später immer noch beantworten: „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 und Soundeffekte, hinter drei kleinen Schnittstellen (ImageProvider, Model3DProvider, AudioProvider). 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.

• Optional: Eine lokale Blender-Installation 4.x+ ermöglicht die Reparatur-Hälfte von normalize_mesh und batch_prepare_meshes. Jedes andere Tool funktioniert ohne sie; das Tool verweigert mit Anweisungen, wenn es fehlt. Auf macOS ist Blender nicht im PATH, also setze BLENDER_PATH oder verlasse dich auf den gebündelten Standard /Applications/Blender.app.

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

Related MCP server: Context3D MCP Server

Installation

Direkt von GitHub installieren. Beide Formen bauen das TypeScript während der Installation, sodass du in beiden Fällen ein ausführbares game-asset-mcp-Binary erhältst.

# run it without installing anything permanently
npx github:theisegoria/game-asset-mcp

# or add it to a project
npm install github:theisegoria/game-asset-mcp

# pin a specific version — recommended for anything you depend on
npm install github:theisegoria/game-asset-mcp#v0.3.7

Version pinnen. Ohne ein #vX.Y.Z-Suffix lösen beide Formen auf, was main zu diesem Zeitpunkt ist, was keine stabile Abhängigkeit darstellt. Jede Version ist getaggt, also bekommst du mit #v0.3.7 genau diesen Baum. Versionen sind unter github.com/theisegoria/game-asset-mcp/releases aufgelistet, jede mit den Fehlern, die diese Version behoben hat.

⛔ Pinne nicht v0.3.0, v0.3.1 oder v0.3.2. Spätere Überprüfungen fanden Live-Pfade in diesen, die das Mesh, das du übergibst, zerstören und Erfolg melden. Sie sind nur getaggt, damit die Historie vollständig ist. Ihre Release-Seiten sagen das auch.

Oder arbeite von einem Klon, was du willst, wenn du etwas ändern möchtest:

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

Nicht auf npm. Es gibt kein npm install @theisegoria/game-asset-mcp – das Paket wird nur über GitHub verteilt. Alles, was dir etwas anderes sagt, ist veraltet.

Der Server spricht MCP über stdio. Direkt in einem Terminal gestartet, sitzt er einfach da und wartet auf einen Client, der mit ihm spricht – das ist korrektes Verhalten, kein Hängen. Logs gehen an stderr; stdout gehört zum Protokoll.

Konfiguration

Setze diese in den env-Block deines MCP-Clients – siehe die Ausschnitte unten. Es gibt kein .env-Laden: Der Server liest process.env und sonst nichts, also tut eine .env-Datei auf der Festplatte nichts, es sei denn, deine Shell oder dein Client exportiert sie zuerst.

⚠️ 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 Guthaben. 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.

Begrenzung der Ausgaben

Setze ASSET_SPEND_LIMIT_CENTS und jedes kreditverbrauchende Tool prüft es bevor es den Provider überhaupt kontaktiert – auch bevor ein Mesh oder ein Referenzbild hochgeladen wird – und verweigert mit dem verbleibenden Guthaben, anstatt zu überziehen. Die Obergrenze ist in US-Cent, weil die beiden Provider in unterschiedlichen Einheiten abrechnen – Tripo in $0.01-Guthaben, Leonardo in USD – und ein Limit, das sie mischt, würde nichts bedeuten.

Wo ein Provider einen Preis pro Aufruf veröffentlicht, verwenden wir ihn. Wo nicht, verwendet die Absicherung einen bewusst pessimistischen Platzhalter und get_spend_report sagt, welche Zahlen welche sind. Es ist eine Absicherung, keine Rechnung: Echte Gebühren sollten bei oder unter der Schätzung liegen, niemals darüber.

Ein Provider reicht

Anmeldeinformationen werden lazy validiert, in dem Moment, in dem ein Tool sie benötigt, niemals beim Start. Wenn du nur TRIPO_API_KEY setzt, startet der Server problemlos und alle 3D-Tools funktionieren; die Bild-Tools geben einen klaren CONFIG_MISSING-Fehler zurück, der die Variable benennt, die du vermisst. Das Gegenteil gilt auch. Du bist nie gezwungen, ein Konto zu halten, 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, was du denkst, und ein relatives Ausgabeverzeichnis verstreut 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", "github:theisegoria/game-asset-mcp"],
  "env": {
    "TRIPO_API_KEY": "tsk_...",
    "LEONARDO_API_KEY": "...",
    "ASSET_OUTPUT_DIR": "/absolute/path/to/assets/generated"
  }
}

Verfügbare Tools

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

Die kostenlose lokale Hälfte (keine API-Schlüssel, kein Netzwerk)

Elf der zwanzig Tools geben nie einen Credit aus, und nur zwei dieser elf nutzen überhaupt das Netzwerk – get_asset_job fragt ab, und download_asset lädt herunter; beide sind kostenlos, aber es sind Netzwerkaufrufe. Die anderen neun arbeiten offline. Die fünf unten sind die Mesh-Pipeline, und wenn du bereits Meshes hast, sind sie das gesamte Produkt.

Die übliche Schleife ist validieren → normalisieren → erneut validieren, damit die Reparatur bewiesen statt angenommen ist:

validate_game_asset  modelPath=/art/crate.glb
   → fails: uvs_present   ("nothing can texture this")
normalize_mesh       modelPath=/art/crate.glb  outputDir=/art/out
   → objectsUnwrapped=2, triangles 3183 → 1750
validate_game_asset  modelPath=/art/out/crate_normalized.glb
   → passes

batch_prepare_meshes führt diese Schleife über eine Liste aus und meldet jedes Element separat. Meshes, die bereits bestehen, bleiben unangetastet statt neu geschrieben zu werden, eine fehlerhafte Datei stoppt den Lauf nie, und zwei Quellen mit demselben Basisnamen erhalten unterschiedliche Ausgaben, statt sich gegenseitig zu überschreiben.

Fehlende UVs sind der Defekt, den man kennen sollte. Ein Mesh ohne UV-Koordinaten kann von nichts texturiert werden – nicht von diesem Tool, nicht von einem Anbieter, nicht von dir von Hand. Generatoren und Marketplace-Assets werden routinemäßig ohne sie ausgeliefert. validate_game_asset nennt sie aus diesem Grund zuerst.

Für die Normalisierung wird Blender benötigt (4.x+). Ohne ihn validieren und berichten die Tools weiterhin; sie können nur nicht reparieren. Auf macOS ist Blender nicht auf PATH, also setze entweder BLENDER_PATH oder verlasse dich auf den gebündelten Standardpfad /Applications/Blender.app.

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-Credits ausgegeben werden, ist der ganze Grund, warum die Pipeline hier geteilt ist: Eine schlechte Referenz erzeugt ein zerlaufenes 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 Nebeneffekte

Aufrufe, die Anbieter-Credits verbrauchen: generate_asset_reference, generate_reference_variations, create_3d_asset, texture_existing_asset, generate_sound_effect, rig_asset, animate_asset, retopologize_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, preview_asset_prompt, extract_pbr_trio, normalize_mesh, validate_game_asset, batch_prepare_meshes, get_spend_report. Frag ab, inspiziere, zerlege und lade herunter, so oft du möchtest.

Ein kostenpflichtiger POST wird niemals automatisch wiederholt. Das 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 wissen, ob der Anbieter sie angenommen hat, bevor die Verbindung abbrach. Ein erneuter Versuch könnte kostenlos sein; er könnte Sie aber auch doppelt für ein Mesh belasten, das Sie nie erhalten. Also wird nicht wiederholt, der Fehler kommt direkt zurück, und die Entscheidung, es erneut zu versuchen, liegt bei Ihnen. Idempotente Lesevorgänge — Statusabfragen, Dateidownloads — werden frei mit Backoff wiederholt, weil sie nichts kosten, wenn man sie wiederholt.

Weitere Nebeneffekte, die wissenswert sind:

• Dateien werden auf die Festplatte geschrieben. Heruntergeladene Assets landen unter ASSET_OUTPUT_DIR, und ein Download-Pfad, der den Workspace-Root verlässt, wird verweigert. Drei Tools sind anders und bewusst so: extract_pbr_trio, normalize_mesh und batch_prepare_meshes schreiben dorthin, wo Sie es ihnen sagen, auch außerhalb des Workspace, weil sie mit Meshes arbeiten, die Sie bereits besitzen, und diese nicht in einem Asset-Generierungsverzeichnis liegen. Geben Sie ihnen ein Ziel, das Sie gemeint haben.

• download_asset und generate_sound_effect akzeptieren ein destination, das ASSET_OUTPUT_DIR für diesen einen Aufruf überschreibt. Es bleibt weiterhin eingeschränkt: Ein Pfad, der den angegebenen Root verlässt, wird verweigert.

• ASSET_OUTPUT_DIR sollte absolut sein. Ein relativer Wert wird relativ zum Arbeitsverzeichnis des Servers aufgelöst, das Ihr MCP-Client wählt — mehrere starten von /. Der Server weigert sich zu starten, mit einer Meldung, die den aufgelösten Pfad und das Arbeitsverzeichnis, aus dem er stammt, benennt. Diese Diagnose deckt die acht Errnos ab, die dies realistisch erzeugen kann — ENOENT, EACCES, EPERM, EROFS, ENOTDIR, ELOOP, ENAMETOOLONG und ENOSPC, einschließlich ASSET_OUTPUT_DIR, das auf eine Datei statt auf ein Verzeichnis zeigt. Alles andere wird weiterhin roh propagiert.

• Nichts wird stillschweigend überschrieben. Ein abgeleiteter Ausgabename erhält ein numerisches Suffix (crate, crate_2, …), anstatt ein Ergebnis zu zerstören, das Sie möglicherweise bereits geprüft haben, und der Name wird durch exklusives Erstellen beansprucht, sodass zwei Elemente in einem Batch nicht darum konkurrieren können. Ein explizites outputPath wird rundweg verweigert, wenn dort bereits eine Datei liegt, es sei denn, Sie übergeben overwrite: true — und es wird bedingungslos verweigert, ohne Ausweichmöglichkeit, wenn es auf das Eingabe-Mesh aufgelöst wird. Diese Auflösung berücksichtigt Symlinks, Hardlinks, case-insensitive Volumes und die Gewohnheit des Exporters, die Erweiterung umzuschreiben, denn jede einzelne davon hat hier bereits ein Quell-Mesh zerstört.

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

• Nur HTTPS. Nicht-HTTPS-URLs werden rundweg verweigert, einschließlich solcher, die in der Antwort eines Anbieters ankommen.

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

Workspace-Layout

Jedes Asset erhält ein in sich geschlossenes Verzeichnis. Öffnen Sie es sechs Monate später in einem Dateibrowser, und es erklärt sich immer noch von 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

<asset_name> ist der Name Ihrer Spezifikation, bereinigt: kleingeschrieben, Nicht-Alphanumerisches zu Unterstrichen zusammengezogen. Das .jobs-Verzeichnis ist absichtlich ein Punktverzeichnis — beim Durchsuchen Ihres Asset-Workspace sollten Assets zu sehen sein, keine Buchhaltung.

Fehlerbehebung

Jeder Fehler trägt ein maschinenlesbares error-Feld, das die Klasse benennt, plus ein retryable-Flag, sodass ein Agent entscheiden kann, was als Nächstes zu tun ist, ohne Prosa zu parsen. Die Namen unten sind die Werte dieses error-Felds.

Der Server startet und beendet sich sofort — der Client sagt nur „Verbindung geschlossen". Drei bekannte Ursachen, und der Server benennt die ersten beiden jetzt selbst, anstatt still zu sterben.

• Ein relativer ASSET_OUTPUT_DIR. Er wird relativ zum Arbeitsverzeichnis des Servers aufgelöst, das Ihr MCP-Client wählt — mehrere starten von /, wo assets/generated zu /assets wird und nicht erstellt werden kann. Verwenden Sie einen absoluten Pfad. Die Verweigerung benennt den aufgelösten Pfad und das Arbeitsverzeichnis, aus dem er stammt.

• Ein Workspace, in den der Prozess nicht schreiben kann. Dieselbe Verweigerung, anderer Errno.

• Ein veralteter Build. Wenn dist/ älter ist als eine Änderung am Einstiegspunkt, neu bauen. npm run verify baut und führt dann einen echten MCP-Handshake durch, was der schnellste Weg ist, einen defekten Server von einer defekten Client-Konfiguration zu unterscheiden.

normalize_mesh oder batch_prepare_meshes verweigert mit „Blender not found". Es gibt kein lokales Blender auf PATH. Unter macOS ist das App-Bundle nicht auf PATH, selbst wenn Blender installiert ist — setzen Sie BLENDER_PATH auf die ausführbare Datei im Bundle. batch_prepare_meshes degradiert, anstatt zu scheitern: Es validiert weiterhin jedes Mesh und berichtet, was repariert werden müsste.

CONFIG_MISSING — fehlende Anmeldedaten. Das von Ihnen aufgerufene Tool benötigt einen Anbieter, den Sie nicht konfiguriert haben. Die Meldung benennt die genaue Umgebungsvariable. Setzen Sie sie im env-Block Ihres MCP-Clients und starten Sie den Client neu. Eine .env-Datei wird niemals gelesen: Es gibt keine dotenv-Abhängigkeit, die Variable muss also von dem exportiert werden, was den Server startet.

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

RATE_LIMITED — HTTP 429. Als wiederholbar markiert. Polls fahren zurück und wiederholen automatisch (400 ms, 800 ms, 1600 ms, begrenzt auf 8 s). Downloads wiederholen nicht — download_asset streamt in einem Versuch, also geben Sie es selbst erneut aus; da Anbieter-URLs ablaufen, pollt zuerst erneut mit get_asset_job, anstatt eine veraltete URL erneut zu versuchen. Generierungsanfragen wiederholen ebenfalls nicht, bewusst, weil sie Geld kosten. Ein 429 während eines Downloads erscheint als PROVIDER_HTTP mit Status 429, nicht als RATE_LIMITED.

PROVIDER_TASK_FAILED — die Aufgabe ist anbieterseitig fehlgeschlagen. Der HTTP-Aufruf war erfolgreich, und die Generierung nicht. Die eigene Meldung des Anbieters bleibt in den Fehlerdetails erhalten. Eine Moderationsverweigerung landet ebenfalls hier: Formulieren Sie den Prompt um, anstatt ihn unverändert erneut zu versuchen. Beachten Sie, dass eine Tripo-Antwort HTTP 200 mit einem Nicht-Null-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, sie 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 pollen, und dann download_asset sofort. Als Gewohnheit: Laden Sie herunter, sobald ein Job ready meldet, nicht am Ende einer langen Sitzung.

INVALID_INPUT — nicht unterstütztes Bildformat. Referenzbilder sollten gängige webfähige Rasterformate sein (PNG, JPEG, WebP). HDR, EXR, mehrschichtiges PSD, SVG und mehrseitiges TIFF sind nicht rekonstruierbare 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, der kein Datei-Token zurückgab. Meist bedeutet das einen anbieterseitigen Vorfall oder eine API-Versionsabweichung. Setzen Sie ASSET_LOG_LEVEL=debug, um die Anfrageform zu sehen (Schlüssel sind geschwärzt), und prüfen Sie die Statusseite des Anbieters, bevor Sie annehmen, der Fehler sei lokal.

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

PATH_ESCAPE. Ein vom Anbieter gelieferter Dateiname versuchte, sich außerhalb Ihres Workspace aufzulösen. Der Schreibvorgang wurde verweigert. Das sollte im Normalbetrieb 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 als gegeben angenommen zu werden.

Tripos v3-Endpunktpfade sind in genau einem Modul festgeschrieben (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 Task-Endpunkt und pro-Operation-Pfade — und beide erscheinen in der aktuellen Dokumentation. Dieser Client implementiert die Task-Form, die dem beobachtbaren Verhalten entspricht, dass jede Generierung eine task_id zum Pollen zurückgibt, und stellt TRIPO_BASE_URL bereit, damit Sie ohne Codeänderung umzielen können. Wenn sie falsch sind, sehen Sie einen 404, der genauso aussieht wie ein falscher API-Schlüssel, also prüfen Sie den Pfad vor dem Schlüssel.

Es wurde noch nie ein Aufruf an eine echte Provider-API gemacht. Das ist der wichtigste Vorbehalt hier, also wird er klar ausgesprochen, anstatt vergraben zu werden. Jeder der 384 Tests läuft gegen Mocks oder das lokale Dateisystem. Sie decken Prompt-Konstruktion, Statuszuordnung, Pfadsicherheit, den Job-Store, die Retry- und Redirect-Regeln der HTTP-Schicht und glTF-Inspektion gegen echte Dateien ab — aber eine grüne Suite sagt nichts darüber aus, ob Leonardo und Tripo sich 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, was die Funktion ist, für die dieser Server existiert. Die Klärung kostet einen HD-Texturaufruf.

• Soundeffekt-Generierung ist unverifiziert. Leonardo dokumentiert den Sound Effects v2-Anfragevertrag (model, prompt, duration 1-22s, prompt_influence, loop, quantity), aber nicht seine Antwortform oder wie das fertige Audio abgerufen wird. Der Client liest die Generierungs-ID und Audio-URLs aus mehreren plausiblen Formen und wirft mit den NAMEN der Top-Level-Schlüssel der Antwort (nicht dem Body, der groß sein oder eine signierte URL tragen könnte), wenn keine übereinstimmt, anstatt einen leeren Erfolg zu melden. Erwarten Sie, dass der erste echte Aufruf eine Korrektur benötigt, und bitte öffnen Sie ein Issue mit der Payload-Form, die Sie gesehen haben.

• 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 Anfrage-Body aussieht. Sowohl LEONARDO_MODEL_ID als auch ein modelId pro Aufruf existieren als Ausweichmöglichkeiten.

Wenn Sie der Erste sind, der dies mit echten Schlüsseln ausführt, erwarten Sie, 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 bestätigt, dass alle zwanzig Tools registriert sind. Das ist ein Protokoll-Roundtrip, keine Versionszeichenkette — ein Server, der seine Tools nicht registriert, startet trotzdem vollkommen zufriedenstellend.

Teile der lokalen Pipeline — inspect_asset, extract_pbr_trio, normalize_mesh, validate_game_asset — werden zusätzlich gegen echte ausgelieferte Spiel-Assets geprüft, anstatt gegen Fixtures, weil ein synthetisches Fixture und der Parser, der es liest, denselben Fehler teilen können und beide grün aussehen. Das ist hier passiert: Eine falsche glTF-Magie-Konstante überlebte eine vollständige synthetische Suite und wurde nur durch eine echte Datei erwischt. Das UV-lose Mesh, das sie verwenden, ist hier eingecheckt, anstatt aus einem Schwester-Checkout gelesen zu werden. Früher wurde es live aus dem Spiel-Repo gelesen, und als dieses Mesh repariert wurde, wurden diese Tests rot für eine Änderung, die vollständig korrekt war — eine Assertion, die eine Tatsache über eine Datei festnagelt, die dieses Projekt nicht kontrolliert. Ein Test darf nicht von Inhalten abhängen, die er nicht besitzt.

Ein Test startet den gebauten Server über ein symlinkiertes bin – was node_modules/.bin tatsächlich enthält – und spricht MCP mit ihm, denn dort ist der Einstiegspunkt-Wächter fehlgeschlagen: Der Server beendete sich bei jeder Installation sofort, während er alle anderen Tests bestand. Er verwendet Symlinks statt einer Installation, kann also keine Verpackungsregression in files oder prepare erkennen; eine echte npm install von GitHub bleibt eine manuelle Prüfung.

Warum die Testanzahl nicht der Punkt ist

In 0.3.4 wurde jede der fünf wichtigsten Korrekturen der vorherigen Version einzeln rückgängig gemacht und die Testsuite erneut ausgeführt. Alle fünf überlebten – jeder Mutant war vollständig grün. Die Korrekturen waren real; nichts in der Suite hielt sie zurück. Die Ursache war eine einzige gemeinsame Annahme: Jeder gestubbte Blender beendete sich mit Exit-Code 0 und gab genau eine Quittung aus, sodass keine der Härtungen des Subprozess-Protokolls durch einen Test beobachtbar war.

Das ist es wert, in einer README festgehalten zu werden, denn es ist die ehrliche Lesart jeder Testanzahl, einschließlich dieser. Eine Suite zertifiziert die Annahmen des Autors, und ein Fehler, der innerhalb einer Annahme lebt, ist für jeden Test unsichtbar, der unter ihr geschrieben wurde. Geändert hat sich die Disziplin, nicht die Zahl: Korrekturen sind jetzt durch Tests abgesichert, die gegen den rückgängig gemachten Code ausgeführt wurden und nachweislich fehlschlugen, und gemeinsame Fakes werden als Verdächtige behandelt, nicht als Infrastruktur.

Dieselbe Prüfung hat einen schlechten Beweis zweimal in einer Sitzung erwischt. Zwei aufeinanderfolgende Fixtures, die geschrieben wurden, um eine Schweißschwellen-Korrektur zu beweisen, meldeten eine identische Dreiecksanzahl, sowohl mit korrektem als auch mit fehlerhaftem Code, und jedes von ihnen wäre als Beweis ausgeliefert worden. Ein Fixture ist kein Beweis, bis es sowohl mit dem korrigierten als auch mit dem fehlerhaften Code ausgeführt wurde und die beiden Zahlen ausgegeben wurden.

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 diskutiert werden sollte.

Lizenz

MIT © 2026 Ben Haire. Siehe LICENSE.