cpp-lectures-mcp

Семантический поиск по лекциям Константина Владимирова по C++ через MCP-сервер.

Лекции содержат ценную авторскую подачу C++, но в видео её нельзя искать по смыслу и нельзя сослаться на конкретную секунду. Проект решает обе задачи: строит базу фрагментов транскрипта с тайм-кодами и отдаёт их через MCP. Вы спрашиваете в своём клиенте (Claude и т.п.), клиент вызывает сервер, получает фрагменты с кликабельными ссылками вида youtu.be/<id>?t=<секунды> и объясняет материал, ссылаясь на момент в видео.

Как это работает

Два контура, намеренно разделённых.

• Подготовка (офлайн, разово): yt-dlp скачивает аудио → Deepgram Nova-3 распознаёт речь с пословными тайм-кодами → разбиение на фрагменты ~75 с по границам предложений с перекрытием → Jina векторизует → Postgres + pgvector.
• Обслуживание (онлайн): MCP-сервер отдаёт по запросу search(query) найденные фрагменты с тайм-кодами. Сервер не зовёт языковую модель — объяснение генерирует клиент пользователя своей подпиской. Следствие: владелец сервера не платит за чужой инференс.

Статус

Работает конвейер подготовки и MCP-сервер с ручкой search. На тестовом наборе из блока «Атомики» (3 лекции, 274 фрагмента) смысловой поиск возвращает верный фрагмент в топ-5 в 9 случаях из 10. Подробнее об архитектуре и этапах — .claude/skills/cpp-lectures-dev/references/plan.md.

Окружение

uv sync --extra prep --extra server   # конвейер + сервер + dev-инструменты
cp .env.example .env                  # заполнить ключи Deepgram/Jina и DATABASE_URL
docker compose up -d                  # Postgres + pgvector

Наполнение базы (контур подготовки)

Платный шаг — Deepgram распознаёт аудио (≈$1 за 3 лекции). Набор лекций задан в prep/lectures.py.

uv run python -m prep.ingest                          # весь манифест
uv run python -m prep.ingest --url <youtube> --title "…"   # одна лекция

Поиск

Из командной строки:

uv run python -m prep.ask "что такое happens-before"

Через MCP из своего клиента (Claude Code) — сервер виден из любого каталога:

claude mcp add -s user cpp-lectures -- \
  uv run --directory <path-to-repo> python -m server.main

Предусловие — поднятая база (docker compose up -d). После подключения клиент вызывает ручку search сам и объясняет найденное со ссылками на тайм-коды.

Разработка

uv run pytest                 # быстрые тесты (без integration)
uv run pytest -m integration  # реальные сервисы, нужны ключи
uv run mypy .                 # типы (strict)
uv run ruff check             # линт

Лицензия и контент

Код — под лицензией MIT (файл LICENSE).

Лекции Константина Владимирова принадлежат их автору. Этот репозиторий содержит только код конвейера и сервера — в нём нет ни аудио, ни транскриптов, ни векторной базы: все производные данные вы генерируете сами, на свой риск и под свою ответственность. Инструмент предназначен для личного и образовательного использования. Любое публичное использование, выходящее за эти рамки, требует согласия автора лекций и явного указания авторства.