youtube-knowledge-mcp 2.1.0 → 3.0.0

package/dist/tools/fetch-videos.js

@@ -1,43 +1,87 @@
 import { z } from 'zod';
 import { listVideos } from '../utils/youtube.js';
-import { pageInfo, toolResult } from '../utils/format.js';
-import { paginationShape, videoSummarySchema } from '../schemas.js';
+import { toolResult } from '../utils/format.js';
+import { cursorPageShape, videoSummarySchema } from '../schemas.js';
+import { decodeCursor, encodeCursor } from '../utils/listing-cursor.js';
+import { playlistTotal } from '../utils/youtube-channel.js';
 export const fetchVideosSchema = {
     url: z
         .string()
+        .max(2048)
         .describe('YouTube playlist URL, channel URL, or channel handle (e.g., https://www.youtube.com/@channel)'),
     limit: z
         .number()
+        .int()
         .min(1)
-        .max(100)
+        .max(500)
         .default(20)
-        .describe('Maximum number of videos to return (1-100, default: 20)'),
+        .describe('Videos per page (1-500, default 20)'),
+    cursor: z
+        .string()
+        .max(512)
+        .optional()
+        .describe('Opaque token from a previous nextCursor. Omit for the first page.'),
 };
 export const fetchVideosOutputSchema = {
     source: z.string(),
     videos: z.array(videoSummarySchema),
-    ...paginationShape,
+    ...cursorPageShape,
 };
