Постоянные индексы вместо извлечения: архитектура сервера MCP для YouTube

Разработчик поделился подробными архитектурными заметками по созданию YouTube MCP-сервера, реализующего постоянные локальные индексы, в отличие от распространённого паттерна «извлечь и забыть», наблюдаемого в более чем 40 существующих серверах.

Архитектурные решения

• Трёхуровневое резервирование для каждого инструмента: Используется YouTube Data API → yt-dlp → извлечение со страницы. Каждый ответ включает поле происхождения ({sourceTier, fallbackDepth, partial, fetchedAt, sourceNotes}) для предотвращения скрытой деградации. Исчерпание квоты на первом уровне приводит к деградированному ответу с чётким указанием происхождения вместо сбоя.
• Модель персистентности: SQLite + sqlite-vec для локального векторного хранения в одном файле, без Docker или внешней базы данных. Эмбеддинги сохраняются между сессиями, позволяя накапливать знания — десятый запрос к проиндексированному плейлисту будет богаче и быстрее первого.
• Абстракция провайдера эмбеддингов: Используется Gemini text-embedding-004 (768d) при наличии ключа Gemini, с резервным вариантом all-MiniLM-L6-v2 (384d) полностью офлайн через локальный вывод. Оба обрабатываются одной абстракцией, позволяя осуществлять семантический поиск без API-ключей с пониженным качеством или прозрачно улучшать его при добавлении ключа.
• Визуальный поиск как отдельный индекс: Три независимых слоя: Apple Vision VNGenerateImageFeatureVectorRequest для векторных отпечатков признаков каждого кадра для поиска по сходству изображений, Gemini Vision для описания сцен на естественном языке для ключевых кадров, и Gemini text-embedding-004 для 768d эмбеддингов над OCR-текстом + описаниями для текстового→визуального поиска. Возвращает реальные пути к кадрам на диске + временные метки + обоснование совпадения, полностью отдельно от пайплайна транскрипции.
• Эффективность токенов через строгие схемы вывода: Достигает на 75–87% меньших ответов по сравнению с сырым выводом YouTube API за счёт удаления миниатюр, eTags и раздувания локализации, а также использования нормализованных коэффициентов вовлечённости вместо сырых подсчётов.

Обнаруженные компромиссы

• Использование диска растёт с персистентностью: Решено с помощью TTL-кэшей по категориям инструментов, диагностики mediaStoreHealth и инструментов очистки для каждой коллекции.
• Визуальная индексация ресурсоёмка: Из-за извлечения ключевых кадров + компьютерного зрения + OCR + эмбеддингов. Сделана опциональной для каждого видео, а не автоматической при импорте.
• Трёхуровневое резервирование добавляет задержку при сбое ранних уровней: Считается оправданным для надёжности, так как исчерпание квоты API — реальная проблема в продакшене, а yt-dlp/извлечение со страницы поддерживают работу.
• Риск коллизии mcpName и npm имени: Реестр MCP использует io.github.<user>/<name>, а npm — плоский. Решено путём их явного разграничения.
• Apple Vision привязывает слой поиска по сходству изображений к macOS: Принятый компромисс, так как слои на основе Gemini работают кроссплатформенно.

Код открыт, и разработчик открыт к дальнейшему обсуждению архитектурных решений, особенно по компромиссу персистентность vs извлечение или визуальному пайплайну.