mcptube (0xchamin)

🎬 麦克普图贝愿景

YouTube视频知识引擎——文字记录、视觉和持久维基。

  

mcptube vision使用转录本和视觉帧分析将YouTube视频转换为持久的结构化知识库。建立在 Karpathy LLM维基 模式：知识随着你添加的每一个视频而复合。

进化自 麦普托贝 v0.1 --mcptubevision用一个持久的wiki取代了语义块搜索，这个wiki随着每一个视频的摄入而变得更加智能。

______________________________________________________________________

🧠 运作原理

传统的视频工具在每个查询中从头开始重新发现知识。麦克普托贝的愿景是不同的：

           mcptube v0.1                    mcptube-vision
    ┌─────────────────────┐         ┌─────────────────────────┐
    │ Query → vector search│         │ Video ingested → LLM     │
    │ → raw chunks → LLM  │         │ extracts knowledge →     │
    │ → answer (from scratch│        │ wiki pages created →     │
    │   every time)        │         │ cross-references built   │
    └─────────────────────┘         │                         │
                                    │ Query → FTS5 + agent    │
                                    │ → reasons over compiled  │
                                    │   knowledge → answer     │
                                    └─────────────────────────┘

______________________________________________________________________

🏗️ 技术架构

mcptube的愿景是围绕一个核心观点构建的： 视频知识应该复合，而不是被重新发现每一个架构决策都源于这一原则。

系统概述

flowchart TD
    YT[YouTube URL] --> EXT[YouTubeExtractor\ntranscript + metadata]
    EXT --> FRAMES[SceneFrameExtractor\nffmpeg scene-change detection]
    FRAMES --> VISION[VisionDescriber\nLLM vision model]
    VISION --> WIKI_EXT[WikiExtractor\nLLM knowledge extraction]
    EXT --> WIKI_EXT
    WIKI_EXT --> WIKI_ENG[WikiEngine\nmerge + update]
    WIKI_ENG --> FILE[FileWikiRepository\nJSON pages on disk]
    WIKI_ENG --> FTS[SQLite FTS5\nsearch index]
    FILE --> AGENT[Ask Agent\nFTS5 → LLM reasoning]
    FTS --> AGENT
    FILE --> CLI[CLI / MCP Server]
    FTS --> CLI

    subgraph Ingestion Pipeline
        EXT
        FRAMES
        VISION
        WIKI_EXT
    end

    subgraph Knowledge Store
        WIKI_ENG
        FILE
        FTS
    end

    subgraph Retrieval
        AGENT
    end

系统概述显示了由单向数据流连接的三个不同的子系统。这 数据摄取管道 （左）通过四个阶段将原始YouTube URL转换为结构化知识：转录提取、场景变化帧检测、视觉模型描述和LLM驱动的知识提取。每个阶段都丰富了信号——原始视频变成了文本，文本变成了键入的知识对象。

这 知识存储 （中心）是持久层。WikiEngine应用合并语义——决定是创建新页面还是附加到现有页面——然后将JSON文件写入磁盘，并并行更新FTS5搜索索引。这两个存储提供不同的访问模式：文件用于整页读取和导出，FTS5用于亚毫秒关键字检索。

这 检索 图层（右）组合了这两个商店。Ask Agent首先通过FTS5缩小范围，然后从磁盘加载完整页面，最后根据wiki TOC的结构意识对候选人进行推理。CLI和MCP服务器作为精简的表示层放在一起——它们从不包含业务逻辑。

______________________________________________________________________

摄入流量

sequenceDiagram
    participant User
    participant CLI
    participant YouTubeExtractor
    participant SceneFrameExtractor
    participant VisionDescriber
    participant WikiExtractor
    participant WikiEngine
    participant FileRepo
    participant FTS5

    User->>CLI: mcptube add 
    CLI->>YouTubeExtractor: fetch transcript + metadata
    YouTubeExtractor-->>CLI: segments, duration, channel

    CLI->>SceneFrameExtractor: extract scene frames (ffmpeg)
    SceneFrameExtractor-->>CLI: frame images (scene_000x.jpg)

    CLI->>VisionDescriber: describe frames (LLM vision)
    VisionDescriber-->>CLI: frame descriptions (prose)

    CLI->>WikiExtractor: extract knowledge\n(transcript + frame descriptions)
    WikiExtractor-->>CLI: entities, topics, concepts, video page

    CLI->>WikiEngine: merge into wiki
    WikiEngine->>FileRepo: write/update JSON pages\n(append entities, rewrite synthesis)
    WikiEngine->>FTS5: update search index
    FileRepo-->>WikiEngine: ✅
    FTS5-->>WikiEngine: ✅
    WikiEngine-->>CLI: wiki processed
    CLI-->>User: ✅ Added + Wiki: full_analysis

