MCP Video Gen

Ein selbst gehosteter MCP-Server, der lokale Mediengenerierungs-Backends wie ComfyUI und Blender bereitstellen kann und gleichzeitig lokale Medienanalyse, -bearbeitung, FFmpeg, HyperFrames, Timeline, Untertitel, Sprach- und Audio-Dienstprogramme bietet.

Das Projekt ist für Portainer-Only-Bereitstellungen konzipiert: Das öffentliche Repository enthält eine normale Multi-Datei-Anwendung, während ein einzelner video-mcp.yml Stack als Bootstrap-Loader für unveränderliche GitHub-Releases fungiert.

Fähigkeiten

• Entdecken von ComfyUI-Knoten, die tatsächlich von /object_info registriert werden, wenn ComfyUI verfügbar ist.

• Schreibgeschütztes Scannen von ComfyUI models/ und custom_nodes/ Verzeichnissen, wenn diese eingebunden sind.

• Untersuchen von kompatiblen Custom-Node-Quell-/Dokumentationsdateien.

• Übermitteln von beliebigen gültigen ComfyUI-API-Workflow-JSONs und Überprüfen des Warteschlangen-/Verlaufs-/Ausgabestatus.

• Optionale Steuerung von hostinstalliertem Blender über eine authentifizierte Bridge für bpy-Automatisierung, Still-Rendering, Animations-Rendering und GLB-Export.

• Importieren von Dateien vom MCP-Client/KI in den persistenten Cache mittels Text, One-Shot-Base64 oder chunked binary transfer.

• Zurückgeben von gecachten Dateien an den Client/die KI über authentifizierten HTTP-Download, Inline-Base64 oder begrenzte chunked base64 reads.

• Hochladen von Eingaben, Zwischenspeichern von Ausgaben und Abrufen von generierten Bild-, Video-, Audio-, 3D-, Szenen-, Untertitel- und anderen Dateien über einen einheitlichen file_id-Vertrag.

• Erstellen und Rendern von lokalen HyperFrames-Projekten mit HTML/CSS/Medien.

• Analysieren, Transkodieren, Verketten, Überlagern, Audiomuxen, Zuschneiden, Umkehren, Loopen, Speed-Ramping und Extrahieren von Frames mit FFmpeg.

• Erkennen von Stille, schwarzen/eingefrorenen Abschnitten, Lautstärke, Interlacing, Zuschneideregionen, Keyframes und objektiven SSIM/PSNR-Unterschieden.

• Erstellen von Kontaktabzügen/Storyboards und Durchführen von leichter Frame-Ähnlichkeits-, Bewegungs-, Duplikat-Frame- und Best-Frame-Analyse.

• Erkennen und Aufteilen von Szenen mit PySceneDetect.

• Erstellen, Retimen, Konvertieren, Stylen und Einbrennen von Untertiteln mit pysubs2 + FFmpeg.

• Verwalten von persistenten OpenTimelineIO-Timelines mit Spuren, Clips, Übergängen, Markern, Neuanordnung, Inspektion und Export.

• Erkennen von Beats, Tempo, Onsets und Tonhöhe mit aubio.

• Lokales Entrauschen von Sprache mit RNNoise.

• Erkennen von Sprachsegmenten mit einem kleinen Silero VAD ONNX-Modell.

• Transkribieren von Medien, Generieren von Untertiteln und Erhalten von wortähnlichen Zeitstempeln lokal mit whisper.cpp.

• Optionales Synthetisieren von Sprache mit benutzerdefinierten Piper-Stimmen; Piper ist standardmäßig deaktiviert.

• Optionales Validieren von Cloudflare Access JWTs am Ursprung und Ausführen eines Cloudflare Tunnel Sidecars.

Dieser Server enthält absichtlich keine festen KI-Generierungs-Workflows, kein Langzeitgedächtnis und keine Agent-Fähigkeiten. Er stellt Ausführungs-Primitive bereit, damit ein Client oder ein separates Wissens-/Fähigkeiten-MCP entscheiden kann, wie Workflows erstellt werden sollen.

ComfyUI und Blender sind externe optionale Backends. Wenn ein Backend deaktiviert, nicht vorhanden oder vorübergehend nicht erreichbar ist, bleibt der MCP selbst gesund. Netzwerkabhängige Tools geben ein modelllesbares available=false-Ergebnis zurück, anstatt den Server zu beeinträchtigen oder einen Backend-Abwesenheits-Toolfehler zu verursachen.

Related MCP server: comfyui-mcp-server-node

Architektur

MCP client / AI
   |
   |<------ generic MCP file transfer ------>
   v
