yt-intel MCP Server — The Markup (Automation 04)

MCP-сервер, предоставляющий данные каналов из ../yt (yt-intel) в виде диагностических инструментов — работает с любым MCP-клиентом (Claude Desktop, Claude Code, Cursor, Codex или любым другим, говорящим на MCP), не привязан к одному продукту. Родственный проект для ../yt, ../storyboard и ../scriptwriter.

Для чего это нужно

Ответы на вопросы «как на самом деле дела у канала и что делать дальше» прямо из редактора или чат-клиента, без открытия веб-интерфейса yt-intel. Девять инструментов, сгруппированных по диагностическим вопросам, которые продюсер задаёт последовательно, а не по одному инструменту на таблицу базы данных:

Здоровье канала

• channel_overview — тенденции роста подписчиков/просмотров, разбивка shorts и длинных видео, частота публикаций

• list_videos — базовый список с фильтрацией/сортировкой

Диагностика производительности

• diagnose_video — инструмент «почему это видео ведёт себя именно так»: статистика, аналитика, география, источники трафика, соответствие алгоритму, динамика и крючок

• find_underperformers / find_winners — ранжированные списки с диагнозом Тип-1 (исполнение/плохой крючок) или Тип-2 (потолок темы) согласно логике Раздела 8 внутреннего Чек-листа выбора тем

• search_tag_gaps — поисковые запросы, приносящие просмотры, без соответствующего тега

Поиск по контенту — полнотекстовый поиск Postgres (GIN-индексы, уже существующие в схеме yt-intel — ix_transcripts_fts, ix_videos_title_fts — были созданы и не использовались; теперь они наконец нашли применение), а не наивный LIKE-скан:

• search_transcripts — ранжированный поиск с подсветкой фрагментов, а не только ID

• search_videos — то же самое по заголовку и описанию

Проверка тем/сценариев — переиспользует уже готовую и протестированную логику scriptwriter напрямую (локальная зависимость, а не копия):

• check_topic — проверка данных Top Country/Best Source перед утверждением темы

• qa_script — полный механический чек-лист контроля качества (количество слов/темп, проверка скобок, обнаружение дублирующихся фактов, расчёт временных меток)

Related MCP server: YouTube MCP Server

Почему полнотекстовый поиск Postgres, а не Elasticsearch

При ~67 видео и нескольких сотнях килобайт текста транскриптов это намного ниже масштаба, где распределённая архитектура Elasticsearch оправдывает эксплуатационные расходы (второй сервис для развёртывания и синхронизации на VPS с 2-4 ГБ ОЗУ, разделяемом с тремя другими приложениями). Все источники по этой теме сходятся во мнении, что полнотекстовый поиск Postgres покрывает подавляющее большинство сценариев без какой-либо дополнительной инфраструктуры, а нужные GIN-индексы уже есть в схеме yt-intel и не используются. pgvector (семантический поиск по смыслу) — естественный кандидат на v2, если ключевой поиск окажется недостаточным на практике — но не Elasticsearch, при таком масштабе.

Быстрый старт

