@thenavidm/youtube-mcp-cli 2.0.0

package/dist/youtube/ytdlp.js

@@ -0,0 +1,145 @@
+/**
+ * yt-dlp transport for caption tracks.
+ *
+ * As of 2026 YouTube answers a bare `timedtext` URL with 200 and an empty body
+ * unless the request carries a proof-of-origin token tied to a real player
+ * session. Scraping the watch page still lists which tracks exist, but it can
+ * no longer read their contents, so the track list and the track body now come
+ * from different places.
+ *
+ * yt-dlp already solves the hard half and is maintained against YouTube's
+ * changes far faster than this repo could be, so we shell out to it rather than
+ * reimplement token minting. It is an optional dependency: without it you can
+ * still list languages, and every other tool in this server is unaffected.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const BINARY = process.env.YOUTUBE_YTDLP_PATH?.trim() || "yt-dlp";
+export class YtDlpMissingError extends Error {
+    constructor() {
+        super("yt-dlp is not installed. Transcripts need it because YouTube no longer serves caption text directly. Install it with `brew install yt-dlp` (macOS) or `pipx install yt-dlp`, or set YOUTUBE_YTDLP_PATH to its location.");
+        this.name = "YtDlpMissingError";
+    }
+}
+function run(args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(BINARY, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(new Error(`yt-dlp timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            if (err.code === "ENOENT")
+                reject(new YtDlpMissingError());
+            else
+                reject(err);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+/** True when yt-dlp can actually be launched. Used by `doctor` and by tool errors. */
+export async function isAvailable() {
+    try {
+        const { code } = await run(["--version"], 10000);
+        return code === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** `en-orig` and `en-en` both just mean `en`. */
+function normalizeLang(code) {
+    const bare = code.replace(/-orig$/, "");
+    const halves = bare.split("-");
+    if (halves.length === 2 && halves[0] && halves[0].toLowerCase() === halves[1]?.toLowerCase()) {
+        return halves[0];
+    }
+    return bare;
+}
+function parseJson3(raw) {
+    const doc = JSON.parse(raw);
+    const out = [];
+    for (const ev of doc.events ?? []) {
+        const text = (ev.segs ?? [])
+            .map((s) => s.utf8 ?? "")
+            .join("")
+            .replace(/\s+/g, " ")
+            .trim();
+        // Auto-caption streams include empty timing events used for on-screen
+        // positioning. They carry no words and would show up as blank lines.
+        if (!text)
+            continue;
+        out.push({
+            start: (ev.tStartMs ?? 0) / 1000,
+            duration: (ev.dDurationMs ?? 0) / 1000,
+            text,
+        });
+    }
+    return out;
+}
+/**
+ * Download one caption track.
+ *
+ * `--sub-langs` accepts a glob, so `en.*` picks up `en`, `en-GB` and the
+ * auto-generated `en-orig` in one pass. We take whichever file lands and report
+ * the language from its name rather than assuming we got the exact code asked
+ * for.
+ */
+export async function fetchCaptions(videoId, language = "en", timeoutMs = 90000) {
+    const dir = await mkdtemp(join(tmpdir(), "youtube-mcp-"));
+    try {
+        const lang = language.includes("*") ? language : `${language}.*`;
+        const { code, stderr } = await run([
+            "--skip-download",
+            "--write-subs",
+            "--write-auto-subs",
+            "--sub-langs",
+            lang,
+            "--sub-format",
+            "json3",
+            "--no-warnings",
+            "--no-playlist",
+            "-o",
+            join(dir, "cap"),
+            `https://www.youtube.com/watch?v=${videoId}`,
+        ], timeoutMs);
+        const files = (await readdir(dir)).filter((f) => f.endsWith(".json3"));
+        if (files.length === 0) {
+            if (/HTTP Error 429|Too Many Requests/i.test(stderr)) {
+                throw new Error("YouTube is rate limiting this IP (HTTP 429). Wait a few minutes before retrying, or run with a proxy.");
+            }
+            if (/Sign in to confirm|bot/i.test(stderr)) {
+                throw new Error("YouTube asked yt-dlp to prove it is not a bot. Pass cookies with YOUTUBE_YTDLP_COOKIES, or retry later.");
+            }
+            throw new Error(code === 0
+                ? "No captions were downloaded. The video probably has none in that language."
+                : `yt-dlp failed: ${stderr.trim().split("\n").pop() ?? "unknown error"}`);
+        }
+        // Prefer a human-written track over the auto one when both arrive. yt-dlp
+        // names auto-generated files `<id>.<lang>-orig.json3`.
+        const chosen = files.find((f) => !f.includes("-orig.")) ?? files[0];
+        const raw = await readFile(join(dir, chosen), "utf8");
+        const matched = /\.([A-Za-z0-9-]+)\.json3$/.exec(chosen);
+        return {
+            segments: parseJson3(raw),
+            // yt-dlp writes variant tracks as `<lang>-<lang>` (e.g. `en-en`) and its
+            // auto track as `<lang>-orig`. Both mean the plain language to a caller.
+            language: normalizeLang(matched?.[1] ?? language),
+            autoGenerated: chosen.includes("-orig."),
+        };
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=ytdlp.js.map

package/dist/youtube/ytdlp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp.js","sourceRoot":"","sources":["../../src/youtube/ytdlp.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@thenavidm/youtube-mcp-cli",
+  "version": "2.0.0",
+  "description": "YouTube MCP server and CLI for Claude Code, Codex and AI agents. 16 tools for transcripts, search, channel research, comments, analytics and multi-channel management.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "youtube-mcp": "dist/index.js",
+    "youtube-cli": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "build:mcpb": "bash desktop-extension/build.sh",
+    "check:counts": "node scripts/check-counts.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "license": "MIT",
+  "author": "Navid Moazzez (https://navid.me)",
+  "homepage": "https://navid.me",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thenavidm/youtube-mcp-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thenavidm/youtube-mcp-cli/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "youtube",
+    "youtube-api",
+    "transcript",
+    "mcp-server",
+    "claude",
+    "claude-code",
+    "ai-agents",
+    "llm-tools",
+    "cli",
+    "youtube-cli"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md",
+    "LICENSE"
+  ]
+}