video-evidence-mcp

video-evidence-mcp es un servicio MCP autohospedado y de solo lectura, y un plugin video-evidence para ChatGPT/Codex. Busca contenido público anónimo de YouTube y Bilibili y produce un paquete de evidencia compacto: metadatos verificados, subtítulos con marca de tiempo o ASR local, fotogramas distribuidos de todo el vídeo, fotogramas de cambios de escena, OCR chino/inglés, hojas de contacto y reinspección acotada de ventanas.

El despliegue predeterminado escucha solo en 127.0.0.1:8787. Los análisis largos se ponen en cola en Redis y los ejecuta un worker separado; una solicitud MCP solo encola o consulta el trabajo. No se requiere LLM en el servidor. El ChatGPT que realiza la llamada lee la transcripción y la hoja de contacto ImageContent y redacta la explicación final.

El código y el estado están deliberadamente separados: el checkout contiene solo código/configuración, mientras que todo el estado persistente del servicio se monta mediante bind-mount bajo el directorio dedicado del host /data/video-evidence-mcp (app, redis, models, estado opcional de Caddy y perfil de túnel).

Arquitectura y flujo de datos

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

Las cuatro herramientas MCP son search_videos, start_video_analysis, get_video_analysis y get_video_window. Cada modelo de entrada/salida prohíbe campos adicionales. Las respuestas incluyen un ID de traza, estado legible por máquina, advertencias y un código de error en caso de fallo. get_video_analysis y get_video_window añaden un bloque ImageContent WebP comprimido cuando se solicita.

Límites de seguridad:

• Las URL de entrada son solo URL canónicas de vídeo de YouTube/Bilibili con HTTPS; se rechazan listas de reproducción, userinfo, puertos no predeterminados y hosts desconocidos.

• Las respuestas DNS se comprueban para detectar direcciones loopback/privadas/link-local/reservadas. Las solicitudes del navegador se limitan a la plataforma seleccionada y a los sufijos CDN/API requeridos.

• TRUSTED_DNS_PROXY_CIDR está vacío por defecto. Un host cuyo proxy transparente verificado mapea nombres públicos al espacio de benchmarking RFC 2544 puede optar por una subred de 198.18.0.0/15; los CIDR privados arbitrarios son rechazados por la validación de configuración, y las listas permitidas de hosts de plataforma/redirección siguen aplicándose.

• Los adaptadores solo descartan avisos conocidos de cerrar/cancelar/continuar sin iniciar sesión/cookies/aplicación. Nunca introducen credenciales ni omiten controles de CAPTCHA, edad, pago, contenido privado o autenticación forzada.

• El mapeo privado de Compose es exactamente 127.0.0.1:8787:8787; Redis no tiene puerto de host. AUTH_MODE=none rechaza un listener que no sea loopback a menos que TRUSTED_LOOPBACK_PROXY=true, que el despliegue privado de Compose usa solo detrás de ese mapeo loopback.

• El perfil público requiere un emisor OIDC/OAuth externo, valida emisor/audiencia/ámbitos/firmas, publica metadatos de recurso protegido, devuelve WWW-Authenticate, limita la tasa de solicitudes, acota la concurrencia y redacta cabeceras/valores de consulta sensibles. Caddy limita los cuerpos de solicitud pública a 4 MB.

Esta implementación sigue la guía actual de servidor MCP de OpenAI, la guía de empaquetado de plugins, la guía de autenticación, la guía de conexión de ChatGPT y la guía de Secure MCP Tunnel. El servidor usa la línea estable actual v2 del SDK oficial de MCP para Python.

Orientación sobre recursos

El servidor detectado (Intel N100, 4 núcleos, 7.5 GiB de RAM, sin GPU) debe mantener ANALYSIS_CONCURRENCY=1, ASR_MODEL=small, ASR_COMPUTE_TYPE=int8, análisis estándar a 24 fotogramas y análisis profundo a 48 fotogramas. Es de esperar que el ASR en vídeos largos esté limitado por CPU. Entre 10 y 15 GiB de disco libre son un mínimo razonable para imágenes, binarios del navegador, caché de modelos ASR y medios temporales; este checkout tiene por defecto un límite de evidencia de 10 GiB y un límite de medios temporales de 4 GiB por trabajo.

Para un host NVIDIA compatible, verifique primero nvidia-smi y NVIDIA Container Toolkit, detenga el worker de CPU y luego compile/arranque worker-gpu:

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

La imagen GPU está dirigida a CUDA 12/cuDNN 9. Este host no tiene GPU detectada, por lo que solo el perfil de CPU se valida localmente.

Inicio local

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