Для check_topic/qa_script необходимо, чтобы ../scriptwriter присутствовал как соседняя директория и был установлен ПЕРВЫМ — его нет в списке зависимостей этого проекта (зависимость через file:// оказалась хрупкой: абсолютный путь работает только на одной машине, а обработка относительного пути в pip была недостаточно последовательной, что сломало реальную Docker-сборку — см. примечание в pyproject.toml и комментарий в Dockerfile).

python -m venv .venv
./.venv/Scripts/python.exe -m pip install -e ../scriptwriter   # first
./.venv/Scripts/python.exe -m pip install -e ".[dev]"          # Windows

cp .env.example .env      # YTINTEL_DATABASE_URL, OWN_CHANNEL_ID

Запуск локально через stdio (для конфигурации Claude Desktop / Cursor / Codex):

python -m ytintel_mcp.server

Запуск через HTTP (для удалённого развёртывания на VPS):

YTINTEL_MCP_TRANSPORT=http python -m ytintel_mcp.server

Подключение локального MCP-клиента (Claude Desktop / Cursor / Codex)

Каждый клиент запускает этот сервер как дочерний процесс через stdio — укажите ему Python из виртуального окружения этого проекта и модуль:

{
  "mcpServers": {
    "ytintel": {
      "command": "D:/Axion/ytintel-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "ytintel_mcp.server"],
      "env": {
        "YTINTEL_DATABASE_URL": "postgresql+psycopg://yt:yt@localhost:5432/yt_intel",
        "OWN_CHANNEL_ID": "UCODE52XZvkuimEZfGD10Bcw"
      }
    }
  }
}

Claude Desktop: claude_desktop_config.json (Settings → Developer → Edit Config). Cursor: Settings → MCP → Add new MCP server (та же JSON-структура). Codex: собственная конфигурация MCP-сервера с теми же полями command/args/env.

Развёртывание на VPS — вместе со scriptwriter

У этого проекта локальная зависимость от ../scriptwriter (для check_topic/qa_script, которые импортируют модули domain/ из scriptwriter напрямую, а не копируют их — см. pyproject.toml). Это означает, что Docker-образ можно собрать только там, где ОБА проекта существуют рядом, и развёртывать их нужно вместе, а не по отдельности. Конкретно, на VPS:

# 1. Clone (or already have) BOTH projects as siblings under the same parent,
#    e.g. ~/Axion/scriptwriter and ~/Axion/ytintel-mcp — mirroring this dev
#    machine's D:\Axion layout. The path dependency in ytintel-mcp's
#    pyproject.toml is an ABSOLUTE dev-machine path
#    (file:///D:/Axion/scriptwriter) that only matters locally — the
#    Dockerfile does NOT use it; it installs scriptwriter from the shared
#    build context instead (see Dockerfile's own header comment), so the
#    exact clone path on the VPS doesn't need to match this dev machine's.
cd ~/Axion
git clone <scriptwriter repo> scriptwriter
git clone <ytintel-mcp repo> ytintel-mcp

# 2. scriptwriter's own .env (needed for its own deploy — OPENAI_API_KEY /
#    MISTRAL_API_KEY, YTINTEL_DB_PASSWORD, YTINTEL_NETWORK_NAME — see
#    ../scriptwriter/README.md's own Deployment section) and ytintel-mcp's
#    .env (same YTINTEL_DB_*/YTINTEL_NETWORK_NAME vars, plus OWN_CHANNEL_ID)
cp scriptwriter/.env.example scriptwriter/.env && nano scriptwriter/.env
cp ytintel-mcp/.env.example ytintel-mcp/.env && nano ytintel-mcp/.env
chmod 600 scriptwriter/.env ytintel-mcp/.env

# 3. Confirm yt-intel's actual Docker network name BEFORE either deploy —
#    both .env files' YTINTEL_NETWORK_NAME must match this exactly:
docker network ls | grep default

# 4. Deploy scriptwriter first (no cross-project build dependency, so order
#    doesn't strictly matter, but this mirrors provisioning it before the
#    tool that references its code)
cd ~/Axion/scriptwriter
docker compose -f docker-compose.prod.yml up -d --build

# 5. Deploy ytintel-mcp — note the build context is the AXION ROOT, not this
#    directory (the Dockerfile COPYs ../scriptwriter into the image):
cd ~/Axion
docker compose -f ytintel-mcp/docker-compose.prod.yml up -d --build

Порт 8003 (yt-intel=8000, storyboard=8001, scriptwriter=8002, этот=8003), привязан к 127.0.0.1, как и остальные — добавьте его в тот же обратный прокси-сервер Caddy, если удалённому MCP-клиенту нужен доступ по сети (удалённое развёртывание работает через streamable-http, а не stdio — см. YTINTEL_MCP_TRANSPORT в config.py).

Повторное развёртывание после изменения кода scriptwriter: поскольку образ включает копию кода scriptwriter на этапе сборки (а не живую монтировку), образ ytintel-mcp необходимо пересобрать (docker compose -f ytintel-mcp/docker-compose.prod.yml up -d --build) при каждом изменении domain/topic_scoring.py или domain/script_qa.py на стороне scriptwriter — простого git pull в scriptwriter недостаточно для обновления уже собранного контейнера ytintel-mcp.

Тестирование

./.venv/Scripts/python.exe -m pytest -q
./.venv/Scripts/python.exe -m ruff check .
./.venv/Scripts/python.exe -m mypy src