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

Un servidor MCP que expone los datos de canal de ../yt (yt-intel) como herramientas de diagnóstico: funciona con cualquier cliente MCP (Claude Desktop, Claude Code, Cursor, Codex o cualquier otro que hable MCP), sin estar ligado a un producto concreto. Proyecto hermano de ../yt, ../storyboard y ../scriptwriter.

Para qué sirve

Responde a «¿cómo le está yendo realmente a este canal y qué debería hacer a continuación?» directamente desde un editor o un cliente de chat, sin abrir la interfaz web de yt-intel. Nueve herramientas organizadas en torno a las preguntas de diagnóstico que un productor se hace realmente en orden, no una herramienta por tabla de base de datos:

Salud del canal

• channel_overview — tendencia de crecimiento de suscriptores/vistas, desglose entre shorts y formato largo, cadencia de publicación

• list_videos — listado base filtrable y ordenable

Diagnóstico de rendimiento

• diagnose_video — la herramienta del «por qué este vídeo está haciendo lo que está haciendo»: estadísticas, analíticas, geo, fuentes de tráfico, alineación con el algoritmo, impulso y el gancho

• find_underperformers / find_winners — listas clasificadas anotadas con un diagnóstico de Tipo 1 (ejecución/mal gancho) frente a Tipo 2 (techo del tema), según la lógica de la propia Sección 8 de la Topic Selection Checklist de la casa

• search_tag_gaps — términos de búsqueda que generan vistas sin una etiqueta que coincida

Búsqueda de contenido — búsqueda de texto completo en Postgres (los índices GIN que ya estaban en el esquema de yt-intel — ix_transcripts_fts, ix_videos_title_fts — se crearon y no se usaban; esto es lo que por fin los utiliza), no un escaneo ingenuo con LIKE:

• search_transcripts — ordenado por relevancia, devuelve fragmentos resaltados, no solo IDs

• search_videos — igual, sobre título + descripción

Validación de temas/guiones — reutiliza la lógica ya construida y ya probada de scriptwriter directamente (una dependencia de ruta local, no una copia):

• check_topic — la comprobación de datos de Top Country/Best Source antes de comprometerse con un tema

• qa_script — la lista completa de verificación mecánica de control de calidad (QA) (recuento de palabras/ritmo, verificación de corchetes, detección de hechos duplicados, cálculo de marcas de tiempo)

Related MCP server: YouTube MCP Server

Por qué búsqueda de texto completo en Postgres, no Elasticsearch

Con ~67 vídeos y unos pocos cientos de KB de texto de transcripciones, esto está muy por debajo de la escala en la que la arquitectura distribuida de Elasticsearch justifica su coste operativo (un segundo servicio que desplegar y mantener sincronizado, en un VPS de 2-4 GB compartido con otras tres aplicaciones). Todas las fuentes comparadas coinciden en que la búsqueda de texto completo de Postgres cubre la gran mayoría de los casos de uso con cero infraestructura añadida, y los índices GIN que esto necesita ya existen en el esquema de yt-intel, sin usar. pgvector (búsqueda semántica/por significado) es la v2 natural si la búsqueda por palabras clave resulta insuficiente en la práctica — no Elasticsearch, a esta escala.

Inicio rápido

check_topic/qa_script necesitan que ../scriptwriter esté presente como directorio hermano e instalado PRIMERO; no está en la lista de dependencias de este proyecto (una dependencia de ruta file:// resultó frágil: una ruta absoluta solo se resuelve en una máquina, y el manejo de una relativa por parte de pip fue lo bastante inconsistente como para romper una compilación real de Docker — ver la nota de pyproject.toml y el comentario del 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

Ejecutar localmente por stdio (para configurar Claude Desktop / Cursor / Codex):

python -m ytintel_mcp.server

Ejecutar por HTTP (para un despliegue remoto/en VPS):

YTINTEL_MCP_TRANSPORT=http python -m ytintel_mcp.server

Conexión de un cliente MCP local (Claude Desktop / Cursor / Codex)

Cada cliente lanza este servidor como un subproceso por stdio — indícale el Python del venv de este proyecto y el módulo:

{
  "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 (la misma forma JSON). Codex: su propia configuración de servidor MCP, con los mismos campos command/args/env.

Despliegue en el VPS — junto con scriptwriter

Este proyecto tiene una dependencia de ruta local de ../scriptwriter (para check_topic/qa_script, que importan los módulos domain/ de scriptwriter directamente en lugar de incluir copias — ver pyproject.toml). Eso significa que la imagen de Docker solo se puede construir donde AMBOS proyectos existan lado a lado, y que los dos deben desplegarse juntos, no de forma independiente. Concretamente, en el 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

Puerto 8003 (yt-intel=8000, storyboard=8001, scriptwriter=8002, este=8003), enlazado a 127.0.0.1 como los demás — añádelo al mismo proxy inverso Caddy si un cliente MCP remoto necesita alcanzarlo a través de la red (streamable-http, no stdio, es lo que sirve un despliegue remoto — ver YTINTEL_MCP_TRANSPORT en config.py).

Redespliegue tras un cambio de código en scriptwriter: como la imagen incorpora una copia del código de scriptwriter en tiempo de compilación (no un montaje en vivo), la imagen de ytintel-mcp debe reconstruirse (docker compose -f ytintel-mcp/docker-compose.prod.yml up -d --build) cada vez que domain/topic_scoring.py o domain/script_qa.py cambien en el lado de scriptwriter — un simple git pull solo en scriptwriter no actualiza el contenedor ytintel-mcp ya construido.

Pruebas

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