video-evidence-mcp

video-evidence-mcp ist ein selbst gehosteter, schreibgeschützter MCP-Dienst und ein video-evidence-Plugin für ChatGPT/Codex. Es durchsucht anonyme öffentliche YouTube- und Bilibili-Inhalte und erzeugt ein kompaktes Beweispaket: verifizierte Metadaten, mit Zeitstempeln versehene Untertitel oder lokale ASR, über das gesamte Video verteilte Frames, Szenenwechsel-Frames, chinesische/englische OCR, Kontaktbögen und eine begrenzte Fenster-Nachprüfung.

Die Standardbereitstellung lauscht nur auf 127.0.0.1:8787. Längere Analysen werden in Redis eingereiht und von einem separaten Worker ausgeführt; eine MCP-Anfrage stellt lediglich Arbeit in die Warteschlange oder fragt den Status ab. Es ist kein serverseitiges LLM erforderlich. Das aufrufende ChatGPT liest das Transkript und den ImageContent-Kontaktbogen und verfasst die abschließende Erklärung.

Code und Zustand sind bewusst getrennt: Das Checkout enthält nur Code/Konfiguration, während der gesamte persistente Dienstzustand unter dem dedizierten Host-Verzeichnis /data/video-evidence-mcp (app, redis, models, optional Caddy-Zustand und Tunnel-Profil) bind-gemountet ist.

Architektur und Datenfluss

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

Die vier MCP-Tools sind search_videos, start_video_analysis, get_video_analysis und get_video_window. Jedes Eingabe-/Ausgabemodell verbietet zusätzliche Felder. Antworten enthalten eine Trace-ID, einen maschinenlesbaren Status, Warnungen und bei Fehlern einen Fehlercode. get_video_analysis und get_video_window fügen auf Wunsch einen komprimierten WebP-ImageContent-Block hinzu.

Sicherheitsgrenzen:

• Eingabe-URLs sind ausschließlich HTTPS-kanonische YouTube/Bilibili-Video-URLs; Playlists, Userinfo, nicht standardmäßige Ports und unbekannte Hosts werden abgelehnt.

• DNS-Antworten werden auf Loopback-/private/link-lokale/reservierte Adressen geprüft. Browseranfragen sind auf die ausgewählte Plattform und die erforderlichen CDN/API-Suffixe beschränkt.

• TRUSTED_DNS_PROXY_CIDR ist standardmäßig leer. Ein Host, dessen verifizierter transparenter Proxy öffentliche Namen in den RFC-2544-Benchmarkbereich abbildet, kann sich für ein Subnetz von 198.18.0.0/15 entscheiden; beliebige private CIDRs werden durch die Konfigurationsvalidierung abgelehnt, und die Plattform-/Redirect-Host-Allowlists gelten weiterhin.

• Die Adapter blenden nur bekannte Schließen-/Abbrechen-/Weiter-ohne-Anmeldung-/Cookie-/App-Prompts aus. Sie geben niemals Anmeldedaten ein und umgehen keine CAPTCHA-, Alters-, Zahlungs-, Privat- oder Zwangsauthentifizierungskontrollen.

• Das private Compose-Mapping ist exakt 127.0.0.1:8787:8787; Redis hat keinen Host-Port. AUTH_MODE=none verweigert einen Nicht-Loopback-Listener, es sei denn, TRUSTED_LOOPBACK_PROXY=true, was die private Compose-Bereitstellung nur hinter diesem Loopback-Mapping verwendet.

• Das öffentliche Profil erfordert einen externen OIDC/OAuth-Issuer, validiert Issuer/Audience/Scopes/Signaturen, veröffentlicht Metadaten für geschützte Ressourcen, gibt WWW-Authenticate zurück, begrenzt Anfragenraten, begrenzt die Nebenläufigkeit und schwärzt sensible Header/Query-Werte. Caddy begrenzt öffentliche Anforderungskörper auf 4 MB.

Diese Implementierung folgt dem aktuellen OpenAI-MCP-Serverleitfaden, Plugin-Paketierungsleitfaden, Authentifizierungsleitfaden, ChatGPT-Verbindungsleitfaden und Secure-MCP-Tunnel-Leitfaden. Der Server verwendet die aktuelle stabile v2-Linie des offiziellen MCP-Python-SDKs.

