MCP Video Gen

Самодостаточный MCP-сервер, который может предоставлять локальные медиа-генерационные бэкенды, такие как ComfyUI и Blender, а также обеспечивать локальный анализ медиа, редактирование, FFmpeg, HyperFrames, таймлайн, субтитры, речь и аудиоутилиты.

Проект предназначен только для развертываний Portainer: публичный репозиторий содержит обычное многофайловое приложение, в то время как один Stack video-mcp.yml выступает в роли загрузчика для неизменяемых релизов GitHub.

Возможности

• Обнаруживать узлы ComfyUI, фактически зарегистрированные через /object_info, когда ComfyUI доступен.

• Сканировать доступные только для чтения директории models/ и custom_nodes/ ComfyUI, если они смонтированы.

• Просматривать совместимые файлы исходного кода/документации пользовательских узлов.

• Отправлять произвольный корректный JSON рабочего процесса API ComfyUI и проверять состояние очереди/истории/вывода.

• Опционально управлять установленным на хосте Blender через аутентифицированный мост для автоматизации bpy, рендеринга, анимационного рендеринга и экспорта в GLB.

• Импортировать файлы от MCP-клиента/ИИ в постоянный кеш с помощью текста, одноразовой base64 или чанковой бинарной передачи.

• Возвращать кешированные файлы клиенту/ИИ через аутентифицированную HTTP-загрузку, встроенную base64 или ограниченное чанковое чтение base64.

• Загружать входные данные, кешировать выходные и извлекать сгенерированные изображения, видео, аудио, 3D, сцены, субтитры и другие файлы через единый контракт file_id.

• Создавать и рендерить локальные проекты HyperFrames с использованием HTML/CSS/медиа.

• Зондировать, транскодировать, объединять, накладывать, микшировать аудио, обрезать, реверсировать, зацикливать, изменять скорость, извлекать кадры с помощью FFmpeg.

• Обнаруживать тишину, черные/замороженные участки, громкость, чересстрочную развертку, области обрезки, ключевые кадры и объективные различия SSIM/PSNR.

• Создавать контактные листы/раскадровки и выполнять легкий анализ схожести кадров, движения, дублирования кадров и лучшего кадра.

• Обнаруживать и разбивать сцены с помощью PySceneDetect.

• Создавать, изменять временные параметры, преобразовывать, стилизовать и вживлять субтитры с помощью pysubs2 + FFmpeg.

• Поддерживать постоянные таймлайны OpenTimelineIO с треками, клипами, переходами, маркерами, переупорядочиванием, проверкой и экспортом.

• Обнаруживать биты, темп, атаки и высоту тона с помощью aubio.

• Локально подавлять шум речи с помощью RNNoise.

• Обнаруживать речевые сегменты с помощью небольшой модели Silero VAD ONNX.

• Транскрибировать медиа, генерировать субтитры и получать временные метки уровня слов локально с помощью whisper.cpp.

• Опционально синтезировать речь с помощью предоставленных пользователем голосов Piper; Piper отключен по умолчанию.

• Опционально проверять JWT Cloudflare Access на источнике и запускать сайдкар Cloudflare Tunnel.

Этот сервер намеренно не содержит фиксированные AI-генерационные рабочие процессы, долговременную память или навыки агента. Он предоставляет примитивы выполнения, чтобы клиент или отдельный MCP знаний/навыков мог решить, как должны строиться рабочие процессы.

ComfyUI и Blender являются внешними опциональными бэкендами. Если один из бэкендов отключен, отсутствует или временно недоступен, сам MCP остается работоспособным. Инструменты, зависящие от сети, возвращают читаемый моделью результат available=false вместо того, чтобы вывести сервер из строя или вызвать ошибку инструмента из-за отсутствия бэкенда.

Related MCP server: comfyui-mcp-server-node

Архитектура

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

Используйте video-mcp.yml в качестве определения Stack.

Опциональный ComfyUI

Типичные переменные подключения ComfyUI:

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

Для обнаружения файловой системы укажите пути хоста, когда ComfyUI существует:

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

Эти переменные пути больше не требуются для запуска MCP. Stack имеет общие резервные пустые директории, поэтому он может запуститься до установки ComfyUI. Если ComfyUI недоступен, его сетевые инструменты сообщают об этом состоянии модели, в то время как локальные инструменты MCP продолжают работать.

Опциональный Blender

