@mkterswingman/yt-mcp 0.1.0

package/dist/tools/subtitles.js

@@ -0,0 +1,393 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+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 { 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) {
+    return {
+        structuredContent: payload,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload),
+            },
+        ],
+    };
+}
+function toolErr(code, message) {
+    const payload = { status: "failed", error: { code, message } };
+    return {
+        structuredContent: payload,
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+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"
+ */
+function vttToCsv(vtt) {
+    const lines = vtt.split("\n");
+    const rows = ["timestamp,text"];
+    let currentTimestamp = "";
+    let currentText = [];
+    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}"`);
+            }
+            currentTimestamp = trimmed;
+            currentText = [];
+        }
+        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 cue
+    if (currentTimestamp && currentText.length > 0) {
+        const text = currentText.join(" ").replace(/"/g, '""');
+        rows.push(`"${currentTimestamp}","${text}"`);
+    }
+    return rows.join("\n") + "\n";
+}
+async function downloadSubtitle(videoId, lang, format) {
+    mkdirSync(PATHS.subtitlesDir, { recursive: true });
+    const outTemplate = join(PATHS.subtitlesDir, `${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([
+        "--skip-download",
+        "--write-sub",
+        "--write-auto-sub",
+        "--sub-langs",
+        lang,
+        "--sub-format",
+        dlFormat,
+        "--output",
+        outTemplate,
+        `https://www.youtube.com/watch?v=${videoId}`,
+    ]);
+    if (result.exitCode !== 0 &&
+        (result.stderr.includes("Sign in") ||
+            result.stderr.includes("cookies") ||
+            result.stderr.includes("login"))) {
+        return { ok: false, cookiesExpired: true, error: "COOKIES_EXPIRED" };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            ok: false,
+            error: result.stderr.slice(0, 500) || `yt-dlp exited with ${result.exitCode}`,
+        };
+    }
+    // Find the output file - yt-dlp appends lang and format extension
+    const possibleExts = [`${lang}.${format}`, `${lang}.vtt`, `${lang}.srt`, `${lang}.ttml`, `${lang}.srv3`];
+    let foundFile;
+    for (const ext of possibleExts) {
+        const candidate = `${outTemplate}.${ext}`;
+        if (existsSync(candidate)) {
+            foundFile = candidate;
+            break;
+        }
+    }
+    if (!foundFile) {
+        // Try auto-generated subtitles which may have slightly different naming
+        const dir = PATHS.subtitlesDir;
+        try {
+            const files = readdirSync(dir);
+            const prefix = `${videoId}_${lang}`;
+            const match = files.find((f) => f.startsWith(prefix));
+            if (match) {
+                foundFile = join(dir, match);
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (!foundFile) {
+        return {
+            ok: false,
+            error: `No subtitle file found for language '${lang}'`,
+        };
+    }
+    // If CSV format requested, convert VTT to CSV (timestamp, text)
+    if (format === "csv") {
+        const vttContent = readFileSync(foundFile, "utf8");
+        const csvContent = vttToCsv(vttContent);
+        const csvPath = foundFile.replace(/\.vtt$/, ".csv");
+        writeFileSync(csvPath, csvContent, "utf8");
+        foundFile = csvPath;
+    }
+    const stat = statSync(foundFile);
+    if (stat.size <= 100 * 1024) {
+        const text = readFileSync(foundFile, "utf8");
+        return { ok: true, text, filePath: foundFile };
+    }
+    return { ok: true, filePath: foundFile };
+}
+export function registerSubtitleTools(server, config, tokenManager) {
+    /**
+     * Auth guard — every tool call must pass authentication.
+     * Both OAuth (JWT) and PAT modes are supported.
+     * Returns error message if not authenticated.
+     */
+    async function requireAuth() {
+        const token = await tokenManager.getValidToken();
+        if (!token)
+            return AUTH_REQUIRED_MSG;
+        return null;
+    }
+    // ── get_subtitles ──
+    server.registerTool("get_subtitles", {
+        description: "Download subtitles for a YouTube video. Accepts video ID or any YouTube URL (watch, shorts, youtu.be). Each language is fetched separately. Supports CSV output (timestamp + text columns).",
+        inputSchema: {
+            video: z.string().min(1).describe("YouTube video ID or URL"),
+            languages: z.array(z.string().min(1)).optional(),
+            format: z.enum(["vtt", "srt", "ttml", "srv3", "csv"]).optional(),
+        },
+    }, async ({ video, languages, format }) => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        const videoId = resolveVideoInput(video);
+        if (!videoId)
+            return toolErr("INVALID_INPUT", `无法解析视频 ID: ${video}`);
+        const langs = languages ?? config.default_languages;
+        const fmt = format ?? "vtt";
+        const results = [];
+        for (let i = 0; i < langs.length; i++) {
+            if (i > 0) {
+                await randomSleep(2000, 5000);
+            }
+            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");
+            }
+            if (!dl.ok) {
+                results.push({
+                    language: lang,
+                    status: "failed",
+                    error: dl.error,
+                });
+            }
+            else if (dl.text) {
+                results.push({
+                    language: lang,
+                    status: "ok",
+                    text: dl.text,
+                    file_path: dl.filePath,
+                });
+            }
+            else {
+                results.push({
+                    language: lang,
+                    status: "ok",
+                    file_path: dl.filePath,
+                });
+            }
+        }
+        return toolOk({
+            status: "completed",
+            video_id: videoId,
+            format: fmt,
+            results,
+        });
+    });
+    // ── batch_get_subtitles ──
+    server.registerTool("batch_get_subtitles", {
+        description: "Download subtitles for multiple YouTube videos. Max 10 per batch. Accepts video IDs or URLs (can mix).",
+        inputSchema: {
+            videos: z.array(z.string().min(1)).min(1).max(10).describe("Video IDs or YouTube URLs"),
+            languages: z.array(z.string().min(1)).optional(),
+            format: z.enum(["vtt", "srt", "ttml", "srv3", "csv"]).optional(),
+        },
+    }, async ({ videos, languages, format }) => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        const { resolvedIds, invalidInputs } = normalizeVideoInputs(videos);
+        if (resolvedIds.length === 0) {
+            return toolErr("INVALID_INPUT", `无法解析任何视频 ID。无效输入: ${invalidInputs.join(", ")}`);
+        }
+        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");
+        }
+        const results = [];
+        let succeeded = 0;
+        let failed = 0;
+        for (let v = 0; v < resolvedIds.length; v++) {
+            if (v > 0) {
+                await randomSleep(config.batch_sleep_min_ms, config.batch_sleep_max_ms);
+            }
+            const videoId = resolvedIds[v];
+            const langFound = [];
+            let lastError;
+            let cookiesExpired = false;
+            for (let l = 0; l < langs.length; l++) {
+                if (l > 0) {
+                    await randomSleep(2000, 5000);
+                }
+                const dl = await downloadSubtitle(videoId, langs[l], fmt);
+                if (dl.cookiesExpired) {
+                    cookiesExpired = true;
+                    break;
+                }
+                if (dl.ok) {
+                    langFound.push(langs[l]);
+                }
+                else {
+                    lastError = dl.error;
+                }
+            }
+            if (cookiesExpired) {
+                return toolErr("COOKIES_EXPIRED", "YouTube cookies have expired. Run: npx @mkterswingman/yt-mcp setup-cookies");
+            }
+            if (langFound.length > 0) {
+                succeeded++;
+                results.push({
+                    video_id: videoId,
+                    status: "ok",
+                    languages_found: langFound,
+                    file_path: PATHS.subtitlesDir,
+                });
+            }
+            else {
+                failed++;
+                results.push({
+                    video_id: videoId,
+                    status: "failed",
+                    error: lastError ?? "No subtitles found",
+                });
+            }
+        }
+        return toolOk({
+            status: "completed",
+            total: resolvedIds.length,
+            succeeded,
+            failed,
+            invalid_inputs: invalidInputs.length > 0 ? invalidInputs : undefined,
+            results,
+        });
+    });
+    // ── list_available_subtitles ──
+    server.registerTool("list_available_subtitles", {
+        description: "List available subtitle tracks for a YouTube video. Accepts video ID or URL.",
+        inputSchema: {
+            video: z.string().min(1).describe("YouTube video ID or URL"),
+        },
+    }, async ({ video }) => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        const videoId = resolveVideoInput(video);
+        if (!videoId)
+            return toolErr("INVALID_INPUT", `无法解析视频 ID: ${video}`);
+        const result = await runYtDlp([
+            "--list-subs",
+            "--skip-download",
+            `https://www.youtube.com/watch?v=${videoId}`,
+        ]);
+        if (result.exitCode !== 0) {
+            return toolErr("YT_DLP_ERROR", result.stderr.slice(0, 500) || "Failed to list subtitles");
+        }
+        const output = result.stdout;
+        const manual = [];
+        const automatic = [];
+        let section = "none";
+        for (const line of output.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.includes("Available subtitles") ||
+                trimmed.includes("manual subtitles")) {
+                section = "manual";
+                continue;
+            }
+            if (trimmed.includes("Available automatic captions") ||
+                trimmed.includes("automatic captions")) {
+                section = "auto";
+                continue;
+            }
+            if (!trimmed || trimmed.startsWith("Language") || trimmed.startsWith("---")) {
+                continue;
+            }
+            const langCode = trimmed.split(/\s+/)[0];
+            if (!langCode)
+                continue;
+            if (section === "manual")
+                manual.push(langCode);
+            else if (section === "auto")
+                automatic.push(langCode);
+        }
+        return toolOk({
+            status: "completed",
+            video_id: videoId,
+            manual,
+            automatic,
+            translatable: automatic,
+        });
+    });
+    // ── validate_cookies ──
+    server.registerTool("validate_cookies", {
+        description: "Validate current YouTube cookies by testing a subtitle download.",
+        inputSchema: {},
+    }, async () => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        if (!existsSync(PATHS.cookiesTxt)) {
+            return toolOk({
+                valid: false,
+                error: "cookies.txt not found",
+            });
+        }
+        if (!hasSIDCookies(PATHS.cookiesTxt)) {
+            return toolOk({
+                valid: false,
+                error: "cookies.txt does not contain YouTube SID cookies",
+            });
+        }
+        // Test with a known public video (Rick Astley - Never Gonna Give You Up)
+        const result = await runYtDlp([
+            "--skip-download",
+            "--write-auto-sub",
+            "--sub-langs",
+            "en",
+            "--sub-format",
+            "vtt",
+            "--output",
+            join(PATHS.subtitlesDir, "cookie_test"),
+            "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+        ]);
+        if (result.exitCode === 0) {
+            return toolOk({ valid: true });
+        }
+        const isExpired = result.stderr.includes("Sign in") ||
+            result.stderr.includes("cookies") ||
+            result.stderr.includes("login");
+        return toolOk({
+            valid: false,
+            error: isExpired
+                ? "Cookies expired"
+                : result.stderr.slice(0, 300),
+        });
+    });
+}