摄入流量为 一次写入管道 --LLM在摄取时很重，但从未在同一视频中重复。这是关键的成本权衡：预先投资代币来构建编译的知识，因此检索成本很低。

该序列显示了两个关键的分支点。首先，在转录提取之后，流水线分叉到视觉处理（场景帧→ LLM视觉描述），并将这两个流馈送到WikiExtractor中。这种双信号方法意味着LLM可以看到两者 *说* 那是什么 *展示* --对于编码教程或基于幻灯片的讲座等内容至关重要，因为仅凭成绩单就错过了视觉信息。

其次，WikiEngine合并步骤是知识复合发生的地方。它不是盲目地编写新页面，而是检查现有的实体、主题和概念——将新的视频贡献添加到现有页面并重写合成摘要。这就是为什么摄入视频#10也会使维基对视频#1-9更聪明：共享的概念会随着每个新来源而变得更加丰富。

最终的FTS5索引更新在文件写入后同步运行，确保搜索一致性。没有最终的一致性窗口——只有一次 add_video 返回后，所有新知识都可以立即搜索。

______________________________________________________________________

检索流程

sequenceDiagram
    participant User
    participant CLI
    participant FTS5
    participant FileRepo
    participant Agent

    User->>CLI: mcptube ask "What is RLHF?"

    CLI->>FTS5: keyword search (sanitized query)
    FTS5-->>CLI: candidate page slugs (ranked)

    CLI->>FileRepo: load candidate pages (JSON)
    FileRepo-->>CLI: wiki pages (entities, topics, concepts)

    CLI->>FileRepo: load wiki TOC
    FileRepo-->>CLI: table of contents (all page titles + types)

    CLI->>Agent: candidates + TOC + question
    Agent-->>CLI: reasoned answer with source citations

    CLI-->>User: answer + (source-slug) citations

检索流程是故意的 两阶段 平衡成本和智力。第一阶段——FTS5关键字搜索——完全在本地运行，没有LLM令牌，在毫秒内将数千个维基页面缩小到排名靠前的少数几个。查询净化条带特殊字符（例如。 ?, !)这将破坏FTS5语法，确保自然语言问题的稳健性。

第二阶段为代理加载两种类型的上下文： 候选页面 （详细信息——摘要、贡献、实体参考）和 维基目录 （所有知识的紧凑结构图）。TOC至关重要——它让代理意识到它是什么 *不* 知道。没有它，代理人会从弱匹配中产生幻觉。有了它，代理可以推理：“维基上有关于RLHF和缩放定律的页面，但没有关于量子计算的页面——所以我应该说我没有这些信息。”

在CLI模式（BYOK）下，代理是一个LLM调用，它将最终答案与源引用进行合成。在MCP服务器模式（passthrough）下，此阶段将原始候选对象和TOC返回给客户端，让客户端自己的模型（Copilot、Claude、Gemini）进行推理。这种双模设计意味着服务器在通过MCP使用时从不需要API密钥。

______________________________________________________________________

子系统分解

1.摄入管道

YouTube提取器 通过以下方式提取转录片段 youtube-transcript-api 和视频元数据 yt-dlp转录是由自然的片段边界分块的，而不是固定的标记窗口——保持语义连贯性。

场景帧提取器 使用ffmpeg的感知场景变化滤波器(select='gt(scene,{threshold})')而不是固定间隔采样。这是故意的：固定间隔在静态帧（幻灯片保持30秒）上浪费令牌，而场景变化检测捕获 *过渡* --信息密度最高的时刻。阈值（默认值 0.4)是可配置的。

愿景描述者 将检测到的帧发送到可实现视觉的LLM（GPT-4o、Claude、Gemini-通过API密钥优先级自动检测）。框架描述是简单的散文，而不是结构化的JSON，以最大限度地提高LLM的描述自由度。

为什么这很重要： 编码教程的成绩单遗漏了屏幕上的代码。场景变化视觉捕捉可以恢复该信号，而无需密集固定间隔采样的令牌成本。

______________________________________________________________________

2.维基引擎——新颖的核心⭐

灵感来自 Karpathy LLM Wiki模式，这是架构上最独特的组件。

