# Video Pipeline MCP Server

MCP-сервер для управления видеопайплайном. Работает с Claude AI Web через cloudflared-туннель.

> **Статус (2026-07):** реализован слой управления данными (файлы, таблицы/Excel, структура каналов,
> поиск) + файрвол + транспорт. Продуктовый видео-пайплайн (озвучка/транскрибация/картинки/монтаж) —
> в разработке. План доведения до корпоративного уровня: [`docs/roadmap/`](docs/roadmap/README.md).
> Легенда ниже: ✅ реализовано · 🟠 заглушка/частично · 🔲 план.

## Структура проекта (фактическая)

```
video_pipeline_mcp/
├── server.py              ✅ точка входа: MCP-эндпоинт + туннель; регистрация инструментов
├── pyproject.toml         ✅ сборка/зависимости (PEP 621) · requirements.lock — точные пины
├── install.sh · run.sh    ✅ установка (.venv + cloudflared) · запуск (--tunnel)
│
├── config/                ✅ декларации (поведение, НЕ код)
│   │                          (конфиг канала с S22 — не файл, а 7 листов channel_data.xlsx:
│   │                           RESOURCE_LIMITS, WORKFLOW_SEQUENCES, PUBLISHING_SCHEDULE,
│   │                           METADATA_DEFAULTS, AUTOMATION_RULES, SCENE_PROFILE, RENDER_CONFIG)
│   ├── server_reactions.yaml  ✅ реестр реакций (коды → класс + recovery)
│   ├── firewall.yaml          ✅ правила файрвола
│   ├── tunnel.yaml            ✅ конфиг туннеля (gitignored — секрет)
│   └── templates/
│       ├── workspace/         ✅ 6 шаблонов: niche/network/channel/video/competitor_channel/competitor_video
│       └── tables/            🔲 схемы книг (*.schema.yaml) — воркстрим A1′
│
├── core/                  — ядро (бизнес-логика)
│   ├── contracts/         ✅ Pydantic: ToolResult, ErrorDetail, Fact, TaskStatus
│   ├── engine/            ✅ generic-движок + template_engine
│   ├── firewall/          ✅ файрвол + rules/ (rate_limit, injection, ip_blocklist, anomaly)
│   ├── state/             ✅ read.json / write.json / session log
│   ├── reactions/         ✅ читалка server_reactions
│   ├── ids/               ✅ генерация ID + link_registry
│   ├── tables/ · excel/   ✅ слой таблиц и Excel-книг
│   ├── search/            ✅ поиск по ФС/таблицам (FsSearcher + QueryPlanner)
│   ├── transport/         ✅ туннель к Claude (transport + tunnel)
│   ├── runner/            ✅ инференс в отдельном процессе: сервис на петле + супервизор
│   ├── paths.py           ✅ containment путей в workspace/
│   └── providers/         🟠 адаптеры провайдеров (заглушки — в разработке)
│       ├── stt/ (stable-ts) · tts/ (LiteLLM) · img/ (LiteLLM) · ffmpeg/ (внешний MCP)
│
├── tools/                 🔲 тонкие обёртки Bounded Context (план: вынос из server.py, A2)
├── pipeline/              🔲 оркестрация процессов (entry_points + steps) — план
├── scripts/               🔲 утилиты (план: introspect_tables.py — A1′)
├── docker/                ✅ образ раннера (среда инференса заперта в контейнере)
├── tests/                 ✅ quick/ (unit) + симуляции (virus/bot_army/cache_*/…)
└── docs/
    ├── dev/               — история файлов, спеки (gitignored)
    └── roadmap/           ✅ план развития до корпоративного уровня + канон спек (spec/)
```

**Инструменты сейчас** (52 в `tools/list`): ✅ `fs_*` (файлы), `table_*`/`json_*` (таблицы),
`excel_*` (книги), `structure_*` (создание каналов/видео по шаблонам), `search_*` (поиск);
🟠 `tts_*`/`stt_*`/`img_*`/video (media — заглушки).

## Установка