package/dist/utils/config.d.ts

@@ -0,0 +1,21 @@
+export declare const PATHS: {
+    configDir: string;
+    authJson: string;
+    cookiesTxt: string;
+    browserProfile: string;
+    subtitlesDir: string;
+    configJson: string;
+};
+export interface YtMcpConfig {
+    /** Auth gateway root URL — for OAuth, PAT, introspection (e.g., https://mkterswingman.com) */
+    auth_url: string;
+    /** v2 API URL — for data tools (e.g., https://mkterswingman.com/mcp/yt) */
+    api_url: string;
+    default_languages: string[];
+    batch_sleep_min_ms: number;
+    batch_sleep_max_ms: number;
+    batch_max_size: number;
+}
+export declare function ensureConfigDir(): void;
+export declare function loadConfig(): YtMcpConfig;
+export declare function saveConfig(config: Partial<YtMcpConfig>): void;

package/dist/utils/config.js

@@ -0,0 +1,43 @@
+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");
+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"),
+    configJson: join(CONFIG_DIR, "config.json"),
+};
+const DEFAULTS = {
+    auth_url: "https://mkterswingman.com",
+    api_url: "https://mkterswingman.com/mcp/yt",
+    default_languages: ["en"],
+    batch_sleep_min_ms: 3000,
+    batch_sleep_max_ms: 8000,
+    batch_max_size: 10,
+};
+export function ensureConfigDir() {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+}
+export function loadConfig() {
+    ensureConfigDir();
+    if (!existsSync(PATHS.configJson)) {
+        return { ...DEFAULTS };
+    }
+    try {
+        const raw = readFileSync(PATHS.configJson, "utf8");
+        const parsed = JSON.parse(raw);
+        return { ...DEFAULTS, ...parsed };
+    }
+    catch {
+        return { ...DEFAULTS };
+    }
+}
+export function saveConfig(config) {
+    ensureConfigDir();
+    const existing = loadConfig();
+    const merged = { ...existing, ...config };
+    writeFileSync(PATHS.configJson, JSON.stringify(merged, null, 2), "utf8");
+}