No se abre ningún puerto entrante de la red doméstica. No cambie el mapeo de puertos de Compose a 0.0.0.0:8787 mientras AUTH_MODE=none.

Si tanto getent ahosts www.youtube.com como getent ahosts www.bilibili.com devuelven direcciones sintéticas 198.18.x.x porque este host usa un proxy DNS transparente de confianza, establezca TRUSTED_DNS_PROXY_CIDR=198.18.0.0/15 en el .env local ignorado. Déjelo vacío en DNS normal.

Para desarrollo y pruebas dentro de la imagen bloqueada:

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

Inspector MCP

La CLI oficial del Inspector puede inicializar el servidor Streamable HTTP en vivo y enumerar las herramientas:

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

Para la interfaz de navegador, ejecute npx -y @modelcontextprotocol/inspector@latest, seleccione Streamable HTTP e introduzca http://127.0.0.1:8787/mcp. El equivalente automatizado en memoria es python scripts/mcp_smoke.py.

Activación de Secure MCP Tunnel

Secure MCP Tunnel es la ruta privada preferida: el servidor permanece solo-loopback y tunnel-client realiza solicitudes HTTPS salientes a OpenAI. Un Tunnel ID y una clave API del plano de control no se pueden fabricar localmente.

1. En los ajustes de túneles de la Plataforma OpenAI, cree o seleccione un túnel, asocie la organización de la Plataforma y el espacio de trabajo de ChatGPT previstos, y conceda al operador Tunnels Read + Use (se necesita Manage para crear/editar).

2. Descargue el último tunnel-client desde la página de la Plataforma o la última versión pública de openai/tunnel-client; guárdelo como deploy/tunnel/tunnel-client, hágalo ejecutable y manténgalo fuera de Git.

3. Cree /etc/video-evidence-mcp/tunnel.env como root con modo 0600:

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

4. Inicialice el perfil como el usuario de servicio dedicado desde /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. Instale deploy/systemd/video-evidence-compose.service y deploy/systemd/video-evidence-tunnel.service en /etc/systemd/system y luego actívelos. Son plantillas; revise las rutas absolutas y cree el usuario sin privilegios video-evidence antes de la instalación.

La unidad ejecuta doctor antes de run y se reinicia en caso de fallo. La interfaz de administración local de tunnel-client, /healthz, /readyz y /metrics deben permanecer solo-loopback. Los secretos nunca deben estar en .env, en el YAML de Compose, en una imagen, en los registros de línea de comandos ni en este repositorio.

Añadir la conexión en ChatGPT

Según el flujo actual de OpenAI:

1. Abra ChatGPT Settings → Security and login → active Developer mode (sujeto a la política de cuenta/espacio de trabajo).

2. Abra ChatGPT Plugins, seleccione +, introduzca un nombre/descripción, elija Tunnel y seleccione o pegue el tunnel_id.

3. Revise las cuatro herramientas detectadas y cree la conexión. Actualice los metadatos después de cambios en las herramientas del servidor.

4. Instale/active el plugin video-evidence en la misma cuenta/espacio de trabajo de destino y pruebe los casos de comportamiento en evals/plugin-behavior.json.

El marketplace del repositorio (marketplace.json) y el .mcp.json local son elementos de desarrollo. Hacen visible el plugin a una instalación de desarrollo local de Codex/escritorio; no lo publican ni sincronizan con ChatGPT web, escritorio y móvil. El uso entre dispositivos con la misma cuenta/espacio de trabajo requiere crear/instalar la conexión de plugin correspondiente en esa cuenta/espacio de trabajo. La disponibilidad pública requiere el envío/revisión de plugin de OpenAI y un endpoint HTTPS público estable.

Para instalar este marketplace de repositorio en el desarrollo con Codex:

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

Tras los cambios, ejecute el asistente cachebuster desde la skill plugin-creator instalada y reinstale el plugin; inicie un nuevo hilo para que se carguen las instrucciones de skill actualizadas.

Perfil público HTTPS/OAuth opcional

No escriba un sistema de contraseñas para este servicio. Configure un proveedor OAuth 2.1/OIDC externo y maduro que admita Authorization Code, PKCE S256, el parámetro/audiencia resource de MCP, los ámbitos requeridos y, o bien CIMD preferido (none o private_key_jwt), o bien DCR. El proveedor —no este repositorio— es el propietario del inicio de sesión, el consentimiento, CIMD/DCR, la emisión de tokens y la seguridad de las cuentas.

Establezca DOMAIN, OIDC_ISSUER, OIDC_AUDIENCE, OIDC_REQUIRED_SCOPES y opcionalmente OIDC_JWKS_URL, apunte el DNS público al servidor y arranque explícitamente solo los servicios públicos:

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

