MCP Video Gen

Un servidor MCP autoalojado que puede exponer backends locales de generación de medios como ComfyUI y Blender, al mismo tiempo que proporciona análisis, edición, FFmpeg, HyperFrames, línea de tiempo, subtítulos, voz y utilidades de audio locales.

El proyecto está diseñado para implementaciones solo con Portainer: el repositorio público contiene una aplicación normal de varios archivos, mientras que un único Stack video-mcp.yml actúa como cargador de arranque para GitHub Releases inmutables.

Capacidades

• Descubrir nodos de ComfyUI realmente registrados por /object_info cuando ComfyUI está disponible.

• Escanear los directorios models/ y custom_nodes/ de ComfyUI en modo solo lectura cuando están montados.

• Inspeccionar archivos fuente/documentación de nodos personalizados compatibles.

• Enviar cualquier JSON de flujo de trabajo de API de ComfyUI válido e inspeccionar el estado de la cola/historial/salida.

• Controlar opcionalmente Blender instalado en el host a través de un puente autenticado para automatización bpy, renderizado de animaciones, renderizado de fotogramas y exportación GLB.

• Importar archivos desde el cliente MCP/IA a la caché persistente usando texto, base64 de una sola vez o transferencia binaria fragmentada.

• Devolver archivos en caché al cliente/IA a través de descarga HTTP autenticada, base64 en línea o lecturas base64 fragmentadas acotadas.

• Subir entradas, almacenar en caché salidas y recuperar archivos de imagen, video, audio, 3D, escena, subtítulos y otros generados a través de un único contrato file_id.

• Crear y renderizar proyectos HyperFrames locales usando HTML/CSS/medios.

• Sondear, transcodificar, concatenar, superponer, multiplexar audio, recortar, invertir, repetir, variar la velocidad y extraer fotogramas con FFmpeg.

• Detectar silencio, secciones negras/congeladas, sonoridad, entrelazado, regiones de recorte, fotogramas clave y diferencias objetivas SSIM/PSNR.

• Crear hojas de contacto/storyboards y realizar análisis ligeros de similitud de fotogramas, movimiento, fotogramas duplicados y mejor fotograma.

• Detectar y dividir escenas con PySceneDetect.

• Crear, reajustar tiempo, convertir, estilizar y quemar subtítulos con pysubs2 + FFmpeg.

• Mantener líneas de tiempo OpenTimelineIO persistentes con pistas, clips, transiciones, marcadores, reordenación, inspección y exportación.

• Detectar ritmo, tempo, ataques y tono con aubio.

• Eliminar el ruido del habla localmente con RNNoise.

• Detectar segmentos de habla con un pequeño modelo Silero VAD ONNX.

• Transcribir medios, generar subtítulos y obtener marcas de tiempo similares a palabras localmente con whisper.cpp.

• Sintetizar voz opcionalmente con voces Piper proporcionadas por el usuario; Piper está deshabilitado por defecto.

• Validar opcionalmente JWTs de Cloudflare Access en el origen y ejecutar un sidecar de Cloudflare Tunnel.

Este servidor intencionalmente no contiene flujos de trabajo fijos de generación de IA, memoria a largo plazo o habilidades de agente. Expone primitivas de ejecución para que un cliente o un MCP de conocimiento/habilidades separado decida cómo se deben construir los flujos de trabajo.

ComfyUI y Blender son backends externos opcionales. Si algún backend está deshabilitado, ausente o temporalmente inalcanzable, el MCP en sí permanece saludable. Las herramientas dependientes de la red devuelven un resultado available=false legible por el modelo en lugar de derribar el servidor o mostrar un error de herramienta por ausencia de backend.

Related MCP server: comfyui-mcp-server-node

Arquitectura

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.

Implementación con Portainer

Usa video-mcp.yml como definición del Stack.

ComfyUI opcional

Las variables de conexión típicas de ComfyUI son:

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

Para el descubrimiento del sistema de archivos, establece las rutas del host cuando ComfyUI existe:

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

Estas variables de ruta ya no son necesarias para el inicio del MCP. El Stack tiene directorios vacíos genéricos de respaldo, por lo que puede iniciarse antes de que ComfyUI esté instalado. Si ComfyUI es inalcanzable, sus herramientas de red informan ese estado al modelo mientras las herramientas MCP locales continúan funcionando.

Blender opcional

Blender está deshabilitado por defecto:

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

