simplify_video_transcript

Instructions

Implementation Reference

• src/tools/eli5-simplifier.ts:21-84 (handler)

  Main handler logic in ELI5Simplifier.execute(): parses args with schema, fetches transcript, simplifies using LLM for target age, computes readability, caches and returns structured SimplifiedTranscript.

  async execute(args: unknown): Promise<SimplifiedTranscript> {
    const params = SimplifyVideoTranscriptSchema.parse(args);
    
    this.logger.info(`Simplifying transcript for video ${params.videoId} (target age: ${params.targetAge})`);
  
    // Generate cache key
    const cacheKey = `eli5:${params.videoId}:${params.targetAge}:${params.outputFormat}:${params.includeDefinitions}`;
  
    // Check cache first
    const cached = await this.cache.get<SimplifiedTranscript>(cacheKey);
    if (cached) {
      this.logger.info(`Returning cached ELI5 transcript 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 and prepare transcript
      const processedTranscript = this.transcriptProcessor.processTranscript(videoDetails.transcript);
      
      // Step 3: Simplify using LLM
      const simplifiedContent = await this.simplifyTranscript(
        processedTranscript.fullText,
        videoDetails.video,
        params
      );
  
      // Step 4: Calculate readability improvement
      const readabilityScores = this.calculateReadabilityScores(
        processedTranscript.fullText,
        simplifiedContent.content.sections.map(s => s.content).join(' ')
      );
  
      const result: SimplifiedTranscript = {
        videoId: params.videoId,
        originalLength: processedTranscript.fullText.length,
        simplifiedLength: simplifiedContent.content.sections.map(s => s.content).join(' ').length,
        targetAge: params.targetAge,
        content: simplifiedContent.content,
        readabilityScore: readabilityScores
      };
  
      // Cache the result
      await this.cache.set(cacheKey, result, 7200); // 2 hours cache
      
      this.logger.info(`ELI5 simplification completed for ${params.videoId}. Readability improved by ${readabilityScores.improvement}%`);
      
      return result;
  
    } catch (error) {
      this.logger.error(`Failed to simplify transcript for ${params.videoId}:`, error);
      throw error;
    }
  }

• src/types.ts:255-260 (schema)

  Zod schema defining input parameters: videoId (required), targetAge (5-18, default 12), outputFormat (paragraph/bullet_points/qa, default paragraph), includeDefinitions (default true).

  export const SimplifyVideoTranscriptSchema = z.object({
    videoId: z.string().describe('YouTube video ID'),
    targetAge: z.number().min(5).max(18).default(12).describe('Target age for simplification'),
    includeDefinitions: z.boolean().default(true).describe('Include definitions for complex terms'),
    outputFormat: z.enum(['paragraph', 'bullet_points', 'qa']).default('paragraph').describe('Output format'),
  });

• src/index.ts:443-473 (registration)

  Tool registration in MCP server's listTools handler: defines name, description, and inputSchema matching the Zod schema.

    name: 'simplify_video_transcript',
    description: 'Create age-appropriate simplified versions of video transcripts (ELI5 mode)',
    inputSchema: {
      type: 'object',
      properties: {
        videoId: {
          type: 'string',
          description: 'YouTube video ID to simplify'
        },
        targetAge: {
          type: 'number',
          minimum: 5,
          maximum: 18,
          default: 12,
          description: 'Target age for simplification'
        },
        outputFormat: {
          type: 'string',
          enum: ['paragraph', 'bullet_points', 'qa'],
          default: 'paragraph',
          description: 'Preferred output format'
        },
        includeDefinitions: {
          type: 'boolean',
          default: true,
          description: 'Include definitions for key terms'
        }
      },
      required: ['videoId']
    }
  },

• src/index.ts:588-590 (registration)

  Switch case in callTool handler dispatching to ELI5Simplifier instance's execute method.

  case 'simplify_video_transcript':
    result = await this.eli5Tool.execute(args);
    break;

• src/index.ts:180-180 (registration)

  Instantiation of ELI5Simplifier class instance (this.eli5Tool) used as the tool handler, injected with dependencies.

  this.eli5Tool = new ELI5Simplifier(this.youtubeClient, this.cache, this.llmService, this.transcriptProcessor, this.logger);