内容
# 视频上下文MCP
[](https://github.com/smallthinkingmachines/video-context-mcp/actions/workflows/ci.yml)
[](https://github.com/smallthinkingmachines/video-context-mcp/actions/workflows/runtime-smoke.yml)
[](https://www.npmjs.com/package/@smallthinkingmachines/video-context-mcp)
[](LICENSE)
一个MCP服务器，允许AI代理**搜索、检查和推理视频**，使用带有时间戳的转录文本、章节、关键帧、OCR和语义搜索。
## 演示
助手通过视频上下文MCP检索带有时间戳的视频证据，然后再组成答案。
代理使用MCP工具来定位和检索相关的带有时间戳的证据：
```mermaid
flowchart LR
Q[代理问题] --> I[摄入视频]
I --> S[获取摄入状态]
S --> T[获取视频时间线]
T --> H[搜索视频]
H --> K{证据类型}
K -->|语音| X[获取转录文本<br/>目标范围]
K -->|屏幕| F[预览帧<br/>最近关键帧]
F --> C[裁剪区域<br/>可选缩放]
X --> A[用视频ID<br/>和时间戳回答]
C --> A
S -. 功能和警告 .-> H
```
来源：[`agent-evidence-loop.mmd`](docs/assets/agent-evidence-loop.mmd).
## 要求
- Node ≥ 22
- 首次使用时需要网络访问
| 平台 | 架构 | 支持 |
| --- | --- | --- |
| macOS | Apple Silicon 和 Intel | 已测试托管运行时 |
| Windows | x64 | 已测试托管运行时 |
| Linux | glibc x64 | 已测试托管运行时 |
| Linux | musl 或 ARM | 使用系统工具链模式；不提供托管二进制文件 |
在支持的托管运行时平台上，服务器仅在需要时下载固定的 yt-dlp 和 FFmpeg 构建，然后在 `VCM_CACHE_DIR` 下缓存它们。OCR 和无字幕语音使用本地 Tesseract.js 和 Transformers.js 作为备用方案，当本机工具不可用时，因此不需要 Python、Nix 环境、系统包管理器或预安装的媒体工具。因此，第一次操作可能会更慢，并且需要足够的磁盘空间来存储请求的运行时和模型。
## 安装和注册
全局安装已发布的软件包：
```bash
npm install -g @smallthinkingmachines/video-context-mcp
```
**Claude Code / Gemini 风格的 JSON 配置：**
```json
{
"mcpServers": {
"video-context": {
"command": "video-context-mcp"
}
}
}
```
**Codex (`~/.codex/config.toml`):**
```toml
[mcp_servers.video-context]
command = "video-context-mcp"
```
全局安装提供了每个客户端配置使用的 `video-context-mcp` 二进制文件。
可选的启动和诊断：
```bash
video-context-mcp setup # 预下载 yt-dlp + FFmpeg
video-context-mcp setup --all # 还预下载 OCR、ASR 和嵌入模型
video-context-mcp setup --update # 显式激活此版本的固定工具
video-context-mcp doctor # 只读健康和修复报告
```
`doctor --json` 还将嵌入模型缓存报告为 `not_cached`、`verified`、`invalid` 或 `custom_unverified`。默认固定的 MiniLM ONNX 工件经过校验和验证；如果校验和失败，将在下一次嵌入加载时替换，同时全文搜索仍然可用。
## 工具
| 工具 | 用途 |
| --- | --- |
| `ingest_video` | 索引 YouTube URL/ID 或本地文件（异步作业，立即返回） |
| `get_ingest_status` | 阶段、进度、可查询、操作错误 |
| `get_video_timeline` | 紧凑的概述：结构化元数据 + Markdown 章节/大纲 |
| `get_transcript` | 带时间戳的转录文本，可切片内联或导出为完整本地文件 |
| `search_videos` | 语音和屏幕文本的混合搜索（全文 + 语义，RRF 融合） |
| `repair_embeddings` | 从存储的文本重建语义向量，无需重新下载视频 |
| `peek_frame` | 最近时间戳的关键帧图像及其 OCR 文本 — *您*查看它 |
| `crop_region` | 缩放帧的 bbox（IDE 面板，图表）用于密集文本 |
| `list_videos` / `delete_video` | 缓存库存和显式在保存笔记后释放 |
| `prune_cache` | 预览或应用基于配额的整个视频 LRU 清理 |
典型代理流程：`ingest_video` → 轮询 `get_ingest_status` → 检查时间线/搜索/转录/帧切片 → 将结果笔记保存在其他地方 → `delete_video` 释放工作资产。如果仅语义索引失败，请调用 `repair_embeddings` 而不是强制重新摄入。
内联转录输出保持紧凑，并包含截断时的结构化恢复时间戳。本地 stdio 客户端可以读取服务器的文件系统，可以请求整个选定范围而无需另一个 MCP 往返：
```text
get_transcript(video_id="…", delivery="file")
```
响应包含一个绝对的 UTF-8 文件路径。该导出从 SQLite 重新生成，计入视频缓存，并在 `delete_video` 或自动缓存淘汰时删除。
参见 [`docs/tool-contract.md`](docs/tool-contract.md) 了解公共响应契约、功能语义、时间戳约定和缓存生命周期。底层图表及其可编辑源在 [`docs/diagrams.md`](docs/diagrams.md) 中收集。
## 配置
所有设置都是可选的；参见 `.env.example`。托管工具是默认的。设置 `VCM_TOOLCHAIN_MODE=system` 以恢复仅限 PATH 的解析。显式 `VCM_YTDLP_BIN`、`VCM_FFMPEG_BIN` 或 `VCM_FFPROBE_BIN` 始终优先。OCR 和 ASR 提供商可以通过 `VCM_OCR_BACKEND` 和 `VCM_ASR_BACKEND` 进行选择。限制 YouTube 视频的 Cookie 仍由用户通过 `YTDLP_COOKIES_FILE` 提供，从不捆绑。
## 故障排除
从 `video-context-mcp doctor --json` 开始；它报告平台支持、托管工具、缓存权限、配置的后端和嵌入模型完整性，而不更改安装。
- **第一次调用很慢：** yt-dlp、FFmpeg、OCR/ASR 和嵌入工件是延迟下载的。运行 `video-context-mcp setup --all` 以预下载和负载测试所有内容。
- **YouTube 请求需要登录或拒绝自动化：** 导出一个新鲜的 Netscape 格式的 Cookie 文件并设置 `YTDLP_COOKIES_FILE`。永不粘贴或提交该文件。
- **`EMBED_FAILED`：** 全文搜索仍然有效。默认 ONNX 文件经过校验和验证并自愈一次；运行 `setup --all`，然后调用 `repair_embeddings(video_id)` 以仅重建语义向量。
- **缓存权限或磁盘错误：** 将 `VCM_CACHE_DIR` 指向一个绝对的、可写的路径，并具有足够的空闲空间，然后重新运行 `doctor`。
- **密集屏幕文本难以阅读：** YouTube 可能将 yt-dlp 限制为 360p 渐进流。该条件出现在 `get_ingest_status` 中；更新 yt-dlp 或稍后重新摄入可能会恢复 720p。
- **Linux musl/ARM：** 设置 `VCM_TOOLCHAIN_MODE=system` 并通过 PATH 或显式 `VCM_*_BIN` 变量提供兼容的 yt-dlp/FFmpeg 二进制文件。
## 缓存生命周期
下载的源视频/音频、字幕、暂存文件、WAV 文件和临时裁剪在每次摄入后自动删除。保留的转录文本、OCR、关键帧和向量形成一个可查询的工作集，直到代理调用 `delete_video` 以保存其笔记。
`VCM_MAX_CACHE_GB` 默认值为 20 GB，仅适用于保留的每个视频数据。如果代理忘记释放视频，则启动和摄入维护会按照最近最少使用（LRU）的顺序淘汰完整的视频，直到使用量低于预算的 90%。正在运行和刚刚完成的摄入受到保护；如果大小超过限制，则会保留新的结果并发出警告。可共享的托管二进制文件和 OCR/ASR/嵌入模型是可重用的，永远不会自动淘汰。使用 `list_videos` 进行核算，或使用 `prune_cache` 进行干预预览。中断的运行时和本机 ASR 下载会在下一个服务器启动或 `setup` 运行后，在至少一小时内未活动后被回收。
## 注意
用于您合法访问的内容的个人研究和记笔记。字幕/元数据获取使用 `yt-dlp`；尊重 YouTube 的服务条款和版权。Cookie 由用户提供，从不捆绑。
托管的可执行文件保留其上游许可证；参见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。npm 软件包保持较小；运行时二进制文件和模型下载到可处理的缓存中，而不是嵌入在 tarball 中。
**信任边界：** 服务器信任其 MCP 客户端。特别是，`ingest_video` 将读取客户端请求的任何本地文件路径（按设计 - 您的代理索引您的文件），并且缓存是磁盘上的普通文件。为您控制的客户端运行它作为本地_stdio 服务器；不要在未经添加您自己的授权层的情况下将其公开给不受信任的客户端或网络。
## 开发
```bash
just setup # npm install
just ci # lint + typecheck + test + build
just e2e # 可选的实时提供商检查来自维护人员的工作站
```
自动化 CI 和发布永远不会联系 YouTube。它们使用合成的 yt-dlp 形元数据和字幕固定装置来锻炼相同的摄入边界；`just e2e` 保留用于有意的提供商健康检查，因为托管运行器流量容易受到机器人挑战，并且不是软件包质量的确定性衡量标准。
Nix 是可选的；存储库的标准工作流程是 Node 22 加 `just`。参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解项目规则，[`SECURITY.md`](SECURITY.md) 了解私人报告，[`CHANGELOG.md`](CHANGELOG.md) 了解发布说明。
MIT © Studio1804, Small Thinking Machines, and Ricardo Ledan
