video-evidence-mcp

video-evidence-mcp — это самостоятельно размещаемый (self-hosted), read-only MCP-сервис и плагин video-evidence для ChatGPT/Codex. Он ищет анонимный общедоступный контент YouTube и Bilibili и формирует компактный пакет доказательств: проверенные метаданные, субтитры с временными метками или локальный ASR, распределённые по всему видео кадры, кадры смены сцен, китайский/английский OCR, контактные листы и ограниченную повторную проверку окна.

По умолчанию развёртывание прослушивает только 127.0.0.1:8787. Длительные анализы помещаются в очередь Redis и выполняются отдельным воркером; запрос MCP только ставит задачу в очередь или опрашивает её статус. Серверный LLM не требуется. Вызывающий ChatGPT читает транскрипт и контактный лист ImageContent и пишет итоговое объяснение.

Код и состояние намеренно разделены: в checkout-каталоге находится только код/конфигурация, а всё постоянное состояние сервиса подмонтировано (bind-mount) ниже выделенного каталога хоста /data/video-evidence-mcp (app, redis, models, опциональное состояние Caddy и профиль туннеля).

Архитектура и поток данных

ChatGPT/Codex plugin
        |
        | Secure MCP Tunnel (outbound HTTPS only)
        v
127.0.0.1:8787/mcp  -> MCP service -> SQLite/WAL job + evidence metadata
                                      |
                                      v
                                Redis durable queue
                                      |
                                      v
                                  one worker
                                      |
          URL/DNS guard -> yt-dlp metadata -> Playwright popup handling
                                      |
                  captions -> faster-whisper fallback
                                      |
              FFmpeg distributed + scene frames -> timestamp overlay
                                      |
                    RapidOCR -> evidence selection -> WebP sheets
                                      |
              retain metadata/transcript/OCR/thumbnails; delete raw media

Четыре инструмента MCP: search_videos, start_video_analysis, get_video_analysis и get_video_window. Каждая модель ввода/вывода запрещает дополнительные поля. Ответы включают идентификатор трассировки, машиночитаемый статус, предупреждения и код ошибки при сбое. get_video_analysis и get_video_window добавляют сжатый WebP-блок ImageContent по запросу.

Границы безопасности:

• Входные URL-адреса — это только HTTPS-канонические URL-адреса видео YouTube/Bilibili; плейлисты, userinfo, нестандартные порты и неизвестные хосты отклоняются.

• Ответы DNS проверяются на наличие loopback/частных/link-local/зарезервированных адресов. Запросы браузера ограничены выбранной платформой и требуемыми суффиксами CDN/API.

• TRUSTED_DNS_PROXY_CIDR по умолчанию пуст. Хост, чей проверенный прозрачный прокси отображает публичные имена в пространство RFC 2544 для бенчмарков, может включить подсеть 198.18.0.0/15; произвольные частные CIDR отклоняются проверкой конфигурации, а списки разрешённых хостов платформы/редиректов по-прежнему действуют.

• Адаптеры только закрывают известные подсказки close/cancel/continue-without-login/cookie/app. Они никогда не вводят учётные данные и не обходят CAPTCHA, возрастные ограничения, платёжные, приватные или принудительные проверки подлинности.

• Приватное сопоставление Compose — ровно 127.0.0.1:8787:8787; Redis не имеет порта на хосте. AUTH_MODE=none отказывает в не-loopback слушателе, если только TRUSTED_LOOPBACK_PROXY=true; приватное развёртывание Compose использует это только за этим loopback-сопоставлением.

• Публичный профиль требует внешнего OIDC/OAuth-провайдера, проверяет issuer/audience/scopes/подписи, публикует метаданные защищённого ресурса, возвращает WWW-Authenticate, ограничивает частоту запросов, ограничивает параллелизм и редактирует чувствительные заголовки/значения параметров. Caddy ограничивает публичные тела запросов 4 МБ.

Эта реализация следует текущему руководству по MCP-серверам OpenAI, руководству по упаковке плагинов, руководству по аутентификации, руководству по подключению ChatGPT и руководству по Secure MCP Tunnel. Сервер использует текущую стабильную линию v2 официального MCP Python SDK.

