get_trending_videos

Instructions

Implementation Reference

• src/tools/trending.ts:12-84 (handler)

  Main handler implementation in TrendingVideosTool.execute() - validates params, handles caching, quota management, calls YouTube API via client, enhances results.

  export class TrendingVideosTool {
    constructor(
      private youtubeClient: YouTubeClient,
      private cache: CacheManager,
      private quotaManager: QuotaManager,
      private logger: Logger
    ) {}
  
    async execute(args: unknown): Promise<TrendingVideosResult> {
      // Validate input parameters
      const params = GetTrendingVideosSchema.parse(args);
      
      this.logger.info(`Getting trending videos for region: ${params.region}, category: ${params.category || 'all'}`);
  
      // Generate cache key
      const cacheKey = this.cache.getTrendingKey(params.region, params.category);
  
      // Check cache first
      const cached = await this.cache.get<TrendingVideosResult>(cacheKey);
      if (cached) {
        this.logger.info(`Returning cached trending videos for region: ${params.region}`);
        return cached;
      }
  
      // Check quota before making API call
      const operationCost = QuotaManager.getOperationCost('trending');
      if (!this.quotaManager.canPerformOperation(operationCost)) {
        throw new QuotaExceededError('Insufficient quota for trending videos operation');
      }
  
      // Optimize operation based on quota availability
      const optimizedMaxResults = this.quotaManager.optimizeOperation('trending', params.maxResults);
      if (optimizedMaxResults === 0) {
        throw new QuotaExceededError('Cannot perform trending operation due to quota constraints');
      }
  
      const optimizedParams: GetTrendingVideosParams = {
        ...params,
        maxResults: optimizedMaxResults
      };
  
      try {
        // Get trending videos from YouTube API
        const result = await this.youtubeClient.getTrendingVideos(optimizedParams);
        
        // Record quota usage
        await this.quotaManager.recordUsage(operationCost, 'trending');
        
        // Enhance the result with additional metadata
        const enhancedResult = await this.enhanceTrendingData(result);
        
        // Cache the result (trending data changes frequently, so shorter TTL)
        await this.cache.set(cacheKey, enhancedResult, 1800); // 30 minutes TTL
        
        this.logger.info(`Retrieved ${result.videos.length} trending videos for region: ${params.region}`);
        
        return enhancedResult;
  
      } catch (error) {
        this.logger.error(`Failed to get trending videos for region ${params.region}:`, error);
        
        // Try to return cached data if quota exceeded
        if (error instanceof QuotaExceededError) {
          const fallbackCache = await this.getFallbackTrendingData(params.region);
          if (fallbackCache) {
            this.logger.warn('Returning fallback trending data due to quota limits');
            return fallbackCache;
          }
        }
        
        throw error;
      }
    }

• src/types.ts:80-84 (schema)

  Zod schema definition for get_trending_videos input parameters.

  export const GetTrendingVideosSchema = z.object({
    category: z.string().optional().describe('Category ID or name (e.g., "Technology", "Education")'),
    region: z.string().default('US').describe('Region code for trending videos'),
    maxResults: z.number().min(1).max(50).default(25).describe('Maximum number of trending videos to return'),
  });

• src/index.ts:297-319 (registration)

  Tool registration in listToolsRequestHandler - defines name, description, and inputSchema.

  name: 'get_trending_videos',
  description: 'Discover trending videos in different categories and regions',
  inputSchema: {
    type: 'object',
    properties: {
      category: {
        type: 'string',
        description: 'Category ID or name (e.g., "Technology", "Education")'
      },
      region: {
        type: 'string',
        default: 'US',
        description: 'Region code for trending videos'
      },
      maxResults: {
        type: 'number',
        minimum: 1,
        maximum: 50,
        default: 25,
        description: 'Maximum number of trending videos to return'
      }
    }
  }

• src/index.ts:567-569 (registration)

  Tool dispatch in CallToolRequestHandler switch statement - calls TrendingVideosTool.execute().

  case 'get_trending_videos':
    result = await this.trendingTool.execute(args);
    break;

• src/youtube-client.ts:151-177 (helper)

  YouTubeClient.getTrendingVideos() - core API call to fetch trending videos using YouTube Data API v3.

  async getTrendingVideos(params: GetTrendingVideosParams): Promise<TrendingVideosResult> {
    try {
      this.checkQuota(1); // Videos.list costs 1 quota unit
  
      const response = await this.youtube.videos.list({
        part: ['snippet', 'statistics', 'contentDetails'],
        chart: 'mostPopular',
        regionCode: params.region,
        maxResults: params.maxResults,
        videoCategoryId: params.category
      });
  
      this.quotaUsed += 1;
  
      const videos = this.mapVideosResponse(response.data.items || []);
  
      return {
        videos,
        category: params.category,
        region: params.region
      };
  
    } catch (error) {
      this.handleError(error);
      throw error;
    }
  }