WikiExtractor 获取组合的成绩单+框架描述，并提示LLM提取四个类型化的知识对象：

维基引擎 处理合并语义——当一个新视频引用一个现有的实体或概念时，它会在不破坏先前贡献的情况下整合新的证据。这是一个 类似CRDT的附加模型 对于知识，不是向量存储替换索引。

为什么这很重要： 矢量存储是检索索引，它们不是合成的。两个关于“注意力机制”的视频产生了两个孤立的块。WikiEngine将它们合并为一个 concept-attention-mechanisms 页面上有一个随着证据积累而演变的综合。知识化合物。

所有非不可变页面的版本历史都会得到维护——每次合成重写都会被快照，从而实现完全的可审计性。

______________________________________________________________________

3.存储层

FileWikiRepository 将wiki页面以JSON格式存储在磁盘上，每页一个文件。故意选择文档数据库：

• 人类可读且git可读
• 轻松导出到markdown/HTML
• 无需迁移的模式演化

SQLite FTS5 维护页面标题、标签和内容的并行搜索索引。之所以选择矢量存储，是因为：

• 查询时零嵌入成本
• 确定性、可审计的结果
• 数千页的亚毫秒延迟

为什么不选择ChromaDB/Pinecone？ 在wiki规模上，BM25风格的关键字搜索超过 *编译知识页* 在以下方面优于语义相似性 *生块* --wiki页面在构造上已经语义丰富。

______________________________________________________________________

4.混合检索代理⭐

这 ask 命令使用了一种深思熟虑的两阶段模式：

1. FTS5关键字搜索 --将整个wiki缩小到一个小的候选集（毫秒，零LLM成本）
2. LLM代理 --接收候选人+维基目录、相关性原因，将有根据的答案与源引用进行综合

为什么这对RAG很重要： 标准RAG检索块并生成。此处的代理检索 *编译知识页* 和 *原因*wiki TOC让代理对存在的知识有结构性的认识，使其能够正确地说“我没有关于X的信息”，而不是从弱块匹配中产生幻觉。

______________________________________________________________________

5.MCP服务器

将所有子系统作为可供任何MCP兼容客户端使用的工具。报告和综合工具使用 直通模式 --返回结构化数据供客户端自己的LLM分析，而不是在服务器端进行第二次LLM调用。这避免了双重计费，并允许客户端模型应用自己的推理风格。

______________________________________________________________________

关键设计决策

______________________________________________________________________

✨ 特性

BYOK =带上自己的钥匙（Anthropic、OpenAI或谷歌） 穿透 =MCP客户自己的LLM进行分析

______________________________________________________________________

📦 安装

先决条件

• Python 3.12或3.13
• FFmpeg --帧提取所需(安装指南)

推荐：pipx

pipx install mcptube --python python3.12

替代品：pip

python3.12 -m venv venv
source venv/bin/activate
pip install mcptube

验证安装

mcptube --help

______________________________________________________________________

🚀 快速开始

# 1. Add a video (builds wiki automatically)
mcptube add "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# 2. Add with text-only processing (cheaper, faster)
mcptube add "https://www.youtube.com/watch?v=abc123" --text-only

# 3. Browse the wiki
mcptube wiki list
mcptube wiki show "video-dQw4w9WgXcQ"

# 4. Search the knowledge base
mcptube search "main topic"

# 5. Ask a question (agentic retrieval over wiki)
mcptube ask "What are the key ideas discussed?"

# 6. View the table of contents
mcptube wiki toc

💡 始终将多个单词的参数括在双引号中。

______________________________________________________________________

📖 CLI 参考

图书馆管理

`` 可以是视频索引号、视频ID或部分标题。

______________________________________________________________________

Wiki知识库

______________________________________________________________________

搜索和询问

______________________________________________________________________

框架

______________________________________________________________________

分析和报告（BYOK）

______________________________________________________________________

服务器

______________________________________________________________________

🧩 Wiki页面类型

当你摄取视频时，mcptube vision会构建四种类型的维基页面：

原理： 原始源内容（每个视频中所说/显示的内容）永远不会被修改。只有合成摘要会随着新视频的添加而演变。所有更改都会保留版本历史记录。

______________________________________________________________________

🔍 搜索工作原理（混合检索）

mcptube vision采用两步混合方法：

1. SQLite FTS5 --关键字搜索将数千个维基页面缩小到少数候选页面（毫秒，零LLM成本）
2. LLM代理 --阅读候选人+wiki目录，解释相关性，综合答案