Blender отключен по умолчанию:

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

Рекомендуемая интеграция запускает scripts/blender_bridge.py напрямую на виртуальной машине как выделенную учетную запись ОС с низкими привилегиями. Контейнер связывается с ним через аутентифицированный локальный HTTP-мост; сам Blender работает без графического интерфейса на хосте. Это позволяет избежать монтирования корневой файловой системы хоста или исполняемых файлов хоста в контейнер MCP.

После установки моста настройте его приватно в Portainer:

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

См. docs/BLENDER_BRIDGE.md для получения информации о настройке, безопасности, усилении безопасности systemd, потоке файлов и примерах.

Cloudflare Tunnel

Если вы используете включенный сайдкар Cloudflare Tunnel, укажите:

CLOUDFLARED_TUNNEL_TOKEN=<set privately in Portainer>

Направьте удаленное имя хоста туннела на:

http://video-mcp:8000

Конечная точка MCP:

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

Cloudflare Access / Managed OAuth

Приложение может проверить JWT Cloudflare Access на источнике. Настройте эти значения приватно в 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

Никакой реальный домен, аудитория, токен туннела, токен моста, внутрений IP или учетные данные не должны находиться в этом публичном репозитории.

Доступность внешних бэкендов

external_backends_status сообщает текущее состояние ComfyUI и Blender. inventory_summary включает тот же статус бэкендов наряду с локальными возможностями.

Когда внешний бэкенд недоступен, вызовы возвращают структуру, такую как:

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

Это преднамеренно отличается от сбоя сервера MCP: модель узнает, что один опциональный путь выполнения недоступен, и может продолжить с другим.

Передача файлов и общий кеш

Каждый сгенерированный/импортированный артефакт нормируется в кеш MCP и идентифицируется по file_id. Это слой обмена между AI-клиентом, ComfyUI, Blender, FFmpeg, HyperFrames, субтирами, таймлайнами и аудиоутилитами.

Клиент / AI -> MCP

Для маленких файлов:

cache_text_file
cache_file_base64

Для более крупных бинарных файлов:

file_upload_begin
file_upload_chunk
file_upload_finish
file_upload_abort

Чанковые загрузки могут указывать ожидаемую длину в байтах и SHA-256 перед продвижением в постоянный кеш.

MCP -> клиент / AI

Метаданные:

get_cached_file_info

Маленкий существующий путь совместимости:

get_output_inline_base64

Ограниченные общие чтения:

read_cached_file_chunk_base64

Каждый обычный объект метаданных кеша также содержит /files/{file_id} и, когда настроен PUBLIC_BASE_URL, полный аутентифицированный URL для загрузки.

Это означает, что AI может написать скрипт Blender Python как текст, поместить любые ссылочные артефакты в кеш, отправить эти значения file_id в Blender, получиь .blend/.glb/рендеры обратно как новые значения file_id, а затем подать эти файлы в ComfyUI или локальный стэк постобработки.

Продвинутые локальные медиаутилиты

Среда выполнения подготавливает несколько небольших локальных утилит в дополнение к FFmpeg/HyperFrames. Виртуальное окружение Python содежит PySceneDetect, OpenTimelineIO, pysubs2, ONNX Runtime, NmPy и headles OpenCV. Debian предоставляет маленкий CLI-пакет aubio-tools. RNNoise и whiper.cpp собираются локально из закрепленного исходного кода вышестоящего проекта в постоянный том данных.

Артефакты моделей/исходного кода Silero VAD, RNNoise и whiper.cpp хранятся под постоянным томом данных. Загрузка исходного кода RNNoise и модели, а также моделей Silero/Whisper использует явную проверку SHA-256. Модель Whiper по умолчанию - это маленкая квантизированная модель, предназначенная для легковесной локальной транскрипции; URL-ы/хэши моделей и ссылки на источники могут быть переопределены через переменные Stack.

Соотвествующие переменные включают:

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>

Первый запуск после включения этих утилит может занять больше времени, так как RNNoise и whiper.cpp собираются локально, а выбранные артефакты загружаются. Полученные сборки и модели остаются в /data, поетому обычное пересоздание контейнера не поворяет эти сборки, когда постоянный том сохраняется. Stack дает первому запуску расширенный грейс-период проверки здоровья по этой причине.

Опциональный Piper TTS

Piper реализован как опциональная среда выполнения и отключен по умолчанию:

