VidCraft Technik
Technische Referenz zu VidCraft: Aufbau des Plugins, Start des MCP-Servers, alle 36 MCP-Tools nach Kategorie, Zustands-Cache, Pfad-Beschränkung, Knowledge-Dateien, Vorlagen und das nicht registrierte Szenen-Hook-Skript.
VidCraft Technik
Aufbau
| Verzeichnis | Inhalt |
|---|---|
skills/ |
33 Skills, je ein Ordner mit SKILL.md |
servers/vidcraft-server/ |
MCP-Server vidcraft-mcp (server.py, Starter run.py) |
tools/ |
Python-Module für Zustand, Dokument-Parser und Konfiguration |
video-types/ |
12 Video-Typ-Definitionen |
knowledge/ |
Script-Regeln, Plattform-Checkliste, Muster KI-typischer Sprache, Status-Workflow |
reference/ |
Plattform-Referenzen für HeyGen und Synthesia, Pacing-Guide, State-Schema |
templates/ |
Markdown-Vorlagen für Projekt, Episode, Szene, Brief, Script, Storyboard und Shot-Liste |
config/ |
config.example.yaml |
bin/ |
Startwrapper run-server (POSIX) und run-server.cmd (Windows) |
hooks/ |
Prüfskript für Szenen-Dateien |
MCP-Server
.mcp.json startet den Server vidcraft-mcp per stdio über bin/run-server mit dem Python aus ~/.vidcraft/venv/. Er baut mit dem mcp-Paket auf und stellt 36 Tools bereit. Die Skills nutzen sie über Namen der Form mcp__vidcraft-mcp__<tool>.
Die Plugin-Regel lautet: Zustandsabfragen laufen über die MCP-Tools, Skills parsen Projektdateien nicht selbst.
Zustand (8)
| Tool | Zweck |
|---|---|
list_projects |
Alle Projekte mit Status und Episodenzahl |
find_project |
Projekt per Slug oder Namensteil |
get_project_full |
Vollständige Projektdaten mit Episoden und Szenen |
get_project_progress |
Episoden je Status mit Prozentwerten |
rebuild_state |
Cache aus den Dateien neu aufbauen |
get_session |
Letztes Projekt, letzte Episode, letzte Phase |
update_session |
Sitzungskontext speichern |
search |
Stichwortsuche über Projekte und Episoden |
Inhalte (9)
| Tool | Zweck |
|---|---|
create_project_structure |
Projektverzeichnis mit Vorlage anlegen |
create_episode |
Episode anlegen, Nummer wird automatisch vergeben |
create_scene |
Szene anlegen (avatar, screencast, slides, b-roll) |
get_episode |
Episodendaten mit Szenen |
list_episodes |
Episoden eines Projekts |
list_scenes |
Szenen einer Episode |
update_field |
Frontmatter-Feld einer Markdown-Datei ändern |
resolve_path |
Pfad zu Inhalt, Video oder Assets auflösen |
extract_section |
Abschnitt unter einer ##-Überschrift lesen |
Script-Analyse (3)
analyze_timing, check_readability, validate_structure
Plattform (5)
validate_platform_limits, get_platform_capabilities, heygen_format_script, synthesia_format_script, list_required_assets
Quality Gates (2)
run_pre_generation_gates, validate_project_structure
Dokument-Analyse (5)
analyze_document, extract_key_points, suggest_video_structure, analyze_complexity, suggest_video_topics
Ideen und Sonstiges (4)
create_video_idea, get_video_ideas, check_pronunciation, get_plugin_version
Die Ideen-Tools tragen das Präfix video, damit sie nicht mit gleichnamigen Tools anderer Plugins wie StoryForge kollidieren.
Pfad-Beschränkung
update_field, extract_section und die fünf Dokument-Analyse-Tools akzeptieren nur Dateien unterhalb von paths.content_root. Der Pfad wird aufgelöst (inklusive Symlinks), bevor er geprüft wird. Andere Pfade liefern die Meldung "Path outside content root".
Zustands-Cache
~/.vidcraft/cache/state.json enthält Projekte, Episoden, Szenen, Ideen, die Sitzungsdaten und die geladene Konfiguration. Die Abfrage-Tools (list_projects, get_project_full, get_episode und weitere) lesen aus dieser Datei.
Aus den Markdown-Dateien neu aufgebaut wird der Cache nur, wenn die Datei fehlt, nicht lesbar ist oder die Schema-Version nicht passt, und durch das Tool rebuild_state. Die schreibenden Tools (create_project_structure, create_episode, create_scene, update_field, create_video_idea) verwerfen lediglich den Speicher-Cache. Neu angelegte oder geänderte Dateien erscheinen deshalb in den Abfrage-Tools erst nach rebuild_state oder /vidcraft:session-start. Die Sitzungsdaten bleiben beim Neuaufbau erhalten.
Szenen-Prüfskript
hooks/validate_scene.py prüft eine Szenen-Datei auf Frontmatter, die Felder title, number und status, die Abschnitte ## Narration und ## Visual Direction sowie Sätze über 25 Wörter. Es meldet nur Warnungen auf stderr und blockiert nie.
Das Skript ist im Repo enthalten, aber nirgends als Hook registriert.
plugin.jsonund.mcp.jsonenthalten keine Hook-Konfiguration. Es läuft daher nicht automatisch, du kannst es mit dem Dateipfad als Argument von Hand oder über einen eigenen Hook in deiner Claude-Code-Konfiguration aufrufen.
Wissensdateien
| Datei | Inhalt |
|---|---|
knowledge/script-writing-rules.md |
Narration, Pausen-Syntax, Bildschirmtext, Variablen, SSML |
knowledge/platform-checklist.md |
HeyGen- und Synthesia-Regeln |
knowledge/ai-language-patterns.md |
Stufenliste KI-typischer Formulierungen |
knowledge/status-workflow.md |
Zuordnung Status zu nächstem Skill |
Skills verweisen auf diese Dateien, statt Regeln zu duplizieren.
Entwicklung
Tests liegen in tests/ und laufen mit pytest. Dev-Abhängigkeiten stehen in requirements-dev.txt. Mitwirken ist unter einem BDFL-Modell mit CLA möglich, siehe CONTRIBUTING.md im Repository.