-export async function fetchVideosHandler({ url, limit, }) {
-    const videos = await listVideos(url, limit);
-    const lines = [`✓ Found ${videos.length} video${videos.length !== 1 ? 's' : ''}`, ''];
-    videos.forEach((v, i) => {
-        lines.push(`${i + 1}. ${v.title}`);
-        lines.push(`   ${v.durationFormatted} · ${v.uploadDate || 'Unknown date'}`);
-        lines.push(`   ${v.url}`);
+/**
+ * One page of a playlist or channel listing.
+ *
+ * Previously this reported `total` as the number of videos it happened to
+ * return, so a caller asking for 20 of a 5,000-video channel was told it had
+ * all 5,000 — `hasMore` was structurally false. Now `total` is only present
+ * when YouTube states one, and its absence means unknown rather than none.
+ */
+export async function fetchVideosHandler({ url, limit, cursor, }) {
+    const position = cursor === undefined ? { v: 1, start: 1, anchor: '' } : decodeCursor(cursor);
+    const [page, total] = await Promise.all([
+        listVideos(url, limit, position.start),
+        playlistTotal(url),
+    ]);
+    // A new upload shifts every index by one, so the item we ended on can
+    // reappear at the top of the next page. Dropping it is the honest fix; yt-dlp
+    // cannot offer a cursor stable against edits.
+    const driftDetected = position.anchor !== '' && page.some((video) => video.id === position.anchor);
+    const videos = driftDetected ? page.filter((video) => video.id !== position.anchor) : page;
+    const nextStart = position.start + page.length;
+    const hasMore = total === undefined ? page.length === limit : nextStart <= total && page.length > 0;
+    const last = videos.at(-1);
+    const lines = [
+        `✓ ${String(videos.length)} video${videos.length === 1 ? '' : 's'}${total === undefined ? '' : ` of ${String(total)}`}`,
+        ...(total === undefined && hasMore
+            ? ['YouTube states no total for this listing, so the number remaining is unknown.']
+            : []),
+        ...(driftDetected ? ['The listing changed between pages; a duplicate was dropped.'] : []),
+        '',
+    ];
+    videos.forEach((video, index) => {
+        lines.push(`${String(position.start + index)}. ${video.title}`);
+        lines.push(`   ${video.durationFormatted} · ${video.uploadDate || 'Unknown date'}`);
+        lines.push(`   ${video.url}`);
         lines.push('');
     });
     return toolResult(lines.join('\n'), {
         source: url,
-        videos: videos.map((v) => ({
-            id: v.id,
-            title: v.title,
-            durationSeconds: v.duration,
-            durationFormatted: v.durationFormatted,
-            url: v.url,
-            uploadDate: v.uploadDate,
+        videos: videos.map((video) => ({
+            id: video.id,
+            title: video.title,
+            durationSeconds: video.duration,
+            durationFormatted: video.durationFormatted,
+            url: video.url,
+            uploadDate: video.uploadDate,
+            ...(video.thumbnailUrl === undefined ? {} : { thumbnailUrl: video.thumbnailUrl }),
+            ...(video.viewCount === undefined ? {} : { viewCount: video.viewCount }),
         })),
-        ...pageInfo(videos.length, videos.length),
+        count: videos.length,
+        hasMore,
+        ...(hasMore && last !== undefined
+            ? { nextCursor: encodeCursor({ v: 1, start: nextStart, anchor: last.id }) }
+            : {}),
+        ...(total === undefined ? {} : { total, totalSource: 'youtube:playlist_count' }),
+        driftDetected,
     });
 }
 //# sourceMappingURL=fetch-videos.js.map

package/dist/tools/fetch-videos.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-videos.js","sourceRoot":"","sources":["../../src/tools/fetch-videos.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGpE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,GAAG,EAAE,CAAC;SACH,MAAM,EAAE;SACR,QAAQ,CACP,+FAA+F,CAChG;IACH,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,yDAAyD,CAAC;CACvE,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;IACnC,GAAG,eAAe;CACnB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,GAAG,EACH,KAAK,GAIN;IACC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAE5C,MAAM,KAAK,GAAa,CAAC,WAAW,MAAM,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAEhG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,iBAAiB,MAAM,CAAC,CAAC,UAAU,IAAI,cAAc,EAAE,CAAC,CAAC;QAC5E,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAClC,MAAM,EAAE,GAAG;QACX,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,eAAe,EAAE,CAAC,CAAC,QAAQ;YAC3B,iBAAiB,EAAE,CAAC,CAAC,iBAAiB;YACtC,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,UAAU,EAAE,CAAC,CAAC,UAAU;SACzB,CAAC,CAAC;QACH,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;KAC1C,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"fetch-videos.js","sourceRoot":"","sources":["../../src/tools/fetch-videos.ts"],"names":[],"mappings":"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"}

package/dist/tools/frames-subtitles.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Stills and subtitles: the two extraction tools that produce something other
+ * than a media clip. Split from clips.ts only for size.
+ */
+export declare const extractFrameSchema: {
+    video: z.ZodString;
+    timestamp: z.ZodString;
+    format: z.ZodDefault<z.ZodEnum<["png", "jpg"]>>;
+    outputDir: z.ZodOptional<z.ZodString>;
+};
+export declare const extractFrameOutputSchema: {
+    videoId: z.ZodString;
+    title: z.ZodString;
+    filePath: z.ZodString;
+    timestampSeconds: z.ZodNumber;
+};
+export declare function extractFrameHandler(args: {
+    video: string;
+    timestamp: string;
+    format: 'png' | 'jpg';
+    outputDir?: string;
+}): Promise<CallToolResult>;
+export declare const exportSubtitlesSchema: {
+    video: z.ZodString;
+    format: z.ZodDefault<z.ZodEnum<["srt", "vtt", "txt"]>>;
+    language: z.ZodDefault<z.ZodString>;
+    outputDir: z.ZodOptional<z.ZodString>;
+};
+export declare const exportSubtitlesOutputSchema: {
+    videoId: z.ZodString;
+    language: z.ZodString;
+    format: z.ZodEnum<["srt", "vtt", "txt"]>;
+    filePath: z.ZodString;
+    cueCount: z.ZodNumber;
+};
+export declare function exportSubtitlesHandler(args: {
+    video: string;
+    format: 'srt' | 'vtt' | 'txt';
+    language: string;
+    outputDir?: string;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=frames-subtitles.d.ts.map

package/dist/tools/frames-subtitles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames-subtitles.d.ts","sourceRoot":"","sources":["../../src/tools/frames-subtitles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;GAGG;AAIH,eAAO,MAAM,kBAAkB;;;;;CAQ9B,CAAC;AAEF,eAAO,MAAM,wBAAwB;;;;;CAKpC,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,GAAG,KAAK,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,cAAc,CAAC,CA4B1B;AAID,eAAO,MAAM,qBAAqB;;;;;CAajC,CAAC;AAEF,eAAO,MAAM,2BAA2B;;;;;;CAMvC,CAAC;AAEF,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,cAAc,CAAC,CA2C1B"}

package/dist/tools/frames-subtitles.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { join } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { fileResult } from '../utils/format.js';
+import { parseTimestamp, resolveOutputDir } from '../utils/validate.js';
+import { extractFrame, safeStem, subtitlesDir } from '../utils/clips.js';
+import { getTranscript } from '../utils/youtube.js';
+import { formatTimestamp, segmentsToText, toSrt, toVtt } from '../utils/transcript.js';
+/**
+ * Stills and subtitles: the two extraction tools that produce something other
+ * than a media clip. Split from clips.ts only for size.
+ */
+// -- extract_frame -------------------------------------------------------
+export const extractFrameSchema = {
+    video: z.string().describe('YouTube video ID or full URL'),
+    timestamp: z.string().describe('When to capture. Seconds, MM:SS or HH:MM:SS.'),
+    format: z.enum(['png', 'jpg']).default('png').describe('Image format. Default: png'),
+    outputDir: z
+        .string()
+        .optional()
+        .describe('Where to write the image. Must be inside your home directory.'),
+};
+export const extractFrameOutputSchema = {
+    videoId: z.string(),
+    title: z.string(),
+    filePath: z.string(),
+    timestampSeconds: z.number(),
+};
+export async function extractFrameHandler(args) {
+    const seconds = parseTimestamp(args.timestamp, 'timestamp');
+    const result = await extractFrame(args.video, seconds, {
+        outputDir: args.outputDir,
+        format: args.format,
+    });
+    return fileResult([
+        '✓ Frame captured',
+        '',
+        result.title,
+        `at ${formatTimestamp(result.timestamp)}`,
+        '',
+        result.filePath,
+    ].join('\n'), {
+        videoId: result.videoId,
+        title: result.title,
+        filePath: result.filePath,
+        timestampSeconds: result.timestamp,
+    }, {
+        path: result.filePath,
+        name: `${result.title} frame`,
+        mimeType: args.format === 'png' ? 'image/png' : 'image/jpeg',
+    });
+}
+// -- export_subtitles ----------------------------------------------------
+export const exportSubtitlesSchema = {
+    video: z.string().describe('YouTube video ID or full URL'),
+    format: z
+        .enum(['srt', 'vtt', 'txt'])
+        .default('srt')
+        .describe('Subtitle format. srt and vtt import into any editor; txt is plain text. Default: srt'),
+    language: z.string().default('en').describe('Caption language. Default: en'),
+    outputDir: z
+        .string()
+        .optional()
+        .describe('Where to write the file. Must be inside your home directory.'),
+};
+export const exportSubtitlesOutputSchema = {
+    videoId: z.string(),
+    language: z.string(),
+    format: z.enum(['srt', 'vtt', 'txt']),
+    filePath: z.string(),
+    cueCount: z.number().int(),
+};
+export async function exportSubtitlesHandler(args) {
+    // Validate the destination before spending a network round trip on a
+    // transcript we would then have nowhere to write.
+    const targetDir = resolveOutputDir(args.outputDir, subtitlesDir());
+    const transcript = await getTranscript(args.video, { language: args.language });
+    const body = args.format === 'srt'
+        ? toSrt(transcript.segments)
+        : args.format === 'vtt'
+            ? toVtt(transcript.segments)
+            : segmentsToText(transcript.segments);
+    await mkdir(targetDir, { recursive: true });
+    const filePath = join(targetDir, `${safeStem(transcript.videoId, transcript.videoId)}.${args.language}.${args.format}`);
+    await writeFile(filePath, body, 'utf-8');
+    return fileResult([
+        `✓ Subtitles exported (${args.format.toUpperCase()})`,
+        '',
+        `${transcript.segments.length.toLocaleString()} cues · ${transcript.language}`,
+        '',
+        filePath,
+    ].join('\n'), {
+        videoId: transcript.videoId,
+        language: transcript.language,
+        format: args.format,
+        filePath,
+        cueCount: transcript.segments.length,
+    }, {
+        path: filePath,
+        name: `${transcript.videoId}.${args.format}`,
+        mimeType: args.format === 'txt' ? 'text/plain' : `text/${args.format}`,
+    });
+}
+//# sourceMappingURL=frames-subtitles.js.map

package/dist/tools/frames-subtitles.js.map

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

package/dist/tools/get-channel-info.d.ts

@@ -10,6 +10,8 @@ export declare const getChannelInfoOutputSchema: {
     subscriberCount: z.ZodNumber;
     channelUrl: z.ZodString;
     description: z.ZodString;
+    avatarUrl: z.ZodOptional<z.ZodString>;
+    bannerUrl: z.ZodOptional<z.ZodString>;
 };
 export declare function getChannelInfoHandler({ channel, }: {
     channel: string;

package/dist/tools/get-channel-info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-channel-info.d.ts","sourceRoot":"","sources":["../../src/tools/get-channel-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,eAAO,MAAM,oBAAoB;;CAEhC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;CAA0B,CAAC;AAElE,wBAAsB,qBAAqB,CAAC,EAC1C,OAAO,GACR,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB1B"}
+{"version":3,"file":"get-channel-info.d.ts","sourceRoot":"","sources":["../../src/tools/get-channel-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,eAAO,MAAM,oBAAoB;;CAKhC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;;CAA0B,CAAC;AAElE,wBAAsB,qBAAqB,CAAC,EAC1C,OAAO,GACR,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,cAAc,CAAC,CAmB1B"}

package/dist/tools/get-channel-info.js

@@ -3,7 +3,10 @@ import { getChannelInfo } from '../utils/youtube.js';
 import { formatCount, toolResult } from '../utils/format.js';
 import { channelInfoSchema } from '../schemas.js';
 export const getChannelInfoSchema = {
-    channel: z.string().describe('YouTube channel URL, handle (e.g., @Fireship), or channel name'),
+    channel: z
+        .string()
+        .max(256)
+        .describe('YouTube channel URL, handle (e.g., @Fireship), or channel name'),
 };
 export const getChannelInfoOutputSchema = channelInfoSchema.shape;
 export async function getChannelInfoHandler({ channel, }) {
@@ -14,6 +17,10 @@ export async function getChannelInfoHandler({ channel, }) {
         `${formatCount(info.subscriberCount)} subscribers`,
         info.channelUrl,
     ].filter(Boolean);
+    if (info.avatarUrl !== undefined)
+        lines.push(`Avatar: ${info.avatarUrl}`);
+    if (info.bannerUrl !== undefined)
+        lines.push(`Banner: ${info.bannerUrl}`);
     if (info.description) {
         lines.push('');
         lines.push(info.description);

package/dist/tools/get-channel-info.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-channel-info.js","sourceRoot":"","sources":["../../src/tools/get-channel-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGlD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gEAAgE,CAAC;CAC/F,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,iBAAiB,CAAC,KAAK,CAAC;AAElE,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,EAC1C,OAAO,GAGR;IACC,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;IAE3C,MAAM,KAAK,GAAa;QACtB,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;QAC9B,GAAG,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,cAAc;QAClD,IAAI,CAAC,UAAU;KAChB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAElB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"get-channel-info.js","sourceRoot":"","sources":["../../src/tools/get-channel-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGlD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,CAAC,gEAAgE,CAAC;CAC9E,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,iBAAiB,CAAC,KAAK,CAAC;AAElE,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,EAC1C,OAAO,GAGR;IACC,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;IAE3C,MAAM,KAAK,GAAa;QACtB,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;QAC9B,GAAG,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,cAAc;QAClD,IAAI,CAAC,UAAU;KAChB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAElB,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAC1E,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAE1E,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC"}

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

@@ -3,13 +3,10 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 export declare const getCommentsSchema: {
     video: z.ZodString;
     limit: z.ZodDefault<z.ZodNumber>;
+    includeReplies: z.ZodDefault<z.ZodBoolean>;
+    sort: z.ZodDefault<z.ZodEnum<["top", "new"]>>;
 };
 export declare const getCommentsOutputSchema: {
-    total: z.ZodNumber;
-    count: z.ZodNumber;
-    offset: z.ZodNumber;
-    hasMore: z.ZodBoolean;
-    nextOffset: z.ZodOptional<z.ZodNumber>;
     comments: z.ZodArray<z.ZodObject<{
         author: z.ZodString;
         text: z.ZodString;
@@ -26,9 +23,244 @@ export declare const getCommentsOutputSchema: {
         text: string;
         isPinned: boolean;
     }>, "many">;
+    threads: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        comment: z.ZodObject<{
+            id: z.ZodString;
+            parentId: z.ZodNullable<z.ZodString>;
+            author: z.ZodString;
+            authorId: z.ZodOptional<z.ZodString>;
+            authorUrl: z.ZodOptional<z.ZodString>;
+            authorThumbnailUrl: z.ZodOptional<z.ZodString>;
+            authorIsUploader: z.ZodBoolean;
+            authorIsVerified: z.ZodBoolean;
+            text: z.ZodString;
+            likeCount: z.ZodNumber;
+            isPinned: z.ZodBoolean;
+            isFavorited: z.ZodBoolean;
+            timestamp: z.ZodOptional<z.ZodNumber>;
+            publishedAt: z.ZodOptional<z.ZodString>;
+            timeText: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            likeCount: number;
+            author: string;
+            text: string;
+            isPinned: boolean;
+            parentId: string | null;
+            authorIsUploader: boolean;
+            authorIsVerified: boolean;
+            isFavorited: boolean;
+            authorId?: string | undefined;
+            authorUrl?: string | undefined;
+            authorThumbnailUrl?: string | undefined;
+            timestamp?: number | undefined;
+            publishedAt?: string | undefined;
+            timeText?: string | undefined;
+        }, {
+            id: string;
+            likeCount: number;
+            author: string;
+            text: string;
+            isPinned: boolean;
+            parentId: string | null;
+            authorIsUploader: boolean;
+            authorIsVerified: boolean;
+            isFavorited: boolean;
+            authorId?: string | undefined;
+            authorUrl?: string | undefined;
+            authorThumbnailUrl?: string | undefined;
+            timestamp?: number | undefined;
+            publishedAt?: string | undefined;
+            timeText?: string | undefined;
+        }>;
+        replies: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            parentId: z.ZodNullable<z.ZodString>;
+            author: z.ZodString;
+            authorId: z.ZodOptional<z.ZodString>;
+            authorUrl: z.ZodOptional<z.ZodString>;
+            authorThumbnailUrl: z.ZodOptional<z.ZodString>;
+            authorIsUploader: z.ZodBoolean;
+            authorIsVerified: z.ZodBoolean;
+            text: z.ZodString;
+            likeCount: z.ZodNumber;
+            isPinned: z.ZodBoolean;
+            isFavorited: z.ZodBoolean;
+            timestamp: z.ZodOptional<z.ZodNumber>;
+            publishedAt: z.ZodOptional<z.ZodString>;
+            timeText: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            likeCount: number;
+            author: string;
+            text: string;
+            isPinned: boolean;
+            parentId: string | null;
+            authorIsUploader: boolean;
+            authorIsVerified: boolean;
+            isFavorited: boolean;
+            authorId?: string | undefined;
+            authorUrl?: string | undefined;
+            authorThumbnailUrl?: string | undefined;
+            timestamp?: number | undefined;
+            publishedAt?: string | undefined;
+            timeText?: string | undefined;
+        }, {
+            id: string;
+            likeCount: number;
+            author: string;
+            text: string;
+            isPinned: boolean;
+            parentId: string | null;
+            authorIsUploader: boolean;
+            authorIsVerified: boolean;
+            isFavorited: boolean;
+            authorId?: string | undefined;
+            authorUrl?: string | undefined;
+            authorThumbnailUrl?: string | undefined;
+            timestamp?: number | undefined;
+            publishedAt?: string | undefined;
+            timeText?: string | undefined;
+        }>, "many">;
+        replyCount: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        comment: {
+            id: string;
+            likeCount: number;
+            author: string;
+            text: string;
+            isPinned: boolean;
+            parentId: string | null;
+            authorIsUploader: boolean;
+            authorIsVerified: boolean;
+            isFavorited: boolean;
+            authorId?: string | undefined;
+            authorUrl?: string | undefined;
+            authorThumbnailUrl?: string | undefined;
+            timestamp?: number | undefined;
+            publishedAt?: string | undefined;
+            timeText?: string | undefined;
+        };
+        replies: {
+            id: string;
+            likeCount: number;
+            author: string;
+            text: string;
+            isPinned: boolean;
+            parentId: string | null;
+            authorIsUploader: boolean;
+            authorIsVerified: boolean;
+            isFavorited: boolean;
+            authorId?: string | undefined;
+            authorUrl?: string | undefined;
+            authorThumbnailUrl?: string | undefined;
+            timestamp?: number | undefined;
+            publishedAt?: string | undefined;
+            timeText?: string | undefined;
+        }[];
+        replyCount: number;
+    }, {
+        comment: {
+            id: string;
+            likeCount: number;
+            author: string;
+            text: string;
+            isPinned: boolean;
+            parentId: string | null;
+            authorIsUploader: boolean;
+            authorIsVerified: boolean;
+            isFavorited: boolean;
+            authorId?: string | undefined;
+            authorUrl?: string | undefined;
+            authorThumbnailUrl?: string | undefined;
+            timestamp?: number | undefined;
+            publishedAt?: string | undefined;
+            timeText?: string | undefined;
+        };
+        replies: {
+            id: string;
+            likeCount: number;
+            author: string;
+            text: string;
+            isPinned: boolean;
+            parentId: string | null;
+            authorIsUploader: boolean;
+            authorIsVerified: boolean;
+            isFavorited: boolean;
+            authorId?: string | undefined;
+            authorUrl?: string | undefined;
+            authorThumbnailUrl?: string | undefined;
+            timestamp?: number | undefined;
+            publishedAt?: string | undefined;
+            timeText?: string | undefined;
+        }[];
+        replyCount: number;
+    }>, "many">>;
+    extractedTotal: z.ZodNumber;
+    orphanReplies: z.ZodNumber;
+    coverage: z.ZodObject<{
+        scope: z.ZodEnum<["channel-catalog", "video-details", "video-comments"]>;
+        targetId: z.ZodString;
+        complete: z.ZodBoolean;
+        reason: z.ZodEnum<["COMPLETE", "CAP_REACHED", "BUDGET_SPENT", "RATE_LIMITED", "CANCELLED", "TIMEOUT", "SOURCE_REFUSED", "COMMENTS_DISABLED", "SOURCE_SILENT", "PARTIAL_ERROR", "NOT_ATTEMPTED"]>;
+        have: z.ZodNumber;
+        expected: z.ZodOptional<z.ZodNumber>;
+        expectedSource: z.ZodOptional<z.ZodEnum<["youtube:comment_count", "youtube:playlist_count", "source-exhausted"]>>;
+        ranToExhaustion: z.ZodOptional<z.ZodBoolean>;
+        source: z.ZodString;
+        harvestedAt: z.ZodString;
+        staleAfter: z.ZodOptional<z.ZodString>;
+        limitApplied: z.ZodOptional<z.ZodNumber>;
+        sortApplied: z.ZodOptional<z.ZodEnum<["top", "new"]>>;
+        resumeToken: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        have: number;
+        scope: "channel-catalog" | "video-details" | "video-comments";
+        targetId: string;
+        complete: boolean;
+        reason: "RATE_LIMITED" | "TIMEOUT" | "CANCELLED" | "COMPLETE" | "CAP_REACHED" | "BUDGET_SPENT" | "SOURCE_REFUSED" | "COMMENTS_DISABLED" | "SOURCE_SILENT" | "PARTIAL_ERROR" | "NOT_ATTEMPTED";
+        source: string;
+        harvestedAt: string;
+        expected?: number | undefined;
+        note?: string | undefined;
+        ranToExhaustion?: boolean | undefined;
+        expectedSource?: "youtube:playlist_count" | "source-exhausted" | "youtube:comment_count" | undefined;
+        staleAfter?: string | undefined;
+        limitApplied?: number | undefined;
+        sortApplied?: "top" | "new" | undefined;
+        resumeToken?: string | undefined;
+    }, {
+        have: number;
+        scope: "channel-catalog" | "video-details" | "video-comments";
+        targetId: string;
+        complete: boolean;
+        reason: "RATE_LIMITED" | "TIMEOUT" | "CANCELLED" | "COMPLETE" | "CAP_REACHED" | "BUDGET_SPENT" | "SOURCE_REFUSED" | "COMMENTS_DISABLED" | "SOURCE_SILENT" | "PARTIAL_ERROR" | "NOT_ATTEMPTED";
+        source: string;
+        harvestedAt: string;
+        expected?: number | undefined;
+        note?: string | undefined;
+        ranToExhaustion?: boolean | undefined;
+        expectedSource?: "youtube:playlist_count" | "source-exhausted" | "youtube:comment_count" | undefined;
+        staleAfter?: string | undefined;
+        limitApplied?: number | undefined;
+        sortApplied?: "top" | "new" | undefined;
+        resumeToken?: string | undefined;
+    }>;
 };
-export declare function getCommentsHandler({ video, limit, }: {
+/**
+ * A sample of a video's comments, with a receipt saying so.
+ *
+ * There is no cursor: YouTube exposes none for a live comment read, so this
+ * cannot page. `coverage.expected` is the video's real comment count, read
+ * from a separate metadata pass — yt-dlp overwrites `comment_count` with the
+ * number it extracted whenever --write-comments is used, so the number cannot
+ * come from the same call that fetched the comments.
+ */
+export declare function getCommentsHandler({ video, limit, includeReplies, sort, }: {
     video: string;
     limit: number;
+    includeReplies: boolean;
+    sort: 'top' | 'new';
 }): Promise<CallToolResult>;
 //# sourceMappingURL=get-comments.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"get-comments.d.ts","sourceRoot":"","sources":["../../src/tools/get-comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,eAAO,MAAM,iBAAiB;;;CAQ7B,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;CAGnC,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,EACvC,KAAK,EACL,KAAK,GACN,EAAE;IACD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,cAAc,CAAC,CAmB1B"}
+{"version":3,"file":"get-comments.d.ts","sourceRoot":"","sources":["../../src/tools/get-comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,eAAO,MAAM,iBAAiB;;;;;CAoB7B,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYnC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,KAAK,EACL,KAAK,EACL,cAAc,EACd,IAAI,GACL,EAAE;IACD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,OAAO,CAAC;IACxB,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;CACrB,GAAG,OAAO,CAAC,cAAc,CAAC,CAuD1B"}