Рекомендации по ресурсам

Обнаруженный сервер (Intel N100, 4 ядра, 7.5 ГиБ ОЗУ, без GPU) должен сохранять ANALYSIS_CONCURRENCY=1, ASR_MODEL=small, ASR_COMPUTE_TYPE=int8, стандартный анализ с 24 кадрами и глубокий анализ с 48 кадрами. Ожидайте, что ASR на длинных видео будет упираться в CPU. Около 10–15 ГиБ свободного диска — комфортный минимум для изображений, бинарников браузера, кэша моделей ASR и временных медиа; данная рабочая копия по умолчанию использует лимит доказательств 10 ГиБ и лимит временных медиа 4 ГиБ на задачу.

Для поддерживаемого хоста NVIDIA сначала проверьте nvidia-smi и NVIDIA Container Toolkit, остановите CPU-воркер, затем соберите/запустите worker-gpu:

sudo docker compose stop worker
sudo docker compose --profile gpu up -d --build worker-gpu

Образ GPU рассчитан на CUDA 12/cuDNN 9. На этом хосте GPU не обнаружен, поэтому локально проверен только CPU-профиль.

Локальный запуск

cp .env.example .env
sudo ./scripts/prepare_data_dir.sh /data/video-evidence-mcp
sudo docker compose build mcp
sudo docker compose up -d --wait redis mcp worker
curl --fail http://127.0.0.1:8787/healthz
curl --fail http://127.0.0.1:8787/readyz

Ни один входящий порт домашней сети не открывается. Не меняйте сопоставление портов Compose на 0.0.0.0:8787, пока AUTH_MODE=none.

Если и getent ahosts www.youtube.com, и getent ahosts www.bilibili.com возвращают синтетические адреса 198.18.x.x, потому что этот хост использует доверенный прозрачный DNS-прокси, установите TRUSTED_DNS_PROXY_CIDR=198.18.0.0/15 в локальном игнорируемом .env. При обычном DNS оставьте его пустым.

Для разработки и тестов внутри заблокированного образа:

sudo docker compose run --rm --no-deps mcp ruff check .
sudo docker compose run --rm --no-deps mcp mypy src
sudo docker compose run --rm --no-deps mcp pytest

MCP Inspector

Официальный CLI Inspector может инициализировать живой Streamable HTTP-сервер и перечислить инструменты:

npx -y @modelcontextprotocol/inspector@latest --cli \
  http://127.0.0.1:8787/mcp --transport http --method tools/list

Для браузерного интерфейса выполните npx -y @modelcontextprotocol/inspector@latest, выберите Streamable HTTP и введите http://127.0.0.1:8787/mcp. Автоматизированный эквивалент в памяти — python scripts/mcp_smoke.py.

Активация Secure MCP Tunnel

Secure MCP Tunnel — предпочтительный приватный маршрут: сервер остаётся loopback-only, а tunnel-client совершает исходящие HTTPS-запросы к OpenAI. Tunnel ID и ключ API плоскости управления невозможно создать локально.

1. В настройках туннелей OpenAI Platform создайте или выберите туннель, свяжите целевую организацию Platform и рабочее пространство ChatGPT и предоставьте оператору права Tunnels Read + Use (Manage требуется для создания/редактирования).

2. Скачайте последний tunnel-client со страницы Platform или из последнего публичного релиза openai/tunnel-client; сохраните его как deploy/tunnel/tunnel-client, сделайте исполняемым и не добавляйте в Git.

3. Создайте /etc/video-evidence-mcp/tunnel.env от root с правами 0600:

TUNNEL_ID=tunnel_...
CONTROL_PLANE_API_KEY=sk-...

4. Инициализируйте профиль от выделенного служебного пользователя из /data/video-evidence-mcp/tunnel:

cd /data/video-evidence-mcp/tunnel
set -a
. /etc/video-evidence-mcp/tunnel.env
set +a
/opt/video-evidence-mcp/deploy/tunnel/init-profile.sh
tunnel-client doctor --profile video-evidence --explain

