yt-intel MCP サーバー — The Markup (Automation 04)

../yt (yt-intel) のチャンネルデータを診断ツールとして公開する MCP サーバー。あらゆる MCP クライアント（Claude Desktop、Claude Code、Cursor、Codex、その他 MCP を話すもの）で動作し、特定の製品に縛られません。../yt、../storyboard、../scriptwriter の兄弟プロジェクトです。

これは何のためか

「このチャンネルは実際どうなっているのか、次に何をすべきか」という問いに、yt-intel の Web UI を開かずに、エディタやチャットクライアントから直接答えるためのものです。9 つのツールは、プロデューサーが実際に順番に問う診断的な質問に沿って構成されており、データベースのテーブルごとに 1 ツールという形ではありません。

チャンネルの健全性

• channel_overview — 登録者数・視聴数の成長トレンド、ショートと長尺の比率、アップロード頻度

• list_videos — フィルタ・ソート可能な基本一覧

パフォーマンス診断

• diagnose_video — 「この動画がなぜこうなっているのか」を診断するツール: 統計、アナリティクス、地域、トラフィックソース、アルゴリズム適合性、勢い、フック

• find_underperformers / find_winners — ランキング形式のリストに、ハウスのトピック選択チェックリストのセクション 8 のロジックに基づく Type-1（実行/フック不良）と Type-2（トピックの天井）の診断を注記

• search_tag_gaps — 視聴を牽引しているが一致するタグがない検索語

コンテンツ検索 — Postgres 全文検索（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

なぜ Elasticsearch ではなく Postgres 全文検索なのか

約 67 本の動画と数百 KB のトランスクリプトテキストでは、Elasticsearch の分散アーキテクチャが運用コストに見合う規模をはるかに下回っています（2〜4GB の VPS で他の 3 つのアプリと共有し、デプロイと同期を維持する必要がある 2 つ目のサービス）。比較したすべての情報源が、Postgres の全文検索はインフラを追加せずに大多数のユースケースを処理でき、必要な GIN インデックスは yt-intel のスキーマに既に未使用で存在すると述べています。pgvector（意味ベースの検索）は、キーワード検索が実際に不十分であることが証明された場合の自然な v2 です — この規模では Elasticsearch ではありません。

クイックスタート

check_topic/qa_script は、../scriptwriter が兄弟ディレクトリとして存在し、最初にインストールされている必要があります。これはこのプロジェクト自身の依存リストには含まれていません（file:// パス依存は脆弱であることが判明: 絶対パスは 1 台のマシンでしか解決できず、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 イメージは両方のプロジェクトが並んで存在する場所でのみビルドでき、2 つは独立してではなく一緒にデプロイする必要があります。具体的には、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