La integración recomendada ejecuta scripts/blender_bridge.py directamente en la VM como una cuenta de sistema dedicada con pocos privilegios. El contenedor se comunica con él a través de un puente HTTP local autenticado; Blender se ejecuta sin interfaz gráfica en el host. Esto evita montar el sistema de archivos raíz del host o ejecutables del host en el contenedor MCP.

Después de instalar el puente, configúralo de forma privada en Portainer:

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

Consulta docs/BLENDER_BRIDGE.md para la configuración, seguridad, endurecimiento de systemd, flujo de archivos y ejemplos.

Cloudflare Tunnel

Si usas el sidecar de Cloudflare Tunnel incluido, proporciona:

CLOUDFLARED_TUNNEL_TOKEN=<set privately in Portainer>

Apunta el nombre de host del Tunnel remoto a:

http://video-mcp:8000

El endpoint MCP es:

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

Cloudflare Access / Managed OAuth

La aplicación puede verificar el JWT de Cloudflare Access en el origen. Configura estos valores de forma privada en 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

Ningún dominio real, audiencia, token de túnel, token de puente, IP interna o credencial pertenece a este repositorio público.

Disponibilidad del backend externo

external_backends_status informa el estado actual de ComfyUI y Blender. inventory_summary incluye el mismo estado del backend junto con las capacidades locales.

Cuando un backend externo no está disponible, las llamadas devuelven una estructura como:

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

Esto es deliberadamente diferente de un fallo del servidor MCP: el modelo aprende que una ruta de ejecución opcional no está disponible y puede continuar con otra.

Transferencia de archivos y caché compartida

Cada artefacto generado/importado se normaliza en la caché MCP y se identifica por file_id. Esta es la capa de intercambio entre el cliente IA, ComfyUI, Blender, FFmpeg, HyperFrames, subtítulos, líneas de tiempo y utilidades de audio.

Cliente / IA -> MCP

Para archivos pequeños:

cache_text_file
cache_file_base64

Para archivos binarios más grandes:

file_upload_begin
file_upload_chunk
file_upload_finish
file_upload_abort

Las cargas fragmentadas pueden especificar la longitud de bytes esperada y SHA-256 antes de la promoción a la caché persistente.

MCP -> cliente / IA

Metadatos:

get_cached_file_info

Ruta de compatibilidad existente para pequeños:

get_output_inline_base64

Lecturas genéricas acotadas:

read_cached_file_chunk_base64

Cada objeto de metadatos de caché normal también contiene /files/{file_id} y, cuando PUBLIC_BASE_URL está configurado, una URL de descarga autenticada completa.

Esto significa que una IA puede redactar un script de Python para Blender como texto, colocar activos referenciados arbitrarios en la caché, enviar esos valores file_id a Blender, recibir archivos .blend/.glb/renderizados como nuevos valores file_id, y luego alimentar esos archivos a ComfyUI o al stack de posprocesamiento local.

Utilidades avanzadas de medios locales

El tiempo de ejecución prepara varias utilidades locales pequeñas además de FFmpeg/HyperFrames. El venv de Python contiene PySceneDetect, OpenTimelineIO, pysubs2, ONNX Runtime, NumPy y OpenCV sin interfaz gráfica. Debian proporciona el pequeño paquete CLI aubio-tools. RNNoise y whisper.cpp se construyen localmente a partir de fuentes ascendentes fijadas en el volumen de datos persistente.

Los artefactos de modelo/fuente de Silero VAD, RNNoise y whisper.cpp se almacenan bajo el volumen de datos persistente. La fuente y el modelo de RNNoise más las descargas del modelo Silero/Whisper utilizan validación SHA-256 explícita. El modelo Whisper predeterminado es un modelo cuantizado pequeño destinado a la transcripción local ligera; las URL/hashes del modelo y las referencias de origen se pueden anular a través de variables del Stack.

Las variables relevantes incluyen:

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>

El primer inicio después de habilitar estas utilidades puede llevar más tiempo porque RNNoise y whisper.cpp se construyen localmente y los activos seleccionados se descargan. Sus compilaciones y modelos resultantes permanecen en /data, por lo que la recreación normal del contenedor no repite esas compilaciones cuando se conserva el volumen persistente. El Stack le da al primer inicio un período de gracia de verificación de salud extendido por esta razón.

Piper TTS opcional

Piper se implementa como un tiempo de ejecución opcional y está deshabilitado por defecto:

PIPER_ENABLED=false
PIPER_PACKAGE_SPEC=piper-tts

