Indexes Persistants sur l'Extraction : Architecture pour un Serveur MCP YouTube

Un développeur a partagé des notes d'architecture détaillées issues de la construction d'un serveur MCP YouTube qui implémente des index locaux persistants, contrastant avec le modèle courant d'"extraction-oubli" observé dans plus de 40 serveurs existants.

Décisions d'Architecture

• Rétrocession à trois niveaux sur chaque outil : Utilise l'API YouTube Data → yt-dlp → extraction de page. Chaque réponse inclut un champ de provenance ({sourceTier, fallbackDepth, partial, fetchedAt, sourceNotes}) pour éviter une dégradation silencieuse. L'épuisement du quota au niveau 1 entraîne une réponse dégradée avec provenance claire au lieu d'un échec.
• Modèle de persistance : SQLite + sqlite-vec pour le stockage vectoriel local dans un seul fichier, sans Docker ni base de données externe. Les embeddings persistent entre les sessions, permettant aux connaissances de s'accumuler—la dixième requête sur une playlist indexée est plus riche et plus rapide que la première.
• Abstraction du fournisseur d'embeddings : Utilise Gemini text-embedding-004 (768d) lorsqu'une clé Gemini est présente, avec repli sur all-MiniLM-L6-v2 (384d) entièrement hors ligne via inférence locale. Les deux sont gérés par la même abstraction, permettant une recherche sémantique sans clés API à qualité réduite ou des mises à niveau transparentes lorsqu'une clé est ajoutée.
• Recherche visuelle comme index séparé : Trois couches indépendantes : Apple Vision VNGenerateImageFeatureVectorRequest pour des empreintes de caractéristiques par image pour la similarité image-à-image, Gemini Vision pour des descriptions de scène en langage naturel par image clé, et Gemini text-embedding-004 pour des embeddings 768d sur le texte OCR + descriptions pour la recherche texte→visuel. Renvoie les chemins réels des images sur disque + horodatages + raisonnement de correspondance, véritablement séparé du pipeline de transcription.
• Efficacité des tokens via des schémas de sortie stricts : Réalise des réponses 75–87 % plus petites que la sortie brute de l'API YouTube en supprimant les miniatures, eTags et le gonflement de localisation, et en utilisant des ratios d'engagement normalisés au lieu de comptes bruts.

Compromis Rencontrés

• L'utilisation du disque augmente avec la persistance : Résolu avec des caches TTL par catégorie d'outil, un diagnostic mediaStoreHealth et des outils de nettoyage par collection.
• L'indexation visuelle est coûteuse : En raison de l'extraction d'images clés + vision + OCR + embeddings. Rendu optionnel par vidéo plutôt qu'automatique lors de l'importation.
• La rétrocession à trois niveaux ajoute de la latence lorsque les niveaux précédents échouent : Considéré comme valable pour la fiabilité, car l'épuisement du quota API est un vrai problème en production, et yt-dlp/l'extraction de page maintiennent le fonctionnement.
• Risque de collision entre mcpName et nom npm : Le registre MCP utilise io.github.<user>/<name> tandis que npm est plat. Résolu en les rendant explicites et différents.
• Apple Vision verrouille la couche de similarité image-à-image sur macOS : Compromis accepté, car les couches basées sur Gemini fonctionnent multiplateforme.

Le code est open source, et le développeur est ouvert à discuter des décisions de conception plus en détail, notamment sur le compromis persistance vs extraction ou le pipeline visuel.