# 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`.

## Окружение

```bash
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`.

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

## Поиск

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

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

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

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

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

## Разработка

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

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

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

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