video-evidence-mcp

video-evidence-mcp 是一个自托管的只读 MCP 服务，也是一个 video-evidence ChatGPT/Codex 插件。它搜索匿名的公共 YouTube 和 Bilibili 内容，并生成一个紧凑的证据包：已验证的元数据、带时间戳的字幕或本地 ASR、全视频分布式帧、场景变化帧、中/英文 OCR、联系表和有界窗口复查。

默认部署仅监听 127.0.0.1:8787。长时间分析在 Redis 中排队，由单独的 worker 执行；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

四个 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 会被配置验证拒绝，并且平台/重定向主机允许列表仍然适用。

• 适配器只会关闭已知的关闭/取消/继续而不登录/cookie/应用提示。它们绝不会输入凭据或绕过 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 内存、无 GPU）应保持 ANALYSIS_CONCURRENCY=1、ASR_MODEL=small、ASR_COMPUTE_TYPE=int8，标准分析为 24 帧，深度分析为 48 帧。预计长视频的 ASR 会受 CPU 限制。大约 10–15 GiB 的可用磁盘是图像、浏览器二进制文件、ASR 模型缓存和临时媒体的舒适下限；此检出默认将证据限制为 10 GiB，并将每个作业的临时媒体限制为 4 GiB。

对于受支持的 NVIDIA 主机，首先验证 nvidia-smi 和 NVIDIA Container Toolkit，停止 CPU worker，然后构建/启动 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。

如果 getent ahosts www.youtube.com 和 getent ahosts www.bilibili.com 都返回合成的 198.18.x.x 地址，因为此主机使用受信任的透明 DNS 代理，请在本地被忽略的 .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 读取 + 使用（创建/编辑需要管理权限）。

2. 从 Platform 页面或最新的公共 openai/tunnel-client 版本下载最新的 tunnel-client；将其保存为 deploy/tunnel/tunnel-client，使其可执行，并将其排除在 Git 之外。

3. 以 root 身份创建 /etc/video-evidence-mcp/tunnel.env，模式为 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 用户。

该单元在 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 配置文件

不要为此服务编写密码系统。配置一个成熟的外部 OAuth 2.1/OIDC 提供商，支持授权码、PKCE S256、MCP resource 参数/受众、所需范围，以及首选 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。验证颁发者发现文档是否宣传所选的授权码、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 提取在站点更改后可能中断。在 worker 镜像中运行 yt-dlp --verbose --skip-download '<canonical-url>' 复现，编辑请求数据，然后升级/锁定/重建。

• 自动字幕、Whisper 和 OCR 可能出错，尤其是在专有名称、数字、重叠语音、风格化文本和低分辨率帧上。该技能要求对重要声明进行转录/视觉窗口交叉检查。

• 场景检测加上固定采样提供全视频覆盖，而非逐帧完整观察。get_video_window 有上限并返回缓存的缩略图，绝不会返回任意原始媒体。

• 第一个 ASR 作业会下载配置的模型，可能需要更长时间。检查 worker 日志、可用磁盘和模型卷权限。

• 如果 Inspector 返回 421，请检查主机允许列表并准确连接到 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 日期、结果和确切的错误类别。被阻止或速率受限的实时测试会如实记录，绝不会报告为通过。