🎬 mcptube-vision

YouTube 비디오 지식 엔진 — 스크립트(transcripts), 비전(vision), 그리고 지속적인 위키(wiki).

mcptube-vision은 스크립트(transcripts)와 시각적 프레임 분석(visual frame analysis)을 모두 사용하여 YouTube 비디오를 지속적이고 구조화된 지식 베이스(knowledge base)로 변환합니다. Karpathy LLM Wiki 패턴을 기반으로 구축되었습니다: 비디오를 추가할 때마다 지식이 복리로 쌓입니다.

mcptube v0.1에서 진화함 — mcptube-vision은 의미론적 청크 검색(semantic chunk search)을 비디오가 수집될 때마다 더 똑똑해지는 지속적인 위키(persistent wiki)로 대체합니다.

---

🧠 작동 원리

전통적인 비디오 도구들은 매 쿼리(query)마다 지식을 처음부터 다시 찾아냅니다. mcptube-vision은 다릅니다:

           mcptube v0.1                    mcptube-vision
    ┌─────────────────────┐         ┌─────────────────────────┐
    │ Query → vector search│         │ Video ingested → LLM     │
...

	v0.1 (비디오 검색 엔진)	vision (비디오 지식 엔진)
수집 시 (On ingest)	스크립트(transcript)를 청크(chunk)로 나누고 벡터 DB에 임베딩(embed)	LLM이 시청 및 읽기, 위키 페이지 작성
...

---

🏗️ 기술 아키텍처 (Technical Architecture)

mcptube-vision은 핵심적인 통찰을 중심으로 구축되었습니다: 비디오 지식은 다시 발견되는 것이 아니라 복리로 쌓여야 한다. 모든 아키텍처 결정은 이 원칙에서 비롯됩니다.

시스템 개요 (System Overview)

flowchart TD
    YT[YouTube URL] --> EXT[YouTubeExtractor
transcript + metadata]
    EXT --> FRAMES[SceneFrameExtractor
ffmpeg scene-change detection]
...

시스템 개요 (System Overview)는 단방향 데이터 흐름(unidirectional data flow)으로 연결된 세 개의 별도 서브시스템을 보여줍니다. 수집 파이프라인 (Ingestion Pipeline) (왼쪽)은 네 가지 단계, 즉 전사(transcript) 추출, 장면 전환(scene-change) 프레임 감지, 비전 모델(vision-model) 설명, 그리고 LLM 기반 지식 추출을 통해 원시 YouTube URL을 구조화된 지식으로 변환합니다. 각 단계는 신호를 풍부하게 만듭니다. 즉, 원시 비디오가 텍스트가 되고, 텍스트가 유형화된 지식 객체(typed knowledge objects)가 됩니다.

지식 저장소 (Knowledge Store) (중앙)는 영구 계층(persistent layer)입니다. WikiEngine은 병합 의미론(merge semantics)을 적용하여 새로운 페이지를 생성할지 아니면 기존 페이지에 추가할지를 결정한 다음, JSON 파일을 디스크에 쓰고 FTS5 검색 인덱스(search index)를 병렬로 업데이트합니다. 이 두 저장소는 서로 다른 액세스 패턴(access patterns)을 위해 사용됩니다. 파일은 전체 페이지 읽기 및 내보내기용으로, FTS5는 밀리초 미만의 키워드 검색(keyword retrieval)용으로 사용됩니다.

검색 (Retrieval) 계층 (오른쪽)은 두 저장소를 결합합니다. Ask Agent는 먼저 FTS5를 통해 범위를 좁힌 다음, 디스크에서 전체 페이지를 로드하고, 마지막으로 위키 목차(TOC)의 구조적 인지(structural awareness)를 바탕으로 후보군에 대해 추론합니다. CLI와 MCP Server는 얇은 프레젠테이션 계층(presentation layers)으로서 함께 존재하며, 비즈니스 로직(business logic)을 포함하지 않습니다.

---

수집 흐름 (Ingestion Flow)

sequenceDiagram
    participant User
    participant CLI
...

수집 흐름은 **단회성 파이프라인 (write-once pipeline)**입니다. 수집 시점에는 LLM을 집중적으로 사용하지만, 동일한 비디오에 대해 반복 수행되지 않습니다. 이것이 핵심적인 비용 트레이드오프(cost tradeoff)입니다. 즉, 컴파일된 지식을 구축하기 위해 초기에 토큰을 투자함으로써 검색 비용을 저렴하게 유지하는 것입니다.

