youtube-knowledge-mcp 2.0.2 → 2.1.0

package/dist/tools/brain-info.d.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Reading what a brain covers: which channels have one, and how much of each
+ * channel it actually reached.
+ */
+export declare const listBrainsSchema: {};
+export declare const listBrainsOutputSchema: {
+    total: z.ZodNumber;
+    count: z.ZodNumber;
+    offset: z.ZodNumber;
+    hasMore: z.ZodBoolean;
+    nextOffset: z.ZodOptional<z.ZodNumber>;
+    brains: z.ZodArray<z.ZodObject<{
+        channelId: z.ZodString;
+        name: z.ZodString;
+        handle: z.ZodString;
+        channelUrl: z.ZodString;
+        language: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        hasProfile: z.ZodBoolean;
+        videoCount: z.ZodNumber;
+        indexedCount: z.ZodNumber;
+        chunkCount: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        channelId: string;
+        handle: string;
+        channelUrl: string;
+        videoCount: number;
+        chunkCount: number;
+        indexedCount: number;
+        language: string;
+        createdAt: string;
+        updatedAt: string;
+        hasProfile: boolean;
+    }, {
+        name: string;
+        channelId: string;
+        handle: string;
+        channelUrl: string;
+        videoCount: number;
+        chunkCount: number;
+        indexedCount: number;
+        language: string;
+        createdAt: string;
+        updatedAt: string;
+        hasProfile: boolean;
+    }>, "many">;
+};
+export declare function listBrainsHandler(): Promise<CallToolResult>;
+export declare const getBrainInfoSchema: {
+    channel: z.ZodString;
+    includeVideos: z.ZodDefault<z.ZodBoolean>;
+};
+export declare const getBrainInfoOutputSchema: {
+    channelId: z.ZodString;
+    name: z.ZodString;
+    handle: z.ZodString;
+    channelUrl: z.ZodString;
+    language: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    hasProfile: z.ZodBoolean;
+    stats: z.ZodObject<{
+        videoCount: z.ZodNumber;
+        excludedCount: z.ZodNumber;
+        indexedCount: z.ZodNumber;
+        noCaptionsCount: z.ZodNumber;
+        failedCount: z.ZodNumber;
+        pendingCount: z.ZodNumber;
+        chunkCount: z.ZodNumber;
+        totalWords: z.ZodNumber;
+        medianWordsPerMinute: z.ZodNumber;
+        firstUpload: z.ZodOptional<z.ZodString>;
+        lastUpload: z.ZodOptional<z.ZodString>;
+        uploadsPerMonth: z.ZodArray<z.ZodObject<{
+            month: z.ZodString;
+            videos: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            month: string;
+            videos: number;
+        }, {
+            month: string;
+            videos: number;
+        }>, "many">;
+        recurringPhrases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            phrase: z.ZodString;
+            videoCount: z.ZodNumber;
+            occurrences: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }, {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        videoCount: number;
+        chunkCount: number;
+        excludedCount: number;
+        indexedCount: number;
+        noCaptionsCount: number;
+        failedCount: number;
+        pendingCount: number;
+        totalWords: number;
+        medianWordsPerMinute: number;
+        uploadsPerMonth: {
+            month: string;
+            videos: number;
+        }[];
+        firstUpload?: string | undefined;
+        lastUpload?: string | undefined;
+        recurringPhrases?: {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }[] | undefined;
+    }, {
+        videoCount: number;
+        chunkCount: number;
+        excludedCount: number;
+        indexedCount: number;
+        noCaptionsCount: number;
+        failedCount: number;
+        pendingCount: number;
+        totalWords: number;
+        medianWordsPerMinute: number;
+        uploadsPerMonth: {
+            month: string;
+            videos: number;
+        }[];
+        firstUpload?: string | undefined;
+        lastUpload?: string | undefined;
+        recurringPhrases?: {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }[] | undefined;
+    }>;
+    videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        videoId: z.ZodString;
+        title: z.ZodString;
+        url: z.ZodString;
+        uploadDate: z.ZodString;
+        durationSeconds: z.ZodNumber;
+        state: z.ZodEnum<["pending", "indexed", "no-captions", "failed", "excluded"]>;
+        chunkCount: z.ZodNumber;
+        wordCount: z.ZodNumber;
+        error: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        durationSeconds: number;
+        url: string;
+        uploadDate: string;
+        videoId: string;
+        state: "pending" | "indexed" | "no-captions" | "failed" | "excluded";
+        chunkCount: number;
+        wordCount: number;
+        error?: string | undefined;
+    }, {
+        title: string;
+        durationSeconds: number;
+        url: string;
+        uploadDate: string;
+        videoId: string;
+        state: "pending" | "indexed" | "no-captions" | "failed" | "excluded";
+        chunkCount: number;
+        wordCount: number;
+        error?: string | undefined;
+    }>, "many">>;
+};
+export declare function getBrainInfoHandler({ channel, includeVideos, }: {
+    channel: string;
+    includeVideos: boolean;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=brain-info.d.ts.map

package/dist/tools/brain-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-info.d.ts","sourceRoot":"","sources":["../../src/tools/brain-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAYzE;;;GAGG;AAIH,eAAO,MAAM,gBAAgB,IAAK,CAAC;AAEnC,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGlC,CAAC;AAEF,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC,CAgBjE;AAsBD,eAAO,MAAM,kBAAkB;;;CAM9B,CAAC;AAEF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAWpC,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,EACxC,OAAO,EACP,aAAa,GACd,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+D1B"}

package/dist/tools/brain-info.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { brainStatsSchema, brainSummarySchema, brainVideoStateSchema, } from '../brain-schemas.js';
+import { resolveBrain } from '../utils/brain-lookup.js';
+import { hasProfile, listManifests } from '../utils/brain-storage.js';
+import { pageInfo, toolResult } from '../utils/format.js';
+import { paginationShape } from '../schemas.js';
+/**
+ * Reading what a brain covers: which channels have one, and how much of each
+ * channel it actually reached.
+ */
+// -- list_brains ---------------------------------------------------------
+export const listBrainsSchema = {};
+export const listBrainsOutputSchema = {
+    brains: z.array(brainSummarySchema),
+    ...paginationShape,
+};
+export async function listBrainsHandler() {
+    const manifests = await listManifests();
+    const brains = manifests.map(summarize);
+    const lines = brains.length === 0
+        ? ['No brains have been built yet.', '', 'Call build_brain with a channel URL or handle.']
+        : brains.map((brain) => `${brain.name} (${brain.handle || brain.channelId}) — ${brain.indexedCount}/${brain.videoCount} videos, ${brain.chunkCount.toLocaleString()} passages, updated ${brain.updatedAt.slice(0, 10)}${brain.hasProfile ? ', has a profile' : ''}`);
+    return toolResult(lines.join('\n'), {
+        brains,
+        ...pageInfo(brains.length, brains.length),
+    });
+}
+function summarize(manifest) {
+    const { channelId, name, handle, channelUrl } = manifest.channel;
+    return {
+        channelId,
+        name,
+        handle,
+        channelUrl,
+        language: manifest.language,
+        createdAt: manifest.createdAt,
+        updatedAt: manifest.updatedAt,
+        hasProfile: hasProfile(channelId),
+        videoCount: manifest.stats.videoCount,
+        indexedCount: manifest.stats.indexedCount,
+        chunkCount: manifest.stats.chunkCount,
+    };
+}
+// -- get_brain_info ------------------------------------------------------
+export const getBrainInfoSchema = {
+    channel: z.string().describe('Channel URL, @handle, name, or channel id of an existing brain'),
+    includeVideos: z
+        .boolean()
+        .default(false)
+        .describe('List every video and its state. Long for a large channel. Default: false'),
+};
+export const getBrainInfoOutputSchema = {
+    channelId: z.string(),
+    name: z.string(),
+    handle: z.string(),
+    channelUrl: z.string(),
+    language: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    hasProfile: z.boolean(),
+    stats: brainStatsSchema,
+    videos: z.array(brainVideoStateSchema).optional(),
+};
+export async function getBrainInfoHandler({ channel, includeVideos, }) {
+    const manifest = await resolveBrain(channel);
+    const { channelId, name, handle, channelUrl } = manifest.channel;
+    const { stats } = manifest;
+    const videos = Object.values(manifest.videos);
+    const lines = [
+        `${name} (${handle || channelId})`,
+        `${stats.indexedCount} of ${stats.videoCount} videos indexed from ${manifest.language} captions · ${stats.chunkCount.toLocaleString()} passages · ${stats.totalWords.toLocaleString()} words`,
+        `${stats.medianWordsPerMinute} words per minute (median)`,
+        stats.firstUpload === undefined
+            ? 'No upload dates reported'
+            : `Uploads from ${stats.firstUpload} to ${stats.lastUpload ?? stats.firstUpload}`,
+        `Updated ${manifest.updatedAt}`,
+    ];
+    if (stats.noCaptionsCount > 0)
+        lines.push(`${stats.noCaptionsCount} videos have no captions`);
+    if (stats.excludedCount > 0) {
+        lines.push(`${stats.excludedCount} videos are outside the filters this brain was built with`);
+    }
+    if (stats.failedCount + stats.pendingCount > 0) {
+        lines.push(`${stats.failedCount + stats.pendingCount} videos still to read — call build_brain to continue`);
+    }
+    if (stats.recurringPhrases === undefined) {
+        lines.push('', 'Repeated phrases have not been measured yet — the last build did not finish. Call build_brain to complete it.');
+    }
+    else if (stats.recurringPhrases.length > 0) {
+        lines.push('', 'Phrases repeated across videos:', ...stats.recurringPhrases.map((entry) => `  "${entry.phrase}" — ${entry.videoCount} videos, ${entry.occurrences} times`));
+    }
+    if (includeVideos) {
+        lines.push('', ...videos.map((video) => `${video.state.padEnd(12)} ${video.uploadDate || '          '} ${video.title}${video.error === undefined ? '' : ` (${video.error})`}`));
+    }
+    return toolResult(lines.join('\n'), {
+        channelId,
+        name,
+        handle,
+        channelUrl,
+        language: manifest.language,
+        createdAt: manifest.createdAt,
+        updatedAt: manifest.updatedAt,
+        hasProfile: hasProfile(channelId),
+        stats,
+        ...(includeVideos ? { videos } : {}),
+    });
+}
+//# sourceMappingURL=brain-info.js.map

package/dist/tools/brain-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-info.js","sourceRoot":"","sources":["../../src/tools/brain-info.ts"],"names":[],"mappings":"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"}

package/dist/tools/build-brain.d.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const buildBrainSchema: {
+    channel: z.ZodString;
+    maxVideos: z.ZodDefault<z.ZodNumber>;
+    language: z.ZodDefault<z.ZodString>;
+    since: z.ZodOptional<z.ZodString>;
+    minDurationSeconds: z.ZodDefault<z.ZodNumber>;
+};
+export declare const buildBrainOutputSchema: {
+    channelId: z.ZodString;
+    name: z.ZodString;
+    handle: z.ZodString;
+    channelUrl: z.ZodString;
+    language: z.ZodString;
+    considered: z.ZodNumber;
+    processed: z.ZodNumber;
+    skipped: z.ZodNumber;
+    excluded: z.ZodNumber;
+    stoppedEarly: z.ZodBoolean;
+    stopReason: z.ZodOptional<z.ZodString>;
+    stats: z.ZodObject<{
+        videoCount: z.ZodNumber;
+        excludedCount: z.ZodNumber;
+        indexedCount: z.ZodNumber;
+        noCaptionsCount: z.ZodNumber;
+        failedCount: z.ZodNumber;
+        pendingCount: z.ZodNumber;
+        chunkCount: z.ZodNumber;
+        totalWords: z.ZodNumber;
+        medianWordsPerMinute: z.ZodNumber;
+        firstUpload: z.ZodOptional<z.ZodString>;
+        lastUpload: z.ZodOptional<z.ZodString>;
+        uploadsPerMonth: z.ZodArray<z.ZodObject<{
+            month: z.ZodString;
+            videos: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            month: string;
+            videos: number;
+        }, {
+            month: string;
+            videos: number;
+        }>, "many">;
+        recurringPhrases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            phrase: z.ZodString;
+            videoCount: z.ZodNumber;
+            occurrences: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }, {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        videoCount: number;
+        chunkCount: number;
+        excludedCount: number;
+        indexedCount: number;
+        noCaptionsCount: number;
+        failedCount: number;
+        pendingCount: number;
+        totalWords: number;
+        medianWordsPerMinute: number;
+        uploadsPerMonth: {
+            month: string;
+            videos: number;
+        }[];
+        firstUpload?: string | undefined;
+        lastUpload?: string | undefined;
+        recurringPhrases?: {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }[] | undefined;
+    }, {
+        videoCount: number;
+        chunkCount: number;
+        excludedCount: number;
+        indexedCount: number;
+        noCaptionsCount: number;
+        failedCount: number;
+        pendingCount: number;
+        totalWords: number;
+        medianWordsPerMinute: number;
+        uploadsPerMonth: {
+            month: string;
+            videos: number;
+        }[];
+        firstUpload?: string | undefined;
+        lastUpload?: string | undefined;
+        recurringPhrases?: {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }[] | undefined;
+    }>;
+};
+/**
+ * Build or extend a channel brain.
+ *
+ * Idempotent by construction: it reads what is missing and leaves what is
+ * already there, so calling it again after an interruption continues, and
+ * calling it on a finished brain picks up new uploads. That is also why there
+ * is no separate refresh tool.
+ *
+ * The filters describe the brain rather than just this call, so a build makes
+ * the brain match them: narrowing one discards the passages of videos it now
+ * excludes, and widening it reads them again.
+ */
+export declare function buildBrainHandler({ channel, maxVideos, language, since, minDurationSeconds, }: {
+    channel: string;
+    maxVideos: number;
+    language: string;
+    since?: string;
+    minDurationSeconds: number;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=build-brain.d.ts.map

package/dist/tools/build-brain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-brain.d.ts","sourceRoot":"","sources":["../../src/tools/build-brain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AASzE,eAAO,MAAM,gBAAgB;;;;;;CA6B5B,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAalC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,OAAO,EACP,SAAS,EACT,QAAQ,EACR,KAAK,EACL,kBAAkB,GACnB,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,cAAc,CAAC,CA+B1B"}

package/dist/tools/build-brain.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { brainStatsSchema } from '../brain-schemas.js';
+import { buildBrain } from '../utils/brain-build.js';
+import { withBuildLock } from '../utils/brain-lock.js';
+import { readManifest } from '../utils/brain-storage.js';
+import { toolResult } from '../utils/format.js';
+import { assertChannelId, assertLanguageTag } from '../utils/validate.js';
+import { getChannelInfo, listVideos } from '../utils/youtube.js';
+export const buildBrainSchema = {
+    channel: z.string().describe('Channel URL, @handle, or name'),
+    maxVideos: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .default(100)
+        .describe('How many of the most recent videos to consider. Default: 100'),
+    language: z
+        .string()
+        .default('en')
+        .describe('Caption language to read. A brain holds one language; build a separate one to read another. Default: en'),
+    since: z
+        .string()
+        .optional()
+        .describe("Only videos published on or after this date (YYYY-MM-DD), read from each video's own metadata rather than guessed at. Re-applied on every call, so narrowing or widening it takes effect without a rebuild."),
+    minDurationSeconds: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe('Skip anything shorter, to leave out shorts and clips. Re-applied on every call, like since. Default: 0'),
+};
+export const buildBrainOutputSchema = {
+    channelId: z.string(),
+    name: z.string(),
+    handle: z.string(),
+    channelUrl: z.string(),
+    language: z.string(),
+    considered: z.number().int().describe('Videos the filters kept'),
+    processed: z.number().int().describe('Videos read during this call'),
+    skipped: z.number().int().describe('Videos already in the brain'),
+    excluded: z.number().int().describe('Videos ruled out by since or minDurationSeconds'),
+    stoppedEarly: z.boolean(),
+    stopReason: z.string().optional(),
+    stats: brainStatsSchema,
+};
+/**
+ * Build or extend a channel brain.
+ *
+ * Idempotent by construction: it reads what is missing and leaves what is
+ * already there, so calling it again after an interruption continues, and
+ * calling it on a finished brain picks up new uploads. That is also why there
+ * is no separate refresh tool.
+ *
+ * The filters describe the brain rather than just this call, so a build makes
+ * the brain match them: narrowing one discards the passages of videos it now
+ * excludes, and widening it reads them again.
+ */
+export async function buildBrainHandler({ channel, maxVideos, language, since, minDurationSeconds, }) {
+    assertLanguageTag(language);
+    const info = await getChannelInfo(channel);
+    assertChannelId(info.channelId);
+    const result = await withBuildLock(info.channelId, async () => buildBrain({
+        channel: info,
+        videos: await listUploads(info.channelUrl, maxVideos),
+        existing: await readManifest(info.channelId),
+        language,
+        minDurationSeconds,
+        ...(since === undefined ? {} : { since }),
+    }));
+    return toolResult(render(info.name, result), {
+        channelId: info.channelId,
+        name: info.name,
+        handle: info.handle,
+        channelUrl: info.channelUrl,
+        language,
+        considered: result.considered,
+        processed: result.processed,
+        skipped: result.skipped,
+        excluded: result.excluded,
+        stoppedEarly: result.stoppedEarly,
+        ...(result.stopReason === undefined ? {} : { stopReason: result.stopReason }),
+        stats: result.manifest.stats,
+    });
+}
+/**
+ * The channel's uploads, newest first.
+ *
+ * Deliberately the uploads tab rather than the channel itself. A bare channel
+ * URL expands to every tab it has — shorts, live, releases — so `--playlist-end`
+ * applies per tab and asking for two videos can return eight, from four
+ * different places. The slice is belt and braces for a channel whose tabs
+ * yt-dlp expands anyway.
+ */
+async function listUploads(channelUrl, maxVideos) {
+    const uploads = `${channelUrl.replace(/\/+$/, '')}/videos`;
+    // No fallback to the bare channel URL. Every channel has an uploads tab, so a
+    // failure here is a failure worth reporting — throttling, a network fault, a
+    // channel that no longer exists — and retrying it against a URL that expands
+    // to more work would double the load while reporting the wrong cause.
+    return (await listVideos(uploads, maxVideos)).slice(0, maxVideos);
+}
+function render(name, result) {
+    const { stats } = result.manifest;
+    const lines = [
+        `Brain for ${name}: ${stats.indexedCount} of ${stats.videoCount} videos indexed, ${stats.chunkCount.toLocaleString()} passages.`,
+        '',
+        `Considered ${result.considered} videos · read ${result.processed} · already had ${result.skipped}${result.excluded > 0 ? ` · ${result.excluded} outside the filters` : ''}`,
+    ];
+    if (stats.noCaptionsCount > 0)
+        lines.push(`${stats.noCaptionsCount} have no captions`);
+    if (stats.failedCount > 0) {
+        lines.push(`${stats.failedCount} could not be read — call build_brain again to retry them`);
+    }
+    if (stats.pendingCount > 0)
+        lines.push(`${stats.pendingCount} not read yet`);
+    if (result.stopReason !== undefined) {
+        lines.push('', `Stopped early: ${result.stopReason}`, 'Call build_brain again to continue.');
+    }
+    lines.push('', 'Ask it something with ask_brain.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=build-brain.js.map

package/dist/tools/build-brain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-brain.js","sourceRoot":"","sources":["../../src/tools/build-brain.ts"],"names":[],"mappings":"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"}

package/dist/tools/clips.d.ts

@@ -78,18 +78,18 @@ export declare const extractClipsOutputSchema: {
         durationSeconds: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
         title: string;
-        videoId: string;
-        filePath: string;
         durationSeconds: number;
         startSeconds: number;
         endSeconds: number;
-    }, {
-        title: string;
         videoId: string;
         filePath: string;
+    }, {
+        title: string;
         durationSeconds: number;
         startSeconds: number;
         endSeconds: number;
+        videoId: string;
+        filePath: string;
     }>, "many">;
     failures: z.ZodArray<z.ZodObject<{
         start: z.ZodString;

package/dist/tools/fetch-videos.d.ts

@@ -21,23 +21,23 @@ export declare const fetchVideosOutputSchema: {
         viewCount: z.ZodOptional<z.ZodNumber>;
         uploadDate: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        url: string;
-        title: string;
         id: string;
-        durationFormatted: string;
+        title: string;
         durationSeconds: number;
+        durationFormatted: string;
+        url: string;
         channel?: string | undefined;
-        uploadDate?: string | undefined;
         viewCount?: number | undefined;
+        uploadDate?: string | undefined;
     }, {
-        url: string;
-        title: string;
         id: string;
-        durationFormatted: string;
+        title: string;
         durationSeconds: number;
+        durationFormatted: string;
+        url: string;
         channel?: string | undefined;
-        uploadDate?: string | undefined;
         viewCount?: number | undefined;
+        uploadDate?: string | undefined;
     }>, "many">;
 };
 export declare function fetchVideosHandler({ url, limit, }: {

package/dist/tools/get-chapters.d.ts

@@ -13,15 +13,15 @@ export declare const getChaptersOutputSchema: {
         endFormatted: z.ZodString;
         url: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        url: string;
         title: string;
+        url: string;
         startSeconds: number;
         startFormatted: string;
         endSeconds: number;
         endFormatted: string;
     }, {
-        url: string;
         title: string;
+        url: string;
         startSeconds: number;
         startFormatted: string;
         endSeconds: number;

package/dist/tools/get-comments.d.ts

@@ -16,14 +16,14 @@ export declare const getCommentsOutputSchema: {
         likeCount: z.ZodNumber;
         isPinned: z.ZodBoolean;
     }, "strip", z.ZodTypeAny, {
-        text: string;
         likeCount: number;
         author: string;
+        text: string;
         isPinned: boolean;
     }, {
-        text: string;
         likeCount: number;
         author: string;
+        text: string;
         isPinned: boolean;
     }>, "many">;
 };

package/dist/tools/get-transcript.d.ts

@@ -20,13 +20,13 @@ export declare const getTranscriptOutputSchema: {
         endSeconds: z.ZodNumber;
         text: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        text: string;
         startSeconds: number;
         endSeconds: number;
-    }, {
         text: string;
+    }, {
         startSeconds: number;
         endSeconds: number;
+        text: string;
     }>, "many">;
     wordCount: z.ZodNumber;
     chapter: z.ZodOptional<z.ZodString>;