Hinweise zu Ressourcen

Der erkannte Server (Intel N100, 4 Kerne, 7.5 GiB RAM, keine GPU) sollte ANALYSIS_CONCURRENCY=1, ASR_MODEL=small, ASR_COMPUTE_TYPE=int8, Standardanalyse mit 24 Frames und Tiefenanalyse mit 48 Frames beibehalten. Erwarten Sie, dass ASR bei langen Videos CPU-gebunden ist. Etwa 10–15 GiB freier Speicherplatz sind ein angenehmes Minimum für Bilder, Browser-Binärdateien, ASR-Modell-Cache und temporäre Medien; dieses Checkout hat standardmäßig ein Beweislimit von 10 GiB und ein temporäres Medienlimit von 4 GiB pro Auftrag.

Für einen unterstützten NVIDIA-Host überprüfen Sie zuerst nvidia-smi und das NVIDIA Container Toolkit, stoppen Sie den CPU-Worker und erstellen/starten Sie dann worker-gpu:

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

Das GPU-Image zielt auf CUDA 12/cuDNN 9. Dieser Host hat keine erkannte GPU, daher wird nur das CPU-Profil lokal validiert.

Lokaler Start

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

Es wird kein eingehender Heimnetzwerk-Port geöffnet. Ändern Sie das Compose-Port-Mapping nicht auf 0.0.0.0:8787, solange AUTH_MODE=none gilt.

Wenn sowohl getent ahosts www.youtube.com als auch getent ahosts www.bilibili.com synthetische 198.18.x.x-Adressen zurückgeben, weil dieser Host einen vertrauenswürdigen transparenten DNS-Proxy verwendet, setzen Sie TRUSTED_DNS_PROXY_CIDR=198.18.0.0/15 in der lokalen ignorierten .env. Bei gewöhnlichem DNS lassen Sie es leer.

Für Entwicklung und Tests innerhalb des gesperrten Images:

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

Die offizielle Inspector-CLI kann den Live-Streamable-HTTP-Server initialisieren und Tools auflisten:

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

Für die Browser-UI führen Sie npx -y @modelcontextprotocol/inspector@latest aus, wählen Streamable HTTP und geben http://127.0.0.1:8787/mcp ein. Das automatisierte In-Memory-Äquivalent ist python scripts/mcp_smoke.py.

Aktivierung des Secure MCP Tunnel

Secure MCP Tunnel ist die bevorzugte private Route: Der Server bleibt reiner Loopback, und tunnel-client stellt ausgehende HTTPS-Anfragen an OpenAI. Eine Tunnel-ID und ein Control-Plane-API-Schlüssel können lokal nicht erzeugt werden.

1. Öffnen Sie in den OpenAI-Platform-Tunnel-Einstellungen einen Tunnel oder wählen Sie einen aus, ordnen Sie die gewünschte Platform-Organisation und den ChatGPT-Arbeitsbereich zu und gewähren Sie dem Betreiber Tunnels Lesen + Verwenden (Verwalten ist zum Erstellen/Bearbeiten erforderlich).

2. Laden Sie den neuesten tunnel-client von der Platform-Seite oder dem neuesten öffentlichen openai/tunnel-client-Release herunter; speichern Sie ihn als deploy/tunnel/tunnel-client, machen Sie ihn ausführbar und halten Sie ihn aus Git heraus.

3. Erstellen Sie /etc/video-evidence-mcp/tunnel.env als root mit Modus 0600:

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

4. Initialisieren Sie das Profil als dedizierter Dienstbenutzer aus /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. Installieren Sie deploy/systemd/video-evidence-compose.service und deploy/systemd/video-evidence-tunnel.service unter /etc/systemd/system und aktivieren Sie sie. Dies sind Vorlagen; überprüfen Sie absolute Pfade und erstellen Sie den unprivilegierten Benutzer video-evidence vor der Installation.

Die Unit führt doctor vor run aus und startet bei Fehlern neu. Die lokale Admin-UI von tunnel-client, /healthz, /readyz und /metrics sollten reiner Loopback bleiben. Geheimnisse gehören niemals in .env, Compose-YAML, ein Image, Befehlszeilenprotokolle oder dieses Repository.

