추출보다 지속적인 인덱스: YouTube MCP 서버 아키텍처

한 개발자가 YouTube MCP 서버를 구축한 상세한 아키텍처 노트를 공유했습니다. 이 서버는 지속적인 로컬 인덱스를 구현하며, 기존 40개 이상의 서버에서 흔히 볼 수 있는 '추출 후 잊기' 패턴과 대조됩니다.

아키텍처 결정 사항

• 모든 도구에 3단계 폴백 시스템: YouTube Data API → yt-dlp → 페이지 추출 순으로 사용합니다. 모든 응답에는 조용한 성능 저하를 방지하기 위해 출처 필드({sourceTier, fallbackDepth, partial, fetchedAt, sourceNotes})가 포함됩니다. 1단계에서 할당량이 소진되면 실패 대신 명확한 출처 정보가 포함된 성능 저하 응답을 반환합니다.
• 지속성 모델: 단일 파일 내 로컬 벡터 저장을 위해 SQLite + sqlite-vec를 사용하며, Docker나 외부 데이터베이스가 필요 없습니다. 임베딩은 세션 간에 유지되어 지식이 축적됩니다—인덱싱된 플레이리스트에 대한 열 번째 쿼리는 첫 번째보다 더 풍부하고 빠릅니다.
• 임베딩 제공자 추상화: Gemini 키가 있을 때는 Gemini text-embedding-004 (768d)를 사용하고, 그렇지 않으면 로컬 추론을 통해 완전 오프라인으로 all-MiniLM-L6-v2 (384d)로 폴백합니다. 둘 다 동일한 추상화로 처리되어 API 키 없이도 품질이 낮아진 상태에서 의미론적 검색이 가능하거나, 키가 추가되면 투명하게 업그레이드됩니다.
• 별도의 시각 검색 인덱스: 세 가지 독립적인 계층으로 구성됩니다: 이미지 간 유사성을 위한 프레임별 특징 인쇄용 Apple Vision VNGenerateImageFeatureVectorRequest, 키프레임별 자연어 장면 설명용 Gemini Vision, 텍스트→시각 검색을 위한 OCR 텍스트 + 설명에 대한 768d 임베딩용 Gemini text-embedding-004. 실제 디스크 상의 프레임 경로 + 타임스탬프 + 일치 이유를 반환하며, 자막 파이프라인과 완전히 분리되어 있습니다.
• 엄격한 출력 스키마를 통한 토큰 효율성: 썸네일, eTags, 지역화 관련 불필요한 데이터를 제거하고 원시 카운트 대신 정규화된 참여 비율을 사용하여 원시 YouTube API 출력보다 75–87% 더 작은 응답을 달성합니다.

발견된 절충점

• 지속성으로 인한 디스크 사용량 증가: 도구 카테고리별 TTL 캐시, mediaStoreHealth 진단 도구, 컬렉션별 정리 도구로 해결했습니다.
• 시각 인덱싱의 높은 비용: 키프레임 추출 + 비전 + OCR + 임베딩으로 인해 발생합니다. 가져오기 중 자동 적용 대신 비디오별 옵트인 방식으로 설정했습니다.
• 3단계 폴백으로 인한 이전 단계 실패 시 지연 시간 증가: API 할당량 소진은 실제 운영에서 문제가 되므로, yt-dlp/페이지 추출이 작동을 유지해주는 신뢰성 측면에서 가치 있는 절충이라고 판단했습니다.
• mcpName 대 npm 이름 충돌 위험: MCP 레지스트리는 io.github.<user>/<name> 형식을 사용하는 반면 npm은 평면 구조입니다. 이를 명시적이고 다르게 설정하여 해결했습니다.
• Apple Vision이 이미지 간 유사성 계층을 macOS로 제한: Gemini 기반 계층이 크로스 플랫폼에서 작동하므로 수용한 절충점입니다.

코드는 오픈 소스이며, 개발자는 특히 지속성 대 추출 절충점이나 시각 파이프라인에 대한 설계 결정을 더 논의할 의사가 있습니다.