MCP Video Gen + persistent file_id cache
   |
   |---------------- optional ComfyUI API
   |                    |
   |                    +-- installed models
   |                    +-- custom nodes
   |                    +-- image/video/audio generation
   |
   |---------------- optional Blender bridge on VM
   |                    |
   |                    +-- bpy scene creation/editing
   |                    +-- .blend / GLB export
   |                    +-- still / animation rendering
   |
   |---------------- HyperFrames
   |---------------- OpenTimelineIO / subtitles
   |---------------- scene / frame analysis
   |---------------- whisper.cpp / Silero VAD / RNNoise / aubio
   +---------------- FFmpeg

All execution paths exchange files through the same MCP cache.

Portainer-Bereitstellung

Verwenden Sie video-mcp.yml als Stack-Definition.

Optionales ComfyUI

Typische ComfyUI-Verbindungsvariablen sind:

COMFYUI_HOST=host.docker.internal
COMFYUI_PORT=8188
COMFYUI_SCHEME=http

Für die Dateisystemerkennung legen Sie die Host-Pfade fest, wenn ComfyUI vorhanden ist:

COMFYUI_MODELS_PATH=/host/path/to/ComfyUI/models
COMFYUI_CUSTOM_NODES_PATH=/host/path/to/ComfyUI/custom_nodes

Diese Pfadvariablen werden für den MCP-Start nicht mehr benötigt. Der Stack hat generische Fallbacks für leere Verzeichnisse, sodass er gestartet werden kann, bevor ComfyUI installiert ist. Wenn ComfyUI nicht erreichbar ist, melden seine Netzwerktools diesen Status dem Modell, während die lokalen MCP-Tools weiterarbeiten.

Optionales Blender

Blender ist standardmäßig deaktiviert:

BLENDER_ENABLED=false
BLENDER_BRIDGE_URL=http://host.docker.internal:9876
BLENDER_BRIDGE_TOKEN=
BLENDER_BRIDGE_TIMEOUT_SEC=7200

Die empfohlene Integration führt scripts/blender_bridge.py direkt auf der VM als dediziertes, niedrig privilegiertes OS-Konto aus. Der Container kommuniziert mit ihm über eine authentifizierte lokale HTTP-Bridge; Blender selbst läuft headless auf dem Host. Dies vermeidet das Einbinden des Host-Root-Dateisystems oder von Host-Ausführungsdateien in den MCP-Container.

Nachdem die Bridge installiert ist, konfigurieren Sie privat in Portainer:

BLENDER_ENABLED=true
BLENDER_BRIDGE_URL=http://host.docker.internal:9876
BLENDER_BRIDGE_TOKEN=<same long random token used by the host bridge>

Siehe docs/BLENDER_BRIDGE.md für Einrichtung, Sicherheit, systemd-Härtung, Dateifluss und Beispiele.

Cloudflare Tunnel

Wenn Sie den enthaltenen Cloudflare Tunnel Sidecar verwenden, geben Sie an:

CLOUDFLARED_TUNNEL_TOKEN=<set privately in Portainer>

Richten Sie den Remote-Tunnel-Hostnamen auf:

http://video-mcp:8000

Der MCP-Endpunkt ist:

https://your-public-host.example/mcp

Cloudflare Access / Managed OAuth

Die Anwendung kann das Cloudflare Access JWT am Ursprung überprüfen. Konfigurieren Sie diese Werte privat in Portainer:

CF_ACCESS_VERIFY=true
CF_ACCESS_TEAM_DOMAIN=https://your-team.cloudflareaccess.com
CF_ACCESS_AUD=<Access application audience tag>
PUBLIC_BASE_URL=https://your-public-host.example

Keine echte Domain, Zielgruppe, Tunnel-Token, Bridge-Token, interne IP oder Anmeldeinformationen gehören in dieses öffentliche Repository.

Verfügbarkeit externer Backends

external_backends_status meldet den aktuellen Status von ComfyUI und Blender. inventory_summary enthält denselben Backend-Status zusammen mit lokalen Fähigkeiten.

Wenn ein externes Backend nicht verfügbar ist, geben Aufrufe eine Struktur wie diese zurück:

{
  "ok": false,
  "available": false,
  "backend": "blender",
  "status": "unavailable",
  "message": "Blender integration is disabled..."
}

Dies unterscheidet sich bewusst von einem MCP-Serverfehler: Das Modell erfährt, dass ein optionaler Ausführungspfad nicht verfügbar ist, und kann mit einem anderen fortfahren.

Dateitransfer und gemeinsamer Cache

Jedes generierte/importierte Artefakt wird in den MCP-Cache normalisiert und durch file_id identifiziert. Dies ist die Austauschebene zwischen dem KI-Client, ComfyUI, Blender, FFmpeg, HyperFrames, Untertiteln, Timelines und Audio-Dienstprogrammen.