这为您提供了LLM代理智能的关键字搜索速度。

______________________________________________________________________

👁️ 愿景管道

当你在没有视频的情况下摄取视频时 --text-only麦克普托贝愿景：

1. 使用以下命令提取关键帧 ffmpeg场景变化检测 (select='gt(scene,0.4)')
2. 将帧发送到 视觉能力LLM （GPT-4o，克劳德，双子座）用于描述
3. 在知识提取过程中结合框架描述和转录

这捕获了仅转录本所遗漏的视觉内容（幻灯片、代码、图表、演示）。

______________________________________________________________________

🔌 MCP客户端设置

mcptube通过两种传输方式公开25+MCP工具：

ℹ️ MCP服务器当前可用于 仅限本地使用你必须跑 mcptube serve 或者让客户端生成它。

______________________________________________________________________

VS代码+GitHub副本✅ 已测试

打开 Cmd+Shift+P → MCP：打开用户配置 并添加：

{
  "servers": {
    "mcptube": {
      "url": "http://127.0.0.1:9093/mcp"
    }
  }
}

然后在终端中启动服务器：

mcptube serve

______________________________________________________________________

克劳德代码✅ 已测试

claude mcp add mcptube --transport http http://127.0.0.1:9093/mcp

然后在单独的终端中启动服务器：

mcptube serve

______________________________________________________________________

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

如果通过安装 pipx （推荐）：

{
  "mcpServers": {
    "mcptube": {
      "command": "mcptube",
      "args": ["serve", "--stdio"]
    }
  }
}

如果安装在虚拟环境中：

{
  "mcpServers": {
    "mcptube": {
      "command": "/full/path/to/.venv/bin/mcptube",
      "args": ["serve", "--stdio"]
    }
  }
}

不需要单独的服务器——Claude Desktop会自动生成该进程。

______________________________________________________________________

光标

创建或编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （项目范围）：

{
  "mcpServers": {
    "mcptube": {
      "url": "http://127.0.0.1:9093/mcp"
    }
  }
}

然后启动服务器：

mcptube serve

______________________________________________________________________

帆板运动

编辑 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mcptube": {
      "serverUrl": "http://127.0.0.1:9093/mcp"
    }
  }
}

然后启动服务器：

mcptube serve

______________________________________________________________________

OpenAI Codex

编辑 ~/.codex/config.toml:

[mcp_servers.mcptube]
url = "http://127.0.0.1:9093/mcp"

然后启动服务器：

mcptube serve

______________________________________________________________________

Gemini CLI

编辑 ~/.gemini/settings.json:

{
  "mcpServers": {
    "mcptube": {
      "httpUrl": "http://127.0.0.1:9093/mcp"
    }
  }
}

然后启动服务器：

mcptube serve

______________________________________________________________________

验证连接

连接后，询问您的MCP客户端：

使用麦普托贝。列出我库中的所有视频

它应该调用 list_videos 工具并返回结果。

MCP工具

______________________________________________________________________

⚙️ 配置

所有设置都可以通过前缀为的环境变量覆盖 MCPTUBE_:

BYOK API密钥

设置一个或多个以启用LLM功能：

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="AI..."

自动检测优先级：人工→ 开放人工智能→ 谷歌

______________________________________________________________________

📁 数据布局

~/.mcptube/
├── mcptube.db          # Video metadata (SQLite)
├── wiki.db             # FTS5 search index (SQLite)
├── wiki/
│   ├── video/          # Video pages (JSON)
│   ├── entity/         # Entity pages (JSON)
│   ├── topic/          # Topic pages (JSON)
│   ├── concept/        # Concept pages (JSON)
│   └── _history/       # Version history
└── frames/
    ├── _.jpg   # Single extracted frames
    └── _scenes/    # Scene-change frames + metadata

______________________________________________________________________

🧪 发展

git clone https://github.com/0xchamin/mcptube.git
cd mcptube
git checkout vision
python3.12 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pytest

______________________________________________________________________

🗺️ 路线图

• \[x\] Wiki知识引擎（实体、主题、概念）
• \[x\] 场景变化帧提取+视觉分析
• \[x\] 混合检索（FTS5+代理）
• \[x\] CLI+MCP服务器
• \[\]播放列表/系列支持
• \[\]具有早期访问注册功能的Web应用程序
• \[\]基于令牌的支付集成

______________________________________________________________________

📄 许可证

麻省理工学院——见 许可证 了解详情。