VidCraft Technical
Technical reference for VidCraft: plugin layout, how the MCP server starts, all 36 MCP tools by category, state cache, path restriction, knowledge files, templates and the unregistered scene hook script.
VidCraft Technical
Layout
| Directory | Content |
|---|---|
skills/ |
33 skills, one folder each with a SKILL.md |
servers/vidcraft-server/ |
MCP server vidcraft-mcp (server.py, launcher run.py) |
tools/ |
Python modules for state, document parser and configuration |
video-types/ |
12 video type definitions |
knowledge/ |
Script rules, platform checklist, AI-language patterns, status workflow |
reference/ |
Platform references for HeyGen and Synthesia, pacing guide, state schema |
templates/ |
Markdown templates for project, episode, scene, brief, script, storyboard and shot list |
config/ |
config.example.yaml |
bin/ |
Launch wrappers run-server (POSIX) and run-server.cmd (Windows) |
hooks/ |
Check script for scene files |
MCP server
.mcp.json starts the vidcraft-mcp server over stdio through bin/run-server, using the Python from ~/.vidcraft/venv/. It is built on the mcp package and provides 36 tools. Skills use them under names of the form mcp__vidcraft-mcp__<tool>.
The plugin rule is: state queries go through the MCP tools, skills do not parse project files themselves.
State (8)
| Tool | Purpose |
|---|---|
list_projects |
All projects with status and episode count |
find_project |
Project by slug or part of the name |
get_project_full |
Complete project data with episodes and scenes |
get_project_progress |
Episodes per status with percentages |
rebuild_state |
Rebuild the cache from the files |
get_session |
Last project, last episode, last phase |
update_session |
Save session context |
search |
Keyword search across projects and episodes |
Content (9)
| Tool | Purpose |
|---|---|
create_project_structure |
Create a project directory from the template |
create_episode |
Create an episode, number assigned automatically |
create_scene |
Create a scene (avatar, screencast, slides, b-roll) |
get_episode |
Episode data with scenes |
list_episodes |
Episodes of a project |
list_scenes |
Scenes of an episode |
update_field |
Change a frontmatter field of a Markdown file |
resolve_path |
Resolve path to content, video or assets |
extract_section |
Read the section under a ## heading |
Script analysis (3)
analyze_timing, check_readability, validate_structure
Platform (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
Document analysis (5)
analyze_document, extract_key_points, suggest_video_structure, analyze_complexity, suggest_video_topics
Ideas and misc (4)
create_video_idea, get_video_ideas, check_pronunciation, get_plugin_version
The idea tools carry the video prefix so they do not collide with identically named tools of other plugins such as StoryForge.
Path restriction
update_field, extract_section and the five document analysis tools only accept files below paths.content_root. The path is resolved (including symlinks) before it is checked. Other paths return the message "Path outside content root".
State cache
~/.vidcraft/cache/state.json holds projects, episodes, scenes, ideas, the session data and the loaded configuration. The query tools (list_projects, get_project_full, get_episode and others) read from this file.
The cache is rebuilt from the Markdown files only when the file is missing, unreadable or has a different schema version, and by the rebuild_state tool. The writing tools (create_project_structure, create_episode, create_scene, update_field, create_video_idea) merely discard the in-memory cache. Newly created or changed files therefore show up in the query tools only after rebuild_state or /vidcraft:session-start. Session data is preserved across a rebuild.
Scene check script
hooks/validate_scene.py checks a scene file for frontmatter, the fields title, number and status, the sections ## Narration and ## Visual Direction, and sentences over 25 words. It only prints warnings to stderr and never blocks.
The script ships in the repo but is not registered as a hook anywhere.
plugin.jsonand.mcp.jsoncontain no hook configuration. It therefore does not run automatically; you can call it by hand with the file path as argument or through your own hook in your Claude Code configuration.
Knowledge files
| File | Content |
|---|---|
knowledge/script-writing-rules.md |
Narration, pause syntax, on-screen text, variables, SSML |
knowledge/platform-checklist.md |
HeyGen and Synthesia rules |
knowledge/ai-language-patterns.md |
Tiered list of AI-sounding phrases |
knowledge/status-workflow.md |
Mapping from status to next skill |
Skills point to these files instead of duplicating rules.
Development
Tests live in tests/ and run with pytest. Dev dependencies are in requirements-dev.txt. Contributions are possible under a BDFL model with a CLA, see CONTRIBUTING.md in the repository.