Yt Intel Server

An MCP server exposing ../yt (yt-intel)'s channel data as diagnostic tools — works with any MCP client (Claude Desktop, Claude Code, Cursor, Codex, or anything else speaking MCP), not tied to one product. Sibling to ../yt, ../storyboard, and ../scriptwriter.

What this is for

Answering "how is this channel actually doing, and what should I do next" directly from an editor or chat client, without opening the yt-intel web UI. Nine tools, organized around the diagnostic questions a producer actually asks in sequence, not one tool per database table:

Channel health

• channel_overview — subscriber/view growth trend, shorts vs. long-form split, upload cadence
• list_videos — filterable/sortable base listing

Performance diagnosis

• diagnose_video — the "why is this video doing what it's doing" tool: stats, analytics, geo, traffic sources, algorithm alignment, momentum, and the hook
• find_underperformers / find_winners — ranked lists annotated with a Type-1 (execution/bad hook) vs. Type-2 (topic ceiling) diagnosis per the house Topic Selection Checklist's own Section 8 logic
• search_tag_gaps — search terms driving views with no matching tag

Content search — Postgres full-text search (the GIN indexes already in yt-intel's schema — ix_transcripts_fts, ix_videos_title_fts — were built and unused; this is what finally uses them), not a naive LIKE scan:

• search_transcripts — ranked, returns highlighted snippets, not just IDs
• search_videos — same, over title + description

Topic/script vetting — reuses scriptwriter's already-built, already- tested logic directly (a local path dependency, not a copy):

• check_topic — the Top Country/Best Source data check before committing to a topic
• qa_script — the full mechanical QA checklist (word count/pace, bracket verification, duplicate-fact detection, timestamp math)

Why Postgres full-text search, not Elasticsearch

At ~67 videos and a few hundred KB of transcript text, this is far below the scale where Elasticsearch's distributed architecture earns its operational cost (a second service to deploy and keep in sync, on a 2-4GB VPS shared with three other apps). Every source on this compared agrees Postgres full-text search handles the large majority of use cases with zero added infrastructure, and the GIN indexes this needs already exist in yt-intel's schema, unused. pgvector (semantic/meaning-based search) is the natural v2 if keyword search proves insufficient in practice — not Elasticsearch, at this scale.

Quick start

check_topic/qa_script need ../scriptwriter present as a sibling directory and installed FIRST — it's not in this project's own dependency list (a file:// path dependency proved fragile: an absolute path only resolves on one machine, and pip's handling of a relative one was inconsistent enough to break a real Docker build — see pyproject.toml's own note and Dockerfile's comment).

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

Run locally over stdio (for Claude Desktop / Cursor / Codex config):

python -m ytintel_mcp.server

Run over HTTP (for a remote/VPS deployment):

YTINTEL_MCP_TRANSPORT=http python -m ytintel_mcp.server

Connecting a local MCP client (Claude Desktop / Cursor / Codex)

Each client spawns this server as a subprocess over stdio — point it at this project's venv Python and the module:

{
  "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 (same JSON shape). Codex: its own MCP server config, same command/args/env fields.

Deploying to the VPS — together with scriptwriter

This project has a local path dependency on ../scriptwriter (for check_topic/qa_script, which import scriptwriter's domain/ modules directly rather than vendoring copies — see pyproject.toml). That means the Docker image can only be built where BOTH projects exist side by side, and the two must be deployed together, not independently. Concretely, on the 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, this=8003), bound to 127.0.0.1 like the others — add it to the same Caddy reverse proxy if a remote MCP client needs to reach it over the network (streamable-http, not stdio, is what a remote deployment serves — see config.py's YTINTEL_MCP_TRANSPORT).

Redeploying after a scriptwriter code change: because the image bakes in a copy of scriptwriter's code at build time (not a live mount), ytintel-mcp's image must be rebuilt (docker compose -f ytintel-mcp/docker-compose.prod.yml up -d --build) whenever domain/topic_scoring.py or domain/script_qa.py changes on scriptwriter's side — a plain git pull on scriptwriter alone does not update the already-built ytintel-mcp container.

Testing

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