@mkterswingman/yt-mcp 0.2.1 → 0.3.0

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.js

@@ -1,9 +1,62 @@
 import { writeFileSync } from "node:fs";
 import { PATHS, ensureConfigDir } from "../utils/config.js";
 import { cookiesToNetscape } from "../utils/cookies.js";
+/**
+ * Detect which browser channel is available on the system.
+ * Prefers Chrome → Edge → falls back to bundled Chromium.
+ */
+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
+        }
+    }
+    return "chromium";
+}
+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. */
+function hasYouTubeSession(cookies) {
+    return cookies.some((c) => (c.name === "SID" || c.name === "HSID" || c.name === "SSID") &&
+        c.domain.includes("youtube.com"));
+}
+/**
+ * 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) {
+        // Detect if user closed the browser / all pages
+        if (isClosed()) {
+            return null;
+        }
+        try {
+            const cookies = await context.cookies("https://www.youtube.com");
+            if (hasYouTubeSession(cookies)) {
+                // Give a moment for all cookies to settle after login redirect
+                await new Promise((r) => setTimeout(r, 2000));
+                return await context.cookies("https://www.youtube.com");
+            }
+        }
+        catch {
+            // Browser was closed by user — bail out
+            return null;
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    return null; // timeout
+}
 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;
@@ -12,32 +65,111 @@ export async function runSetupCookies() {
         chromium = pw.chromium;
     }
     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",
-        ],
+        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;
+    }
+    // Graceful handling when user closes browser manually
+    let browserClosed = false;
+    context.on("close", () => {
+        browserClosed = true;
     });
     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");
+    // Also detect when user closes the page/window (not just the whole context)
+    page.on("close", () => {
+        // If no more pages remain, treat as browser closed
+        if (context.pages().length === 0) {
+            browserClosed = true;
+        }
+    });
+    // Navigate to YouTube first — familiar page for the user
     try {
-        await page.waitForURL("**/youtube.com/**", { timeout: 5 * 60 * 1000 });
-        // Wait a bit for cookies to settle
-        await page.waitForTimeout(3000);
+        await page.goto("https://www.youtube.com");
+        await page.waitForLoadState("domcontentloaded");
     }
     catch {
-        console.error("Timed out waiting for YouTube login.");
+        if (browserClosed) {
+            console.log("\n⚠️  Browser was closed. Setup cancelled.\n");
+            return;
+        }
+        throw new Error("Failed to navigate to YouTube");
+    }
+    // Check if already logged in (e.g., from a previous session in this profile)
+    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 to click the "Sign in" button on YouTube homepage
+    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 {
+        // Couldn't find sign-in button — navigate directly
+        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; // 2 minutes
+    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) {
+        // Timeout — clean up
+        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);
+}
+async function saveCookiesAndClose(context, rawCookies) {
+    try {
         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 +181,7 @@ export async function runSetupCookies() {
     }));
     const netscape = cookiesToNetscape(entries);
     writeFileSync(PATHS.cookiesTxt, netscape, { mode: 0o600 });
+    const httpOnlyCount = entries.filter((c) => c.httpOnly).length;
     console.log(`✅ Cookies saved to ${PATHS.cookiesTxt}`);
-    console.log(`   ${entries.length} cookies extracted\n`);
+    console.log(`   ${entries.length} cookies extracted (${httpOnlyCount} httpOnly)\n`);
 }

package/dist/tools/subtitles.js

@@ -32,43 +32,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)) {
-            // Strip HTML tags from subtitle text
-            const clean = trimmed.replace(/<[^>]*>/g, "");
-            if (clean)
-                currentText.push(clean);
+        else if (trimmed &&
+            !trimmed.startsWith("WEBVTT") &&
+            !trimmed.startsWith("Kind:") &&
+            !trimmed.startsWith("Language:") &&
+            !/^\d+$/.test(trimmed)) {
+            currentTextLines.push(trimmed);
         }
     }
-    // Flush last cue
-    if (currentTimestamp && currentText.length > 0) {
-        const text = currentText.join(" ").replace(/"/g, '""');
-        rows.push(`"${currentTimestamp}","${text}"`);
+    // 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 });
+    }
+    // ── 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 +226,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);

package/dist/utils/config.js

@@ -2,12 +2,13 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const CONFIG_DIR = join(homedir(), ".yt-mcp");
+const SUBTITLES_DIR = join(homedir(), "Downloads", "yt-mcp");
 export const PATHS = {
     configDir: CONFIG_DIR,
     authJson: join(CONFIG_DIR, "auth.json"),
     cookiesTxt: join(CONFIG_DIR, "cookies.txt"),
     browserProfile: join(CONFIG_DIR, "browser-profile"),
-    subtitlesDir: join(CONFIG_DIR, "subtitles"),
+    subtitlesDir: SUBTITLES_DIR,
     configJson: join(CONFIG_DIR, "config.json"),
 };
 const DEFAULTS = {

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.1",
+  "version": "0.3.0",
   "description": "YouTube MCP client — local subtitles + remote API proxy",
   "type": "module",
   "bin": {

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(