Client / KI -> MCP

Für kleine Dateien:

cache_text_file
cache_file_base64

Für größere Binärdateien:

file_upload_begin
file_upload_chunk
file_upload_finish
file_upload_abort

Chunked Uploads können vor der Übernahme in den persistenten Cache die erwartete Bytelänge und SHA-256 angeben.

MCP -> Client / KI

Metadaten:

get_cached_file_info

Kleiner bestehender Kompatibilitätspfad:

get_output_inline_base64

Begrenzte generische Lesevorgänge:

read_cached_file_chunk_base64

Jedes normale Cache-Metadatenobjekt enthält auch /files/{file_id} und, wenn PUBLIC_BASE_URL konfiguriert ist, eine vollständige authentifizierte Download-URL.

Dies bedeutet, dass eine KI ein Blender-Python-Skript als Text verfassen, beliebige referenzierte Assets in den Cache legen, diese file_id-Werte an Blender senden, .blend/.glb/Rendern als neue file_id-Werte empfangen und diese Dateien dann in ComfyUI oder den lokalen Nachbearbeitungs-Stack einspeisen kann.

Erweiterte lokale Medien-Dienstprogramme

Die Laufzeit bereitet zusätzlich zu FFmpeg/HyperFrames mehrere kleine lokale Dienstprogramme vor. Die Python-Venv enthält PySceneDetect, OpenTimelineIO, pysubs2, ONNX Runtime, NumPy und headless OpenCV. Debian stellt das kleine aubio-tools CLI-Paket bereit. RNNoise und whisper.cpp werden lokal aus gepinnten Upstream-Quellen in das persistente Datenvolumen gebaut.

Silero VAD-, RNNoise- und whisper.cpp-Modell-/Quellartefakte werden unter dem persistenten Datenvolumen gespeichert. Die RNNoise-Quelle und das Modell sowie die Silero/Whisper-Modell-Downloads verwenden explizite SHA-256-Validierung. Das Standard-Whisper-Modell ist ein kleines quantisiertes Modell, das für die leichte lokale Transkription vorgesehen ist; Modell-URLs/Hashes und Quell-Refs können durch Stack-Variablen überschrieben werden.

Relevante Variablen umfassen:

SILERO_VAD_ENABLED=true
SILERO_VAD_MODEL_URL=<public model URL>
SILERO_VAD_MODEL_SHA256=<expected sha256>

RNNOISE_ENABLED=true
RNNOISE_REF=<pinned upstream commit>
RNNOISE_SOURCE_URL=<public source archive URL>
RNNOISE_SOURCE_SHA256=<expected sha256>
RNNOISE_MODEL_URL=<public model URL>
RNNOISE_MODEL_SHA256=<expected sha256>

WHISPER_CPP_ENABLED=true
WHISPER_CPP_REF=v1.8.6
WHISPER_CPP_BUILD_JOBS=2
WHISPER_MODEL_AUTO_DOWNLOAD=true
WHISPER_MODEL_NAME=tiny-q5_1
WHISPER_MODEL_URL=<public model URL>
WHISPER_MODEL_SHA256=<expected sha256>

Der erste Start nach Aktivieren dieser Dienstprogramme kann länger dauern, da RNNoise und whisper.cpp lokal gebaut und die ausgewählten Assets heruntergeladen werden. Ihre resultierenden Builds und Modelle verbleiben in /data, sodass die normale Container-Neuerstellung diese Builds nicht wiederholt, wenn das persistente Volume erhalten bleibt. Der Stack gewährt dem ersten Start aus diesem Grund eine verlängerte Healthcheck-Schonfrist.

Optionales Piper TTS

Piper ist als optionale Laufzeit implementiert und standardmäßig deaktiviert:

PIPER_ENABLED=false
PIPER_PACKAGE_SPEC=piper-tts

Wenn aktiviert, wird keine Stimme automatisch heruntergeladen. Sprach-.onnx- und passende Konfigurationsdateien befinden sich unter /data/piper/voices; sie können mit piper_import_voice_file aus dem MCP-Medien-Cache importiert werden. Dies hält TTS optional, da ComfyUI selbst auch Audio/TTS-Workflows hosten kann.

Siehe THIRD_PARTY.md für Hinweise zur Lizenzierung Dritter.

Release-Auswahl

Der Stack unterstützt:

VIDEO_MCP_VERSION=latest
VIDEO_MCP_CHECK_UPDATES_ON_START=true
VIDEO_MCP_FORCE_REFRESH=false

latest bedeutet das höchste Nicht-Entwurfs-, Nicht-Pre-Release-GitHub-Release, dessen Tag exakt vX.Y.Z entspricht. Es bedeutet nicht main.

Sie können auch ein Release anpinnen:

