@mkterswingman/5mghost-yonder 0.0.1 → 0.0.3

package/dist/runtime/manifest.js

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { PATHS } from "../utils/config.js";
+export function createEmptyRuntimeManifest() {
+    return {
+        schema_version: 1,
+        components: {},
+    };
+}
+export function loadRuntimeManifest(manifestPath = PATHS.runtimeManifestJson) {
+    if (!existsSync(manifestPath)) {
+        return createEmptyRuntimeManifest();
+    }
+    try {
+        const raw = readFileSync(manifestPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.schema_version !== 1 || parsed.components == null || typeof parsed.components !== "object") {
+            return createEmptyRuntimeManifest();
+        }
+        return {
+            schema_version: 1,
+            components: parsed.components,
+        };
+    }
+    catch {
+        return createEmptyRuntimeManifest();
+    }
+}
+export function saveRuntimeManifest(manifestPath = PATHS.runtimeManifestJson, manifest) {
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    const tempPath = `${manifestPath}.tmp`;
+    writeFileSync(tempPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    renameSync(tempPath, manifestPath);
+}
+export function updateRuntimeComponent(manifest, name, state) {
+    return {
+        schema_version: 1,
+        components: {
+            ...manifest.components,
+            [name]: state,
+        },
+    };
+}

package/dist/runtime/playwrightRuntime.d.ts

@@ -0,0 +1,13 @@
+import type { RuntimeComponentState } from "./manifest.js";
+export declare function checkPlaywrightRuntime(): Promise<RuntimeComponentState & {
+    name: "playwright";
+    message?: string;
+}>;
+export declare function installPlaywrightRuntime(): Promise<RuntimeComponentState & {
+    name: "playwright";
+    message?: string;
+}>;
+export declare function updatePlaywrightRuntime(): Promise<RuntimeComponentState & {
+    name: "playwright";
+    message?: string;
+}>;

package/dist/runtime/playwrightRuntime.js

@@ -0,0 +1,37 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+export async function checkPlaywrightRuntime() {
+    try {
+        const { chromium } = await import("playwright");
+        const executablePath = chromium.executablePath();
+        if (existsSync(executablePath)) {
+            return {
+                name: "playwright",
+                status: "installed",
+                version: executablePath.split("/").pop() ?? "chromium",
+                source: "runtime",
+                installed_at: null,
+                binary_path: executablePath,
+            };
+        }
+    }
+    catch {
+        // fall through to missing state
+    }
+    return {
+        name: "playwright",
+        status: "missing",
+        version: null,
+        source: "runtime",
+        installed_at: null,
+        binary_path: null,
+        message: "npx playwright install chromium",
+    };
+}
+export async function installPlaywrightRuntime() {
+    execSync("npx playwright install chromium", { stdio: "inherit" });
+    return checkPlaywrightRuntime();
+}
+export async function updatePlaywrightRuntime() {
+    return installPlaywrightRuntime();
+}

package/dist/runtime/systemDeps.d.ts

@@ -0,0 +1,3 @@
+export declare function hasCommand(name: string): boolean;
+export declare function getFfmpegInstallHint(platform?: NodeJS.Platform): string;
+export declare function getNodeInstallHint(platform?: NodeJS.Platform): string;

package/dist/runtime/systemDeps.js

@@ -0,0 +1,30 @@
+import { execSync } from "node:child_process";
+export function hasCommand(name) {
+    try {
+        execSync(`${name} --version`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getFfmpegInstallHint(platform = process.platform) {
+    switch (platform) {
+        case "darwin":
+            return "brew install ffmpeg";
+        case "win32":
+            return "winget install Gyan.FFmpeg";
+        default:
+            return "sudo apt update && sudo apt install -y ffmpeg";
+    }
+}
+export function getNodeInstallHint(platform = process.platform) {
+    switch (platform) {
+        case "darwin":
+            return "brew install node";
+        case "win32":
+            return "winget install OpenJS.NodeJS.LTS";
+        default:
+            return "sudo apt update && sudo apt install -y nodejs npm";
+    }
+}

package/dist/runtime/ytdlpRuntime.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeComponentState } from "./manifest.js";
+export declare function buildYtDlpInstallCommand(): string;
+export declare function checkYtDlpRuntime(): RuntimeComponentState & {
+    name: "yt-dlp";
+    message?: string;
+};
+export declare function installYtDlpRuntime(): Promise<RuntimeComponentState & {
+    name: "yt-dlp";
+    message?: string;
+}>;
+export declare function updateYtDlpRuntime(): Promise<RuntimeComponentState & {
+    name: "yt-dlp";
+    message?: string;
+}>;

package/dist/runtime/ytdlpRuntime.js

@@ -0,0 +1,58 @@
+import { execSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PATHS } from "../utils/config.js";
+import { getRuntimeYtDlpPath, getYtDlpVersion } from "../utils/ytdlpPath.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(__dirname, "..", "..");
+export function buildYtDlpInstallCommand() {
+    return "node scripts/download-ytdlp.mjs";
+}
+export function checkYtDlpRuntime() {
+    const runtimePath = getRuntimeYtDlpPath();
+    const runtimeInfo = getYtDlpVersion(runtimePath);
+    if (runtimeInfo) {
+        return {
+            name: "yt-dlp",
+            status: "installed",
+            version: runtimeInfo.version,
+            source: runtimeInfo.source,
+            installed_at: null,
+            binary_path: runtimePath,
+        };
+    }
+    const systemInfo = getYtDlpVersion("yt-dlp");
+    if (systemInfo) {
+        return {
+            name: "yt-dlp",
+            status: "installed",
+            version: systemInfo.version,
+            source: systemInfo.source,
+            installed_at: null,
+            binary_path: "yt-dlp",
+        };
+    }
+    return {
+        name: "yt-dlp",
+        status: "missing",
+        version: null,
+        source: "runtime",
+        installed_at: null,
+        binary_path: null,
+        message: "yt-mcp runtime install",
+    };
+}
+export async function installYtDlpRuntime() {
+    execSync(buildYtDlpInstallCommand(), {
+        cwd: pkgRoot,
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            YT_MCP_BINARY_DIR: PATHS.runtimeBinDir,
+        },
+    });
+    return checkYtDlpRuntime();
+}
+export async function updateYtDlpRuntime() {
+    return installYtDlpRuntime();
+}

package/dist/server.d.ts

@@ -1,6 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { YtMcpConfig } from "./utils/config.js";
 import type { TokenManager } from "./auth/tokenManager.js";
+import { DownloadJobManager } from "./download/jobManager.js";
+import type { DownloadToolDeps } from "./tools/downloads.js";
 /**
  * Creates the MCP server.
  *
@@ -18,4 +20,4 @@ import type { TokenManager } from "./auth/tokenManager.js";
  *                ├─ PAT login URL (user clicks to get token)
  *                └─ setup command (for full OAuth + cookies)
  */
-export declare function createServer(config: YtMcpConfig, tokenManager: TokenManager): Promise<McpServer>;
+export declare function createServer(config: YtMcpConfig, tokenManager: TokenManager, downloadJobManager?: DownloadJobManager, downloadToolDeps?: DownloadToolDeps): Promise<McpServer>;

package/dist/server.js

@@ -1,5 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DownloadJobManager } from "./download/jobManager.js";
 import { registerSubtitleTools } from "./tools/subtitles.js";
+import { registerDownloadTools } from "./tools/downloads.js";
 import { registerRemoteTools } from "./tools/remote.js";
 /**
  * Creates the MCP server.
@@ -18,7 +20,7 @@ import { registerRemoteTools } from "./tools/remote.js";
  *                ├─ PAT login URL (user clicks to get token)
  *                └─ setup command (for full OAuth + cookies)
  */
-export async function createServer(config, tokenManager) {
+export async function createServer(config, tokenManager, downloadJobManager = new DownloadJobManager(), downloadToolDeps = {}) {
     const server = new McpServer({
         name: "@mkterswingman/yt-mcp",
         version: "0.1.0",
@@ -74,6 +76,7 @@ export async function createServer(config, tokenManager) {
     }
     // Authenticated — register all tools
     registerSubtitleTools(server, config, tokenManager);
+    registerDownloadTools(server, config, tokenManager, downloadJobManager, downloadToolDeps);
     registerRemoteTools(server, config, tokenManager);
     return server;
 }

package/dist/tools/downloads.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { YtMcpConfig } from "../utils/config.js";
+import type { TokenManager } from "../auth/tokenManager.js";
+import { downloadOneItem } from "../download/downloader.js";
+import type { DownloadJobManager } from "../download/jobManager.js";
+export interface DownloadToolDeps {
+    executeItem?: typeof downloadOneItem;
+    mediaRootDir?: string;
+    nowDate?: () => string;
+}
+export declare function registerDownloadTools(server: McpServer, config: YtMcpConfig, tokenManager: TokenManager, manager: DownloadJobManager, deps?: DownloadToolDeps): void;

package/dist/tools/downloads.js

@@ -0,0 +1,220 @@
+import { z } from "zod";
+import { MEDIA_ROOT_DIR } from "../utils/config.js";
+import { downloadOneItem } from "../download/downloader.js";
+import { buildMediaOutputPaths } from "../utils/mediaPaths.js";
+import { resolveVideoInput } from "../utils/videoInput.js";
+const AUTH_REQUIRED_MSG = "❌ 未认证。请先登录：\n• OAuth: npx @mkterswingman/5mghost-yonder setup\n• PAT: 设置环境变量 YT_MCP_TOKEN 或在 https://mkterswingman.com/pat/login 生成 token";
+const DOWNLOAD_MODES = ["video", "subtitles", "both"];
+const VIDEO_QUALITIES = ["1080p", "max"];
+const SUBTITLE_FORMATS = ["vtt", "srt", "ttml", "srv3", "csv"];
+const MAX_DOWNLOAD_VIDEOS = 5;
+class DownloadToolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "DownloadToolError";
+    }
+}
+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 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}`;
+}
+function dedupeValues(values) {
+    return values == null ? undefined : [...new Set(values)];
+}
+function toSourceUrl(input, videoId) {
+    const trimmed = input.trim();
+    if (/^https?:\/\//u.test(trimmed)) {
+        return trimmed;
+    }
+    return `https://www.youtube.com/watch?v=${videoId}`;
+}
+function normalizeSubtitleFormats(mode, subtitleFormats) {
+    if (mode === "video") {
+        return [];
+    }
+    const normalized = dedupeValues(subtitleFormats) ?? ["srt"];
+    if (normalized.length === 0) {
+        throw new DownloadToolError("INVALID_INPUT", "subtitle_formats must include at least one format when mode includes subtitles");
+    }
+    return normalized;
+}
+function buildJobInput(videos, mode, videoQuality, subtitleFormats, deps) {
+    const invalidInputs = [];
+    const resolvedVideos = [];
+    const seenIds = new Set();
+    const dateStr = deps.nowDate?.() ?? todayDateStr();
+    const mediaRootDir = deps.mediaRootDir ?? MEDIA_ROOT_DIR;
+    for (const rawInput of videos) {
+        const videoId = resolveVideoInput(rawInput);
+        if (!videoId) {
+            invalidInputs.push(rawInput);
+            continue;
+        }
+        if (seenIds.has(videoId)) {
+            continue;
+        }
+        seenIds.add(videoId);
+        resolvedVideos.push({
+            video_id: videoId,
+            // Why: yt-dlp should keep the original URL when the user passed one so polls reflect the submitted source.
+            source_url: toSourceUrl(rawInput, videoId),
+            title: videoId,
+            output_dir: buildMediaOutputPaths(mediaRootDir, dateStr, videoId).outputDir,
+        });
+    }
+    if (resolvedVideos.length === 0) {
+        throw new DownloadToolError("INVALID_INPUT", `无法解析任何视频 ID。无效输入: ${invalidInputs.join(", ")}`);
+    }
+    return {
+        jobInput: {
+            videos: resolvedVideos,
+            mode,
+            video_quality: mode === "subtitles" ? undefined : videoQuality,
+            subtitle_formats: normalizeSubtitleFormats(mode, subtitleFormats),
+        },
+        invalidInputs,
+    };
+}
+async function runDownloadJob(manager, snapshot, subtitleLanguages, defaultSubtitleLanguages, deps) {
+    const executeItem = deps.executeItem ?? downloadOneItem;
+    for (const item of snapshot.items) {
+        try {
+            await executeItem({
+                jobManager: manager,
+                jobId: snapshot.job_id,
+                item,
+                mode: snapshot.mode,
+                videoQuality: snapshot.video_quality,
+                subtitleFormats: snapshot.subtitle_formats,
+                subtitleLanguages,
+                defaultSubtitleLanguages,
+            });
+        }
+        catch {
+            // downloadOneItem already records per-item failures in the manager.
+        }
+    }
+    const latest = manager.pollJob(snapshot.job_id);
+    if (latest.status !== "completed" && latest.status !== "failed") {
+        const stalledItems = latest.items.filter((item) => item.status === "queued");
+        for (const item of stalledItems) {
+            manager.failItem(snapshot.job_id, item.video_id, "Download job stopped before this item started");
+        }
+    }
+}
+export function registerDownloadTools(server, config, tokenManager, manager, deps = {}) {
+    const pendingJobs = [];
+    let draining = false;
+    async function requireAuth() {
+        const token = await tokenManager.getValidToken();
+        if (!token)
+            return AUTH_REQUIRED_MSG;
+        return null;
+    }
+    async function drainQueue() {
+        if (draining) {
+            return;
+        }
+        draining = true;
+        try {
+            while (pendingJobs.length > 0) {
+                const nextJob = pendingJobs.shift();
+                if (!nextJob) {
+                    continue;
+                }
+                await runDownloadJob(manager, nextJob.snapshot, nextJob.subtitleLanguages, nextJob.defaultSubtitleLanguages, deps);
+            }
+        }
+        finally {
+            draining = false;
+            if (pendingJobs.length > 0) {
+                void drainQueue();
+            }
+        }
+    }
+    function enqueueDownloadJob(snapshot, subtitleLanguages, defaultSubtitleLanguages) {
+        pendingJobs.push({
+            snapshot,
+            subtitleLanguages,
+            defaultSubtitleLanguages,
+        });
+        void drainQueue();
+    }
+    server.registerTool("start_download_job", {
+        description: "Start a local media download job for up to 5 YouTube videos. Supports video, subtitles, or both and returns a job snapshot for polling.",
+        inputSchema: {
+            videos: z.array(z.string().min(1)).min(1).max(MAX_DOWNLOAD_VIDEOS),
+            mode: z.enum(DOWNLOAD_MODES).optional(),
+            video_quality: z.enum(VIDEO_QUALITIES).optional(),
+            subtitle_formats: z.array(z.enum(SUBTITLE_FORMATS)).min(1).optional(),
+            subtitle_languages: z.array(z.string().min(1)).min(1).optional(),
+        },
+    }, async ({ videos, mode, video_quality, subtitle_formats, subtitle_languages }) => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        if (!Array.isArray(videos) || videos.length === 0) {
+            return toolErr("INVALID_INPUT", "videos must include at least one input");
+        }
+        try {
+            const resolvedMode = mode ?? "both";
+            const { jobInput, invalidInputs } = buildJobInput(videos, resolvedMode, video_quality, subtitle_formats, deps);
+            const snapshot = manager.createJob(jobInput);
+            enqueueDownloadJob(snapshot, dedupeValues(subtitle_languages), resolvedMode === "video" ? undefined : [...config.default_languages]);
+            const queuedSnapshot = manager.pollJob(snapshot.job_id);
+            return toolOk({
+                ...queuedSnapshot,
+                invalid_inputs: invalidInputs.length > 0 ? invalidInputs : undefined,
+            });
+        }
+        catch (error) {
+            if (error instanceof DownloadToolError) {
+                return toolErr(error.code, error.message);
+            }
+            return toolErr("INTERNAL_ERROR", error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("poll_download_job", {
+        description: "Poll a local media download job and return the current whole-job snapshot.",
+        inputSchema: {
+            job_id: z.string().min(1),
+        },
+    }, async ({ job_id }) => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        if (!job_id) {
+            return toolErr("INVALID_INPUT", "job_id is required");
+        }
+        try {
+            return toolOk(manager.pollJob(job_id));
+        }
+        catch (error) {
+            return toolErr("JOB_NOT_FOUND", error instanceof Error ? error.message : String(error));
+        }
+    });
+}

package/dist/tools/subtitles.d.ts

@@ -1,4 +1,29 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { YtMcpConfig } from "../utils/config.js";
 import type { TokenManager } from "../auth/tokenManager.js";
+export declare function toReadableSubtitleJobError(error: unknown): string;
+/**
+ * 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
+ */
+export declare function vttToCsv(vtt: string): string;
+export declare function downloadSubtitlesForLanguages(input: {
+    videoId: string;
+    sourceUrl?: string;
+    languages: string[];
+    formats: string[];
+    subtitlesDir: string;
+    skipMissingLanguages?: boolean;
+    onProgress?: (completed: number, total: number) => void;
+}): Promise<Record<string, string[]>>;
 export declare function registerSubtitleTools(server: McpServer, config: YtMcpConfig, tokenManager: TokenManager): void;