Índices Persistentes Sobre Extração: Arquitetura para um Servidor MCP do YouTube

Um desenvolvedor compartilhou notas detalhadas de arquitetura da construção de um servidor MCP do YouTube que implementa índices locais persistentes, contrastando com o padrão comum de "extrair-e-esquecer" observado em mais de 40 servidores existentes.

Decisões de Arquitetura

• Fallback de três camadas em todas as ferramentas: Usa YouTube Data API → yt-dlp → extração de página. Cada resposta inclui um campo de proveniência ({sourceTier, fallbackDepth, partial, fetchedAt, sourceNotes}) para evitar degradação silenciosa. Esgotamento de cota na camada 1 resulta em uma resposta degradada com proveniência clara em vez de uma falha.
• Modelo de persistência: SQLite + sqlite-vec para armazenamento vetorial local em um único arquivo, sem Docker ou banco de dados externo. Os embeddings persistem entre sessões, permitindo que o conhecimento se acumule—a décima consulta em uma playlist indexada é mais rica e rápida que a primeira.
• Abstração de provedor de embeddings: Usa Gemini text-embedding-004 (768d) quando uma chave Gemini está presente, com fallback para all-MiniLM-L6-v2 (384d) totalmente offline via inferência local. Ambos são tratados pela mesma abstração, permitindo busca semântica sem chaves de API com qualidade reduzida ou atualizações transparentes quando uma chave é adicionada.
• Busca visual como um índice separado: Três camadas independentes: Apple Vision VNGenerateImageFeatureVectorRequest para impressões de características por quadro para similaridade imagem-a-imagem, Gemini Vision para descrições de cena em linguagem natural por quadro-chave, e Gemini text-embedding-004 para embeddings 768d sobre texto OCR + descrições para busca texto→visual. Retorna caminhos reais de quadros no disco + timestamps + raciocínio de correspondência, genuinamente separado do pipeline de transcrição.
• Eficiência de tokens via esquemas de saída estritos: Alcança respostas 75–87% menores que a saída bruta da API do YouTube removendo miniaturas, eTags e inchaço de localização, e usando proporções de engajamento normalizadas em vez de contagens brutas.

Compromissos Encontrados

• Uso de disco cresce com persistência: Resolvido com caches TTL por categoria de ferramenta, um diagnóstico mediaStoreHealth e ferramentas de limpeza por coleção.
• Indexação visual é cara: Devido à extração de quadros-chave + visão + OCR + embeddings. Tornada opcional por vídeo em vez de automática durante a importação.
• Fallback de três camadas adiciona latência quando as camadas anteriores falham: Considerado válido pela confiabilidade, já que esgotamento de cota da API é um problema real em produção, e yt-dlp/extração de página mantêm o funcionamento.
• Risco de colisão entre mcpName e nome npm: O registro MCP usa io.github.<usuário>/<nome> enquanto npm é plano. Resolvido tornando-os explícitos e diferentes.
• Apple Vision prende a camada de similaridade imagem-a-imagem ao macOS: Compromisso aceito, já que as camadas baseadas em Gemini funcionam multiplataforma.

O código é de código aberto, e o desenvolvedor está aberto a discutir decisões de design, particularmente sobre o compromisso persistência vs extração ou o pipeline visual.