@mkterswingman/5mghost-yonder 0.0.38 → 0.0.40

package/dist/cli/index.js

@@ -28,6 +28,7 @@ Commands:
   setup-cookies  Refresh YouTube cookies using browser login
   runtime        Manage required runtimes
   check          Check auth, runtime, cookies, and connectivity
+  doctor         Alias for check; diagnose local install and runtime health
   uninstall      Remove MCP registrations and local yt-mcp config
   update         Update the main package and required runtimes
   version        Show current version
@@ -70,6 +71,13 @@ export async function runUnifiedUpdate(deps) {
 const command = process.argv[2];
 async function main() {
     switch (command) {
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h": {
+            console.log(buildHelpText(getVersion()));
+            break;
+        }
         case "setup": {
             const { runSetup } = await import("./setup.js");
             await runSetup();
@@ -118,6 +126,11 @@ async function main() {
             await runCheck();
             break;
         }
+        case "doctor": {
+            const { runCheck } = await import("./check.js");
+            await runCheck();
+            break;
+        }
         case "update": {
             const current = getVersion();
             console.log(`Current version: ${current}`);
@@ -165,7 +178,7 @@ async function main() {
         }
         default:
             console.log(buildHelpText(getVersion()));
-            process.exit(command ? 1 : 0);
+            process.exit(1);
     }
 }
 main().catch((err) => {

package/dist/cli/installSkills.js

@@ -2,6 +2,8 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { buildSkillInstallPlan, installSkillTarget, } from "@mkterswingman/5mghost-shared-client/registration";
 import { detectCli } from "@mkterswingman/5mghost-shared-client";
+import { getWorkBuddySkillsDir, isWorkBuddyInstallLikelyInstalled } from "../utils/workBuddy.js";
+import { getCodeBuddySkillsDir, isCodeBuddyInstallLikelyInstalled } from "../utils/codeBuddy.js";
 function resolvePackageRoot() {
     return join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 }
@@ -19,6 +21,22 @@ export async function runInstallSkills() {
         availableCliNames,
         includeOpenClaw: process.env.YT_MCP_INSTALL_OPENCLAW_SKILL === "1",
     });
+    if (isWorkBuddyInstallLikelyInstalled() && !plan.some((target) => target.client === "workbuddy")) {
+        plan.push({
+            client: "workbuddy",
+            label: "WorkBuddy",
+            sourceDir: join(packageRoot, "skills", "use-yt-mcp"),
+            targetDir: join(getWorkBuddySkillsDir(), "use-yt-mcp"),
+        });
+    }
+    if (isCodeBuddyInstallLikelyInstalled() && !plan.some((target) => target.client === "codebuddy")) {
+        plan.push({
+            client: "codebuddy",
+            label: "CodeBuddy",
+            sourceDir: join(packageRoot, "skills", "use-yt-mcp"),
+            targetDir: join(getCodeBuddySkillsDir(), "use-yt-mcp"),
+        });
+    }
     if (plan.length === 0) {
         console.log("[yt-mcp] No supported AI client detected for bundled skill install.");
         return;

package/dist/cli/setup.js

@@ -7,6 +7,8 @@ import { runOAuthFlow } from "@mkterswingman/5mghost-shared-client/auth";
 import { hasSIDCookies } from "../utils/cookies.js";
 import { buildLauncherCommand, writeLauncherFile } from "../utils/launcher.js";
 import { buildBrowserOpenCommand } from "../utils/browserLaunch.js";
+import { getWorkBuddyConfigPath, isWorkBuddyInstallLikelyInstalled, writeWorkBuddyConfig, } from "../utils/workBuddy.js";
+import { getCodeBuddyConfigPath, isCodeBuddyInstallLikelyInstalled, writeCodeBuddyConfig, } from "../utils/codeBuddy.js";
 import { checkAll } from "../runtime/installers.js";
 import { runInstallSkills } from "./installSkills.js";
 import { registerCliCandidates, registerOpenClaw, } from "@mkterswingman/5mghost-shared-client/registration";
@@ -400,6 +402,28 @@ export async function runSetup() {
             console.log(`  ⚠️  Codex CLI (internal) auto-register failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    if (isWorkBuddyInstallLikelyInstalled(getWorkBuddyConfigPath())) {
+        try {
+            const status = writeWorkBuddyConfig("yt-mcp", launcherCommand);
+            const suffix = status === "created" ? "created" : "updated";
+            console.log(`  ✅ MCP registered in WorkBuddy (${suffix} ${getWorkBuddyConfigPath()})`);
+            registered = true;
+        }
+        catch (err) {
+            console.log(`  ⚠️  WorkBuddy auto-register failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (isCodeBuddyInstallLikelyInstalled(getCodeBuddyConfigPath())) {
+        try {
+            const status = writeCodeBuddyConfig("yt-mcp", launcherCommand);
+            const suffix = status === "created" ? "created" : "updated";
+            console.log(`  ✅ MCP registered in CodeBuddy (${suffix} ${getCodeBuddyConfigPath()})`);
+            registered = true;
+        }
+        catch (err) {
+            console.log(`  ⚠️  CodeBuddy auto-register failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     let skillsInstalled = false;
     try {
         process.env.YT_MCP_INSTALL_OPENCLAW_SKILL = isOpenClawInstallLikelyInstalled(detectCli) ? "1" : "0";
@@ -441,6 +465,8 @@ export async function runSetup() {
     console.log("  OpenClaw stdio CLI (recommended):");
     console.log(`  mcporter config add yt-mcp --command node --arg ${JSON.stringify(PATHS.launcherJs)} --arg serve`);
     console.log(`  OpenClaw uses ${PATHS.sharedAuthJson} for PAT/JWT, so env.YT_MCP_TOKEN is optional after setup.`);
+    console.log(`  WorkBuddy MCP config: ${getWorkBuddyConfigPath()}`);
+    console.log(`  CodeBuddy MCP config: ${getCodeBuddyConfigPath()}`);
     if (skillsInstalled) {
         console.log("  ✅ Installed bundled yt-mcp analysis skill for detected AI clients");
     }

package/dist/cli/setupCookies.d.ts

@@ -76,9 +76,6 @@ export declare function readCdpCookiesUntilSession(client: CdpCookieClient, deps
 export declare function tryImportBrowserCookies(chromium: SetupCookiesChromium, deps: SetupCookiesDeps): Promise<boolean>;
 export declare function readImportedBrowserCookies(candidate: BrowserProfileCandidate, chromium: SetupCookiesChromium, deps: SetupCookiesDeps): Promise<PlaywrightCookie[] | null>;
 export declare function runManualCookieSetup(chromium: SetupCookiesChromium, deps: SetupCookiesDeps): Promise<void>;
-/**
- * Interactive cookie setup — opens a visible browser for user to log in.
- */
-export declare function parseSetupCookiesArgs(argv: string[]): void;
+export declare function parseSetupCookiesArgs(argv: string[], warn?: (message: string) => void): void;
 export declare function runSetupCookies(overrides?: Partial<SetupCookiesDeps>): Promise<void>;
 export {};

package/dist/cli/setupCookies.js

@@ -412,9 +412,22 @@ export async function runManualCookieSetup(chromium, deps) {
 /**
  * Interactive cookie setup — opens a visible browser for user to log in.
  */
-export function parseSetupCookiesArgs(argv) {
+const LEGACY_SETUP_COOKIES_FLAGS = new Set(["--import-only", "--headed"]);
+export function parseSetupCookiesArgs(argv, warn = console.warn) {
+    const legacyFlags = [];
     for (const arg of argv) {
-        throw new Error(`Unknown option for setup-cookies: ${arg}. setup-cookies accepts no options.`);
+        if (LEGACY_SETUP_COOKIES_FLAGS.has(arg)) {
+            if (!legacyFlags.includes(arg)) {
+                legacyFlags.push(arg);
+            }
+            continue;
+        }
+        throw new Error(`Unknown option for setup-cookies: ${arg}. Supported legacy flags: --import-only, --headed.`);
+    }
+    if (legacyFlags.length > 0) {
+        warn(`[DEPRECATED] setup-cookies now runs a single guided flow. ` +
+            `Ignoring legacy flags: ${legacyFlags.join(", ")}. ` +
+            `Please run: yt-mcp setup-cookies`);
     }
 }
 export async function runSetupCookies(overrides = {}) {

package/dist/cli/uninstall.js

@@ -1,6 +1,8 @@
 import { execFileSync, spawn } from "node:child_process";
 import { existsSync, rmSync } from "node:fs";
 import { PATHS } from "../utils/config.js";
+import { getWorkBuddyConfigPath, removeWorkBuddyConfig } from "../utils/workBuddy.js";
+import { getCodeBuddyConfigPath, removeCodeBuddyConfig } from "../utils/codeBuddy.js";
 import { getOpenClawConfigPath, getCodexInternalConfigPath, removeCodexInternalConfig, unregisterOpenClaw, detectCli, } from "@mkterswingman/5mghost-shared-client";
 import { unregisterCliCandidates } from "@mkterswingman/5mghost-shared-client/registration";
 function tryRemoveMcp(command, label) {
@@ -72,6 +74,20 @@ export async function runUninstall() {
             console.log("  ℹ️  Codex CLI (internal) did not have yt-mcp registered");
         }
     }
+    const workBuddyStatus = removeWorkBuddyConfig("yt-mcp");
+    if (workBuddyStatus === "removed") {
+        console.log(`  ✅ Removed MCP registration from WorkBuddy (${getWorkBuddyConfigPath()})`);
+    }
+    else {
+        console.log("  ℹ️  WorkBuddy did not have yt-mcp registered");
+    }
+    const codeBuddyStatus = removeCodeBuddyConfig("yt-mcp");
+    if (codeBuddyStatus === "removed") {
+        console.log(`  ✅ Removed MCP registration from CodeBuddy (${getCodeBuddyConfigPath()})`);
+    }
+    else {
+        console.log("  ℹ️  CodeBuddy did not have yt-mcp registered");
+    }
     if (existsSync(PATHS.configDir)) {
         // Why: ~/.yt-mcp contains launcher, token cache, cookies, and npm cache owned by this package.
         rmSync(PATHS.configDir, { recursive: true, force: true });

package/dist/contracts/youtubeToolContracts.d.ts

@@ -0,0 +1,17 @@
+export type YouTubeToolHttpMethod = "GET" | "POST";
+export interface YouTubeToolAliasContract {
+    name: string;
+    remove_after_version: string;
+    remove_after_date: string;
+    note: string;
+}
+export interface YouTubeToolContract {
+    id: string;
+    remote_tool_name: string;
+    mcp_primary_name: string;
+    mcp_aliases: YouTubeToolAliasContract[];
+    http_path: string;
+    http_method: YouTubeToolHttpMethod;
+}
+export declare const YOUTUBE_TOOL_CONTRACTS: YouTubeToolContract[];
+export declare function getYouTubeToolContractById(id: string): YouTubeToolContract;

package/dist/contracts/youtubeToolContracts.js

@@ -0,0 +1,189 @@
+// AUTO-GENERATED by scripts/sync-youtube-tool-contracts.mjs
+// Source of truth: contracts/youtube-tool-contracts.json
+// Do not edit manually.
+export const YOUTUBE_TOOL_CONTRACTS = [
+    {
+        "id": "search_videos",
+        "remote_tool_name": "search_videos",
+        "mcp_primary_name": "search_videos",
+        "mcp_aliases": [],
+        "http_path": "/api/search",
+        "http_method": "POST"
+    },
+    {
+        "id": "get_video_stats",
+        "remote_tool_name": "get_video_stats",
+        "mcp_primary_name": "get_video_stats",
+        "mcp_aliases": [
+            {
+                "name": "get_video_stats_bulk_sync",
+                "remove_after_version": "0.2.0",
+                "remove_after_date": "2026-12-31",
+                "note": "Legacy name kept for backward compatibility."
+            }
+        ],
+        "http_path": "/api/video-stats/bulk",
+        "http_method": "POST"
+    },
+    {
+        "id": "start_video_stats_job",
+        "remote_tool_name": "start_video_stats_job",
+        "mcp_primary_name": "start_video_stats_job",
+        "mcp_aliases": [],
+        "http_path": "/api/video-stats/job/start",
+        "http_method": "POST"
+    },
+    {
+        "id": "poll_video_stats_job",
+        "remote_tool_name": "poll_video_stats_job",
+        "mcp_primary_name": "poll_video_stats_job",
+        "mcp_aliases": [],
+        "http_path": "/api/video-stats/job/poll",
+        "http_method": "POST"
+    },
+    {
+        "id": "resume_video_stats_job",
+        "remote_tool_name": "resume_video_stats_job",
+        "mcp_primary_name": "resume_video_stats_job",
+        "mcp_aliases": [],
+        "http_path": "/api/video-stats/job/resume",
+        "http_method": "POST"
+    },
+    {
+        "id": "get_trending",
+        "remote_tool_name": "get_trending",
+        "mcp_primary_name": "get_trending",
+        "mcp_aliases": [
+            {
+                "name": "get_trending_videos",
+                "remove_after_version": "0.2.0",
+                "remove_after_date": "2026-12-31",
+                "note": "Legacy name kept for backward compatibility."
+            }
+        ],
+        "http_path": "/api/trending",
+        "http_method": "POST"
+    },
+    {
+        "id": "search_channels",
+        "remote_tool_name": "search_channels",
+        "mcp_primary_name": "search_channels",
+        "mcp_aliases": [],
+        "http_path": "/api/channel/search",
+        "http_method": "POST"
+    },
+    {
+        "id": "get_channel_stats",
+        "remote_tool_name": "get_channel_stats",
+        "mcp_primary_name": "get_channel_stats",
+        "mcp_aliases": [],
+        "http_path": "/api/channel/stats",
+        "http_method": "POST"
+    },
+    {
+        "id": "list_channel_uploads",
+        "remote_tool_name": "list_channel_uploads",
+        "mcp_primary_name": "list_channel_uploads",
+        "mcp_aliases": [],
+        "http_path": "/api/channel/uploads",
+        "http_method": "POST"
+    },
+    {
+        "id": "get_comments",
+        "remote_tool_name": "get_comments",
+        "mcp_primary_name": "get_comments",
+        "mcp_aliases": [
+            {
+                "name": "get_video_comments_sync",
+                "remove_after_version": "0.2.0",
+                "remove_after_date": "2026-12-31",
+                "note": "Legacy name kept for backward compatibility."
+            }
+        ],
+        "http_path": "/api/comments/sync",
+        "http_method": "POST"
+    },
+    {
+        "id": "start_comments_job",
+        "remote_tool_name": "start_comments_job",
+        "mcp_primary_name": "start_comments_job",
+        "mcp_aliases": [
+            {
+                "name": "start_comments_export_job",
+                "remove_after_version": "0.2.0",
+                "remove_after_date": "2026-12-31",
+                "note": "Legacy name kept for backward compatibility."
+            }
+        ],
+        "http_path": "/api/comments/start",
+        "http_method": "POST"
+    },
+    {
+        "id": "poll_comments_job",
+        "remote_tool_name": "poll_comments_job",
+        "mcp_primary_name": "poll_comments_job",
+        "mcp_aliases": [
+            {
+                "name": "poll_comments_export_job",
+                "remove_after_version": "0.2.0",
+                "remove_after_date": "2026-12-31",
+                "note": "Legacy name kept for backward compatibility."
+            }
+        ],
+        "http_path": "/api/comments/poll",
+        "http_method": "POST"
+    },
+    {
+        "id": "resume_comments_job",
+        "remote_tool_name": "resume_comments_job",
+        "mcp_primary_name": "resume_comments_job",
+        "mcp_aliases": [
+            {
+                "name": "resume_comments_export_job",
+                "remove_after_version": "0.2.0",
+                "remove_after_date": "2026-12-31",
+                "note": "Legacy name kept for backward compatibility."
+            }
+        ],
+        "http_path": "/api/comments/resume",
+        "http_method": "POST"
+    },
+    {
+        "id": "get_comment_replies",
+        "remote_tool_name": "get_comment_replies",
+        "mcp_primary_name": "get_comment_replies",
+        "mcp_aliases": [
+            {
+                "name": "get_comment_replies_sync",
+                "remove_after_version": "0.2.0",
+                "remove_after_date": "2026-12-31",
+                "note": "Legacy name kept for backward compatibility."
+            }
+        ],
+        "http_path": "/api/comments/replies",
+        "http_method": "POST"
+    },
+    {
+        "id": "get_quota_usage",
+        "remote_tool_name": "get_quota_usage",
+        "mcp_primary_name": "get_quota_usage",
+        "mcp_aliases": [],
+        "http_path": "/api/quota",
+        "http_method": "POST"
+    },
+    {
+        "id": "get_patch_notes",
+        "remote_tool_name": "get_patch_notes",
+        "mcp_primary_name": "get_patch_notes",
+        "mcp_aliases": [],
+        "http_path": "/api/patch-notes",
+        "http_method": "GET"
+    }
+];
+export function getYouTubeToolContractById(id) {
+    const match = YOUTUBE_TOOL_CONTRACTS.find((tool) => tool.id === id);
+    if (!match) {
+        throw new Error(`Unknown YouTube tool contract id: ${id}`);
+    }
+    return match;
+}

package/dist/server.d.ts

@@ -3,6 +3,7 @@ import type { YtMcpConfig } from "./utils/config.js";
 import type { TokenManager } from "@mkterswingman/5mghost-shared-client/auth";
 import { DownloadJobManager } from "./download/jobManager.js";
 import type { DownloadToolDeps } from "./tools/downloads.js";
+import { type ToolTelemetryDeps } from "./telemetry.js";
 /**
  * Creates the MCP server.
  *
@@ -20,4 +21,4 @@ import type { DownloadToolDeps } from "./tools/downloads.js";
  *                ├─ PAT login URL (user clicks to get token)
  *                └─ setup command (for full OAuth + cookies)
  */
-export declare function createServer(config: YtMcpConfig, tokenManager: TokenManager, downloadJobManager?: DownloadJobManager, downloadToolDeps?: DownloadToolDeps): Promise<McpServer>;
+export declare function createServer(config: YtMcpConfig, tokenManager: TokenManager, downloadJobManager?: DownloadJobManager, downloadToolDeps?: DownloadToolDeps, telemetryDeps?: ToolTelemetryDeps): Promise<McpServer>;

package/dist/server.js

@@ -3,6 +3,8 @@ import { DownloadJobManager } from "./download/jobManager.js";
 import { registerSubtitleTools } from "./tools/subtitles.js";
 import { registerDownloadTools } from "./tools/downloads.js";
 import { registerRemoteTools } from "./tools/remote.js";
+import { ToolTelemetryClient } from "./telemetry.js";
+import { buildBrowserOpenCommand } from "./utils/browserLaunch.js";
 /**
  * Creates the MCP server.
  *
@@ -20,7 +22,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, downloadJobManager = new DownloadJobManager(), downloadToolDeps = {}) {
+export async function createServer(config, tokenManager, downloadJobManager = new DownloadJobManager(), downloadToolDeps = {}, telemetryDeps = {}) {
     const server = new McpServer({
         name: "@mkterswingman/yt-mcp",
         version: "0.1.0",
@@ -73,9 +75,29 @@ export async function createServer(config, tokenManager, downloadJobManager = ne
         return server;
     }
     // Authenticated — register all tools
-    registerSubtitleTools(server, config, tokenManager);
-    registerDownloadTools(server, config, tokenManager, downloadJobManager, downloadToolDeps);
-    registerRemoteTools(server, config, tokenManager);
+    const telemetry = new ToolTelemetryClient(config, tokenManager, telemetryDeps);
+    const instrumentedServer = withToolTelemetry(server, telemetry);
+    registerSubtitleTools(instrumentedServer, config, tokenManager);
+    registerDownloadTools(instrumentedServer, config, tokenManager, downloadJobManager, downloadToolDeps);
+    registerRemoteTools(instrumentedServer, config, tokenManager);
     return server;
 }
-import { buildBrowserOpenCommand } from "./utils/browserLaunch.js";
+function withToolTelemetry(server, telemetry) {
+    const originalRegisterTool = server.registerTool.bind(server);
+    const instrumented = Object.create(server);
+    instrumented.registerTool = ((name, config, handler) => {
+        return originalRegisterTool(name, config, async (...args) => {
+            const startedAtMs = Date.now();
+            try {
+                const result = await handler(...args);
+                telemetry.recordToolCall({ toolName: name, startedAtMs, result: result });
+                return result;
+            }
+            catch (error) {
+                telemetry.recordToolCall({ toolName: name, startedAtMs, thrown: error });
+                throw error;
+            }
+        });
+    });
+    return instrumented;
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,64 @@
+import type { TokenManager } from "@mkterswingman/5mghost-shared-client/auth";
+import type { YtMcpConfig } from "./utils/config.js";
+type ToolOutcome = "success" | "failure";
+type ErrorKind = "validation" | "auth" | "upstream" | "rate_limit" | "internal";
+export interface ToolTelemetryEvent {
+    schema_version: 1;
+    event_id: string;
+    occurred_at: string;
+    product: string;
+    product_version: string;
+    install_id: string;
+    event_type: "tool_call";
+    tool_name: string;
+    outcome: ToolOutcome;
+    duration_ms: number;
+    error_kind?: ErrorKind;
+    error_code?: string;
+    error_message?: string;
+}
+interface ToolResultLike {
+    isError?: boolean;
+    structuredContent?: unknown;
+}
+interface FetchLike {
+    (input: string | URL, init?: RequestInit): Promise<Response>;
+}
+interface TelemetryLogger {
+    warn(event: string, data?: Record<string, unknown>): void;
+}
+export interface ToolTelemetryDeps {
+    fetchImpl?: FetchLike;
+    installId?: string;
+    logger?: TelemetryLogger;
+}
+export declare class ToolTelemetryClient {
+    private readonly config;
+    private readonly tokenManager;
+    private readonly fetchImpl;
+    private readonly configuredInstallId;
+    private persistedInstallId;
+    private readonly logger;
+    constructor(config: Pick<YtMcpConfig, "auth_url" | "telemetry_enabled" | "telemetry_endpoint_url" | "telemetry_timeout_ms">, tokenManager: Pick<TokenManager, "getValidToken">, deps?: ToolTelemetryDeps);
+    recordToolCall(input: {
+        toolName: string;
+        startedAtMs: number;
+        result?: ToolResultLike;
+        thrown?: unknown;
+    }): void;
+    private getInstallId;
+    private send;
+}
+export declare function buildToolTelemetryEvent(input: {
+    toolName: string;
+    startedAtMs: number;
+    installId: string;
+    result?: ToolResultLike;
+    thrown?: unknown;
+}): ToolTelemetryEvent;
+export declare function classifyTelemetryError(result?: ToolResultLike, thrown?: unknown): {
+    kind: ErrorKind;
+    code: string;
+    message: string;
+} | null;
+export {};