5. Установите deploy/systemd/video-evidence-compose.service и deploy/systemd/video-evidence-tunnel.service в /etc/systemd/system, затем включите их. Это шаблоны; проверьте абсолютные пути и создайте непривилегированного пользователя video-evidence до установки.

Модуль запускает doctor перед run и перезапускается при сбое. Локальный административный UI tunnel-client, /healthz, /readyz и /metrics должны оставаться loopback-only. Секреты никогда не должны находиться в .env, Compose YAML, образе, журналах командной строки или этом репозитории.

Добавление подключения в ChatGPT

Согласно текущему процессу OpenAI:

1. Откройте ChatGPT Settings → Security and login → включите режим разработчика (в зависимости от политики аккаунта/рабочего пространства).

2. Откройте ChatGPT Plugins, выберите +, введите имя/описание, выберите Tunnel и выберите или вставьте tunnel_id.

3. Проверьте обнаруженные четыре инструмента и создайте подключение. Обновляйте метаданные после изменений инструментов сервера.

4. Установите/включите плагин video-evidence в том же целевом аккаунте/рабочем пространстве и протестируйте сценарии поведения из evals/plugin-behavior.json.

Репозиторный маркетплейс (marketplace.json) и локальный .mcp.json — это фикстуры для разработки. Они делают плагин видимым для локальной установки Codex/desktop разработки; они не публикуют и не синхронизируют его с ChatGPT web, desktop и mobile. Использование на нескольких устройствах в одном аккаунте/рабочем пространстве требует создания/установки соответствующего подключения плагина в этом аккаунте/рабочем пространстве. Публичная доступность требует отправки/проверки плагина OpenAI и стабильной публичной HTTPS-конечной точки.

Чтобы установить этот репозиторный маркетплейс в Codex-разработке:

codex plugin marketplace add /absolute/path/to/video-evidence-mcp

После изменений запустите cachebuster-хелпер из установленного навыка plugin-creator и переустановите плагин; начните новый поток (thread), чтобы загрузились обновлённые инструкции навыка.

Опциональный публичный профиль HTTPS/OAuth

Не пишите собственную систему паролей для этого сервиса. Настройте зрелого внешнего провайдера OAuth 2.1/OIDC, поддерживающего Authorization Code, PKCE S256, параметр/аудиторию resource для MCP, требуемые scopes и либо предпочтительный CIMD (none или private_key_jwt), либо DCR. Провайдер — а не этот репозиторий — владеет входом, согласием, CIMD/DCR, выпуском токенов и безопасностью аккаунта.

Задайте DOMAIN, OIDC_ISSUER, OIDC_AUDIENCE, OIDC_REQUIRED_SCOPES и опционально OIDC_JWKS_URL, укажите публичный DNS на сервер и явно запустите только публичные сервисы:

sudo docker compose --profile public up -d --build redis mcp-public worker-public caddy

Caddy автоматически получает HTTPS. Конечная точка MCP — https://<domain>/mcp; метаданные находятся на https://<domain>/.well-known/oauth-protected-resource/mcp. Убедитесь, что документ обнаружения issuer рекламирует Authorization Code, PKCE S256, выбранный CIMD или DCR и корректные методы аутентификации токенов. Убедитесь, что токены включают настроенную аудиторию и scopes. Никогда не открывайте приватный сервис mcp и не используйте AUTH_MODE=none на публичном слушателе.

Обслуживание и эксплуатация

Обновляйтесь осознанно и перегенерируйте lock-файл; никогда не обновляйте один рантайм на месте:

# All Python dependencies, including yt-dlp/faster-whisper/RapidOCR
sudo docker run --rm -e UV_CACHE_DIR=/app/.uv-cache -v "$PWD:/app" -w /app \
  ghcr.io/astral-sh/uv:python3.12-bookworm-slim lock --upgrade

# Prefer Playwright's matching Chromium when its CDN is reachable
sudo docker compose run --rm --user root mcp playwright install chromium

# Rebuild (the image has a distro Chromium fallback for restricted CDNs)
sudo docker compose build --pull --no-cache mcp
sudo docker compose up -d --wait redis mcp worker

# Choose a different ASR model only after sizing CPU/RAM/disk
sed -i 's/^ASR_MODEL=.*/ASR_MODEL=medium/' .env
sudo docker compose up -d worker

