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

../yt(yt-intel)의 채널 데이터를 진단 도구로 노출하는 MCP 서버입니다 — 모든 MCP 클라이언트(Claude Desktop, Claude Code, Cursor, Codex 또는 MCP를 지원하는 모든 도구)와 함께 작동하며, 특정 제품에 종속되지 않습니다. ../yt, ../storyboard, ../scriptwriter의 형제 프로젝트입니다.

용도

편집기나 채팅 클라이언트에서 yt-intel 웹 UI를 열지 않고도 "이 채널이 실제로 어떻게 돌아가고 있고, 다음에 무엇을 해야 하는가"에 답하기 위한 것입니다. 데이터베이스 테이블당 하나의 도구가 아니라, 프로듀서가 실제로 순서대로 묻는 진단 질문을 중심으로 구성된 9개의 도구입니다:

채널 건강 상태

• channel_overview — 구독자/조회수 성장 추세, 쇼츠 vs. 롱폼 비율, 업로드 주기

• list_videos — 필터/정렬 가능한 기본 목록

성능 진단

• diagnose_video — "이 영상이 왜 이런 성과를 내는가"를 설명하는 도구: 통계, 분석, 지역, 트래픽 소스, 알고리즘 정합성, 모멘텀, 훅

• find_underperformers / find_winners — 사내 Topic Selection Checklist의 Section 8 로직에 따라 Type-1(실행/나쁜 훅) vs. Type-2(주제 한계) 진단이 주석으로 달린 순위 목록

• search_tag_gaps — 조회수를 유도하지만 일치하는 태그가 없는 검색어

콘텐츠 검색 — Postgres 전문(full-text) 검색(yt-intel 스키마에 이미 있는 GIN 인덱스 — ix_transcripts_fts, ix_videos_title_fts — 는 구축만 되고 사용되지 않았습니다. 이것이 마침내 그 인덱스를 사용하는 것입니다), 단순한 LIKE 스캔이 아닙니다:

• search_transcripts — 순위가 매겨지며, ID만이 아니라 하이라이트된 스니펫을 반환

• search_videos — 제목 + 설명에 대해 동일한 방식

주제/스크립트 검증 — scriptwriter의 이미 구축되고 이미 테스트된 로직을 직접 재사용합니다(복사본이 아닌 로컬 경로 의존성):

• check_topic — 주제 확정 전 Top Country/Best Source 데이터 확인

• qa_script — 전체 기계적 QA 체크리스트(단어 수/속도, 대괄호 검증, 중복 사실 감지, 타임스탬프 계산)

Related MCP server: YouTube MCP Server

Postgres 전문 검색을 선택한 이유 — Elasticsearch가 아닌

약 67개 영상과 수백 KB의 트랜스크립트 텍스트 규모에서, Elasticsearch의 분산 아키텍처가 운영 비용(배포하고 동기화를 유지해야 하는 두 번째 서비스, 세 개의 다른 앱과 공유하는 2-4GB VPS에서)을 정당화할 만한 규모와는 거리가 멉니다. 이에 대해 비교한 모든 소스는 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를 통한 하위 프로세스로 실행합니다 — 이 프로젝트의 venv 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가 scriptwriter의 domain/ 모듈을 복사본으로 포함하지 않고 직접 임포트하기 때문 — 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에 바인딩 — 원격 MCP 클라이언트가 네트워크를 통해 접근해야 한다면 동일한 Caddy 리버스 프록시에 추가하세요(원격 배포는 stdio가 아닌 streamable-http를 제공합니다 — config.py의 YTINTEL_MCP_TRANSPORT 참조).

scriptwriter 코드 변경 후 재배포: 이미지가 빌드 시점에 scriptwriter 코드의 복사본을 포함하기 때문에(라이브 마운트가 아님), scriptwriter 쪽에서 domain/topic_scoring.py 또는 domain/script_qa.py가 변경될 때마다 ytintel-mcp의 이미지를 다시 빌드해야 합니다(docker compose -f ytintel-mcp/docker-compose.prod.yml up -d --build) — scriptwriter에서 단순히 git pull만 하는 것은 이미 빌드된 ytintel-mcp 컨테이너를 업데이트하지 않습니다.

테스트

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