video-evidence-mcp

video-evidence-mcp は、セルフホスト型の読み取り専用 MCP サービスであり、video-evidence ChatGPT/Codex プラグインです。匿名の公開 YouTube および Bilibili コンテンツを検索し、検証済みメタデータ、タイムスタンプ付きキャプションまたはローカル ASR、動画全体の分散フレーム、シーンチェンジフレーム、中国語/英語 OCR、コンタクトシート、境界付きウィンドウ再検査を含むコンパクトな証拠パッケージを生成します。

デフォルトのデプロイは 127.0.0.1:8787 のみをリッスンします。長時間の解析は Redis にキューされ、別のワーカーによって実行されます。MCP リクエストは作業をエンキューまたはポーリングするだけです。サーバー側 LLM は不要です。呼び出し元の ChatGPT はトランスクリプトと ImageContent コンタクトシートを読み取り、最終的な説明を記述します。

コードと状態は意図的に分離されています。チェックアウトにはコード/設定のみが含まれ、永続的なサービス状態はすべて専用ホストディレクトリ /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

4つのMCPツールは search_videos、start_video_analysis、get_video_analysis、get_video_window です。すべての入出力モデルは余分なフィールドを禁止します。レスポンスにはトレース ID、機械可読なステータス、警告、失敗時のエラーコードが含まれます。get_video_analysis と get_video_window は、要求された場合に圧縮 WebP ImageContent ブロックを追加します。

セキュリティ境界:

• 入力 URL は HTTPS のみの正規の YouTube/Bilibili ビデオ URL です。プレイリスト、ユーザー情報、非デフォルトポート、不明なホストは拒否されます。

• DNS 応答はループバック/プライベート/リンクローカル/予約アドレスについてチェックされます。ブラウザリクエストは選択されたプラットフォームと必要な CDN/API サフィックスに制限されます。

• TRUSTED_DNS_PROXY_CIDR はデフォルトで空です。検証済み透過プロキシが公開名を RFC 2544 ベンチマーク空間にマッピングするホストは、198.18.0.0/15 のサブネットを選択できます。任意のプライベート CIDR は設定検証によって拒否され、プラットフォーム/リダイレクトホストの許可リストは引き続き適用されます。

• アダプタは既知の閉じる/キャンセル/ログインなしで続行/クッキー/アプリのプロンプトのみを閉じます。資格情報を入力したり、CAPTCHA、年齢、支払い、プライベート、強制認証の制御をバイパスしたりすることはありません。

• プライベート Compose マッピングは正確に 127.0.0.1:8787:8787 です。Redis にホストポートはありません。AUTH_MODE=none は TRUSTED_LOOPBACK_PROXY=true でない限り非ループバックリスナーを拒否します。これはプライベート Compose デプロイがそのループバックマッピングの背後でのみ使用します。

• パブリックプロファイルは外部 OIDC/OAuth 発行者を要求し、発行者/オーディエンス/スコープ/署名を検証し、保護リソースメタデータを公開し、WWW-Authenticate を返し、リクエストをレート制限し、並行性を制限し、機密ヘッダー/クエリ値を編集します。Caddy はパブリックリクエストボディを 4 MB に制限します。

この実装は、現在の OpenAI MCP サーバーガイド、プラグインパッケージングガイド、認証ガイド、ChatGPT 接続ガイド、Secure MCP Tunnel ガイド に従います。サーバーは 公式 MCP Python SDK の現在の安定版 v2 ラインを使用します。

リソースガイダンス

検出されたサーバー (Intel N100、4コア、7.5 GiB RAM、GPUなし) では、ANALYSIS_CONCURRENCY=1、ASR_MODEL=small、ASR_COMPUTE_TYPE=int8、標準解析を24フレーム、詳細解析を48フレームに保つ必要があります。長い動画の ASR は CPU バウンドになると予想されます。画像、ブラウザバイナリ、ASR モデルキャッシュ、一時メディアには、約10〜15 GiB の空きディスクが快適な最小要件です。このチェックアウトは、デフォルトで 10 GiB の証拠制限と、ジョブごとに 4 GiB の一時メディア制限を設定しています。

サポートされている 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

インバウンドのホームネットワークポートは開かれません。AUTH_MODE=none の間は Compose ポートマッピングを 0.0.0.0:8787 に変更しないでください。

このホストが信頼できる透過 DNS プロキシを使用しているために getent ahosts www.youtube.com と getent ahosts www.bilibili.com の両方が合成 198.18.x.x アドレスを返す場合は、ローカルの無視された .env に TRUSTED_DNS_PROXY_CIDR=198.18.0.0/15 を設定してください。通常の 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