Caddy obtiene HTTPS automáticamente. El endpoint MCP es https://<domain>/mcp; los metadatos están en https://<domain>/.well-known/oauth-protected-resource/mcp. Valide que el documento de descubrimiento del emisor anuncia Authorization Code, PKCE S256, CIMD o DCR según lo seleccionado, y los métodos correctos de autenticación de tokens. Valide que los tokens incluyen la audiencia y los ámbitos configurados. Nunca exponga el servicio privado mcp ni use AUTH_MODE=none en un listener público.

Mantenimiento y operaciones

Actualice deliberadamente y regenere el lock; nunca actualice un runtime en caliente:

# 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

Realice una copia de seguridad de /data/video-evidence-mcp con los servicios detenidos, o use la API de copia de seguridad en línea de SQLite. Los metadatos de evidencia están en /data/video-evidence-mcp/app/video-evidence.sqlite3, los archivos de caché están en /data/video-evidence-mcp/app/cache, los archivos AOF/RDB de Redis están en /data/video-evidence-mcp/redis, y las descargas ASR están en /data/video-evidence-mcp/models. Restaure el árbol de directorios y la propiedad correspondientes antes de iniciar la misma versión de la aplicación.

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

La limpieza elimina solo entradas de evidencia caducadas o que superan el límite. Nunca borra configuración, secretos, la base de datos, el estado de Redis ni los modelos ASR. Para desinstalar, detenga primero las unidades/el stack Compose; docker compose down deja /data/video-evidence-mcp intacto. Archive ese directorio antes de eliminarlo explícitamente. Elimine /etc/video-evidence-mcp/tunnel.env por separado y de forma segura.

Limitaciones conocidas y solución de problemas

• El marcado de las plataformas, los subtítulos y la política de acceso anónimo cambian. Cuando los fixtures de popup siguen pasando pero el acceso en vivo falla, capture solo diagnósticos de estado/selector redactados, actualice los roles/atributos/texto estables del adaptador de la plataforma y vuelva a ejecutar tanto los fixtures como las pruebas de humo en vivo.

• El entorno de compilación del 2026-08-17 restableció todas las descargas TLS de la CDN de Playwright, por lo que la imagen verificada lanza explícitamente Chromium de Debian. Cuando el acceso a la CDN regrese, instale el navegador correspondiente de Playwright y elimine la sobreescritura del ejecutable durante una reconstrucción planificada.

• El proxy transparente de este host resuelve ambas plataformas en 198.18.0.0/15; su .env local ignorado confía explícitamente solo en ese CIDR de benchmarking. En otro servidor, elimine este ajuste a menos que el mismo mapeo se verifique de forma independiente.

• Las restricciones regionales, los retos anti-bots, la autenticación forzada, los controles de edad, los vídeos privados/de pago y las transmisiones en vivo se notifican como limitaciones; no se omiten.

• La extracción con yt-dlp puede romperse tras cambios en el sitio. Reprodúzcalo con yt-dlp --verbose --skip-download '<canonical-url>' en la imagen del worker, redacte los datos de la solicitud y luego actualice/bloquee/recompile.

• Los subtítulos automáticos, Whisper y el OCR pueden ser incorrectos, especialmente en nombres propios, números, habla superpuesta, texto estilizado y fotogramas de baja resolución. La Skill exige una verificación cruzada de la transcripción y la ventana visual para afirmaciones importantes.

• La detección de escenas junto con muestras fijas proporciona cobertura de todo el vídeo, no una observación completa de fotogramas. get_video_window está limitado y devuelve miniaturas en caché, nunca medios originales arbitrarios.

• El primer trabajo de ASR descarga el modelo configurado y puede tardar más. Compruebe los registros del worker, el espacio libre en disco y los permisos del volumen de modelos.

• Si el Inspector devuelve 421, compruebe la lista permitida de Host y conéctese exactamente a 127.0.0.1:8787. Si la disponibilidad es 503, compruebe el estado de Redis. Si un trabajo fue interrumpido por un reinicio, se marca explícitamente como fallido y puede reenviarse.

• La descripción visual opcional de OpenAI en el servidor está deshabilitada intencionalmente por defecto; el flujo de trabajo principal de evidencia no requiere OPENAI_API_KEY.

Las pruebas de humo en vivo son opcionales porque contactan con plataformas de terceros:

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

Los resultados se escriben en test-results/ con la URL, la fecha UTC, el resultado y la clase de error exacta. Una prueba en vivo bloqueada o limitada por tasa se registra como tal, nunca se informa como aprobada.