VIDEO_MCP_VERSION=v2.4.0

oder einen Commit-SHA:

VIDEO_MCP_VERSION=<commit-sha>

Wenn die Update-Überprüfung deaktiviert ist und eine gültige /current-Quelle existiert, ist der Start vollständig cache-first. Ein fehlgeschlagener Release-Lookup, Download oder eine fehlgeschlagene Archivvalidierung fällt auf die letzte bekannte gute Quelle zurück, sofern eine vorhanden ist.

Persistente Volumes

Der Stack trennt drei Anliegen:

video_mcp_code  -> /opt/video-mcp   versioned source cache + /current
video_mcp_venv  -> /opt/venv        persistent Python virtual environment
video_mcp_data  -> /data             media, timelines, models, local tooling, HyperFrames projects/cache

Das Anwendungsdaten-Root-Verzeichnis ist standardmäßig /data. Direkte/Nicht-Stack-Bereitstellungen können es mit VIDEO_MCP_DATA_ROOT überschreiben; das Importieren von video_mcp.server oder video_mcp.entrypoint erstellt das Verzeichnis nicht. Laufzeitverzeichnisse werden nur erstellt, wenn die Anwendung startet.

Die Python-Umgebung wird nur neu erstellt, wenn sich requirements.txt ändert. Die Neuerstellung löscht den Inhalt des eingebundenen Venv-Verzeichnisses; sie entfernt niemals den Docker-Mount-Punkt selbst.

Quell-Bootstrap-Sicherheit

Quellarchive werden von GitHub codeload in ein Staging-Verzeichnis heruntergeladen und vor der Extraktion validiert. Der Bootstrap lehnt ab:

• absolute Pfade;

• ..-Traversierung;

• symbolische Links;

• harte Links;

• Archive mit mehr als einem Root-Verzeichnis der obersten Ebene.

Ein Release erhält .mcp-source-ready erst nach erfolgreicher Extraktion und Laufzeitvertragsprüfungen. /current wird erst danach umgeschaltet, sodass ein unterbrochenes oder fehlerhaftes Update die letzte bekannte gute Quelle nicht ersetzen kann.

Die ComfyUI-Modell- und Custom-Node-Dateisystem-Mounts sind schreibgeschützt. KI-Dienstprogramm-Quell-/Modell-Downloads verwenden temporäre Dateien und SHA-256-Überprüfung, bevor gecachte Artefakte ersetzt werden. Die optionale Blender-Bridge verwendet Bearer-Token-Authentifizierung und transportiert nur deklarierte Job-Eingaben/-Ausgaben, aber beliebiges Blender-Python bleibt leistungsstark, und daher muss die Bridge mit einem unprivilegierten OS-Konto isoliert werden.

HyperFrames

HyperFrames läuft lokal im MCP-Container und verwendet denselben persistenten /data-Bereich wie der MCP-Medien-Cache. Browser-Assets werden persistent unter /data/hyperframes-home zwischengespeichert.

Die Standard-Paketspezifikation ist im Stack für Reproduzierbarkeit gepinnt und kann privat überschrieben werden:

HYPERFRAMES_NPM_SPEC=hyperframes@0.7.111

HyperFrames-Fähigkeiten sind in diesem Ausführungsserver absichtlich deaktiviert (HYPERFRAMES_SKIP_SKILLS=1).

Entwicklung

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt pytest PyYAML
PYTHONPATH=src python -m pytest -q
python scripts/check_public_repo.py

CI überprüft Python-Kompilierung, Server-/Entrypoint-Importe, Tests, YAML-Parsing, Shell-/Python-Helfer-Syntax, Compose-Rendering, Versions-/Changelog-Konsistenz und öffentliche Repository-Geheimnis-/privates Netzwerk-Schutzmaßnahmen.

Release-Prozess

1. Auf einem Branch entwickeln und einen PR öffnen.

2. CI muss bestehen.

3. VERSION und CHANGELOG.md aktualisieren.

4. In main zusammenführen.

5. CI erstellt den unveränderlichen vX.Y.Z-Tag und das passende stabile GitHub-Release, falls es noch nicht existiert.

Anwendungs-Tags/Releases sind für exakte vX.Y.Z-Namen reserviert, sodass nicht zusammenhängende Modell- oder Asset-Releases die Auflösung von VIDEO_MCP_VERSION=latest nicht beeinflussen können.

Lizenz und Namensnennung

Lizenziert unter der Apache License 2.0. Siehe LICENSE.

Weiterverbreitungen und abgeleitete Werke müssen den Namensnennungshinweis in NOTICE gemäß der Apache License 2.0 beibehalten. Komponenten Dritter behalten ihre eigenen Lizenzen; siehe THIRD_PARTY.md.