video-evidence-mcp

video-evidence-mcp는 자체 호스팅되는 읽기 전용 MCP 서비스이자 video-evidence ChatGPT/Codex 플러그인입니다. 익명 공개 YouTube 및 Bilibili 콘텐츠를 검색하여 간결한 증거 패키지(검증된 메타데이터, 타임스탬프가 있는 자막 또는 로컬 ASR, 비디오 전체 분산 프레임, 장면 전환 프레임, 중문/영문 OCR, 콘택트 시트, 제한된 창 재검사)를 생성합니다.

기본 배포는 127.0.0.1:8787에서만 수신 대기합니다. 오래 걸리는 분석은 Redis에 대기열로 쌓이고 별도의 작업자에 의해 실행됩니다. MCP 요청은 작업을 큐에 넣거나 폴링만 합니다. 서버 측 LLM은 필요하지 않습니다. 호출하는 ChatGPT는 대본(transcript)과 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

네 가지 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입니다. 재생 목록, userinfo, 비기본 포트, 알 수 없는 호스트는 거부됩니다.

• 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는 공개 요청 본문을 4MB로 제한합니다.

이 구현은 현재 OpenAI MCP 서버 가이드, 플러그인 패키징 가이드, 인증 가이드, ChatGPT 연결 가이드, Secure MCP Tunnel 가이드를 따릅니다. 서버는 공식 MCP Python SDK의 현재 안정적인 v2 라인을 사용합니다.

리소스 지침

감지된 서버(Intel N100, 4코어, 7.5GiB RAM, GPU 없음)는 ANALYSIS_CONCURRENCY=1, ASR_MODEL=small, ASR_COMPUTE_TYPE=int8, 표준 분석 24프레임, 심층 분석 48프레임을 유지해야 합니다. 긴 동영상의 ASR은 CPU 바운드가 될 것으로 예상됩니다. 약 10~15GiB의 여유 디스크는 이미지, 브라우저 바이너리, ASR 모델 캐시, 임시 미디어에 적절한 최소 용량입니다. 이 체크아웃은 기본적으로 10GiB 증거 제한과 작업당 4GiB 임시 미디어 제한을 사용합니다.

지원되는 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. Platform 페이지 또는 최신 공개 openai/tunnel-client 릴리스에서 최신 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. 동일한 대상 계정/작업 영역에 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을 사용하지 마십시오.

유지 관리 및 운영

신중하게 업그레이드하고 잠금 파일을 다시 생성하십시오. 런타임 하나를 제자리에서 업데이트하지 마십시오:

# 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은 특히 고유명사, 숫자, 겹치는 음성, 스타일화된 텍스트, 저해상도 프레임에서 틀릴 수 있습니다. Skill은 중요한 주장에 대해 대본/시각 창 상호 검증을 요구합니다.

• 장면 감지와 고정 샘플은 전체 비디오 범위를 제공하지만 프레임 완전 관찰은 아닙니다. 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

결과는 URL, UTC 날짜, 결과, 정확한 오류 클래스와 함께 test-results/ 아래에 기록됩니다. 차단되거나 속도 제한된 라이브 테스트는 그렇게 기록되며 통과로 보고되지 않습니다.