yt-intel MCP Server – Das Markup (Automatisierung 04)

Ein MCP-Server, der die Kanaldaten von ../yt (yt-intel) als Diagnose-Tools bereitstellt – funktioniert mit jedem MCP-Client (Claude Desktop, Claude Code, Cursor, Codex oder allem anderen, das MCP spricht), nicht an ein Produkt gebunden. Geschwisterprojekt zu ../yt, ../storyboard und ../scriptwriter.

Wofür das gedacht ist

Beantwortung der Frage „Wie läuft es tatsächlich mit diesem Kanal, und was sollte ich als Nächstes tun" direkt aus einem Editor oder Chat-Client, ohne die yt-intel-Weboberfläche zu öffnen. Neun Tools, organisiert um die Diagnosefragen, die ein Produzent tatsächlich der Reihe nach stellt, nicht ein Tool pro Datenbanktabelle:

Kanalgesundheit

• channel_overview – Abonnenten-/Aufruf-Wachstumstrend, Kurz- vs. Langform-Aufteilung, Upload-Rhythmus

• list_videos – filterbare/sortierbare Basisauflistung

Leistungsdiagnose

• diagnose_video – das „Warum macht dieses Video das, was es tut"-Tool: Statistiken, Analysen, Geografie, Traffic-Quellen, Algorithmus-Ausrichtung, Dynamik und der Aufhänger

• find_underperformers / find_winners – sortierte Listen mit einer Typ-1-Diagnose (Umsetzungsproblem/schlechter Aufhänger) vs. Typ-2-Diagnose (Themen-Deckel) gemäß der hauseigenen Abschnitt-8-Logik der Themenauswahl-Checkliste

• search_tag_gaps – Suchbegriffe, die Aufrufe generieren, ohne passenden Tag

Inhaltssuche – Postgres-Volltextsuche (die GIN-Indizes, die bereits im yt-intel-Schema vorhanden sind – ix_transcripts_fts, ix_videos_title_fts – wurden erstellt und nie genutzt; das hier ist die erste echte Verwendung), kein naiver LIKE-Scan:

• search_transcripts – gewichtet, liefert hervorgehobene Ausschnitte, nicht nur IDs

• search_videos – dasselbe, über Titel + Beschreibung

Themen-/Skriptprüfung – nutzt die bereits erstellte, bereits getestete Logik von scriptwriter direkt wieder (eine lokale Pfadabhängigkeit, keine Kopie):

• check_topic – der Top-Land/Beste-Quelle-Datencheck, bevor man sich auf ein Thema festlegt

• qa_script – die komplette mechanische QA-Checkliste (Wortzahl/Tempo, Klammerprüfung, Duplikaterkennung, Zeitstempelberechnung)

Related MCP server: YouTube MCP Server

Warum Postgres-Volltextsuche und nicht Elasticsearch

Bei ~67 Videos und einigen hundert KB Transkripttext liegt man weit unter der Größenordnung, in der sich die verteilte Architektur von Elasticsearch durch ihre Betriebskosten auszahlt (ein zweiter Dienst, der bereitgestellt und synchron gehalten werden muss, auf einem 2–4-GB-VPS, das mit drei anderen Apps geteilt wird). Jede zu diesem Thema verglichene Quelle stimmt überein, dass die Postgres-Volltextsuche die große Mehrheit der Anwendungsfälle ohne zusätzliche Infrastruktur abdeckt, und die dafür benötigten GIN-Indizes existieren bereits ungenutzt im yt-intel-Schema. pgvector (semantische/bedeutungsbasierte Suche) ist die naheliegende Version 2, falls sich die Stichwortsuche in der Praxis als unzureichend erweist – nicht Elasticsearch, bei dieser Größenordnung.

Schnellstart

check_topic/qa_script benötigen ../scriptwriter als Geschwisterverzeichnis und müssen ZUERST installiert werden – es steht nicht in der eigenen Abhängigkeitsliste dieses Projekts (eine file://-Pfadabhängigkeit erwies sich als fragil: Ein absoluter Pfad funktioniert nur auf einem Rechner, und die Verarbeitung eines relativen Pfads durch pip war inkonsistent genug, um einen echten Docker-Build zu brechen – siehe den eigenen Hinweis in pyproject.toml und den Kommentar in der 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

Lokal über stdio ausführen (für Claude-Desktop-/Cursor-/Codex-Konfiguration):

python -m ytintel_mcp.server

Über HTTP ausführen (für eine Remote-/VPS-Bereitstellung):

YTINTEL_MCP_TRANSPORT=http python -m ytintel_mcp.server

Verbinden eines lokalen MCP-Clients (Claude Desktop / Cursor / Codex)

Jeder Client startet diesen Server als Unterprozess über stdio – verweisen Sie ihn auf das venv-Python dieses Projekts und das Modul:

{
  "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 (Einstellungen → Entwickler → Konfiguration bearbeiten). Cursor: Einstellungen → MCP → Neuen MCP-Server hinzufügen (gleiche JSON-Struktur). Codex: eigene MCP-Serverkonfiguration, gleiche command/args/env-Felder.

Bereitstellung auf dem VPS – zusammen mit scriptwriter

Dieses Projekt hat eine lokale Pfadabhängigkeit auf ../scriptwriter (für check_topic/qa_script, die scriptwriters domain/-Module direkt importieren, statt Kopien einzubinden – siehe pyproject.toml). Das bedeutet, das Docker-Image kann nur dort gebaut werden, wo BEIDE Projekte nebeneinander existieren, und beide müssen zusammen bereitgestellt werden, nicht unabhängig voneinander. Konkret auf dem 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

Port 8003 (yt-intel=8000, storyboard=8001, scriptwriter=8002, dieses=8003), wie die anderen an 127.0.0.1 gebunden – fügen Sie es demselben Caddy-Reverse-Proxy hinzu, falls ein Remote-MCP-Client es über das Netzwerk erreichen muss (Streamable-HTTP, nicht stdio, ist das, was eine Remote-Bereitstellung ausliefert – siehe YTINTEL_MCP_TRANSPORT in config.py).

Erneutes Bereitstellen nach einer scriptwriter-Codeänderung: Da das Image zur Buildzeit eine Kopie des scriptwriter-Codes einbettet (kein Live-Mount), muss das ytintel-mcp-Image neu gebaut werden (docker compose -f ytintel-mcp/docker-compose.prod.yml up -d --build), wenn sich domain/topic_scoring.py oder domain/script_qa.py auf der scriptwriter-Seite ändert – ein einfaches git pull nur bei scriptwriter aktualisiert den bereits gebauten ytintel-mcp-Container nicht.

Testen

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