Verbindung in ChatGPT hinzufügen

Gemäß dem aktuellen OpenAI-Ablauf:

1. Öffnen Sie ChatGPT-Einstellungen → Sicherheit und Anmeldung → aktivieren Sie den Entwicklermodus (abhängig von der Konto-/Arbeitsbereichsrichtlinie).

2. Öffnen Sie ChatGPT-Plugins, wählen Sie +, geben Sie einen Namen/eine Beschreibung ein, wählen Sie Tunnel und wählen Sie die tunnel_id aus oder fügen Sie sie ein.

3. Überprüfen Sie die entdeckten vier Tools und erstellen Sie die Verbindung. Aktualisieren Sie Metadaten nach Server-Tool-Änderungen.

4. Installieren/aktivieren Sie das Plugin video-evidence im selben Zielkonto/-arbeitsbereich und testen Sie die Verhaltensfälle unter evals/plugin-behavior.json.

Der Repository-Marketplace (marketplace.json) und das lokale .mcp.json sind Entwicklungs-Fixtures. Sie machen das Plugin für eine lokale Codex-/Desktop-Entwicklungsinstallation sichtbar; sie veröffentlichen oder synchronisieren es nicht mit ChatGPT Web, Desktop und Mobile. Die geräteübergreifende Nutzung im selben Konto/Arbeitsbereich erfordert das Erstellen/Installieren der entsprechenden Plugin-Verbindung in diesem Konto/Arbeitsbereich. Die öffentliche Verfügbarkeit erfordert die Einreichung/Überprüfung des OpenAI-Plugins und einen stabilen öffentlichen HTTPS-Endpunkt.

Um diesen Repository-Marketplace in der Codex-Entwicklung zu installieren:

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

Führen Sie nach Änderungen den Cachebuster-Helfer aus der installierten plugin-creator-Fertigkeit aus und installieren Sie das Plugin neu; starten Sie einen neuen Thread, damit die aktualisierten Fertigkeitsanweisungen geladen werden.

Optionales öffentliches HTTPS/OAuth-Profil

Schreiben Sie kein Passwortsystem für diesen Dienst. Konfigurieren Sie einen ausgereiften externen OAuth-2.1/OIDC-Anbieter, der Authorization Code, PKCE S256, den MCP-resource-Parameter/die Audience, erforderliche Scopes und entweder bevorzugtes CIMD (none oder private_key_jwt) oder DCR unterstützt. Der Anbieter – nicht dieses Repository – besitzt Anmeldung, Einwilligung, CIMD/DCR, Token-Ausstellung und Kontosicherheit.

Setzen Sie DOMAIN, OIDC_ISSUER, OIDC_AUDIENCE, OIDC_REQUIRED_SCOPES und optional OIDC_JWKS_URL, zeigen Sie mit öffentlichem DNS auf den Server und starten Sie explizit nur die öffentlichen Dienste:

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

Caddy erhält HTTPS automatisch. Der MCP-Endpunkt ist https://<domain>/mcp; Metadaten befinden sich unter https://<domain>/.well-known/oauth-protected-resource/mcp. Validieren Sie, dass das Issuer-Discovery-Dokument Authorization Code, PKCE S256, CIMD oder DCR wie ausgewählt und korrekte Token-Authentifizierungsmethoden bewirbt. Validieren Sie, dass Token die konfigurierte Audience und Scopes enthalten. Legen Sie den privaten mcp-Dienst niemals offen und verwenden Sie AUTH_MODE=none nicht auf einem öffentlichen Listener.

Wartung und Betrieb

Führen Sie Upgrades bewusst durch und erzeugen Sie die Lockdatei neu; aktualisieren Sie niemals eine Laufzeit direkt an Ort und Stelle:

# 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

Sichern Sie /data/video-evidence-mcp, während die Dienste gestoppt sind, oder verwenden Sie die Online-Backup-API von SQLite. Beweismetadaten befinden sich in /data/video-evidence-mcp/app/video-evidence.sqlite3, Cache-Dateien unter /data/video-evidence-mcp/app/cache, Redis-AOF/RDB-Dateien unter /data/video-evidence-mcp/redis und ASR-Downloads unter /data/video-evidence-mcp/models. Stellen Sie den passenden Verzeichnisbaum und die Eigentümerschaft wieder her, bevor Sie dieselbe Anwendungsversion starten.

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

