抽出を超えた永続的インデックス：YouTube MCPサーバーのアーキテクチャ

開発者が、既存の40以上のサーバーで観察される一般的な「抽出して忘れる」パターンとは対照的に、永続的なローカルインデックスを実装したYouTube MCPサーバーの構築に関する詳細なアーキテクチャノートを共有しました。

アーキテクチャの決定事項

• すべてのツールにおける3段階フォールバック: YouTube Data API → yt-dlp → ページ抽出を使用。すべての応答には、暗黙の劣化を防ぐための出典フィールド（{sourceTier, fallbackDepth, partial, fetchedAt, sourceNotes}）が含まれます。第1段階でのクォータ枯渇は、失敗ではなく明確な出典情報を持つ劣化応答となります。
• 永続性モデル: 単一ファイル内のローカルベクトルストレージにSQLite + sqlite-vecを使用し、Dockerや外部データベースは不要。埋め込みはセッション間で永続化され、知識が蓄積されるため、インデックス化されたプレイリストに対する10回目のクエリは1回目よりも豊富で高速です。
• 埋め込みプロバイダーの抽象化: Geminiキーが存在する場合はGemini text-embedding-004（768次元）を使用し、フォールバックとしてローカル推論による完全オフラインのall-MiniLM-L6-v2（384次元）を使用。両者は同じ抽象化で処理され、品質低下を伴うAPIキー不要のセマンティック検索や、キー追加時の透過的アップグレードを可能にします。
• 独立したインデックスとしての視覚検索: 3つの独立層：画像間類似性のためのフレームごとの特徴ベクトル生成にApple Vision VNGenerateImageFeatureVectorRequest、キーフレームごとの自然言語シーン記述にGemini Vision、テキスト→視覚検索のためのOCRテキスト＋記述に対する768次元埋め込みにGemini text-embedding-004。実際のディスク上のフレームパス＋タイムスタンプ＋マッチング理由を返し、文字起こしパイプラインから完全に独立しています。
• 厳格な出力スキーマによるトークン効率化: サムネイル、eTag、ローカライゼーションの冗長性を削除し、生のカウントではなく正規化されたエンゲージメント比率を使用することで、生のYouTube API出力より75–87%小さい応答を実現。

直面したトレードオフ

• 永続化によるディスク使用量の増加: ツールカテゴリごとのTTLキャッシュ、mediaStoreHealth診断、コレクションごとのクリーンアップツールで解決。
• 視覚インデックス作成の高コスト: キーフレーム抽出＋視覚処理＋OCR＋埋め込みによる。インポート時の自動化ではなく、動画ごとのオプトイン方式に。
• 3段階フォールバックによる早期段階失敗時の遅延追加: 信頼性のために許容。APIクォータ枯渇は本番環境での現実的問題であり、yt-dlp/ページ抽出が機能を維持します。
• mcpNameとnpm名の衝突リスク: MCPレジストリはio.github.<user>/<name>形式、npmはフラット構造。明示的かつ異なる命名で解決。
• Apple Visionによる画像間類似性層のmacOS限定: 許容されるトレードオフ。Geminiベースの層はクロスプラットフォームで動作します。

コードはオープンソースであり、開発者は特に永続性対抽出のトレードオフや視覚パイプラインに関する設計判断について、さらなる議論に開放しています。