@mkterswingman/5mghost-yonder 0.0.39 → 0.0.40

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 {};

package/dist/telemetry.js

@@ -0,0 +1,225 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { PATHS } from "./utils/config.js";
+const PRODUCT = "5mghost-yonder";
+const PRODUCT_VERSION = "0.0.40";
+const MAX_ERROR_CODE_CHARS = 64;
+export class ToolTelemetryClient {
+    config;
+    tokenManager;
+    fetchImpl;
+    configuredInstallId;
+    persistedInstallId;
+    logger;
+    constructor(config, tokenManager, deps = {}) {
+        this.config = config;
+        this.tokenManager = tokenManager;
+        this.fetchImpl = deps.fetchImpl ?? fetch;
+        this.configuredInstallId = deps.installId;
+        this.logger = deps.logger ?? { warn: () => { } };
+    }
+    recordToolCall(input) {
+        if (!this.config.telemetry_enabled) {
+            return;
+        }
+        const event = buildToolTelemetryEvent({
+            toolName: input.toolName,
+            startedAtMs: input.startedAtMs,
+            installId: this.getInstallId(),
+            result: input.result,
+            thrown: input.thrown,
+        });
+        setImmediate(() => {
+            void this.send(event);
+        });
+    }
+    getInstallId() {
+        if (this.configuredInstallId) {
+            return this.configuredInstallId;
+        }
+        this.persistedInstallId ??= getOrCreateInstallId();
+        return this.persistedInstallId;
+    }
+    async send(event) {
+        if (!isSameOrigin(this.config.telemetry_endpoint_url, this.config.auth_url)) {
+            this.logger.warn("yt_mcp_telemetry_same_origin_blocked", {
+                product: PRODUCT,
+                tool_name: event.tool_name,
+            });
+            return;
+        }
+        try {
+            const token = await this.tokenManager.getValidToken();
+            if (!token) {
+                return;
+            }
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.config.telemetry_timeout_ms);
+            timeout.unref?.();
+            try {
+                const response = await this.fetchImpl(this.config.telemetry_endpoint_url, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({ events: [event] }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    this.logger.warn("yt_mcp_telemetry_send_failed", {
+                        product: PRODUCT,
+                        tool_name: event.tool_name,
+                        status_code: response.status,
+                    });
+                }
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch (error) {
+            this.logger.warn("yt_mcp_telemetry_send_failed", {
+                product: PRODUCT,
+                tool_name: event.tool_name,
+                code: "TELEMETRY_NETWORK_ERROR",
+                message: error instanceof Error ? error.name : "UnknownError",
+            });
+        }
+    }
+}
+export function buildToolTelemetryEvent(input) {
+    const durationMs = Math.max(0, Math.round(Date.now() - input.startedAtMs));
+    const error = classifyTelemetryError(input.result, input.thrown);
+    const base = {
+        schema_version: 1,
+        event_id: `${PRODUCT}-${Date.now()}-${randomUUID()}`,
+        occurred_at: new Date().toISOString(),
+        product: PRODUCT,
+        product_version: PRODUCT_VERSION,
+        install_id: input.installId,
+        event_type: "tool_call",
+        tool_name: input.toolName,
+        duration_ms: durationMs,
+    };
+    if (!error) {
+        return {
+            ...base,
+            outcome: "success",
+        };
+    }
+    return {
+        ...base,
+        outcome: "failure",
+        error_kind: error.kind,
+        error_code: error.code,
+        error_message: error.message,
+    };
+}
+export function classifyTelemetryError(result, thrown) {
+    if (thrown) {
+        return {
+            kind: "internal",
+            code: "INTERNAL_ERROR",
+            message: "Tool handler threw an unexpected error",
+        };
+    }
+    if (!result?.isError) {
+        return null;
+    }
+    const error = readStructuredError(result.structuredContent);
+    const code = normalizeErrorCode(error.code);
+    return {
+        kind: classifyErrorKind(code),
+        code,
+        message: safeErrorMessage(code),
+    };
+}
+function readStructuredError(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { code: null };
+    }
+    const error = value.error;
+    if (!error || typeof error !== "object" || Array.isArray(error)) {
+        return { code: null };
+    }
+    const record = error;
+    return {
+        code: typeof record.code === "string" ? record.code : null,
+    };
+}
+function normalizeErrorCode(code) {
+    if (!code) {
+        return "UNKNOWN_ERROR";
+    }
+    const normalized = code.toUpperCase().replace(/[^A-Z0-9_.:-]/g, "_").slice(0, MAX_ERROR_CODE_CHARS);
+    return normalized || "UNKNOWN_ERROR";
+}
+function classifyErrorKind(code) {
+    if (code.includes("RATE_LIMIT") || code === "HTTP_429") {
+        return "rate_limit";
+    }
+    if (code.startsWith("AUTH") || code.includes("COOKIE") || code === "SIGN_IN_REQUIRED") {
+        return "auth";
+    }
+    if (code === "INVALID_INPUT" || code.includes("VALIDATION")) {
+        return "validation";
+    }
+    if (code.startsWith("REMOTE") || code.startsWith("UPSTREAM") || code.startsWith("HTTP_") || code === "NETWORK_ERROR") {
+        return "upstream";
+    }
+    return "internal";
+}
+function safeErrorMessage(code) {
+    const kind = classifyErrorKind(code);
+    if (kind === "rate_limit") {
+        return "Rate limit was reached";
+    }
+    if (kind === "auth") {
+        return "Authorization failed";
+    }
+    if (kind === "validation") {
+        return "Invalid input";
+    }
+    if (kind === "upstream") {
+        return "Remote tool request failed";
+    }
+    if (code === "NO_SUBTITLES") {
+        return "Requested subtitles were not found";
+    }
+    return "Tool call failed";
+}
+function isSameOrigin(endpoint, authUrl) {
+    try {
+        return new URL(endpoint).origin === new URL(authUrl).origin;
+    }
+    catch {
+        return false;
+    }
+}
+function getOrCreateInstallId() {
+    const path = join(PATHS.configDir, "telemetry.json");
+    try {
+        if (existsSync(path)) {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (typeof parsed.install_id === "string" && parsed.install_id.trim()) {
+                return parsed.install_id.trim();
+            }
+        }
+    }
+    catch {
+        // Why: telemetry must never block MCP tool registration on local state corruption.
+    }
+    const installId = `local-${randomUUID()}`;
+    try {
+        mkdirSync(PATHS.configDir, { recursive: true });
+        const tempPath = `${path}.tmp`;
+        writeFileSync(tempPath, JSON.stringify({ install_id: installId }, null, 2), { encoding: "utf8", mode: 0o600 });
+        renameSync(tempPath, path);
+    }
+    catch {
+        // Why: a read-only home directory should disable persistence, not MCP tools.
+    }
+    return installId;
+}

package/dist/utils/config.d.ts

@@ -47,6 +47,9 @@ export interface YtMcpConfig {
     batch_sleep_min_ms: number;
     batch_sleep_max_ms: number;
     batch_max_size: number;
+    telemetry_enabled: boolean;
+    telemetry_endpoint_url: string;
+    telemetry_timeout_ms: number;
 }
 export declare function ensureConfigDir(): void;
 export declare function loadConfig(): YtMcpConfig;

package/dist/utils/config.js

@@ -51,27 +51,87 @@ const DEFAULTS = {
     batch_sleep_min_ms: 3000,
     batch_sleep_max_ms: 8000,
     batch_max_size: 10,
+    telemetry_enabled: true,
+    telemetry_endpoint_url: "https://mkterswingman.com/telemetry/events",
+    telemetry_timeout_ms: 1500,
 };
 export function ensureConfigDir() {
     mkdirSync(PATHS.configDir, { recursive: true });
 }
 export function loadConfig() {
     ensureConfigDir();
+    let parsed = {};
     if (!existsSync(PATHS.configJson)) {
-        return { ...DEFAULTS };
+        return normalizeConfig(parsed);
     }
     try {
         const raw = readFileSync(PATHS.configJson, "utf8");
-        const parsed = JSON.parse(raw);
-        return { ...DEFAULTS, ...parsed };
+        parsed = JSON.parse(raw);
     }
     catch {
-        return { ...DEFAULTS };
+        parsed = {};
     }
+    return normalizeConfig(parsed);
 }
 export function saveConfig(config) {
     ensureConfigDir();
     const existing = loadConfig();
-    const merged = { ...existing, ...config };
+    const merged = normalizeConfig({ ...existing, ...config });
     writeFileSync(PATHS.configJson, JSON.stringify(merged, null, 2), "utf8");
 }
+function normalizeConfig(config) {
+    const authUrl = parseHttpUrl("auth_url", config.auth_url ?? DEFAULTS.auth_url);
+    const telemetryEndpointUrl = parseTelemetryEndpointUrl(authUrl, config.telemetry_endpoint_url);
+    return {
+        auth_url: authUrl,
+        api_url: parseHttpUrl("api_url", config.api_url ?? DEFAULTS.api_url),
+        default_languages: config.default_languages ?? DEFAULTS.default_languages,
+        batch_sleep_min_ms: config.batch_sleep_min_ms ?? DEFAULTS.batch_sleep_min_ms,
+        batch_sleep_max_ms: config.batch_sleep_max_ms ?? DEFAULTS.batch_sleep_max_ms,
+        batch_max_size: config.batch_max_size ?? DEFAULTS.batch_max_size,
+        telemetry_enabled: parseEnvBool("YT_MCP_TELEMETRY_ENABLED", config.telemetry_enabled ?? DEFAULTS.telemetry_enabled),
+        telemetry_endpoint_url: telemetryEndpointUrl,
+        telemetry_timeout_ms: parseEnvInt("YT_MCP_TELEMETRY_TIMEOUT_MS", config.telemetry_timeout_ms ?? DEFAULTS.telemetry_timeout_ms, 250, 10_000),
+    };
+}
+function parseHttpUrl(name, raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`${name} must be an absolute URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`${name} must start with http:// or https://`);
+    }
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+function parseTelemetryEndpointUrl(authUrl, configured) {
+    const endpoint = parseHttpUrl("telemetry_endpoint_url", process.env.YT_MCP_TELEMETRY_ENDPOINT_URL?.trim() || configured || `${authUrl}/telemetry/events`);
+    if (new URL(endpoint).origin !== new URL(authUrl).origin) {
+        throw new Error("telemetry_endpoint_url origin must match auth_url origin");
+    }
+    return endpoint;
+}
+function parseEnvBool(name, fallback) {
+    const raw = process.env[name]?.trim().toLowerCase();
+    if (!raw)
+        return fallback;
+    if (["1", "true", "yes", "on"].includes(raw))
+        return true;
+    if (["0", "false", "no", "off"].includes(raw))
+        return false;
+    return fallback;
+}
+function parseEnvInt(name, fallback, min, max) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, value));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-yonder",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "description": "Internal MCP client with local data tools and remote API proxy",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "test": "npm run build && node --test tests/*.test.mjs",
     "test:unit": "npm test",
     "test:tool": "npm run build && node --test tests/smoke.test.mjs tests/subtitleTools.test.mjs tests/downloadTools.test.mjs",
+    "test:mcp": "npm run test:tool",
     "test:smoke": "npm run build && node dist/cli/index.js --help && node dist/cli/index.js doctor",
     "test:clean-install": "npm run build && node scripts/clean-install-smoke.mjs",
     "prepublishOnly": "npm run build",