Die Bereinigung entfernt nur abgelaufene/über dem Limit liegende Beweiseinträge. Sie löscht niemals Konfiguration, Geheimnisse, die Datenbank, Redis-Zustand oder ASR-Modelle. Zum Deinstallieren stoppen Sie zuerst die Units/Compose-Stapel; docker compose down lässt /data/video-evidence-mcp unberührt. Archivieren Sie dieses Verzeichnis, bevor Sie es explizit entfernen. Entfernen Sie /etc/video-evidence-mcp/tunnel.env separat und sicher.

Bekannte Einschränkungen und Fehlerbehebung

• Plattform-Markup, Untertitel und die Richtlinie für anonymen Zugriff ändern sich. Wenn Popup-Fixtures weiterhin bestehen, aber der Live-Zugriff fehlschlägt, erfassen Sie nur geschwärzte Status-/Selektor-Diagnosen, aktualisieren Sie die stabilen Rollen/Attribute/Texte des Plattform-Adapters und führen Sie Fixture- plus Live-Smoke-Tests erneut aus.

• Die Build-Umgebung von 2026-08-17 hat jeden Playwright-CDN-TLS-Download zurückgesetzt, daher startet das verifizierte Image ausdrücklich Debian Chromium. Wenn der CDN-Zugriff zurückkehrt, installieren Sie den passenden Browser von Playwright und entfernen Sie die Ausführungs-Override bei einem geplanten Neubau.

• Der transparente Proxy dieses Hosts löst beide Plattformen in 198.18.0.0/15 auf; seine ignorierte lokale .env vertraut nur diesem Benchmark-CIDR ausdrücklich. Entfernen Sie diese Einstellung auf einem anderen Server, es sei denn, dasselbe Mapping ist unabhängig verifiziert.

• Regionsbeschränkungen, Bot-Herausforderungen, erzwungene Authentifizierung, Alterssperren, private/bezahlte Videos und Live-Streams werden als Einschränkungen gemeldet; sie werden nicht umgangen.

• Die yt-dlp-Extraktion kann nach Website-Änderungen brechen. Reproduzieren Sie mit yt-dlp --verbose --skip-download '<canonical-url>' im Worker-Image, schwärzen Sie Anforderungsdaten und führen Sie dann Upgrade/Lock/Neubau durch.

• Automatische Untertitel, Whisper und OCR können falsch sein, insbesondere bei Eigennamen, Zahlen, überlappender Sprache, stilisierter Schrift und niedrig aufgelösten Frames. Die Fertigkeit erfordert für wichtige Behauptungen eine Kreuzprüfung von Transkript und visuellem Fenster.

• Szenenerkennung plus feste Stichproben ergibt eine Abdeckung des gesamten Videos, keine vollständige Frame-Beobachtung. get_video_window ist begrenzt und gibt zwischengespeicherte Thumbnails zurück, niemals beliebige Originalmedien.

• Der erste ASR-Auftrag lädt das konfigurierte Modell herunter und kann länger dauern. Prüfen Sie Worker-Logs, freien Speicherplatz und Berechtigungen des Modell-Volumes.

• Wenn Inspector 421 zurückgibt, überprüfen Sie die Host-Allowlist und verbinden Sie sich exakt mit 127.0.0.1:8787. Wenn die Bereitschaft 503 ist, überprüfen Sie den Redis-Status. Wenn ein Auftrag durch einen Neustart unterbrochen wurde, wird er ausdrücklich als fehlgeschlagen markiert und kann erneut eingereicht werden.

• Die optionale serverseitige OpenAI-Visualbeschreibung ist standardmäßig absichtlich deaktiviert; der Kern-Beweisworkflow erfordert kein OPENAI_API_KEY.

Live-Smoke-Tests sind optional, da sie Drittplattformen kontaktieren:

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

Ergebnisse werden unter test-results/ mit URL, UTC-Datum, Ergebnis und exakter Fehlerklasse geschrieben. Ein blockierter oder ratenbegrenzter Live-Test wird als solcher aufgezeichnet und niemals als bestanden gemeldet.