get-segmented-transcript

Instructions

Implementation Reference

• src/youtube-service.ts:509-600 (handler)

  Core handler logic for segmenting YouTube video transcripts into equal time-based segments, formatting each with timestamps and transcript text, and returning a structured FormattedTranscript object including markdown output.

  async getSegmentedTranscript(
    videoId: string,
    segmentCount: number = 4
  ): Promise<FormattedTranscript> {
    try {
      // Get full transcript
      const transcriptData = await this.getTranscript(videoId);
  
      // Get video details for title and other metadata
      const videoData = await this.getVideoDetails(videoId);
      const video = videoData.items?.[0];
  
      if (!transcriptData.length) {
        throw new Error('No transcript available for this video');
      }
  
      // Calculate total duration
      const lastSegment = transcriptData[transcriptData.length - 1];
      const totalDuration = (lastSegment.offset + lastSegment.duration) / 1000; // in seconds
  
      // Calculate segment size
      const segmentDuration = totalDuration / segmentCount;
      const segments: {
        startTime: number;
        endTime: number;
        text: string;
        transcriptSegments: TranscriptSegment[];
      }[] = [];
  
      // Create segments
      for (let i = 0; i < segmentCount; i++) {
        const startTime = i * segmentDuration;
        const endTime = (i + 1) * segmentDuration;
  
        // Find all transcript segments that fall within this time range
        const segmentTranscript = transcriptData.filter(segment => {
          const segmentStartTime = segment.offset / 1000;
          const segmentEndTime = (segment.offset + segment.duration) / 1000;
          return segmentStartTime >= startTime && segmentStartTime < endTime;
        });
  
        if (segmentTranscript.length > 0) {
          segments.push({
            startTime,
            endTime,
            text: segmentTranscript.map(s => s.text).join(' '),
            transcriptSegments: segmentTranscript
          });
        }
      }
  
      // Create formatted output
      const title = video?.snippet?.title || 'Video Transcript';
      let formattedText = `# Segmented Transcript: ${title}\n\n`;
  
      segments.forEach((segment, index) => {
        const startTimeFormatted = this.formatTimestamp(segment.startTime * 1000);
        const endTimeFormatted = this.formatTimestamp(segment.endTime * 1000);
  
        formattedText += `## Segment ${index + 1} [${startTimeFormatted} - ${endTimeFormatted}]\n\n`;
  
        // Add transcript for this segment
        formattedText += segment.transcriptSegments.map(s =>
          `[${this.formatTimestamp(s.offset)}] ${s.text}`
        ).join('\n');
  
        formattedText += '\n\n';
      });
  
      return {
        segments: transcriptData,
        totalSegments: transcriptData.length,
        duration: totalDuration,
        format: 'timestamped',
        text: formattedText,
        metadata: video ? [{
          id: video.id,
          title: video.snippet?.title,
          channelId: video.snippet?.channelId,
          channelTitle: video.snippet?.channelTitle,
          publishedAt: video.snippet?.publishedAt,
          duration: video.contentDetails?.duration,
          viewCount: video.statistics?.viewCount,
          likeCount: video.statistics?.likeCount
        }] : undefined
      };
    } catch (error) {
      console.error('Error creating segmented transcript:', error);
      throw error;
    }
  }

• src/index.ts:759-789 (registration)

  MCP tool registration using server.tool(), including full description, Zod input schema, and wrapper async handler that parses parameters, calls YouTubeService.getSegmentedTranscript, and formats the response as MCP content.

  server.tool(
    'get-segmented-transcript',
    'Divide a video transcript into segments for easier analysis and navigation. This tool splits the video into equal time segments and extracts the transcript for each segment with proper timestamps. Ideal for analyzing the structure of longer videos or when you need to focus on specific parts of the content. Parameters: videoId (required) - The YouTube video ID; segmentCount (optional) - Number of segments to divide the video into (default: 4, max: 10). Returns a markdown-formatted text with each segment clearly labeled with time ranges and containing the relevant transcript text.',
    {
      videoId: z.string().min(1),
      segmentCount: z.string().optional()
    },
    async ({ videoId, segmentCount }) => {
      try {
        // 문자열 segmentCount를 숫자로 변환
        const segmentCountNum = segmentCount ? parseInt(segmentCount, 10) : 4;
  
        const segmentedTranscript = await youtubeService.getSegmentedTranscript(videoId, segmentCountNum);
  
        return {
          content: [{
            type: 'text',
            text: segmentedTranscript.text || 'Failed to create segmented transcript'
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: 'text',
            text: `Error creating segmented transcript: ${error instanceof Error ? error.message : String(error)}`
          }],
          isError: true
        };
      }
    }
  );

• src/index.ts:762-765 (schema)

  Zod validation schema for tool parameters: videoId (required non-empty string), segmentCount (optional string).

  {
    videoId: z.string().min(1),
    segmentCount: z.string().optional()
  },

• src/types/youtube-types.ts:49-56 (schema)

  TypeScript interface defining the structure of the output FormattedTranscript used by the getSegmentedTranscript method.

  export interface FormattedTranscript {
    segments: TranscriptSegment[];
    totalSegments: number;
    duration: number; // Total duration in seconds
    format: string;
    text?: string; // Formatted text (for timestamped and merged formats)
    metadata?: Array<VideoMetadata | null>;
  }