Cuando está habilitado, no se descarga ninguna voz automáticamente. Los archivos de voz .onnx y los archivos de configuración coincidentes residen en /data/piper/voices; se pueden importar desde la caché de medios MCP con piper_import_voice_file. Esto mantiene TTS opcional porque ComfyUI también puede alojar flujos de trabajo de audio/TTS.

Consulta THIRD_PARTY.md para notas de licencias de terceros.

Selección de versión

El Stack soporta:

VIDEO_MCP_VERSION=latest
VIDEO_MCP_CHECK_UPDATES_ON_START=true
VIDEO_MCP_FORCE_REFRESH=false

latest significa la GitHub Release no borrador, no prelanzamiento más alta cuya etiqueta coincide exactamente con vX.Y.Z. No significa main.

También puedes fijar una versión:

VIDEO_MCP_VERSION=v2.4.0

o un SHA de commit:

VIDEO_MCP_VERSION=<commit-sha>

Cuando la comprobación de actualizaciones está deshabilitada y existe una fuente /current válida, el inicio es completamente primero en caché. Una búsqueda de versión, descarga o validación de archivo fallida recurre a la última fuente conocida buena cuando existe.

Volúmenes persistentes

El Stack separa tres preocupaciones:

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

La raíz de datos de tiempo de ejecución de la aplicación por defecto es /data. Las implementaciones directas/no Stack pueden anularla con VIDEO_MCP_DATA_ROOT; importar video_mcp.server o video_mcp.entrypoint no crea el directorio. Los directorios de tiempo de ejecución se crean solo cuando la aplicación se inicia.

El entorno de Python se reconstruye solo cuando requirements.txt cambia. La reconstrucción limpia el contenido del directorio venv montado; nunca elimina el punto de montaje de Docker en sí.

Seguridad del arranque de la fuente

Los archivos fuente se descargan de GitHub codeload en un directorio de preparación y se validan antes de la extracción. El arranque rechaza:

• rutas absolutas;

• traversal ..;

• enlaces simbólicos;

• enlaces duros;

• archivos con más de una raíz de nivel superior.

Una versión recibe .mcp-source-ready solo después de que la extracción y las comprobaciones del contrato de tiempo de ejecución tengan éxito. /current se cambia solo después de ese punto, por lo que una actualización interrumpida o mal formada no puede reemplazar la última fuente conocida buena.

Los montajes del sistema de archivos de modelos y nodos personalizados de ComfyUI son de solo lectura. Las descargas de modelo/fuente de utilidades de IA utilizan archivos temporales y verificación SHA-256 antes de reemplazar los artefactos en caché. El puente opcional de Blender utiliza autenticación de token portador y solo transporta entradas/salidas de trabajo declaradas, pero el Python arbitrario de Blender sigue siendo potente y, por lo tanto, el puente debe aislarse con una cuenta de sistema sin privilegios.

HyperFrames

HyperFrames se ejecuta localmente en el contenedor MCP y usa la misma área /data persistente que la caché de medios MCP. Los activos del navegador se almacenan en caché de forma persistente en /data/hyperframes-home.

La especificación del paquete predeterminado está fijada en el Stack para la reproducibilidad y se puede anular de forma privada:

HYPERFRAMES_NPM_SPEC=hyperframes@0.7.111

Las habilidades de HyperFrames están intencionalmente deshabilitadas en este servidor de ejecución (HYPERFRAMES_SKIP_SKILLS=1).

Desarrollo

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 verifica la compilación de Python, las importaciones del servidor/punto de entrada, las pruebas, el análisis YAML, la sintaxis de ayudantes de shell/Python, la representación de Compose, la consistencia de versión/changelog y las barreras de seguridad de secretos/red privada del repositorio público.

Proceso de lanzamiento

1. Desarrolla en una rama y abre un PR.

2. CI debe pasar.

3. Actualiza VERSION y CHANGELOG.md.

4. Fusiona a main.

5. CI crea la etiqueta inmutable vX.Y.Z y la GitHub Release estable coincidente si aún no existe.

Las etiquetas/lanzamientos de la aplicación están reservados para nombres exactos vX.Y.Z para que las versiones no relacionadas de modelos o activos no puedan afectar la resolución de VIDEO_MCP_VERSION=latest.

Licencia y atribución

Licenciado bajo la Apache License 2.0. Consulta LICENSE.

Las redistribuciones y trabajos derivados deben conservar el aviso de atribución en NOTICE de acuerdo con la Apache License 2.0. Los componentes de terceros conservan sus propias licencias; consulta THIRD_PARTY.md.