Создавайте резервную копию /data/video-evidence-mcp при остановленных сервисах или используйте онлайн-API резервного копирования SQLite. Метаданные доказательств находятся в /data/video-evidence-mcp/app/video-evidence.sqlite3, файлы кэша — в /data/video-evidence-mcp/app/cache, файлы Redis AOF/RDB — в /data/video-evidence-mcp/redis, а загрузки ASR — в /data/video-evidence-mcp/models. Восстановите соответствующее дерево каталогов и владельца перед запуском той же версии приложения.

sudo docker compose logs --since 1h mcp worker
sudo docker compose exec mcp video-evidence-cache disk-check
sudo docker compose exec mcp video-evidence-cache cleanup --dry-run
sudo docker compose exec mcp video-evidence-cache cleanup

Очистка удаляет только просроченные/превышающие лимит записи доказательств. Она никогда не удаляет конфигурацию, секреты, базу данных, состояние Redis или модели ASR. Для удаления сначала остановите модули/стек Compose; docker compose down оставляет /data/video-evidence-mcp нетронутым. Заархивируйте этот каталог перед явным удалением. Удалите /etc/video-evidence-mcp/tunnel.env отдельно и безопасно.

Известные ограничения и устранение неполадок

• Разметка платформ, субтитры и политика анонимного доступа меняются. Когда фикстуры всплывающих окон всё ещё проходят, а живой доступ не работает, собирайте только отредактированные диагностические данные о статусе/селекторах, обновляйте стабильные роли/атрибуты/текст адаптера платформы и повторно запускайте фикстуры плюс живые smoke-тесты.

• Сборочное окружение от 2026-08-17 сбросило все загрузки Playwright CDN TLS, поэтому проверенный образ явно запускает Debian Chromium. Когда доступ к CDN вернётся, установите соответствующий браузер Playwright и удалите переопределение исполняемого файла во время плановой пересборки.

• Прозрачный прокси этого хоста разрешает обе платформы в 198.18.0.0/15; его игнорируемый локальный .env явно доверяет только этому бенчмаркинг-CIDR. На другом сервере удалите этот параметр, если то же сопоставление не проверено независимо.

• Региональные ограничения, бот-челленджи, принудительная аутентификация, возрастные ограничения, приватные/платные видео и прямые эфиры сообщаются как ограничения; они не обходятся.

• Извлечение yt-dlp может сломаться после изменений сайта. Воспроизведите с помощью yt-dlp --verbose --skip-download '<canonical-url>' в образе воркера, отредактируйте данные запроса, затем обновите/зафиксируйте/пересоберите.

• Автоматические субтитры, Whisper и OCR могут ошибаться, особенно в именах собственных, числах, перекрывающейся речи, стилизованном тексте и кадрах низкого разрешения. Навык требует перекрёстной проверки транскрипта/визуального окна для важных утверждений.

• Обнаружение сцен плюс фиксированные выборки даёт покрытие всего видео, а не покадровое наблюдение. get_video_window ограничен и возвращает кэшированные миниатюры, никогда не произвольные исходные медиа.

• Первая задача ASR загружает настроенную модель и может занять больше времени. Проверяйте журналы воркера, свободное место на диске и права на том моделей.

• Если Inspector возвращает 421, проверьте список разрешённых Host и подключайтесь ровно к 127.0.0.1:8787. Если готовность возвращает 503, проверьте здоровье Redis. Если задание было прервано перезапуском, оно явно помечено как неудавшееся и его можно отправить повторно.

• Опциональное серверное визуальное описание OpenAI намеренно отключено по умолчанию; основной рабочий процесс доказательств не требует OPENAI_API_KEY.

Живые smoke-тесты являются опциональными, поскольку они обращаются к сторонним платформам:

RUN_LIVE_TESTS=1 pytest -m live -vv
python scripts/live_smoke.py
python scripts/live_analysis_smoke.py

Результаты записываются в test-results/ с URL, датой UTC, результатом и точным классом ошибки. Заблокированный или ограниченный по частоте живой тест фиксируется как таковой и никогда не сообщается как пройденный.