```bash
./install.sh            # .venv + БАЗОВЫЕ зависимости (включая torch) + cloudflared
./install.sh --media    # + облачные/HTTP-провайдеры и ONNX (bg_removal/upscale)
./install.sh --local    # + модели поверх torch (stable-ts/piper/diffusers)
./install.sh --gpu-amd  # + torch на карте AMD (rocm-сборка вместо cuda)
```

Экономия: torch идёт в базе — локальный инференс работает сразу после установки, без второго
`pip install`. Optional-группы добавляют только то, что не нужно пустому серверу: стабильные
модели (stable-ts/piper/diffusers), шлюзы облака (litellm/httpx) и ONNX-графы
(onnxruntime/pillow). Сервер на чистой базе работает, а media-инструменты честно отвечают
`PROVIDER_NOT_CONFIGURED` / `LOCAL_INFERENCE_FAILED`.

## Запуск

```bash
./run.sh              # сервер + туннель (--no-tunnel — только локально)
```

## Локальные модели и раннеры

Каждая установленная локальная модель живёт в **своём контейнере** (`docker/runner.Dockerfile`):
её падение (OOM, битые веса) роняет только её контейнер, а не сервер и не соседние модели.
Супервизор ведёт реестр раннеров (имя, порт, токен, pid) в `vendor/runner/state.json` и
прозванивает живость по `/health`, а не верит записи.

```bash
docker build -f docker/runner.Dockerfile -t video-pipeline-runner .
# управление раннерами — инструмент media_runner:
#   media_runner(action='start', model='<имя>')  — поднять контейнер конкретной модели
#   media_runner(action='start')                  — раннер по умолчанию (пул всех моделей)
#   media_runner(action='stop')                   — остановить всё
#   media_runner(action='status')                 — фаза (running/exited/stopped) каждого раннера
```

Порт каждого контейнера модели — первый свободный из `docker.port_range` в
`config/providers.yaml` (по умолчанию 8771–8799), публикуется только на петлю
`127.0.0.1`. Токен и имя модели приходят переменными окружения, а не аргументами —
в `ps` их значений нет. Раннер, закреплённый за моделью, отказывает чужой модели кодом
`MODEL_MISMATCH`. Авто-перезапуска нет намеренно: упавший контейнер виден как `exited`
с хвостом журнала, а поднимает его человек или ИИ той же командой.

## Зависимости

Источник истины — `pyproject.toml` (`pip install -e .`); точные пины базы — `requirements.lock`;
dev-инструменты — `pip install -e ".[dev]"`; media — `pip install -e ".[media]"`; локальный
ML-инференс — `pip install -e ".[local]"` (и `pip install -e ".[gpu-amd]"` для карт AMD).

### База (обязательная, ~1.7 ГБ с torch)

| Пакет | Зачем |
|---|---|
| pydantic | контракты (ToolResult, ErrorDetail) |
| openpyxl | работа с Excel |
| pyyaml · jsonschema | чтение конфигов · валидация params по схеме |
| aiohttp | HTTP-транспорт сервера за туннелем |
| cryptography | подпись артефактов (S9), ключ инстанса |
| torch · torchaudio | рантайм локального инференса (в базе намеренно: без него `.venv` «пустой» для главной нагрузки) |

### Media (по запросу, `.[media]`)

| Пакет | Зачем |
|---|---|
| httpx | HTTP-клиент к облачным шлюзам провайдеров |
| litellm | унифицированный доступ к онлайн-моделям (STT/TTS/IMG) |
| onnxruntime · pillow | удаление фона, апскейл (граф ONNX) |
| ffmpeg-python | видео-операции |

### Local (по запросу, `.[local]` — модели поверх torch)

| Пакет | Зачем |
|---|---|
| stable-ts | локальная транскрипция (whisper) |
| piper-tts · diffusers · transformers | озвучка, генерация картинок |

cloudflared — бинарь (не pip), ставится `install.sh`.

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

План развития, находки и канон спек: [`docs/roadmap/`](docs/roadmap/README.md).
Предложения по улучшению функций: `docs/roadmap/spec/IMPROVEMENTS.md`.