이 시퀀스는 두 가지 중요한 분기점을 보여줍니다. 첫째, 전사(transcript) 추출 후, 파이프라인은 시각 처리(장면 프레임 → LLM 시각 묘사)로 갈라지며 두 스트림 모두를 WikiExtractor에 공급합니다. 이러한 이중 신호(dual-signal) 접근 방식은 LLM이 말해진 내용과 보여진 내용을 모두 볼 수 있음을 의미합니다. 이는 전사 내용만으로는 시각적 정보를 놓칠 수 있는 코딩 튜토리얼이나 슬라이드 기반 강의와 같은 콘텐츠에 매우 중요합니다.

둘째, WikiEngine 병합 단계는 지식의 복리 효과(knowledge compounding)가 발생하는 지점입니다. 새로운 페이지를 맹목적으로 작성하는 대신, 기존의 엔티티(entities), 주제 및 개념을 확인하여 기존 페이지에 새로운 비디오 기여분을 추가하고 종합 요약(synthesis summaries)을 다시 작성합니다. 이것이 비디오 #10을 수집하면 비디오 #1~9에 대해서도 위키가 더 똑똑해지는 이유입니다. 공유된 개념들은 새로운 소스가 추가될 때마다 더 풍부한 종합(synthesis)을 얻게 됩니다.

마지막 FTS5 인덱스 업데이트는 파일 쓰기 후 동기적으로 실행되어 검색 일관성(search consistency)을 보장합니다. 결과적 일관성(eventual-consistency) 구간은 존재하지 않습니다. add_video가 반환되면 모든 새로운 지식은 즉시 검색 가능해집니다.

---

검색 흐름 (Retrieval Flow)

sequenceDiagram
    participant User
    participant CLI
...

검색 흐름은 비용과 지능의 균형을 맞추기 위해 의도적으로 **2단계(two-stage)**로 구성되었습니다. 첫 번째 단계인 FTS5 키워드 검색은 LLM 토큰을 전혀 사용하지 않고 완전히 로컬에서 실행되며, 수천 개의 위키 페이지를 밀리초 단위로 순위가 매겨진 소수의 페이지로 좁힙니다. 쿼리 정제(Query sanitization) 과정은 FTS5 구문을 깨뜨릴 수 있는 특수 문자(예: ?, !)를 제거하여 자연어 질문에 대한 견고성(robustness)을 보장합니다.

두 번째 단계에서는 에이전트(agent)를 위해 두 가지 유형의 컨텍스트(context)를 로드합니다: 후보 페이지 (candidate pages) (상세 정보 — 요약, 기여, 엔티티 참조)와 위키 목차 (wiki TOC) (모든 지식의 압축된 구조적 지도)입니다. 목차(TOC)는 매우 중요합니다. 이는 에이전트에게 자신이 모르는 것이 무엇인지에 대한 인식을 제공합니다. 목차가 없다면 에이전트는 약한 매칭(weak matches)으로부터 답변을 환각(hallucinate)할 것입니다. 목차가 있으면 에이전트는 다음과 같이 추론할 수 있습니다: "위키에 RLHF와 스케일링 법칙(scaling laws)에 대한 페이지는 있지만, 양자 컴퓨팅에 대한 내용은 없다 — 그러므로 해당 정보가 없다고 말해야겠다."

CLI 모드(BYOK)에서 에이전트는 출처 인용과 함께 최종 답변을 합성하는 LLM 호출(call)입니다. MCP 서버 모드(passthrough)에서 이 단계는 원본 후보 페이지와 목차를 클라이언트에 반환하며, 이를 통해 클라이언트 자체의 모델(Copilot, Claude, Gemini)이 추론을 수행하도록 합니다. 이러한 이중 모드 설계 덕분에 MCP를 통해 사용할 때 서버는 API 키를 전혀 요구하지 않습니다.

---

서브시스템 분석 (Subsystem Breakdown)

1. 인제스션 파이프라인 (Ingestion Pipeline)

YouTubeExtractor는 youtube-transcript-api를 통해 스크립트 세그먼트(transcript segments)를 가져오고, yt-dlp를 통해 비디오 메타데이터를 가져옵니다. 스크립트는 고정된 토큰 창(token windows)이 아닌 자연스러운 세그먼트 경계에 따라 청크(chunk)로 나뉘어 의미론적 일관성(semantic coherence)을 보존합니다.