公式の Inspector CLI は、ライブの Streamable HTTP サーバーを初期化し、ツールを列挙できます:

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

ブラウザ UI の場合は、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 は推奨されるプライベートルートです。サーバーはループバック限定のままで、tunnel-client が OpenAI へのアウトバウンド HTTPS リクエストを行います。Tunnel ID とコントロールプレーン API キーはローカルで偽造できません。

1. OpenAI Platform のトンネル設定 で、トンネルを作成または選択し、目的の Platform 組織と ChatGPT ワークスペースを関連付け、オペレーターに Tunnels の読み取り+使用を許可します (作成/編集には Manage が必要です)。

2. 最新の tunnel-client を Platform ページまたは最新の公開 openai/tunnel-client リリースからダウンロードし、deploy/tunnel/tunnel-client として保存し、実行可能にして、Git の管理外に置いてください。

3. ルートとしてモード 0600 で /etc/video-evidence-mcp/tunnel.env を作成します:

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 ユーザーを作成してください。

ユニットは run の前に doctor を実行し、失敗時には再起動します。tunnel-client のローカル管理 UI、/healthz、/readyz、/metrics はループバック限定のままにしてください。シークレットは .env、Compose YAML、イメージ、コマンドラインログ、またはこのリポジトリには決して置かないでください。

ChatGPT で接続を追加する

現在の OpenAI フローに従います:

1. ChatGPT 設定 → セキュリティとログイン を開き、開発者モードを有効にします (アカウント/ワークスペースポリシーに従う)。

2. ChatGPT プラグインを開き、+ を選択し、名前/説明を入力し、Tunnel を選択して、tunnel_id を選択または貼り付けます。

3. 検出された4つのツールを確認し、接続を作成します。サーバーのツール変更後はメタデータを更新してください。

4. 同じターゲットアカウント/ワークスペースに video-evidence プラグインをインストール/有効化し、evals/plugin-behavior.json の下にある動作ケースをテストします。

リポジトリマーケットプレイス (marketplace.json) とローカル .mcp.json は開発用フィクスチャです。これらにより、プラグインはローカルの Codex/デスクトップ開発インストールに表示されますが、ChatGPT ウェブ、デスクトップ、モバイルには公開または同期しません。同じアカウント/ワークスペースでのクロスデバイス使用には、そのアカウント/ワークスペースに対応するプラグイン接続を作成/インストールする必要があります。公開利用には、OpenAI プラグインの提出/レビューと安定した公開 HTTPS エンドポイントが必要です。

Codex 開発でこのリポジトリマーケットプレイスをインストールするには:

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

変更後、インストールされた plugin-creator スキルから cachebuster ヘルパーを実行し、プラグインを再インストールします。更新されたスキル指示が読み込まれるように、新しいスレッドを開始してください。

オプションの公開 HTTPS/OAuth プロファイル

このサービス用にパスワードシステムを自作しないでください。Authorization Code、PKCE S256、MCP resource パラメータ/オーディエンス、必要なスコープ、および優先する CIMD (none または private_key_jwt) または DCR をサポートする、成熟した外部 OAuth 2.1/OIDC プロバイダーを設定してください。ログイン、同意、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 にあります。発行者のディスカバリードキュメントが、選択した Authorization Code、PKCE S256、CIMD または DCR、および正しいトークン認証方法を宣伝していることを検証してください。トークンに設定されたオーディエンスとスコープが含まれていることを検証してください。プライベート mcp サービスを公開したり、公開リスナーで AUTH_MODE=none を使用したりしないでください。

メンテナンスと運用

計画的にアップグレードし、ロックを再生成してください。1つのランタイムをその場で更新しないでください:

# 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 をバックアップするか、SQLite のオンラインバックアップ API を使用してください。証拠メタデータは /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 は別途安全に削除してください。

既知の制限とトラブルシューティング

• プラットフォームのマークアップ、キャプション、匿名アクセスポリシーは変更されます。ポップアップフィクスチャがまだ合格するがライブアクセスが失敗する場合は、編集されたステータス/セレクター診断のみを取得し、プラットフォームアダプタの安定したロール/属性/テキストを更新し、フィクスチャとライブスモークテストを再実行してください。

• 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 を必要としません。

ライブスモークテストは第三者プラットフォームに接触するため、オプトインです:

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

結果は test-results/ の下に、URL、UTC 日付、結果、正確なエラークラスとともに書き込まれます。ブロックまたはレート制限されたライブテストはそのように記録され、合格として報告されることはありません。