YouTube Knowledge MCP

Instructions

Implementation Reference

• src/tools/chapter-generator.ts:14-677 (handler)

  ChapterGenerator class implementing the core logic for 'generate_video_chapters' tool. The execute() method orchestrates transcript fetching, AI-powered chapter detection using LLM, chapter enhancement, optimization, caching, and returns structured ChapterAnalysis.
  export class ChapterGenerator { constructor( private youtubeClient: YouTubeClient, private cache: CacheManager, private llmService: RobustLLMService, private transcriptProcessor: TranscriptProcessor, private logger: Logger ) {} async execute(args: unknown): Promise<ChapterAnalysis> { const params = GenerateVideoChaptersSchema.parse(args); this.logger.info(`Generating chapters for video ${params.videoId}`); // Generate cache key const cacheKey = `chapters:${params.videoId}:${params.minChapterLength}:${params.maxChapters}`; // Check cache first const cached = await this.cache.get<ChapterAnalysis>(cacheKey); if (cached) { this.logger.info(`Returning cached chapters for: ${params.videoId}`); return cached; } try { // Step 1: Get video details with transcript const videoDetails = await this.youtubeClient.getVideoDetails({ videoId: params.videoId, includeTranscript: true, includeComments: false }); if (!videoDetails.transcript || videoDetails.transcript.length === 0) { throw new Error(`No transcript available for video ${params.videoId}`); } // Step 2: Process transcript for structure analysis const processedTranscript = this.transcriptProcessor.processTranscript(videoDetails.transcript); // Step 3: Identify chapter boundaries using AI const chapters = await this.generateChapters( videoDetails.transcript, processedTranscript, videoDetails.video, params ); // Step 4: Enhance chapters with additional analysis const enhancedChapters = await this.enhanceChapters(chapters, videoDetails.transcript); // Step 5: Generate navigation and metadata const analysis = this.generateChapterAnalysis( params.videoId, enhancedChapters, videoDetails.video ); // Cache the result await this.cache.set(cacheKey, analysis, 3600); // 1 hour cache this.logger.info(`Chapter generation completed for ${params.videoId}: ${chapters.length} chapters created`); return analysis; } catch (error) { this.logger.error(`Failed to generate chapters for ${params.videoId}:`, error); throw error; } } /** * Generate chapters using AI analysis of transcript */ private async generateChapters( transcript: YouTubeTranscript[], processedTranscript: any, videoMetadata: any, params: GenerateVideoChaptersParams ): Promise<VideoChapter[]> { // For very long videos, analyze in segments const maxAnalysisLength = 15000; // ~15k characters if (processedTranscript.fullText.length > maxAnalysisLength) { return this.generateChaptersForLongVideo(transcript, videoMetadata, params); } else { return this.generateChaptersWithLLM(transcript, processedTranscript, videoMetadata, params); } } /** * Generate chapters using LLM for shorter videos */ private async generateChaptersWithLLM( transcript: YouTubeTranscript[], processedTranscript: any, videoMetadata: any, params: GenerateVideoChaptersParams ): Promise<VideoChapter[]> { const prompt = this.buildChapterGenerationPrompt( processedTranscript.fullText, videoMetadata, params ); try { const response = await this.llmService.generateWithFallback({ prompt, model: 'gpt-4o', // Use better model for complex structural analysis maxTokens: 1500, temperature: 0.1, responseFormat: 'json' }); const chapterData = JSON.parse(response.content); return this.processLLMChapterResponse(chapterData, transcript, params); } catch (error) { this.logger.warn('LLM chapter generation failed, using rule-based approach:', error); return this.generateChaptersRuleBased(transcript, params); } } /** * Generate chapters for long videos by analyzing segments */ private async generateChaptersForLongVideo( transcript: YouTubeTranscript[], videoMetadata: any, params: GenerateVideoChaptersParams ): Promise<VideoChapter[]> { const segmentDuration = 600; // 10-minute segments const segments = this.segmentTranscript(transcript, segmentDuration); const allChapters: VideoChapter[] = []; for (let i = 0; i < segments.length; i++) { const segment = segments[i]; try { const segmentText = segment.map(t => t.text).join(' '); const prompt = this.buildSegmentAnalysisPrompt(segmentText, i + 1, segments.length); const response = await this.llmService.generateWithFallback({ prompt, model: 'gpt-4o-mini', maxTokens: 800, temperature: 0.1, responseFormat: 'json' }); const segmentChapters = JSON.parse(response.content); if (segmentChapters.chapters && Array.isArray(segmentChapters.chapters)) { const processedChapters = segmentChapters.chapters.map((chapter: any) => ({ title: chapter.title, startTime: segment[0].start + (chapter.relativeStart || 0), endTime: segment[0].start + (chapter.relativeEnd || segment[segment.length - 1].start), duration: chapter.relativeEnd - chapter.relativeStart || 60, description: chapter.description, keyPoints: chapter.keyPoints || [], difficulty: chapter.difficulty || 'medium', importance: chapter.importance || 0.5 })); allChapters.push(...processedChapters); } // Small delay between segments if (i < segments.length - 1) { await new Promise(resolve => setTimeout(resolve, 200)); } } catch (error) { this.logger.warn(`Failed to analyze segment ${i + 1}:`, error); // Add basic chapter for this segment allChapters.push({ title: `Part ${i + 1}`, startTime: segment[0].start, endTime: segment[segment.length - 1].start + segment[segment.length - 1].duration, duration: segmentDuration, description: `Content from part ${i + 1} of the video`, keyPoints: [], difficulty: 'medium', importance: 0.5 }); } } // Merge and optimize chapters return this.optimizeChapters(allChapters, params); } /** * Build chapter generation prompt for LLM */ private buildChapterGenerationPrompt( transcriptText: string, videoMetadata: any, params: GenerateVideoChaptersParams ): string { return `You are an expert video editor who creates logical chapter breakdowns for educational content. Video Information: - Title: ${videoMetadata.title} - Duration: ${videoMetadata.duration} - Category: ${videoMetadata.categoryId} Requirements: - Create ${params.maxChapters} or fewer chapters - Each chapter should be at least ${params.minChapterLength} seconds - ${params.includeDescriptions ? 'Include detailed descriptions' : 'Brief descriptions only'} Transcript: ${transcriptText} Analyze the content flow and create logical chapter divisions. Look for: 1. Topic transitions 2. Natural pauses or transitions 3. Introduction/conclusion sections 4. Distinct concepts or lessons 5. Changes in speaking pace or tone Respond with JSON: { "chapters": [ { "title": "Clear, descriptive chapter title", "startTime": 0, "endTime": 120, "description": "What this chapter covers", "keyPoints": ["key point 1", "key point 2"], "difficulty": "easy|medium|hard", "importance": 0.8 } ] } Important: Base timing on content analysis, not arbitrary divisions.`; } /** * Build segment analysis prompt for long videos */ private buildSegmentAnalysisPrompt( segmentText: string, segmentNumber: number, totalSegments: number ): string { return `Analyze this segment (${segmentNumber}/${totalSegments}) of a video transcript and identify 1-3 logical chapters within it. Segment Content: ${segmentText} Focus on natural topic transitions and content changes. Each chapter should represent a distinct concept or discussion point. Respond with JSON: { "chapters": [ { "title": "Chapter title", "relativeStart": 0, "relativeEnd": 180, "description": "Brief description", "keyPoints": ["point 1", "point 2"], "difficulty": "medium", "importance": 0.7 } ] } Note: Use relative timestamps within this segment (0 = segment start).`; } /** * Process LLM chapter response into VideoChapter objects */ private processLLMChapterResponse( chapterData: any, transcript: YouTubeTranscript[], params: GenerateVideoChaptersParams ): VideoChapter[] { if (!chapterData.chapters || !Array.isArray(chapterData.chapters)) { throw new Error('Invalid chapter response format'); } const videoDuration = transcript[transcript.length - 1]?.start + transcript[transcript.length - 1]?.duration || 0; return chapterData.chapters .filter((chapter: any) => chapter.endTime - chapter.startTime >= params.minChapterLength ) .map((chapter: any) => ({ title: chapter.title || 'Untitled Chapter', startTime: Math.max(0, chapter.startTime || 0), endTime: Math.min(videoDuration, chapter.endTime || chapter.startTime + params.minChapterLength), duration: (chapter.endTime || 0) - (chapter.startTime || 0), description: chapter.description || '', keyPoints: Array.isArray(chapter.keyPoints) ? chapter.keyPoints : [], difficulty: ['easy', 'medium', 'hard'].includes(chapter.difficulty) ? chapter.difficulty : 'medium', importance: Math.max(0, Math.min(1, chapter.importance || 0.5)) })) .slice(0, params.maxChapters); } /** * Rule-based chapter generation fallback */ private generateChaptersRuleBased( transcript: YouTubeTranscript[], params: GenerateVideoChaptersParams ): VideoChapter[] { const videoDuration = transcript[transcript.length - 1]?.start + transcript[transcript.length - 1]?.duration || 0; const idealChapterLength = Math.max(params.minChapterLength, videoDuration / params.maxChapters); const chapters: VideoChapter[] = []; let currentStart = 0; let chapterIndex = 1; while (currentStart < videoDuration && chapters.length < params.maxChapters) { const endTime = Math.min(currentStart + idealChapterLength, videoDuration); // Find natural break points (silence or topic changes) const adjustedEndTime = this.findNaturalBreakPoint(transcript, currentStart, endTime); // Get content for this chapter const chapterTranscript = transcript.filter(t => t.start >= currentStart && t.start < adjustedEndTime ); const chapterText = chapterTranscript.map(t => t.text).join(' '); const keyPoints = this.extractKeyPointsRuleBased(chapterText); chapters.push({ title: `Chapter ${chapterIndex}`, startTime: Math.round(currentStart), endTime: Math.round(adjustedEndTime), duration: Math.round(adjustedEndTime - currentStart), description: `Content from ${this.formatTime(currentStart)} to ${this.formatTime(adjustedEndTime)}`, keyPoints, difficulty: 'medium', importance: 0.6 }); currentStart = adjustedEndTime; chapterIndex++; } return chapters; } /** * Find natural break points in transcript */ private findNaturalBreakPoint( transcript: YouTubeTranscript[], startTime: number, idealEndTime: number ): number { const searchWindow = 30; // Look within 30 seconds of ideal end time const candidates = transcript.filter(t => t.start >= idealEndTime - searchWindow && t.start <= idealEndTime + searchWindow ); // Look for natural pause indicators const breakIndicators = ['.', '!', '?', 'so', 'now', 'next', 'alright', 'okay']; for (const candidate of candidates) { const text = candidate.text.toLowerCase(); if (breakIndicators.some(indicator => text.includes(indicator))) { return candidate.start; } } return idealEndTime; // Fallback to ideal time } /** * Extract key points using rule-based approach */ private extractKeyPointsRuleBased(text: string): string[] { const sentences = text.split(/[.!?]+/).filter(s => s.trim().length > 20); // Look for sentences with important indicators const importantSentences = sentences.filter(sentence => { const lower = sentence.toLowerCase(); return ( lower.includes('important') || lower.includes('key') || lower.includes('remember') || lower.includes('main') || lower.includes('first') || lower.includes('second') || lower.includes('finally') ); }); return importantSentences.slice(0, 3).map(s => s.trim()); } /** * Enhance chapters with additional analysis */ private async enhanceChapters( chapters: VideoChapter[], transcript: YouTubeTranscript[] ): Promise<VideoChapter[]> { return Promise.all( chapters.map(async (chapter) => { try { // Get transcript for this chapter const chapterTranscript = transcript.filter(t => t.start >= chapter.startTime && t.start < chapter.endTime ); // Enhance with better descriptions if possible if (chapterTranscript.length > 0) { const enhanced = await this.enhanceChapterDescription(chapter, chapterTranscript); return enhanced; } return chapter; } catch (error) { this.logger.warn(`Failed to enhance chapter "${chapter.title}":`, error); return chapter; } }) ); } /** * Enhance individual chapter description using LLM */ private async enhanceChapterDescription( chapter: VideoChapter, chapterTranscript: YouTubeTranscript[] ): Promise<VideoChapter> { try { const chapterText = chapterTranscript.map(t => t.text).join(' '); if (chapterText.length < 50) return chapter; // Skip very short chapters const prompt = `Analyze this chapter content and create a better title and description. Chapter Title: ${chapter.title} Duration: ${this.formatTime(chapter.duration)} Content: ${chapterText.slice(0, 1000)}... Create: 1. A more descriptive title (max 6 words) 2. A brief description of what's covered 3. 2-3 key takeaways Respond with JSON: { "title": "Better chapter title", "description": "What this chapter covers", "keyPoints": ["takeaway 1", "takeaway 2"] }`; const response = await this.llmService.generateWithFallback({ prompt, model: 'gpt-4o-mini', maxTokens: 300, temperature: 0.2, responseFormat: 'json' }); const enhancement = JSON.parse(response.content); return { ...chapter, title: enhancement.title || chapter.title, description: enhancement.description || chapter.description, keyPoints: enhancement.keyPoints || chapter.keyPoints }; } catch (error) { this.logger.warn(`Failed to enhance chapter description:`, error); return chapter; } } /** * Generate comprehensive chapter analysis */ private generateChapterAnalysis( videoId: string, chapters: VideoChapter[], videoMetadata: any ): ChapterAnalysis { const avgChapterLength = chapters.length > 0 ? chapters.reduce((sum, ch) => sum + ch.duration, 0) / chapters.length : 0; // Analyze content flow const contentFlow = this.analyzeContentFlow(chapters); // Analyze difficulty progression const difficultyProgression = chapters.map(ch => ch.difficulty); // Find recommended break points (chapters with high importance) const recommendedBreakpoints = chapters .filter(ch => ch.importance > 0.7) .map(ch => ch.startTime); // Create quick access navigation const quickAccess = this.createQuickAccessNavigation(chapters); // Generate learning path suggestions const learningPath = this.generateLearningPath(chapters); // Identify skippable sections const skipSuggestions = chapters .filter(ch => ch.difficulty === 'easy' && ch.importance < 0.4) .map(ch => chapters.indexOf(ch)); return { videoId, chapters, metadata: { totalChapters: chapters.length, avgChapterLength: Math.round(avgChapterLength), contentFlow, difficultyProgression, recommendedBreakpoints }, navigation: { quickAccess, learningPath, skipSuggestions } }; } // Helper methods private segmentTranscript(transcript: YouTubeTranscript[], segmentDuration: number): YouTubeTranscript[][] { const segments: YouTubeTranscript[][] = []; let currentSegment: YouTubeTranscript[] = []; let segmentStartTime = 0; for (const item of transcript) { if (item.start - segmentStartTime >= segmentDuration && currentSegment.length > 0) { segments.push(currentSegment); currentSegment = [item]; segmentStartTime = item.start; } else { currentSegment.push(item); } } if (currentSegment.length > 0) { segments.push(currentSegment); } return segments; } private optimizeChapters(chapters: VideoChapter[], params: GenerateVideoChaptersParams): VideoChapter[] { // Remove very short chapters and merge if necessary let optimized = chapters.filter(ch => ch.duration >= params.minChapterLength); // If too many chapters, merge similar adjacent ones if (optimized.length > params.maxChapters) { optimized = this.mergeChapters(optimized, params.maxChapters); } return optimized; } private mergeChapters(chapters: VideoChapter[], maxChapters: number): VideoChapter[] { if (chapters.length <= maxChapters) return chapters; // Simple merging strategy: combine adjacent chapters with similar difficulty const merged: VideoChapter[] = []; for (let i = 0; i < chapters.length; i++) { if (merged.length >= maxChapters) break; const current = chapters[i]; const next = chapters[i + 1]; if (next && merged.length < maxChapters - 1 && current.difficulty === next.difficulty) { // Merge current and next merged.push({ title: `${current.title} & ${next.title}`, startTime: current.startTime, endTime: next.endTime, duration: next.endTime - current.startTime, description: `${current.description} ${next.description}`, keyPoints: [...current.keyPoints, ...next.keyPoints], difficulty: current.difficulty, importance: Math.max(current.importance, next.importance) }); i++; // Skip next chapter as it's been merged } else { merged.push(current); } } return merged; } private analyzeContentFlow(chapters: VideoChapter[]): string { const difficulties = chapters.map(ch => ch.difficulty); if (difficulties.every(d => d === 'easy')) return 'Consistently easy throughout'; if (difficulties.every(d => d === 'hard')) return 'Consistently challenging'; // Check for logical progression const progression = difficulties.join(' -> '); if (progression.includes('easy') && progression.includes('hard')) { return 'Progresses from easy to complex topics'; } return 'Mixed difficulty levels'; } private createQuickAccessNavigation(chapters: VideoChapter[]): Array<{ topic: string; chapters: number[] }> { // Group chapters by common keywords in titles const topicGroups: Record<string, number[]> = {}; chapters.forEach((chapter, index) => { const words = chapter.title.toLowerCase().split(' '); const significantWords = words.filter(word => word.length > 3 && !['the', 'and', 'for', 'with'].includes(word) ); significantWords.forEach(word => { if (!topicGroups[word]) topicGroups[word] = []; topicGroups[word].push(index); }); }); return Object.entries(topicGroups) .filter(([_, chapters]) => chapters.length > 1) .slice(0, 5) // Top 5 topics .map(([topic, chapterIndices]) => ({ topic, chapters: chapterIndices })); } private generateLearningPath(chapters: VideoChapter[]): string[] { return chapters .sort((a, b) => { // Sort by difficulty, then by importance const diffOrder = { easy: 1, medium: 2, hard: 3 }; const aDiff = diffOrder[a.difficulty] || 2; const bDiff = diffOrder[b.difficulty] || 2; if (aDiff !== bDiff) return aDiff - bDiff; return b.importance - a.importance; }) .map(ch => ch.title); } private formatTime(seconds: number): string { const hours = Math.floor(seconds / 3600); const minutes = Math.floor((seconds % 3600) / 60); const secs = Math.floor(seconds % 60); if (hours > 0) { return `${hours}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`; } return `${minutes}:${secs.toString().padStart(2, '0')}`; } }
• src/types.ts:262-267 (schema)

  Zod schema defining input parameters and validation for generate_video_chapters tool, used in handler for parsing args.
  export const GenerateVideoChaptersSchema = z.object({ videoId: z.string().describe('YouTube video ID'), minChapterLength: z.number().min(30).max(600).default(120).describe('Minimum chapter length in seconds'), maxChapters: z.number().min(3).max(20).default(10).describe('Maximum number of chapters'), includeDescriptions: z.boolean().default(true).describe('Include chapter descriptions'), });
• src/index.ts:592-594 (registration)

  Tool call routing in MCP CallToolRequestSchema handler - dispatches generate_video_chapters calls to ChapterGenerator.execute()
  case 'generate_video_chapters': result = await this.chapterTool.execute(args); break;
• src/index.ts:475-506 (registration)

  Tool registration metadata in ListToolsRequestSchema response - defines name, description, and input schema for client discovery.
  name: 'generate_video_chapters', description: 'Generate AI-powered video chapters with timestamps and descriptions', inputSchema: { type: 'object', properties: { videoId: { type: 'string', description: 'YouTube video ID to generate chapters for' }, maxChapters: { type: 'number', minimum: 3, maximum: 20, default: 10, description: 'Maximum number of chapters to generate' }, minChapterLength: { type: 'number', minimum: 30, maximum: 600, default: 60, description: 'Minimum chapter length in seconds' }, includeDescriptions: { type: 'boolean', default: true, description: 'Include detailed chapter descriptions' } }, required: ['videoId'] } },
• src/index.ts:181-182 (registration)

  Instantiation of ChapterGenerator handler instance with required dependencies (YouTubeClient, CacheManager, LLMService, etc.) in main MCP server class.
  this.chapterTool = new ChapterGenerator(this.youtubeClient, this.cache, this.llmService, this.transcriptProcessor, this.logger); this.knowledgeGraphTool = new KnowledgeGraphGenerator(this.youtubeClient, this.cache, this.llmService, this.transcriptProcessor, this.logger);