SceneFrameExtractor는 고정된 간격의 샘플링 대신 ffmpeg의 지각적 장면 전환 필터(select='gt(scene,{threshold})')를 사용합니다. 이는 의도적인 설계입니다. 고정된 간격은 정적인 프레임(30초 동안 유지되는 슬라이드)에 토큰을 낭비하는 반면, 장면 전환 감지는 정보 밀도가 가장 높은 순간인 *전환(transitions)*을 포착합니다. 임계값(threshold, 기본값 0.4)은 설정 가능합니다.

VisionDescriber는 감지된 프레임을 시각 능력을 갖춘 LLM(GPT-4o, Claude, Gemini — API 키 우선순위에 따라 자동 감지)으로 전송합니다. LLM의 묘사적 자유도를 극대화하기 위해 프레임 설명은 구조화된 JSON이 아닌 일반 산문(plain prose) 형태로 제공됩니다.

이것이 중요한 이유: 코딩 튜토리얼의 스크립트만으로는 화면에 나오는 코드를 놓칠 수 있습니다. 장면 전환 비전 캡처는 밀집된 고정 간격 샘플링의 토큰 비용 없이도 해당 신호를 복구합니다.

---

2. WikiEngine — 혁신적인 핵심 (The Novel Core) ⭐

2. WikiEngine — 혁신적인 핵심 (The Novel Core) ⭐

Karpathy LLM Wiki 패턴에서 영감을 받은 이 컴포넌트는 가장 구조적으로 독특합니다.

WikiExtractor는 결합된 트랜스크립트와 프레임 설명을 받아 LLM에 네 가지 유형의 지식 객체 추출을 요청합니다:

Type	Semantics	Update Policy
video	비디오별 불변 요약 + 타임스탬프	Write-once
...
WikiEngine은 병합 의미론(merge semantics)을 처리합니다. 즉, 새로운 비디오가 기존 엔티티나 개념을 참조할 때, 이전 기여를 파괴하지 않고 새로운 증거를 통합합니다. 이는 지식에 대한 CRDT 유사 추가 모델이며, 벡터 스토어 대체 인덱스가 아닙니다.

이것이 중요한 이유: 벡터 스토어는 검색 인덱스입니다 — 합성(synthesize)하지 않습니다. '주의 메커니즘(attention mechanisms)'에 관한 두 개의 비디오는 두 개의 고립된 청크를 생성합니다. WikiEngine은 이들을 단일 concept-attention-mechanisms 페이지로 병합하며, 증거가 축적됨에 따라 진화하는 합성 내용을 만듭니다. 지식은 복리처럼 쌓입니다.

모든 비불변(non-immutable) 페이지의 버전 기록이 유지됩니다 — 모든 합성 재작성은 스냅샷 처리되어 완전한 감사 가능성(full auditability)을 보장합니다.

---

3. Storage Layer

FileWikiRepository는 위키 페이지를 디스크에 JSON으로 저장하며, 페이지당 하나의 파일을 사용합니다. 문서 DB 대신 의도적으로 선택된 이유:

• 사람이 읽기 쉽고 git-diff가 가능함 (Human-readable and git-diffable)
• 마크다운/HTML로 쉽게 내보내기 가능 (Trivially exportable to markdown/HTML)
• 마이그레이션 없이 스키마 진화 가능

SQLite FTS5는 페이지 제목, 태그 및 콘텐츠에 대한 병렬 검색 인덱스를 유지합니다. 벡터 스토어 대신 선택된 이유:

• 쿼리 시 임베딩 비용 없음 (Zero embedding cost at query time)
• 결정론적이고 감사 가능한 결과 (Deterministic, auditable results)
• 수천 개의 페이지에서도 밀리초 미만의 지연 시간 (Sub-millisecond latency at thousands of pages)

ChromaDB/Pinecone을 사용하지 않는 이유? 위키 규모에서는 컴파일된 지식 페이지에 대한 BM25 스타일의 키워드 검색이 *원시 청크(raw chunks)*에 대한 의미적 유사성 검색보다 우수합니다 — 위키 페이지는 구축 과정에서 이미 의미적으로 풍부하기 때문입니다.

---

4. Hybrid Retrieval Agent ⭐

ask 명령어는 의도적인 2단계 패턴을 사용합니다:

1. FTS5 키워드 검색 (FTS5 keyword search) — 전체 위키를 작은 후보군 세트로 좁힙니다 (밀리초 단위, LLM 비용 발생 없음)
2. LLM 에이전트 (LLM agent) — 후보군과 위키 목차 (TOC)를 전달받아, 관련성을 추론하고 출처 인용과 함께 근거 있는 답변을 합성합니다.