package/dist/utils/cookies.d.ts

@@ -0,0 +1,11 @@
+export interface CookieEntry {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    secure: boolean;
+    httpOnly: boolean;
+    expires: number;
+}
+export declare function cookiesToNetscape(cookies: CookieEntry[]): string;
+export declare function hasSIDCookies(cookiesPath: string): boolean;

package/dist/utils/cookies.js

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from "node:fs";
+export function cookiesToNetscape(cookies) {
+    const lines = [
+        "# Netscape HTTP Cookie File",
+        "# https://curl.haxx.se/rfc/cookie_spec.html",
+        "# This is a generated file!  Do not edit.",
+        "",
+    ];
+    for (const c of cookies) {
+        const domain = c.domain.startsWith(".") ? c.domain : c.domain;
+        const includeSubdomains = c.domain.startsWith(".") ? "TRUE" : "FALSE";
+        const secure = c.secure ? "TRUE" : "FALSE";
+        const expiry = Math.floor(c.expires);
+        lines.push(`${domain}\t${includeSubdomains}\t${c.path}\t${secure}\t${expiry}\t${c.name}\t${c.value}`);
+    }
+    return lines.join("\n") + "\n";
+}
+export function hasSIDCookies(cookiesPath) {
+    if (!existsSync(cookiesPath))
+        return false;
+    try {
+        const content = readFileSync(cookiesPath, "utf8");
+        return content.includes("SID") && content.includes(".youtube.com");
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/videoInput.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveVideoInput(input: string): string | null;
+export declare function normalizeVideoInputs(inputs: string[]): {
+    resolvedIds: string[];
+    invalidInputs: string[];
+};

package/dist/utils/videoInput.js

@@ -0,0 +1,55 @@
+const VIDEO_ID_RE = /^[A-Za-z0-9_-]{11}$/;
+function toValidVideoId(value) {
+    const v = value.trim();
+    return VIDEO_ID_RE.test(v) ? v : null;
+}
+function extractFromUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        return null;
+    }
+    const host = url.hostname.toLowerCase();
+    const normalizedHost = host.startsWith("www.") ? host.slice(4) : host;
+    if (normalizedHost === "youtu.be") {
+        const id = url.pathname.split("/").filter(Boolean)[0] ?? "";
+        return toValidVideoId(id);
+    }
+    if (normalizedHost === "youtube.com" || normalizedHost === "m.youtube.com") {
+        if (url.pathname === "/watch") {
+            return toValidVideoId(url.searchParams.get("v") ?? "");
+        }
+        const parts = url.pathname.split("/").filter(Boolean);
+        if (parts.length >= 2 && ["shorts", "live", "embed"].includes(parts[0])) {
+            return toValidVideoId(parts[1]);
+        }
+    }
+    return null;
+}
+export function resolveVideoInput(input) {
+    const candidate = input.trim();
+    if (!candidate) {
+        return null;
+    }
+    const directId = toValidVideoId(candidate);
+    return directId ?? extractFromUrl(candidate);
+}
+export function normalizeVideoInputs(inputs) {
+    const resolvedIds = [];
+    const invalidInputs = [];
+    const seen = new Set();
+    for (const raw of inputs) {
+        const parsedId = resolveVideoInput(raw);
+        if (!parsedId) {
+            invalidInputs.push(raw);
+            continue;
+        }
+        if (!seen.has(parsedId)) {
+            seen.add(parsedId);
+            resolvedIds.push(parsedId);
+        }
+    }
+    return { resolvedIds, invalidInputs };
+}

