Symptom: Skills report that mcp__vidcraft-mcp__... tools are not available.
Cause: The server only runs with the Python under ~/.vidcraft/venv/ (Windows: %USERPROFILE%\.vidcraft\venv\Scripts\python.exe). If the environment is missing, it does not start.
Fix: Run /vidcraft:setup and restart Claude Code.
Variant: ModuleNotFoundError: No module named 'mcp.server.mcpserver' means the environment has a mcp[cli] that is too old. Running /vidcraft:setup again installs the version pinned in requirements.txt.
Symptom: Right after create_project_structure, create_episode or create_scene, list_projects or get_project_full says the project does not exist. The same applies when you edit files by hand.
Cause: The query tools read the state cache ~/.vidcraft/cache/state.json. It is not rebuilt from the files automatically.
Fix: Run /vidcraft:session-start or call the rebuild_state tool.
Symptom: doc-analyzer, update_field or extract_section refuse a file.
Cause: These tools only work with files below paths.content_root.
Fix: Copy the file into the content root, for example to {content_root}/projects/<project>/research/, or adjust content_root in ~/.vidcraft/config.yaml.
.md, .pdf and .docx are read. .doc is accepted, see the next item. All other extensions are rejected..doc file (legacy Word format): It is passed to the python-docx parser, which can only read .docx. This produces a python-docx error that is not caught and shows up as a tool error. Convert the file to .docx first./vidcraft:setup.pdfplumber extracts text, not images of text. Scanned PDFs without a text layer yield nothing.Cause: The episode status is still Not Started or Script Draft, there are no scenes, or at least one scene has no narration.
Fix: Run /vidcraft:script-reviewer so that the status Script Reviewed is set, and fill empty scenes. The status lives in the frontmatter of the episode README.md. Then rebuild the cache (see above).
Cause: [pause Xs] only works with custom voices (voice clone, ElevenLabs, OpenAI Voice). The public voice library ignores pauses and SSML.
Fix: Use a custom voice or control the pace with punctuation and paragraphs.
Cause: subtitle-generator calls the whisper command. It is not installed or not on the PATH, or ffmpeg is missing.
Fix: Install pipx install openai-whisper (or pip install openai-whisper) and ffmpeg, see Installation. The exported MP4 should be in the episode's assets folder; otherwise give the skill the file path.
Symptom: python or python3 exit with code 49 and no output.
Cause: This is the Microsoft Store placeholder, not a real Python installation.
Fix: The setup skill then tries py -3 and known install locations. If Python is really missing, install Python 3.10 or newer with the option to add python.exe to the PATH.
The script hooks/validate_scene.py is not registered as a hook and therefore does not run automatically. See Technical.
The MCP server only evaluates paths.content_root, paths.video_root, paths.assets_root and defaults.wpm. See Configuration.