RAG보다 중요한 이유: 표준 RAG는 청크 (chunks)를 검색하고 생성합니다. 여기서의 에이전트는 *컴파일된 지식 페이지 (compiled knowledge pages)*를 검색하고 추론합니다. 위키 목차는 에이전트에게 어떤 지식이 존재하는지에 대한 구조적 인식을 제공합니다. 이를 통해 약한 청크 매칭으로 인한 환각 (hallucination)을 일으키는 대신, "X에 대한 정보가 없습니다"라고 정확하게 말할 수 있게 합니다.

---

5. MCP 서버 (MCP Server)

모든 하위 시스템을 MCP 호환 클라이언트가 사용할 수 있는 도구 (tools)로 노출합니다. 보고 및 합성 도구는 **패스스루 패턴 (passthrough pattern)**을 사용합니다. 즉, 서버 측에서 두 번째 LLM 호출을 수행하는 대신, 클라이언트 자체의 LLM이 분석할 수 있도록 구조화된 데이터를 반환합니다. 이는 이중 과금을 방지하고 클라이언트 모델이 자체적인 추론 스타일을 적용할 수 있게 합니다.

---

주요 설계 결정 (Key Design Decisions)

결정 사항	고려된 대안	이유
장면 전환 프레임 추출 (Scene-change frame extraction)	고정 간격 샘플링 (Fixed-interval sampling)	더 높은 신호/토큰 비율 (Higher signal/token ratio)
...

---

✨ 기능 (Features)

기능	CLI	MCP 서버
YouTube 비디오 추가/제거	✅	✅
...
BYOK = Bring Your Own Key (Anthropic, OpenAI 또는 Google)
Passthrough = MCP 클라이언트 자체의 LLM이 분석을 수행함

---

📦 설치 (Installation)

요구 사항 (Prerequisites)

• 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

---

🚀 빠른 시작 (Quick Start)

# 1. 비디오 추가 (자동으로 위키 구축)
mcptube add "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

...

💡 여러 단어로 구성된 인자(argument)는 항상 큰따옴표(" ")로 감싸주세요.

---

📖 CLI Reference (CLI 참조)

Library Management (라이브러리 관리)

Command (명령어)	Description (설명)	Example (예시)
mcptube add "<url>"	비디오 수집 + 위키 구축 (전체 분석)	mcptube add "https://youtu.be/dQw4w9WgXcQ"
...

<query>는 비디오 인덱스 번호, 비디오 ID 또는 부분 제목이 될 수 있습니다.

---

Wiki Knowledge Base (위키 지식 베이스)

Command (명령어)	Description (설명)	Example (예시)
mcptube wiki list	모든 위키 페이지 탐색	mcptube wiki list
...

---

Search & Ask (검색 및 질문)

Command (명령어)	Description (설명)	Example (예시)
mcptube search "<query>"	전체 텍스트 검색, 페이지 목록 반환	mcptube search "transformers"
mcptube ask "<question>"	위키 기반 에이전트 방식의 질의응답 (BYOK)	mcptube ask "What is self-attention?"

---

Frames (프레임)

Command (명령어)	Description (설명)	Example (예시)
mcptube frame <query> <timestamp>	특정 타임스탬프(초 단위)의 프레임 추출	mcptube frame 1 30.5
mcptube frame-query <query> "<description>"	스크립트(transcript) 매칭을 통한 프레임 추출	mcptube frame-query 1 "when they show the diagram"

---

Analysis & Reports (분석 및 보고서) (BYOK)

Command (명령어)	Description (설명)	Example (예시)
mcptube classify <query>	LLM을 이용한 비디오 분류 + 태깅	mcptube classify 1
...

---

Server (서버)

Command (명령어)	Description (설명)
mcptube serve	HTTP를 통해 MCP 서버 시작 (기본값 127.0.0.1:9093)
...

---

🧩 Wiki Page Types (위키 페이지 유형)

비디오를 수집할 때, mcptube-vision은 네 가지 유형의 위키 페이지를 구축합니다:

페이지 유형 (Page Type)	생성 근거 (Created From)	업데이트 정책 (Update Policy)
비디오 (Video)	수집된 각 비디오	1회 작성 (변경 불가능)
...

원칙 (Principle): 원본 소스 콘텐츠(각 비디오에서 말하거나 보여준 내용)는 절대 수정되지 않습니다. 새로운 비디오가 추가됨에 따라 합성된 요약(synthesis summaries)만이 발전합니다. 모든 변경 사항에 대해서는 버전 기록(Version history)이 유지됩니다.