Symptom: Skills melden, dass mcp__vidcraft-mcp__...-Tools nicht verfügbar sind.
Ursache: Der Server läuft nur mit dem Python unter ~/.vidcraft/venv/ (Windows: %USERPROFILE%\.vidcraft\venv\Scripts\python.exe). Fehlt das Environment, startet er nicht.
Lösung: /vidcraft:setup ausführen und Claude Code neu starten.
Variante: ModuleNotFoundError: No module named 'mcp.server.mcpserver' bedeutet, dass im Environment ein zu altes mcp[cli] installiert ist. Ein erneutes /vidcraft:setup installiert die in requirements.txt festgelegte Version.
Symptom: Direkt nach create_project_structure, create_episode oder create_scene sagt list_projects oder get_project_full, das Projekt sei nicht vorhanden. Gleiches gilt, wenn du Dateien von Hand bearbeitest.
Ursache: Die Abfrage-Tools lesen den Zustands-Cache ~/.vidcraft/cache/state.json. Er wird nicht automatisch aus den Dateien neu aufgebaut.
Lösung: /vidcraft:session-start ausführen oder das Tool rebuild_state aufrufen.
Symptom: doc-analyzer, update_field oder extract_section verweigern eine Datei.
Ursache: Diese Tools arbeiten nur mit Dateien unterhalb von paths.content_root.
Lösung: Datei in das Content-Root kopieren, zum Beispiel nach {content_root}/projects/<projekt>/research/, oder content_root in ~/.vidcraft/config.yaml anpassen.
.md, .pdf und .docx. .doc wird angenommen, siehe nächster Punkt. Alle anderen Endungen werden abgelehnt..doc-Datei (altes Word-Format): Sie wird an den python-docx-Parser weitergereicht, der nur .docx lesen kann. Es entsteht ein python-docx-Fehler, der nicht abgefangen wird und als Tool-Fehler erscheint. Konvertiere die Datei vorher nach .docx./vidcraft:setup ausführen.pdfplumber extrahiert Text, keine Bilder von Text. Gescannte PDFs ohne Textebene liefern nichts.Ursache: Der Episoden-Status steht noch auf Not Started oder Script Draft, es gibt keine Szenen, oder mindestens eine Szene hat keine Narration.
Lösung: /vidcraft:script-reviewer ausführen, damit der Status Script Reviewed gesetzt wird, und leere Szenen füllen. Der Status steht im Frontmatter der Episoden-README.md. Danach den Cache neu aufbauen (siehe oben).
Ursache: [pause Xs] wirkt nur mit eigenen Stimmen (Voice Clone, ElevenLabs, OpenAI Voice). Die öffentliche Stimmenbibliothek ignoriert Pausen und SSML.
Lösung: Eigene Stimme verwenden oder das Tempo über Satzzeichen und Absätze steuern.
Ursache: subtitle-generator ruft das Kommando whisper auf. Es ist nicht installiert oder nicht im PATH, oder ffmpeg fehlt.
Lösung: pipx install openai-whisper (oder pip install openai-whisper) und ffmpeg installieren, siehe Installation. Das exportierte MP4 sollte im Assets-Ordner der Episode liegen, sonst nennst du dem Skill den Dateipfad.
Symptom: python oder python3 brechen ohne Ausgabe mit Exit-Code 49 ab.
Ursache: Das ist der Platzhalter des Microsoft Store, nicht eine echte Python-Installation.
Lösung: Der Setup-Skill probiert dann py -3 und bekannte Installationspfade. Ist Python wirklich nicht vorhanden, installiere Python 3.10 oder neuer mit der Option, python.exe zum PATH hinzuzufügen.
Das Skript hooks/validate_scene.py ist nicht als Hook registriert und läuft deshalb nicht automatisch. Siehe Technik.
Im MCP-Server werden nur paths.content_root, paths.video_root, paths.assets_root und defaults.wpm ausgewertet. Siehe Konfiguration.