get_video_details

Instructions

Implementation Reference

• src/tools/video-details.ts:23-80 (handler)

  The primary handler function for the 'get_video_details' tool. Validates input using the schema, checks cache and quota, fetches raw data from YouTubeClient, enhances with analysis (transcript processing, comment analysis, engagement metrics), caches the result, and handles errors with partial cache fallback.

  async execute(args: unknown): Promise<VideoDetailsResult> {
    // Validate input parameters
    const params = GetVideoDetailsSchema.parse(args);
    
    this.logger.info(`Getting video details for: ${params.videoId}`);
  
    // Generate cache key
    const cacheKey = this.cache.getVideoDetailsKey(
      params.videoId, 
      params.includeTranscript, 
      params.includeComments
    );
  
    // Check cache first
    const cached = await this.cache.get<VideoDetailsResult>(cacheKey);
    if (cached) {
      this.logger.info(`Returning cached video details for: ${params.videoId}`);
      return cached;
    }
  
    // Check quota before making API call
    const operationCost = this.calculateOperationCost(params);
    if (!this.quotaManager.canPerformOperation(operationCost)) {
      throw new QuotaExceededError('Insufficient quota for video details operation');
    }
  
    try {
      // Get video details from YouTube API
      const result = await this.youtubeClient.getVideoDetails(params);
      
      // Record quota usage
      await this.quotaManager.recordUsage(operationCost, 'video_details');
      
      // Enhance the result with additional processing
      const enhancedResult = await this.enhanceVideoDetails(result, params);
      
      // Cache the result
      await this.cache.set(cacheKey, enhancedResult);
      
      this.logger.info(`Video details retrieved for: ${params.videoId}`);
      
      return enhancedResult;
  
    } catch (error) {
      this.logger.error(`Failed to get video details for ${params.videoId}:`, error);
      
      // Try to return partial cached data if quota exceeded
      if (error instanceof QuotaExceededError) {
        const partialCache = await this.getPartialCachedData(params.videoId);
        if (partialCache) {
          this.logger.warn('Returning partial cached data due to quota limits');
          return partialCache;
        }
      }
      
      throw error;
    }
  }

• src/types.ts:72-78 (schema)

  Zod schema for input validation of get_video_details tool parameters, defining videoId as required and optional flags for transcript, comments with limits.

  export const GetVideoDetailsSchema = z.object({
    videoId: z.string().describe('YouTube video ID'),
    includeTranscript: z.boolean().default(true).describe('Whether to include video transcript'),
    includeComments: z.boolean().default(true).describe('Whether to include video comments'),
    maxComments: z.number().min(1).max(100).default(50).describe('Maximum number of comments to retrieve'),
    commentsOrder: z.enum(['relevance', 'time']).default('relevance').describe('Sort order for comments'),
  });

• src/index.ts:259-295 (registration)

  Tool registration in the listTools response, defining name, description, and inputSchema matching the Zod schema.

  {
    name: 'get_video_details',
    description: 'Get comprehensive information about a specific YouTube video',
    inputSchema: {
      type: 'object',
      properties: {
        videoId: {
          type: 'string',
          description: 'YouTube video ID'
        },
        includeTranscript: {
          type: 'boolean',
          default: true,
          description: 'Whether to include video transcript'
        },
        includeComments: {
          type: 'boolean',
          default: true,
          description: 'Whether to include video comments'
        },
        maxComments: {
          type: 'number',
          minimum: 1,
          maximum: 100,
          default: 50,
          description: 'Maximum number of comments to retrieve'
        },
        commentsOrder: {
          type: 'string',
          enum: ['relevance', 'time'],
          default: 'relevance',
          description: 'Sort order for comments'
        }
      },
      required: ['videoId']
    }
  },

• src/index.ts:563-565 (registration)

  Handler dispatch in the CallToolRequestSchema handler switch statement, routing 'get_video_details' calls to VideoDetailsTool.execute()

  case 'get_video_details':
    result = await this.videoDetailsTool.execute(args);
    break;

• src/youtube-client.ts:107-146 (helper)

  Supporting helper in YouTubeClient that performs the actual YouTube API calls for video details, optionally fetching transcript and comments.

  async getVideoDetails(params: GetVideoDetailsParams): Promise<VideoDetailsResult> {
    try {
      const videos = await this.getVideosByIds([params.videoId]);
      const video = videos[0];
      
      if (!video) {
        throw new YouTubeAPIError(`Video not found: ${params.videoId}`);
      }
  
      const result: VideoDetailsResult = { video };
  
      // Get transcript if requested
      if (params.includeTranscript) {
        try {
          result.transcript = await this.getVideoTranscript(params.videoId);
        } catch (error) {
          this.logger.warn(`Failed to get transcript for ${params.videoId}:`, error);
        }
      }
  
      // Get comments if requested
      if (params.includeComments) {
        try {
          result.comments = await this.getVideoComments(
            params.videoId,
            params.maxComments,
            params.commentsOrder
          );
        } catch (error) {
          this.logger.warn(`Failed to get comments for ${params.videoId}:`, error);
        }
      }
  
      return result;
  
    } catch (error) {
      this.handleError(error);
      throw error;
    }
  }