package/dist/utils/ytdlp.d.ts

@@ -0,0 +1,7 @@
+export interface YtDlpResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+}
+export declare function runYtDlp(args: string[], timeoutMs?: number): Promise<YtDlpResult>;

package/dist/utils/ytdlp.js

@@ -0,0 +1,51 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { PATHS } from "./config.js";
+export function runYtDlp(args, timeoutMs = 45_000) {
+    return new Promise((resolve, reject) => {
+        const start = Date.now();
+        const finalArgs = ["--force-ipv4", "--no-warnings", ...args];
+        if (existsSync(PATHS.cookiesTxt)) {
+            finalArgs.push("--cookies", PATHS.cookiesTxt);
+        }
+        const proc = spawn("yt-dlp", finalArgs, {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+        proc.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                proc.kill("SIGKILL");
+                resolve({
+                    exitCode: -1,
+                    stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                    stderr: `yt-dlp timed out after ${timeoutMs}ms`,
+                    durationMs: Date.now() - start,
+                });
+            }
+        }, timeoutMs);
+        proc.on("close", (code) => {
+            clearTimeout(timer);
+            if (!settled) {
+                settled = true;
+                resolve({
+                    exitCode: code ?? 1,
+                    stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                    stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                    durationMs: Date.now() - start,
+                });
+            }
+        });
+        proc.on("error", (err) => {
+            clearTimeout(timer);
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        });
+    });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mkterswingman/yt-mcp",
+  "version": "0.1.0",
+  "description": "YouTube MCP client — local subtitles + remote API proxy",
+  "type": "module",
+  "bin": {
+    "yt-mcp": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": "./dist/server.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli/index.ts",
+    "start": "node dist/cli/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "playwright": "^1.58.0",
+    "puppeteer-core": "^24.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "youtube",
+    "subtitles",
+    "yt-dlp"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}