@mkterswingman/5mghost-yonder 0.0.1

package/dist/cli/setup.js

@@ -0,0 +1,318 @@
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig, saveConfig, PATHS, ensureConfigDir } from "../utils/config.js";
+import { TokenManager } from "../auth/tokenManager.js";
+import { runOAuthFlow } from "../auth/oauthFlow.js";
+import { hasSIDCookies } from "../utils/cookies.js";
+import { getYtDlpPath, getYtDlpVersion } from "../utils/ytdlpPath.js";
+import { buildLauncherCommand, writeLauncherFile } from "../utils/launcher.js";
+import { MCP_REGISTER_TIMEOUT_MS, classifyRegistrationFailure, } from "../utils/mcpRegistration.js";
+function detectCli(name) {
+    try {
+        execSync(`${name} --version`, { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function tryRegisterMcp(cmd, label) {
+    try {
+        execSync(cmd, { stdio: "pipe", timeout: MCP_REGISTER_TIMEOUT_MS });
+        console.log(`  ✅ MCP registered in ${label}`);
+        return true;
+    }
+    catch (err) {
+        const failure = classifyRegistrationFailure(err);
+        if (failure.kind === "already_exists") {
+            console.log(`  ✅ MCP already registered in ${label}`);
+            return true;
+        }
+        if (failure.kind === "authentication") {
+            console.log(`  ⚠️  ${label} is waiting for authentication — skipped auto-register.`);
+            return false;
+        }
+        if (failure.kind === "timeout") {
+            console.log(`  ⚠️  ${label} registration timed out after ${MCP_REGISTER_TIMEOUT_MS}ms — skipped auto-register.`);
+            return false;
+        }
+        return false;
+    }
+}
+function quoteForShell(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function quoteForCmd(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+function quoteArg(value) {
+    return process.platform === "win32" ? quoteForCmd(value) : quoteForShell(value);
+}
+/**
+ * Detect if we can open a browser (local machine with display).
+ * Cloud environments (SSH, Docker, cloud IDE) typically can't.
+ */
+function canOpenBrowser() {
+    // Explicit override
+    if (process.env.YT_MCP_NO_BROWSER === "1")
+        return false;
+    // Check for display (Linux/macOS GUI)
+    if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+        return false;
+    }
+    // Check if running in common cloud/container environments
+    if (process.env.CODESPACES || process.env.GITPOD_WORKSPACE_ID || process.env.CLOUD_SHELL) {
+        return false;
+    }
+    // Check if we have a TTY (interactive terminal) — headless environments often don't
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    return true;
+}
+function openUrl(url) {
+    try {
+        const cmd = process.platform === "darwin" ? `open "${url}"` :
+            process.platform === "win32" ? `start "${url}"` :
+                `xdg-open "${url}"`;
+        execSync(cmd, { stdio: "ignore" });
+    }
+    catch {
+        // Can't open — user will see the URL in console
+    }
+}
+/**
+ * Prompt user for input in terminal.
+ */
+function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+export async function runSetup() {
+    console.log("\n🚀 yt-mcp setup\n");
+    ensureConfigDir();
+    const hasBrowser = canOpenBrowser();
+    if (!hasBrowser) {
+        console.log("  ℹ️  Cloud/headless environment detected — using PAT mode\n");
+    }
+    // ── Step 1: Check 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(`  ✅ 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 {
+        // 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: "pipe",
+                env: { ...process.env, YT_MCP_QUIET: "1" },
+            });
+            const retryInfo = getYtDlpVersion();
+            if (retryInfo) {
+                console.log(`\r  ✅ Subtitle engine ready                `);
+            }
+            else {
+                console.log(`\r  ✅ Subtitle engine ready                `);
+            }
+        }
+        catch {
+            console.log(`\r  ⚠️  Subtitle engine setup failed — subtitles will be unavailable`);
+        }
+    }
+    // ── Step 2: Config ──
+    console.log("Step 2/5: Initializing config...");
+    const config = loadConfig();
+    saveConfig(config);
+    writeLauncherFile();
+    console.log(`  ✅ Config: ${PATHS.configJson}`);
+    console.log(`  ✅ Launcher: ${PATHS.launcherJs}`);
+    // ── Step 3: Authentication ──
+    console.log("Step 3/5: Authentication...");
+    const tokenManager = new TokenManager(config.auth_url);
+    const pat = process.env.YT_MCP_TOKEN;
+    if (pat) {
+        // Explicit PAT provided via env var
+        await tokenManager.savePAT(pat);
+        console.log("  ✅ PAT saved from YT_MCP_TOKEN");
+    }
+    else if (hasBrowser) {
+        // Local or cloud desktop — let user choose auth method
+        console.log("  请选择登录方式：");
+        console.log("  [1] OAuth 自动登录（推荐 — 自动弹出浏览器完成登录）");
+        console.log("  [2] PAT Token 登录（手动 — 在浏览器中生成 token 后粘贴）");
+        console.log("");
+        const choice = await prompt("  请输入 1 或 2 (默认 1): ");
+        const usePAT = choice === "2";
+        if (usePAT) {
+            // User chose PAT
+            const patUrl = `${config.auth_url}/pat/login`;
+            console.log("");
+            console.log(`  🔗 Opening PAT login page: ${patUrl}`);
+            openUrl(patUrl);
+            console.log("");
+            console.log("  请在浏览器中登录并生成 PAT token。");
+            const patInput = await prompt("  粘贴你的 PAT token (pat_xxx): ");
+            if (patInput) {
+                await tokenManager.savePAT(patInput);
+                console.log("  ✅ PAT saved");
+            }
+            else {
+                console.log("  ⚠️  未输入 token，稍后可通过环境变量配置：");
+                console.log('     "env": { "YT_MCP_TOKEN": "pat_xxx" }');
+            }
+        }
+        else {
+            // User chose OAuth (default)
+            console.log("");
+            console.log("  🌐 Opening browser for OAuth login...");
+            console.log("  ⚠️  如果你在云桌面上运行，请在云桌面的浏览器中完成登录！");
+            console.log("     在本地电脑打开链接将无法完成回调。");
+            try {
+                const tokens = await runOAuthFlow(config.auth_url);
+                await tokenManager.saveTokens(tokens.accessToken, tokens.refreshToken, tokens.expiresIn, tokens.clientId);
+                console.log("  ✅ OAuth login successful");
+            }
+            catch (err) {
+                // OAuth failed — auto fallback to PAT
+                console.log(`  ⚠️  OAuth failed: ${err instanceof Error ? err.message : String(err)}`);
+                console.log("");
+                console.log("  📋 Falling back to PAT login...");
+                const patUrl = `${config.auth_url}/pat/login`;
+                console.log(`  🔗 Opening PAT login page: ${patUrl}`);
+                openUrl(patUrl);
+                console.log("");
+                const patInput = await prompt("  粘贴你的 PAT token (pat_xxx), 或直接回车跳过: ");
+                if (patInput) {
+                    await tokenManager.savePAT(patInput);
+                    console.log("  ✅ PAT saved");
+                }
+                else {
+                    console.log("  ⚠️  稍后可通过环境变量配置：");
+                    console.log('     "env": { "YT_MCP_TOKEN": "pat_xxx" }');
+                }
+            }
+        }
+    }
+    else {
+        // Cloud/headless — can't open browser, PAT only
+        const patUrl = `${config.auth_url}/pat/login`;
+        console.log(`  🔗 请在本地电脑浏览器中打开此链接获取 PAT token：`);
+        console.log(`     ${patUrl}`);
+        console.log("");
+        const patInput = await prompt("  粘贴你的 PAT token (pat_xxx), 或直接回车跳过: ");
+        if (patInput) {
+            await tokenManager.savePAT(patInput);
+            console.log("  ✅ PAT saved");
+        }
+        else {
+            console.log("  ⚠️  稍后可通过环境变量配置：");
+            console.log('     "env": { "YT_MCP_TOKEN": "pat_xxx" }');
+        }
+    }
+    // ── Step 4: YouTube Cookies ──
+    console.log("Step 4/5: YouTube cookies...");
+    if (!hasBrowser) {
+        console.log("  ⏭️  Skipped (no browser — subtitle features unavailable in cloud)");
+        console.log("  💡 Run on your local machine: npx @mkterswingman/5mghost-yonder setup-cookies");
+    }
+    else if (hasSIDCookies(PATHS.cookiesTxt)) {
+        console.log("  ✅ Cookies already present");
+    }
+    else {
+        console.log("  🌐 Opening browser for YouTube login...");
+        console.log("  ⚠️  如果你在云桌面上运行，请在云桌面的浏览器窗口中登录 YouTube！");
+        console.log("  (Please log in to YouTube in the browser window)");
+        try {
+            const { runSetupCookies } = await import("./setupCookies.js");
+            await runSetupCookies();
+            console.log("  ✅ YouTube cookies saved");
+        }
+        catch (err) {
+            console.log(`  ⚠️  Cookie setup skipped: ${err instanceof Error ? err.message : String(err)}`);
+            console.log("  💡 Run later: npx @mkterswingman/5mghost-yonder setup-cookies");
+        }
+    }
+    // ── Step 5: MCP Registration ──
+    console.log("Step 5/5: Registering MCP in AI clients...");
+    const launcherCommand = buildLauncherCommand();
+    const mcpArgs = [launcherCommand.command, ...launcherCommand.args].map(quoteArg).join(" ");
+    let registered = false;
+    const cliCandidates = [
+        // 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 node <launcher> 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, 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) {
+        console.log("  ℹ️  No supported CLI found. Add manually to your AI client:");
+    }
+    // Always print manual config
+    console.log("");
+    console.log("  MCP config (for manual setup / other clients):");
+    console.log(`
+  {
+    "mcpServers": {
+      "yt-mcp": {
+        "command": "node",
+        "args": [${JSON.stringify(PATHS.launcherJs)}, "serve"]
+      }
+    }
+  }
+`);
+    console.log("✅ Setup complete!");
+    if (hasBrowser) {
+        console.log('   Open your AI client and try: "搜索 Python 教程"');
+    }
+    else {
+        console.log("   Set YT_MCP_TOKEN in your MCP env config, then restart your AI client.");
+    }
+    console.log("");
+}

package/dist/cli/setupCookies.d.ts

@@ -0,0 +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

@@ -0,0 +1,196 @@
+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.
+ */
+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
+        }
+    }
+    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 context.close();
+    }
+    catch { /* already closed */ }
+    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 });
+    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/5mghost-yonder 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/5mghost-yonder setup-cookies\n");
+        return;
+    }
+    await saveCookiesAndClose(context, finalCookies);
+}

