fvtt-mcp-artificer

Ein Foundry-spezifischer Bildgenerierungs-Model Context Protocol-Server für D&D-Table-Art, angetrieben von Claude Code. Er kapselt eine headless ComfyUI-Instanz auf dem lokalen Rechner und stellt eine kleine Reihe auf Foundry zugeschnittener Werkzeuge bereit, damit Claude Prompts verfassen, Illustrations-Batches erzeugen, die Ergebnisse durch tatsächliches Ansehen kuratieren und die Gewinner an die Foundry-Pipeline in seinem Schwester-Server fvtt-mcp-molten5e übergeben kann (upload-asset → set-actor-art / add-journal-image / Szenen-Hintergründe).

Der gesamte Kreislauf ist auf der Zielhardware (RTX 5090) schnell genug für eine dialogische Nutzung: Ein 6-Bilder-Entwurfsbatch liegt nach ~10 s vor, ein fertiger 2560×1600-Render nach ~19 s, und der vollständige Zyklus Prompt → Entwurf → Kuratieren → Finale → In-World-Journal wurde Ende-zu-Ende in notes/m3-loop-proof.md nachgewiesen.

Warum diese Form

Dies ist keine generische ComfyUI-Brücke, so die Vorgabe. Die Werkzeuge sprechen Foundry-Vokabular — Heldenporträts, Token, Handouts, Szenen-Hintergründe — und dürfen für die Foundry-Arbeit frei angepasst werden. Und es bleibt getrennt von fvtt-mcp-molten5e: Dieser Server ist auf die Erstellung von Foundry-Inhalten ausgerichtet und darf nicht an die Bildgenerierung gekoppelt werden. Dieser Server spricht nie mit der Foundry-Brücke; die Übergabe zwischen ihnen erfolgt über Dateien auf der Festplatte plus die Molten5e-Upload-Werkzeuge.

Gleiche Hausphilosophie wie im Rest der Familie: Werkzeuge tun, Skills entscheiden. Korrektheit (Workflow-Ausführung, Abmessungen, die Upscale-Pipeline, Dateikonventionen) steckt hier in getesteten Werkzeugen; Urteilsvermögen (Prompt-Handwerk, Geschmack beim Kuratieren, welcher Actor oder welches Journal die Kunst bekommt, Hausstil) steckt in einem späteren illustration-builder-Skill.

Claude ──MCP──> fvtt-mcp-artificer ──HTTP──> ComfyUI (headless, local)
                      │
                      └── pinned workflow JSONs (draft / final / final-refine / upscale)

ComfyUI läuft headless im API-Modus; dieser Server übermittelt die festgelegten Workflow-JSONs unter workflows/ — niemals frei formulierte Graphen — mit eingesetzten Prompt/Seed/Batch/Preset-Werten (per Knoten-ID, abgesichert durch Klassentyp-Drift-Assertions). Die Werkzeuge geben absolute Dateipfade zurück; Claude liest die PNGs direkt, um zu kuratieren.

Related MCP server: FoundryVTT MCP Server

Zweck-Presets statt roher Abmessungen

generate-image akzeptiert eine kind, nicht Breite/Höhe:

Auflösungs-Pipeline (festgelegt): niemals in Ausgabegröße erzeugen — die Komposition verschlechtert sich jenseits von ~1,5 MP. In der nativen Auflösung des Presets erzeugen, per Modell ×4 mit 4x-UltraSharp hochskalieren, per Lanczos auf die Endgröße verkleinern, alles in einem festgelegten Graphen.

Modelle

• FLUX.1-dev fp8 (Comfy-Org all-in-one) — Renderings in Endqualität, ~15–19 s fertig.

• FLUX.2-klein 4B (Apache 2.0) — das Entwurfsmodell: 4 Schritte, ~1–2 s/Bild, Batch 6–8, auswählen, mit dev neu rendern.

• 4x-UltraSharp — der Modell-Upscaler am Ende der Pipeline.

Werkzeuge

Der Substitutionsvertrag zwischen den Werkzeugen und den festgelegten Graphen ist in workflows/README.md dokumentiert.

Anforderungen

• Windows + NVIDIA-GPU. Entwickelt und nachgewiesen auf einer RTX 5090 (Blackwell benötigt PyTorch mit CUDA 12.8+; das aktuelle ComfyUI-Portable-Build wird damit ausgeliefert).

• ComfyUI (Standalone-Portable-Build, v0.34+) headless laufend — siehe scripts/launch-comfyui.ps1 für die Startkonvention (API-Modus auf 127.0.0.1:8188, festgelegtes --output-directory).

• Die Modelldateien im models/-Verzeichnisbaum von ComfyUI (~33 GB, alle frei verfügbar): checkpoints/flux1-dev-fp8.safetensors, diffusion_models/flux-2-klein-4b.safetensors, text_encoders/qwen_3_4b.safetensors, vae/flux2-vae.safetensors, upscale_models/4x-UltraSharp.safetensors. artificer-status meldet alles Fehlende.

• Node.js 22+ für den MCP-Server selbst.

Build

npm install
npm run build

Tests: npm test (Offline-Unit-Suite; die festgelegten Workflow-JSONs sind die Fixtures). Die Live-Suite — echtes ComfyUI, echte Renderings — ist nur über npm run test:integration erreichbar. Qualitäts-Gates: npm run typecheck, npm run check (biome), npm run knip.

Einbindung in Claude Code

Die Hauskonvention registriert den Server auf Benutzerebene (neue MCP-Werkzeuge ⇒ Claude Code neu starten). Entweder die CLI verwenden:

claude mcp add -s user artificer -- node D:/path/to/fvtt-mcp-artificer/dist/index.js

oder .mcp.json.example in eine .mcp.json kopieren, die Claude Code liest (oder in ~/.claude.json unter mcpServers einfügen), mit absoluten Pfaden. Unter Windows command auf den vollständigen node.exe-Pfad setzen, falls Node nicht im PATH ist.

Konfiguration

Kopieren Sie .env.example nach .env (gitignoriert):

• COMFY_URL — die Headless-Instanz (Standard http://127.0.0.1:8188).

• COMFY_OUTPUT_DIR — muss mit dem --output-directory übereinstimmen, mit dem ComfyUI gestartet wurde; der Server liest erzeugte PNGs direkt von diesem Pfad.

• ARTIFICER_TIMEOUT_MS — Wartezeit-Obergrenze pro Auftrag (Standard 300000).

Lizenz

MIT-Lizenz — siehe LICENSE für Details.