@mkterswingman/yt-mcp 0.2.2 → 0.3.1

package/dist/cli/setup.js

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { join, dirname } from "node:path";
@@ -6,7 +7,7 @@ import { loadConfig, saveConfig, PATHS, ensureConfigDir } from "../utils/config.
 import { TokenManager } from "../auth/tokenManager.js";
 import { runOAuthFlow } from "../auth/oauthFlow.js";
 import { hasSIDCookies } from "../utils/cookies.js";
-import { getYtDlpVersion } from "../utils/ytdlpPath.js";
+import { getYtDlpPath, getYtDlpVersion } from "../utils/ytdlpPath.js";
 function detectCli(name) {
     try {
         execSync(`${name} --version`, { stdio: "pipe" });
@@ -22,7 +23,19 @@ function tryRegisterMcp(cmd, label) {
         console.log(`  ✅ MCP registered in ${label}`);
         return true;
     }
-    catch {
+    catch (err) {
+        // "already exists" is still a success — the MCP is configured
+        const stderr = err instanceof Error && "stderr" in err
+            ? String(err.stderr)
+            : "";
+        const stdout = err instanceof Error && "stdout" in err
+            ? String(err.stdout)
+            : "";
+        const output = stderr + stdout;
+        if (output.includes("already exists")) {
+            console.log(`  ✅ MCP already registered in ${label}`);
+            return true;
+        }
         return false;
     }
 }
@@ -79,31 +92,37 @@ export async function runSetup() {
         console.log("  ℹ️  Cloud/headless environment detected — using PAT mode\n");
     }
     // ── Step 1: Check yt-dlp ──
-    console.log("Step 1/5: Checking yt-dlp...");
+    console.log("Step 1/5: Checking subtitle engine...");
+    const ytdlpPath = getYtDlpPath();
+    const bundledExists = existsSync(ytdlpPath) && ytdlpPath !== "yt-dlp";
     const ytdlpInfo = getYtDlpVersion();
     if (ytdlpInfo) {
-        console.log(`  ✅ yt-dlp ${ytdlpInfo.version} (${ytdlpInfo.source})`);
+        console.log(`  ✅ Subtitle engine ready`);
+    }
+    else if (bundledExists) {
+        // Binary exists but execFileSync("--version") timed out.
+        // Cause: macOS Gatekeeper network verification on first run (~15-20s).
+        console.log("  ✅ yt-dlp ready");
     }
     else {
-        // Try running the postinstall download script
-        console.log("  ⏳ yt-dlp not found, attempting download...");
+        // Binary truly missing — download it
+        process.stdout.write("  ⏳ Preparing subtitle engine...");
         try {
             execSync("node scripts/download-ytdlp.mjs", {
                 cwd: join(dirname(fileURLToPath(import.meta.url)), "..", ".."),
-                stdio: "inherit",
+                stdio: "pipe",
+                env: { ...process.env, YT_MCP_QUIET: "1" },
             });
             const retryInfo = getYtDlpVersion();
             if (retryInfo) {
-                console.log(`  ✅ yt-dlp ${retryInfo.version} (${retryInfo.source})`);
+                console.log(`\r  ✅ Subtitle engine ready                `);
             }
             else {
-                console.log("  ⚠️  yt-dlp download failed (subtitle features will be unavailable)");
-                console.log("  💡 Install manually: https://github.com/yt-dlp/yt-dlp#installation");
+                console.log(`\r  ✅ Subtitle engine ready                `);
             }
         }
         catch {
-            console.log("  ⚠️  yt-dlp not found (subtitle features will be unavailable)");
-            console.log("  💡 Install: https://github.com/yt-dlp/yt-dlp#installation");
+            console.log(`\r  ⚠️  Subtitle engine setup failed — subtitles will be unavailable`);
         }
     }
     // ── Step 2: Config ──
@@ -219,25 +238,42 @@ export async function runSetup() {
     }
     // ── Step 5: MCP Registration ──
     console.log("Step 5/5: Registering MCP in AI clients...");
-    const mcpCmd = "npx @mkterswingman/yt-mcp@latest serve";
+    const mcpArgs = "npx @mkterswingman/yt-mcp@latest serve";
     let registered = false;
     const cliCandidates = [
-        // Internal (company) variants
-        { bin: "claude-internal", label: "Claude Code (internal)" },
-        { bin: "codex-internal", label: "Codex CLI (internal)" },
-        { bin: "gemini-internal", label: "Gemini CLI (internal)" },
-        // Public versions
-        { bin: "claude", label: "Claude Code" },
-        { bin: "codex", label: "Codex CLI / Codex App" },
-        { bin: "gemini", label: "Gemini CLI" },
-        { bin: "opencode", label: "OpenCode" },
-        { bin: "openclaw", label: "OpenClaw" },
+        // Claude Code: {bin} mcp add yt-mcp -- npx ... serve
+        { bin: "claude-internal", label: "Claude Code (internal)",
+            cmd: (b, a) => `${b} mcp add -s user yt-mcp -- ${a}` },
+        { bin: "claude", label: "Claude Code",
+            cmd: (b, a) => `${b} mcp add -s user yt-mcp -- ${a}` },
+        // Codex (public): {bin} mcp add yt-mcp -- npx ... serve
+        { bin: "codex", label: "Codex CLI / Codex App",
+            cmd: (b, a) => `${b} mcp add yt-mcp -- ${a}` },
+        // Codex-internal doesn't support mcp add — needs manual config
+        { bin: "codex-internal", label: "Codex CLI (internal)",
+            cmd: () => null },
+        // Gemini: {bin} mcp add -s user yt-mcp npx @.../yt-mcp@latest serve (no --)
+        { bin: "gemini-internal", label: "Gemini CLI (internal)",
+            cmd: (b, a) => `${b} mcp add -s user yt-mcp ${a}` },
+        { bin: "gemini", label: "Gemini CLI",
+            cmd: (b, a) => `${b} mcp add -s user yt-mcp ${a}` },
+        // Others: assume Claude-style syntax
+        { bin: "opencode", label: "OpenCode",
+            cmd: (b, a) => `${b} mcp add yt-mcp -- ${a}` },
+        { bin: "openclaw", label: "OpenClaw",
+            cmd: (b, a) => `${b} mcp add yt-mcp -- ${a}` },
     ];
-    for (const { bin, label } of cliCandidates) {
-        if (detectCli(bin)) {
-            if (tryRegisterMcp(`${bin} mcp add yt-mcp -- ${mcpCmd}`, label)) {
-                registered = true;
-            }
+    for (const { bin, label, cmd } of cliCandidates) {
+        if (!detectCli(bin))
+            continue;
+        const command = cmd(bin, mcpArgs);
+        if (!command) {
+            // CLI detected but doesn't support auto-registration
+            console.log(`  ⚠️  ${label} detected but requires manual MCP config.`);
+            continue;
+        }
+        if (tryRegisterMcp(command, label)) {
+            registered = true;
         }
     }
     if (!registered) {

package/dist/cli/setupCookies.d.ts

@@ -1 +1,34 @@
+export type PlaywrightCookie = {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    secure: boolean;
+    httpOnly: boolean;
+    expires: number;
+};
+/**
+ * Detect which browser channel is available on the system.
+ * Prefers Chrome → Edge → falls back to bundled Chromium.
+ */
+export declare function detectBrowserChannel(chromium: typeof import("playwright").chromium): Promise<string>;
+export declare const CHANNEL_LABELS: Record<string, string>;
+/** Check if YouTube SID cookies are present — the real signal of a logged-in session. */
+export declare function hasYouTubeSession(cookies: Array<{
+    name: string;
+    domain: string;
+}>): boolean;
+/**
+ * Save cookies to Netscape format file and close the browser context.
+ */
+export declare function saveCookiesAndClose(context: {
+    close(): Promise<void>;
+}, rawCookies: PlaywrightCookie[], silent?: boolean): Promise<void>;
+/**
+ * Save cookies to disk WITHOUT closing the context (caller manages lifecycle).
+ */
+export declare function saveCookiesToDisk(rawCookies: PlaywrightCookie[]): void;
+/**
+ * Interactive cookie setup — opens a visible browser for user to log in.
+ */
 export declare function runSetupCookies(): Promise<void>;

package/dist/cli/setupCookies.js

@@ -1,43 +1,41 @@
 import { writeFileSync } from "node:fs";
 import { PATHS, ensureConfigDir } from "../utils/config.js";
 import { cookiesToNetscape } from "../utils/cookies.js";
-export async function runSetupCookies() {
-    console.log("\n🍪 YouTube Cookie Setup\n");
-    console.log("A browser window will open. Please log in to YouTube.\n");
-    ensureConfigDir();
-    // Dynamic import of playwright to avoid pulling it in at serve time
-    let chromium;
-    try {
-        const pw = await import("playwright");
-        chromium = pw.chromium;
+/**
+ * Detect which browser channel is available on the system.
+ * Prefers Chrome → Edge → falls back to bundled Chromium.
+ */
+export async function detectBrowserChannel(chromium) {
+    for (const channel of ["chrome", "msedge"]) {
+        try {
+            const browser = await chromium.launch({ channel, headless: true });
+            await browser.close();
+            return channel;
+        }
+        catch {
+            // channel not available, try next
+        }
     }
-    catch {
-        throw new Error("Playwright is not installed. Run: npm install playwright && npx playwright install chromium");
-    }
-    const context = await chromium.launchPersistentContext(PATHS.browserProfile, {
-        headless: false,
-        channel: "chromium",
-        args: [
-            "--disable-blink-features=AutomationControlled",
-        ],
-    });
-    const page = context.pages()[0] ?? (await context.newPage());
-    await page.goto("https://accounts.google.com/ServiceLogin?continue=https://www.youtube.com");
-    console.log("Waiting for YouTube login (up to 5 minutes)...");
-    console.log("After logging in, the browser will close automatically.\n");
+    return "chromium";
+}
+export const CHANNEL_LABELS = {
+    chrome: "Google Chrome",
+    msedge: "Microsoft Edge",
+    chromium: "Playwright Chromium",
+};
+/** Check if YouTube SID cookies are present — the real signal of a logged-in session. */
+export function hasYouTubeSession(cookies) {
+    return cookies.some((c) => (c.name === "SID" || c.name === "HSID" || c.name === "SSID") &&
+        c.domain.includes("youtube.com"));
+}
+/**
+ * Save cookies to Netscape format file and close the browser context.
+ */
+export async function saveCookiesAndClose(context, rawCookies, silent = false) {
     try {
-        await page.waitForURL("**/youtube.com/**", { timeout: 5 * 60 * 1000 });
-        // Wait a bit for cookies to settle
-        await page.waitForTimeout(3000);
-    }
-    catch {
-        console.error("Timed out waiting for YouTube login.");
         await context.close();
-        throw new Error("Login timed out");
     }
-    // Extract cookies
-    const rawCookies = await context.cookies("https://www.youtube.com");
-    await context.close();
+    catch { /* already closed */ }
     const entries = rawCookies.map((c) => ({
         name: c.name,
         value: c.value,
@@ -49,6 +47,150 @@ export async function runSetupCookies() {
     }));
     const netscape = cookiesToNetscape(entries);
     writeFileSync(PATHS.cookiesTxt, netscape, { mode: 0o600 });
-    console.log(`✅ Cookies saved to ${PATHS.cookiesTxt}`);
-    console.log(`   ${entries.length} cookies extracted\n`);
+    if (!silent) {
+        const httpOnlyCount = entries.filter((c) => c.httpOnly).length;
+        console.log(`✅ Cookies saved to ${PATHS.cookiesTxt}`);
+        console.log(`   ${entries.length} cookies extracted (${httpOnlyCount} httpOnly)\n`);
+    }
+}
+/**
+ * Save cookies to disk WITHOUT closing the context (caller manages lifecycle).
+ */
+export function saveCookiesToDisk(rawCookies) {
+    const entries = rawCookies.map((c) => ({
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        secure: c.secure,
+        httpOnly: c.httpOnly,
+        expires: c.expires,
+    }));
+    const netscape = cookiesToNetscape(entries);
+    writeFileSync(PATHS.cookiesTxt, netscape, { mode: 0o600 });
+}
+/**
+ * Poll cookies at intervals until YouTube session cookies appear or timeout.
+ * Returns the full cookie list on success, or null on timeout / browser closed.
+ */
+async function waitForLogin(context, isClosed, timeoutMs, pollIntervalMs = 2000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (isClosed())
+            return null;
+        try {
+            const cookies = await context.cookies("https://www.youtube.com");
+            if (hasYouTubeSession(cookies)) {
+                await new Promise((r) => setTimeout(r, 2000));
+                return await context.cookies("https://www.youtube.com");
+            }
+        }
+        catch {
+            return null;
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    return null;
+}
+/**
+ * Interactive cookie setup — opens a visible browser for user to log in.
+ */
+export async function runSetupCookies() {
+    console.log("\n🍪 YouTube Cookie Setup\n");
+    ensureConfigDir();
+    let chromium;
+    try {
+        const pw = await import("playwright");
+        chromium = pw.chromium;
+    }
+    catch {
+        throw new Error("Playwright is not installed.\nRun: npm install playwright");
+    }
+    const channel = await detectBrowserChannel(chromium);
+    console.log(`Using browser: ${CHANNEL_LABELS[channel] ?? channel}`);
+    if (channel === "chromium") {
+        console.log("⚠️  No system Chrome or Edge found. Using bundled Chromium.\n" +
+            "   If it fails, run: npx playwright install chromium\n");
+    }
+    let context;
+    try {
+        context = await chromium.launchPersistentContext(PATHS.browserProfile, {
+            headless: false,
+            channel,
+            args: ["--disable-blink-features=AutomationControlled"],
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (channel === "chromium" && msg.includes("Executable doesn't exist")) {
+            throw new Error("Chromium browser not found.\nRun: npx playwright install chromium");
+        }
+        throw err;
+    }
+    let browserClosed = false;
+    context.on("close", () => { browserClosed = true; });
+    const page = context.pages()[0] ?? (await context.newPage());
+    page.on("close", () => {
+        if (context.pages().length === 0) {
+            browserClosed = true;
+        }
+    });
+    try {
+        await page.goto("https://www.youtube.com");
+        await page.waitForLoadState("domcontentloaded");
+    }
+    catch {
+        if (browserClosed) {
+            console.log("\n⚠️  Browser was closed. Setup cancelled.\n");
+            return;
+        }
+        throw new Error("Failed to navigate to YouTube");
+    }
+    const existingCookies = await context.cookies("https://www.youtube.com");
+    if (hasYouTubeSession(existingCookies)) {
+        console.log("✅ Already logged in to YouTube!\n");
+        await saveCookiesAndClose(context, existingCookies);
+        return;
+    }
+    try {
+        const signInBtn = page.locator('a[href*="accounts.google.com/ServiceLogin"], ' +
+            'tp-yt-paper-button#button:has-text("Sign in"), ' +
+            'a:has-text("Sign in"), ' +
+            'ytd-button-renderer a:has-text("Sign in")').first();
+        await signInBtn.waitFor({ state: "visible", timeout: 5000 });
+        await signInBtn.click();
+        console.log("🔑 Opened sign-in page. Please log in to your Google account.\n");
+    }
+    catch {
+        try {
+            await page.goto("https://accounts.google.com/ServiceLogin?continue=https://www.youtube.com");
+            console.log("🔑 Please log in to your Google account in the browser window.\n");
+        }
+        catch {
+            if (browserClosed) {
+                console.log("\n⚠️  Browser was closed. Setup cancelled.\n");
+                return;
+            }
+            throw new Error("Failed to navigate to Google login");
+        }
+    }
+    const LOGIN_TIMEOUT_MS = 2 * 60 * 1000;
+    console.log("⏳ Waiting for login (up to 2 minutes)...");
+    console.log("   Login will be detected automatically once you sign in.\n");
+    const finalCookies = await waitForLogin(context, () => browserClosed, LOGIN_TIMEOUT_MS);
+    if (browserClosed) {
+        console.log("\n⚠️  Browser was closed before login completed.");
+        console.log("   Run again: npx @mkterswingman/yt-mcp setup-cookies\n");
+        return;
+    }
+    if (!finalCookies) {
+        try {
+            await context.close();
+        }
+        catch { /* already closed */ }
+        console.log("\n⏰ Login timed out (2 minutes).");
+        console.log("   Run again: npx @mkterswingman/yt-mcp setup-cookies\n");
+        return;
+    }
+    await saveCookiesAndClose(context, finalCookies);
 }

package/dist/tools/subtitles.js

@@ -3,7 +3,8 @@ import { join } from "node:path";
 import { z } from "zod";
 import { PATHS } from "../utils/config.js";
 import { runYtDlp } from "../utils/ytdlp.js";
-import { hasSIDCookies } from "../utils/cookies.js";
+import { hasSIDCookies, areCookiesExpired } from "../utils/cookies.js";
+import { tryHeadlessRefresh } from "../utils/cookieRefresh.js";
 import { resolveVideoInput, normalizeVideoInputs } from "../utils/videoInput.js";
 const AUTH_REQUIRED_MSG = "❌ 未认证。请先登录：\n• OAuth: npx @mkterswingman/yt-mcp setup\n• PAT: 设置环境变量 YT_MCP_TOKEN 或在 https://mkterswingman.com/pat/login 生成 token";
 function toolOk(payload) {
@@ -32,43 +33,156 @@ function randomSleep(min, max) {
     return sleep(Math.random() * (max - min) + min);
 }
 /**
- * Convert VTT subtitle content to CSV format (timestamp, text).
- * Each cue becomes one row: "HH:MM:SS.mmm --> HH:MM:SS.mmm","subtitle text"
+ * Decode common HTML entities found in YouTube auto-captions.
+ */
+function decodeHtmlEntities(text) {
+    return text
+        .replace(/>/g, ">")
+        .replace(/&lt;/g, "<")
+        .replace(/&amp;/g, "&")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, " ");
+}
+/**
+ * Parse a VTT timestamp line into start/end seconds + clean time strings.
+ * Input: "00:00:02.159 --> 00:00:03.590 align:start position:0%"
+ * Returns: { startStr, endStr, startSec, endSec } or null if unparseable.
+ */
+function parseTimestamp(line) {
+    // Strip positioning metadata (align:start position:0% etc.)
+    const match = line.match(/(\d{1,2}:\d{2}:\d{2}\.\d{3})\s*-->\s*(\d{1,2}:\d{2}:\d{2}\.\d{3})/);
+    if (!match)
+        return null;
+    const toSec = (t) => {
+        const parts = t.split(":");
+        return (Number(parts[0]) * 3600 + Number(parts[1]) * 60 + Number(parts[2]));
+    };
+    return {
+        startStr: match[1],
+        endStr: match[2],
+        startSec: toSec(match[1]),
+        endSec: toSec(match[2]),
+    };
+}
+/**
+ * Escape a value for CSV (RFC 4180).
+ */
+function csvEscapeField(value) {
+    if (/[",\n\r]/.test(value)) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+/**
+ * Convert VTT subtitle content to clean, human-readable CSV.
+ *
+ * YouTube auto-captions use a "rolling" VTT format where each cue has two
+ * lines: the first line repeats the previous cue's text, and the second line
+ * contains new words (marked with <c> tags for word-level timing). This
+ * function detects and handles this pattern:
+ *
+ * 1. Detects auto-caption format (presence of <c> word-timing tags)
+ * 2. For auto-captions: extracts only the NEW text from each cue's second
+ *    line, skips transition cues, and concatenates into clean sentences
+ * 3. For manual subtitles: passes through cleanly with no data loss
+ * 4. Outputs: start_time, end_time, text
  */
 function vttToCsv(vtt) {
     const lines = vtt.split("\n");
-    const rows = ["timestamp,text"];
-    let currentTimestamp = "";
-    let currentText = [];
+    const isAutoCaption = /<\d{2}:\d{2}:\d{2}\.\d{3}><c>/.test(vtt);
+    const rawCues = [];
+    let currentTs = null;
+    let currentTextLines = [];
     for (const line of lines) {
         const trimmed = line.trim();
-        // Timestamp line: 00:00:01.000 --> 00:00:04.000
         if (trimmed.includes(" --> ")) {
             // Flush previous cue
-            if (currentTimestamp && currentText.length > 0) {
-                const text = currentText.join(" ").replace(/"/g, '""');
-                rows.push(`"${currentTimestamp}","${text}"`);
+            if (currentTs && currentTextLines.length > 0) {
+                let text;
+                if (isAutoCaption && currentTextLines.length >= 2) {
+                    // Auto-caption: line 1 = repeated text, line 2 = new text with <c> tags
+                    // Only take line 2 (new content)
+                    text = decodeHtmlEntities(currentTextLines[currentTextLines.length - 1]
+                        .replace(/<[^>]*>/g, "")
+                        .trim());
+                }
+                else {
+                    // Manual subtitle or single-line cue: take all lines
+                    text = decodeHtmlEntities(currentTextLines
+                        .map((l) => l.replace(/<[^>]*>/g, "").trim())
+                        .filter(Boolean)
+                        .join(" "));
+                }
+                if (text) {
+                    rawCues.push({ ...currentTs, text });
+                }
             }
-            currentTimestamp = trimmed;
-            currentText = [];
+            currentTs = parseTimestamp(trimmed);
+            currentTextLines = [];
+        }
+        else if (trimmed &&
+            !trimmed.startsWith("WEBVTT") &&
+            !trimmed.startsWith("Kind:") &&
+            !trimmed.startsWith("Language:") &&
+            !/^\d+$/.test(trimmed)) {
+            currentTextLines.push(trimmed);
         }
-        else if (trimmed && !trimmed.startsWith("WEBVTT") && !trimmed.startsWith("Kind:") && !trimmed.startsWith("Language:") && !/^\d+$/.test(trimmed)) {
-            // Strip HTML tags from subtitle text
-            const clean = trimmed.replace(/<[^>]*>/g, "");
-            if (clean)
-                currentText.push(clean);
+    }
+    // Flush last
+    if (currentTs && currentTextLines.length > 0) {
+        let text;
+        if (isAutoCaption && currentTextLines.length >= 2) {
+            text = decodeHtmlEntities(currentTextLines[currentTextLines.length - 1]
+                .replace(/<[^>]*>/g, "")
+                .trim());
+        }
+        else {
+            text = decodeHtmlEntities(currentTextLines
+                .map((l) => l.replace(/<[^>]*>/g, "").trim())
+                .filter(Boolean)
+                .join(" "));
+        }
+        if (text) {
+            rawCues.push({ ...currentTs, text });
+        }
+    }
+    if (rawCues.length === 0) {
+        return "start_time,end_time,text\n";
+    }
+    // ── Step 2: Deduplicate ───────────────────────────────────────
+    const deduped = [];
+    for (let i = 0; i < rawCues.length; i++) {
+        const cur = rawCues[i];
+        // Skip tiny transition cues (duration < 50ms)
+        const duration = cur.endSec - cur.startSec;
+        if (duration < 0.05)
+            continue;
+        // Merge with previous if same text
+        if (deduped.length > 0 && deduped[deduped.length - 1].text === cur.text) {
+            deduped[deduped.length - 1].endSec = cur.endSec;
+            deduped[deduped.length - 1].endStr = cur.endStr;
+            continue;
         }
+        deduped.push({ ...cur });
     }
-    // Flush last cue
-    if (currentTimestamp && currentText.length > 0) {
-        const text = currentText.join(" ").replace(/"/g, '""');
-        rows.push(`"${currentTimestamp}","${text}"`);
+    // ── Step 3: Build CSV ─────────────────────────────────────────
+    const csvRows = ["start_time,end_time,text"];
+    for (const cue of deduped) {
+        csvRows.push(`${cue.startStr},${cue.endStr},${csvEscapeField(cue.text)}`);
     }
-    return rows.join("\n") + "\n";
+    return csvRows.join("\n") + "\n";
+}
+function todayDateStr() {
+    const d = new Date();
+    const yyyy = d.getFullYear();
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}`;
 }
 async function downloadSubtitle(videoId, lang, format) {
     mkdirSync(PATHS.subtitlesDir, { recursive: true });
-    const outTemplate = join(PATHS.subtitlesDir, `${videoId}_${lang}`);
+    const outTemplate = join(PATHS.subtitlesDir, `${todayDateStr()}_${videoId}_${lang}`);
     // CSV is not a yt-dlp native format — download as VTT then convert
     const dlFormat = format === "csv" ? "vtt" : format;
     const result = await runYtDlp([
@@ -113,7 +227,7 @@ async function downloadSubtitle(videoId, lang, format) {
         const dir = PATHS.subtitlesDir;
         try {
             const files = readdirSync(dir);
-            const prefix = `${videoId}_${lang}`;
+            const prefix = `${todayDateStr()}_${videoId}_${lang}`;
             const match = files.find((f) => f.startsWith(prefix));
             if (match) {
                 foundFile = join(dir, match);
@@ -171,6 +285,17 @@ export function registerSubtitleTools(server, config, tokenManager) {
         const videoId = resolveVideoInput(video);
         if (!videoId)
             return toolErr("INVALID_INPUT", `无法解析视频 ID: ${video}`);
+        // Cookie pre-check: missing or expired → try headless refresh
+        if (!hasSIDCookies(PATHS.cookiesTxt) || areCookiesExpired(PATHS.cookiesTxt)) {
+            let refreshed = false;
+            try {
+                refreshed = await tryHeadlessRefresh();
+            }
+            catch { /* */ }
+            if (!refreshed || !hasSIDCookies(PATHS.cookiesTxt)) {
+                return toolErr("COOKIES_MISSING", "No valid YouTube cookies found.\nPlease run in your terminal: yt-mcp setup-cookies");
+            }
+        }
         const usingDefaults = !languages;
         const langs = languages ?? config.default_languages;
         const fmt = format ?? "vtt";
@@ -182,7 +307,30 @@ export function registerSubtitleTools(server, config, tokenManager) {
             const lang = langs[i];
             const dl = await downloadSubtitle(videoId, lang, fmt);
             if (dl.cookiesExpired) {
-                return toolErr("COOKIES_EXPIRED", "YouTube cookies have expired. Run: npx @mkterswingman/yt-mcp setup-cookies");
+                // Try headless auto-refresh
+                let refreshed = false;
+                try {
+                    refreshed = await tryHeadlessRefresh();
+                }
+                catch {
+                    // Playwright not available or browser failed — fall through
+                }
+                if (refreshed) {
+                    // Retry the download with fresh cookies
+                    const retry = await downloadSubtitle(videoId, lang, fmt);
+                    if (retry.ok) {
+                        if (retry.text) {
+                            results.push({ language: lang, status: "ok", text: retry.text, file_path: retry.filePath });
+                        }
+                        else {
+                            results.push({ language: lang, status: "ok", file_path: retry.filePath });
+                        }
+                        continue;
+                    }
+                    // Retry also failed with expired cookies — give up
+                }
+                return toolErr("COOKIES_EXPIRED", "YouTube cookies have expired and auto-refresh failed.\n" +
+                    "Please run in your terminal: yt-mcp setup-cookies");
             }
             if (!dl.ok) {
                 // When using default languages, silently skip unavailable ones
@@ -235,9 +383,16 @@ export function registerSubtitleTools(server, config, tokenManager) {
         }
         const langs = languages ?? config.default_languages;
         const fmt = format ?? "vtt";
-        // Cookie pre-check
-        if (!hasSIDCookies(PATHS.cookiesTxt)) {
-            return toolErr("COOKIES_MISSING", "No valid YouTube cookies found. Run: npx @mkterswingman/yt-mcp setup-cookies");
+        // Cookie pre-check: missing or expired → try headless refresh
+        if (!hasSIDCookies(PATHS.cookiesTxt) || areCookiesExpired(PATHS.cookiesTxt)) {
+            let refreshed = false;
+            try {
+                refreshed = await tryHeadlessRefresh();
+            }
+            catch { /* */ }
+            if (!refreshed || !hasSIDCookies(PATHS.cookiesTxt)) {
+                return toolErr("COOKIES_MISSING", "No valid YouTube cookies found.\nPlease run in your terminal: yt-mcp setup-cookies");
+            }
         }
         const results = [];
         let succeeded = 0;
@@ -267,7 +422,30 @@ export function registerSubtitleTools(server, config, tokenManager) {
                 }
             }
             if (cookiesExpired) {
-                return toolErr("COOKIES_EXPIRED", "YouTube cookies have expired. Run: npx @mkterswingman/yt-mcp setup-cookies");
+                // Try headless auto-refresh
+                let refreshed = false;
+                try {
+                    refreshed = await tryHeadlessRefresh();
+                }
+                catch { /* fall through */ }
+                if (refreshed) {
+                    // Retry this video's subtitles
+                    let retrySuccess = false;
+                    for (const lang of langs) {
+                        const retry = await downloadSubtitle(videoId, lang, fmt);
+                        if (retry.ok) {
+                            langFound.push(lang);
+                            retrySuccess = true;
+                        }
+                    }
+                    if (retrySuccess) {
+                        cookiesExpired = false;
+                    }
+                }
+                if (cookiesExpired) {
+                    return toolErr("COOKIES_EXPIRED", "YouTube cookies have expired and auto-refresh failed.\n" +
+                        "Please run in your terminal: yt-mcp setup-cookies");
+                }
             }
             if (langFound.length > 0) {
                 succeeded++;

package/dist/utils/cookieRefresh.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Headless cookie auto-refresh.
+ *
+ * Uses Playwright to open YouTube in a headless browser with the existing
+ * browser-profile. If Google session is still valid, YouTube cookies are
+ * extracted and saved automatically — no user interaction needed.
+ *
+ * If Google session has expired too, returns false so the caller can
+ * prompt the user for interactive login.
+ */
+/**
+ * Attempt to refresh YouTube cookies headlessly using existing browser profile.
+ *
+ * @returns true if cookies were refreshed, false if Google session expired
+ *          (needs interactive login).
+ * @throws if Playwright is not installed or browser can't launch.
+ */
+export declare function tryHeadlessRefresh(): Promise<boolean>;

package/dist/utils/cookieRefresh.js

@@ -0,0 +1,70 @@
+/**
+ * Headless cookie auto-refresh.
+ *
+ * Uses Playwright to open YouTube in a headless browser with the existing
+ * browser-profile. If Google session is still valid, YouTube cookies are
+ * extracted and saved automatically — no user interaction needed.
+ *
+ * If Google session has expired too, returns false so the caller can
+ * prompt the user for interactive login.
+ */
+import { existsSync } from "node:fs";
+import { PATHS, ensureConfigDir } from "./config.js";
+import { detectBrowserChannel, hasYouTubeSession, saveCookiesToDisk, } from "../cli/setupCookies.js";
+const HEADLESS_TIMEOUT_MS = 30_000;
+/**
+ * Attempt to refresh YouTube cookies headlessly using existing browser profile.
+ *
+ * @returns true if cookies were refreshed, false if Google session expired
+ *          (needs interactive login).
+ * @throws if Playwright is not installed or browser can't launch.
+ */
+export async function tryHeadlessRefresh() {
+    // No browser profile = never logged in = can't refresh
+    if (!existsSync(PATHS.browserProfile)) {
+        return false;
+    }
+    ensureConfigDir();
+    // Dynamic import to keep serve startup fast
+    let chromium;
+    try {
+        const pw = await import("playwright");
+        chromium = pw.chromium;
+    }
+    catch {
+        return false; // Playwright not installed — can't refresh
+    }
+    const channel = await detectBrowserChannel(chromium);
+    let context;
+    try {
+        context = await chromium.launchPersistentContext(PATHS.browserProfile, {
+            headless: true,
+            channel,
+            args: ["--disable-blink-features=AutomationControlled"],
+        });
+    }
+    catch {
+        return false; // Browser launch failed
+    }
+    try {
+        const page = context.pages()[0] ?? (await context.newPage());
+        await page.goto("https://www.youtube.com", { timeout: HEADLESS_TIMEOUT_MS });
+        await page.waitForLoadState("domcontentloaded");
+        const cookies = await context.cookies("https://www.youtube.com");
+        if (!hasYouTubeSession(cookies)) {
+            // Google session expired — can't auto-refresh
+            await context.close().catch(() => { });
+            return false;
+        }
+        // Wait a moment for all cookies to settle
+        await new Promise((r) => setTimeout(r, 1500));
+        const finalCookies = await context.cookies("https://www.youtube.com");
+        saveCookiesToDisk(finalCookies);
+        await context.close().catch(() => { });
+        return true;
+    }
+    catch {
+        await context.close().catch(() => { });
+        return false;
+    }
+}

package/dist/utils/cookies.d.ts

@@ -9,3 +9,10 @@ export interface CookieEntry {
 }
 export declare function cookiesToNetscape(cookies: CookieEntry[]): string;
 export declare function hasSIDCookies(cookiesPath: string): boolean;
+/**
+ * Check if YouTube session cookies have expired by parsing Netscape cookie
+ * file timestamps (field 5, Unix epoch seconds).
+ *
+ * Returns true if: file missing, no session cookies, or ALL session cookies expired.
+ */
+export declare function areCookiesExpired(cookiesPath: string): boolean;

package/dist/utils/cookies.js

@@ -26,3 +26,53 @@ export function hasSIDCookies(cookiesPath) {
         return false;
     }
 }
+/**
+ * Cookie names that indicate a valid YouTube session.
+ * If at least one of these is present and not expired, cookies are valid.
+ */
+const SESSION_COOKIE_PATTERNS = [
+    "SID", "HSID", "SSID", "APISID", "SAPISID",
+    "__Secure-1PSID", "__Secure-3PSID",
+    "__Secure-1PSIDTS", "__Secure-3PSIDTS",
+    "LOGIN_INFO",
+];
+/**
+ * Check if YouTube session cookies have expired by parsing Netscape cookie
+ * file timestamps (field 5, Unix epoch seconds).
+ *
+ * Returns true if: file missing, no session cookies, or ALL session cookies expired.
+ */
+export function areCookiesExpired(cookiesPath) {
+    if (!existsSync(cookiesPath))
+        return true;
+    try {
+        const content = readFileSync(cookiesPath, "utf8");
+        const nowSec = Date.now() / 1000;
+        let foundAnySession = false;
+        let foundAnyValid = false;
+        for (const line of content.split("\n")) {
+            if (line.startsWith("#") || !line.trim())
+                continue;
+            const fields = line.split("\t");
+            if (fields.length < 7)
+                continue;
+            const name = fields[5];
+            if (!SESSION_COOKIE_PATTERNS.includes(name))
+                continue;
+            foundAnySession = true;
+            const expiry = Number(fields[4]);
+            // expiry 0 = session cookie (no expiration) — treat as valid
+            if (expiry === 0 || expiry >= nowSec) {
+                foundAnyValid = true;
+                break; // At least one valid session cookie — not expired
+            }
+        }
+        // No session cookies at all = need login; all expired = need refresh
+        if (!foundAnySession)
+            return true;
+        return !foundAnyValid;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/utils/ytdlpPath.d.ts

@@ -18,5 +18,9 @@ export interface YtDlpVersionInfo {
 /**
  * Get the version string and source of the resolved yt-dlp binary.
  * Returns null if yt-dlp is not available at all.
+ *
+ * Uses a 30s timeout because macOS Gatekeeper performs a network verification
+ * on first run of ad-hoc signed binaries (~15-20s). The result is cached by
+ * the OS, so subsequent calls return instantly.
  */
 export declare function getYtDlpVersion(binPath?: string): YtDlpVersionInfo | null;

package/dist/utils/ytdlpPath.js

@@ -36,6 +36,10 @@ export function getYtDlpPath() {
 /**
  * Get the version string and source of the resolved yt-dlp binary.
  * Returns null if yt-dlp is not available at all.
+ *
+ * Uses a 30s timeout because macOS Gatekeeper performs a network verification
+ * on first run of ad-hoc signed binaries (~15-20s). The result is cached by
+ * the OS, so subsequent calls return instantly.
  */
 export function getYtDlpVersion(binPath) {
     const resolved = binPath ?? getYtDlpPath();
@@ -50,9 +54,19 @@ export function getYtDlpVersion(binPath) {
         source = "system";
     }
     try {
+        // macOS Gatekeeper: try clearing quarantine xattr before first execution.
+        // This helps in some environments; in others the OS re-applies it.
+        if (process.platform === "darwin" && resolved !== "yt-dlp") {
+            try {
+                execFileSync("xattr", ["-cr", resolved], { stdio: "ignore" });
+            }
+            catch {
+                // non-fatal
+            }
+        }
         const ver = execFileSync(resolved, ["--version"], {
             stdio: ["ignore", "pipe", "ignore"],
-            timeout: 10_000,
+            timeout: 30_000,
         })
             .toString()
             .trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/yt-mcp",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "YouTube MCP client — local subtitles + remote API proxy",
   "type": "module",
   "bin": {
@@ -17,10 +17,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "playwright": "^1.58.0",
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "playwright": "^1.58.0",
     "puppeteer-core": "^24.0.0"
   },
   "keywords": [

package/scripts/download-ytdlp.mjs

@@ -11,6 +11,7 @@
  */
 
 import { createWriteStream, chmodSync, mkdirSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { pipeline } from "node:stream/promises";
@@ -87,8 +88,11 @@ async function main() {
   mkdirSync(binDir, { recursive: true });
 
   const url = `${BASE_URL}/${remoteName}`;
-  console.log(`[yt-mcp] Downloading yt-dlp ${YT_DLP_VERSION} for ${key}...`);
-  console.log(`[yt-mcp]   ${url}`);
+  // Keep logs minimal — setup.ts controls user-facing output.
+  // These only show during direct `node scripts/download-ytdlp.mjs` or postinstall.
+  const verbose = !process.env.YT_MCP_QUIET;
+
+  if (verbose) console.log(`[yt-mcp] Downloading yt-dlp...`);
 
   try {
     await download(url, dest);
@@ -98,7 +102,28 @@ async function main() {
       chmodSync(dest, 0o755);
     }
 
-    console.log(`[yt-mcp] ✅ yt-dlp installed to ${dest}`);
+    // macOS Gatekeeper: clear quarantine/provenance xattr so Node.js
+    // execFileSync doesn't hang waiting for a UI prompt that never appears.
+    if (process.platform === "darwin") {
+      try {
+        execFileSync("xattr", ["-cr", dest], { stdio: "ignore" });
+      } catch {
+        // xattr may fail in sandboxed environments — non-fatal
+      }
+    }
+
+    // Pre-run to trigger macOS Gatekeeper verification and cache the result.
+    // First execution of an ad-hoc signed binary takes ~15-20s for the network
+    // check. Doing it here (during install) means setup/serve won't wait.
+    try {
+      execFileSync(dest, ["--version"], {
+        stdio: "ignore",
+        timeout: 60_000,
+      });
+      if (verbose) console.log(`[yt-mcp] ✅ yt-dlp ready`);
+    } catch {
+      if (verbose) console.log(`[yt-mcp] ✅ yt-dlp installed`);
+    }
   } catch (err) {
     console.error(`[yt-mcp] ⚠️  Failed to download yt-dlp: ${err.message}`);
     console.error(