PIPER_ENABLED=false
PIPER_PACKAGE_SPEC=piper-tts

При включении ни один голос не загружаетя автоматически. Файлы .onnx голосов и сооветствующие конфигурационные файлы находтся в /data/piper/voises; они могут быть импортированы из MCP-кеша медиа с помощью piper_iport_voise_file. Это деает TTS опциональным, поскольку ComfyUI сам может хостить аудио/TTS рабочие процессы.

См. THIRD_PARTY.md для заметок о лицензировании сторонних компонентов.

Выбор релиза

Stack подерживает:

VIDEO_MCP_VERSION=latest
VIDEO_MCP_CHECK_UPDATES_ON_START=true
VIDEO_MCP_FORCE_REFRESH=false

latest означает наивысший не-черновик, не-пре-релиз GitHub Release, тег которого точно соответствует vX.Y.Z. Это не означает main.

Также можно закрепить релиз:

VIDEO_MCP_VERSION=v2.4.0

или коммит SHA:

VIDEO_MCP_VERSION=<commit-sha>

Когда проверка обновлений отключена и существует валидный источник /current, запуск полностью кеш-первым. Неудачная попытка поиса, загрузки или проверки архива откатывается к последеему извесному хорошему источнику, если таковой существует.

Постоянные томы

Stack разделяет три области ответственности:

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

Корневой каталог данных приложения по умолчанию - /data. Прямые/не Stack развертывания могут переопределить его через VIDEO_MCP_DATA_ROOT; импорт video_mcp.server или video_mcp.entrypoint не создает каталог. Каталоги среды выполнения создаются только при запуске приложения.

Виртуальное окружение Python перестраивается только при изменении requirements.txt. Перестройка очищает содержимое смонтированного каталога venv; она никогда не удаляет саму точку монтирования Docker.

Безопасность загрузчика исходного кода

Архивы исходного кода загружаются с кодолаода GitHub в промежуточный каталог и проверяются перед извлечением. Загрузчик откланяет:

• абсолютные пути;

• обход ..;

• символические ссылки;

• жеские ссылки;

• архивы с более чем одним корневым каталогом верхнего уровня.

Релиз получает .mcp-source-ready только после успешного извлечения и проверок контракта выполнения. /current переключается только после этого, так что прерванное или поврежденное обновление не может заменить последний извесный хороший источник.

Монтирования файловой системы моделей и пользовательских узлов ComfyUI доступны только для чтения. Загрузки исходного кода/моделей AI утилит используют временные файлы и проверку SHA-256 перед заменой кешированных артефактов. Опциональный мост Blender использует аутентификацию по токену Bearer и передает только объявленные входы/выходы задания, но произвольный Python Blender остается мощным, поэтому мост должен быть изолирован непривилегированной учетной записью ОС.

HyperFrames

HyperFrames работает локально в контейнере MCP и использует ту же постоянную област /data, что и MCP-кеш медиа. Ассеы браузера кешируются постоянно под /data/hyperframes-home.

Спецификация пакета по умолчанию закрепена в Stack для воспроизводимости и может быть переопределена приватно:

HYPERFRAMES_NPM_SPEC=hyperframes@0.7.111

Навыки HyperFrames намеренно отключены в этом сервере выполнения (HYPERFRAMES_SKIP_SKILLS=1).

Разработка

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 проверяет компиляцию Python, импорты сервера/точки входа, тесты, анализ YAML, синтаксис оболочки/Python-хелперов, рендеринг Compose, согласованность версий/списка изменений и защитные ограждения для секретов/частных сетей публичного репозитория.

Процесс релиза

1. Разрабатывайте на ветке и откройте PR.

2. CI должен пройти.

3. Обновите VERSION и CHANGELOG.md.

4. Слейте в main.

5. CI создает неизменяемый тег vX.Y.Z и сооветствующий стабильный GitHub Relese, если он еще не существует.

Теги/релизы приложения зарезервированы для точных имен vX.Y.Z, чтобы несвязанные модели или ресизы ассеов не могли повлиять на разрешение VIDEO_MCP_VERSION=latest.

Лицензия и атрибуция

Лицензировано по Apache License 2.0. См. LICENSE.

Рестрибьюции и производные работы должны соханять уведомление об атрибуции в NOTICE в сооветстви с Apache License 2.0. Компоненты сторонних разработчиков соханяют свои собственные лицензии; см. THIRD_PARTY.md.