package/dist/server.d.ts

@@ -0,0 +1,21 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { YtMcpConfig } from "./utils/config.js";
+import type { TokenManager } from "./auth/tokenManager.js";
+/**
+ * Creates the MCP server.
+ *
+ * Authentication flow:
+ *
+ *   serve startup
+ *     │
+ *     ├─ YT_MCP_TOKEN env var? ──▶ PAT mode ──▶ full server (19 tools)
+ *     │
+ *     ├─ auth.json exists? ──▶ JWT mode ──▶ full server (19 tools)
+ *     │
+ *     └─ no token? ──▶ register "setup_required" tool only
+ *           │
+ *           └─ AI calls setup_required ──▶ returns:
+ *                ├─ PAT login URL (user clicks to get token)
+ *                └─ setup command (for full OAuth + cookies)
+ */
+export declare function createServer(config: YtMcpConfig, tokenManager: TokenManager): Promise<McpServer>;

package/dist/server.js

@@ -0,0 +1,79 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerSubtitleTools } from "./tools/subtitles.js";
+import { registerRemoteTools } from "./tools/remote.js";
+/**
+ * Creates the MCP server.
+ *
+ * Authentication flow:
+ *
+ *   serve startup
+ *     │
+ *     ├─ YT_MCP_TOKEN env var? ──▶ PAT mode ──▶ full server (19 tools)
+ *     │
+ *     ├─ auth.json exists? ──▶ JWT mode ──▶ full server (19 tools)
+ *     │
+ *     └─ no token? ──▶ register "setup_required" tool only
+ *           │
+ *           └─ AI calls setup_required ──▶ returns:
+ *                ├─ PAT login URL (user clicks to get token)
+ *                └─ setup command (for full OAuth + cookies)
+ */
+export async function createServer(config, tokenManager) {
+    const server = new McpServer({
+        name: "@mkterswingman/yt-mcp",
+        version: "0.1.0",
+    });
+    const token = await tokenManager.getValidToken();
+    if (!token) {
+        // Not authenticated — register guidance tool only
+        server.registerTool("setup_required", {
+            description: "yt-mcp is not configured yet. Call this to get setup instructions for the user.",
+        }, async () => {
+            // Try to auto-open PAT login page in browser
+            const patUrl = `${config.auth_url}/pat/login`;
+            let opened = false;
+            try {
+                const { exec } = await import("node:child_process");
+                const cmd = process.platform === "darwin" ? `open "${patUrl}"` :
+                    process.platform === "win32" ? `start "${patUrl}"` :
+                        `xdg-open "${patUrl}"`;
+                exec(cmd);
+                opened = true;
+            }
+            catch { /* can't open browser, fall through */ }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "🔧 **yt-mcp 需要登录才能使用**",
+                            "",
+                            opened
+                                ? `✅ 已自动打开登录页面: ${patUrl}`
+                                : `请在浏览器中打开: ${patUrl}`,
+                            "",
+                            "⚠️ **云桌面用户注意：** 如果你在云桌面（如 Win 云桌面版 OpenClaw）上运行，",
+                            "请在 **云桌面的浏览器** 中完成登录，不要在本地电脑打开链接（回调地址是云桌面的 localhost）。",
+                            "",
+                            "**登录步骤：**",
+                            "1. 用 Google 账号登录（首次需要邀请码，已有 x-mcp 账号可跳过）",
+                            "2. 生成 PAT token（和 x-mcp 通用，已有可跳过）",
+                            "3. 将 token 配置到 MCP：",
+                            '   在 MCP 配置中添加 `"env": { "YT_MCP_TOKEN": "pat_xxx" }`',
+                            "4. 重启 AI 客户端",
+                            "",
+                            "**完整设置（含字幕功能）：**",
+                            "在终端运行：`npx @mkterswingman/5mghost-yonder setup`",
+                            "这会同时设置 OAuth 登录和 YouTube cookie（字幕下载需要）",
+                        ].join("\n"),
+                    },
+                ],
+            };
+        });
+        return server;
+    }
+    // Authenticated — register all tools
+    registerSubtitleTools(server, config, tokenManager);
+    registerRemoteTools(server, config, tokenManager);
+    return server;
+}

package/dist/tools/remote.d.ts

@@ -0,0 +1,4 @@
+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 registerRemoteTools(server: McpServer, config: YtMcpConfig, tokenManager: TokenManager): void;