tv-recommender-mcp-server

Implementation Reference

• src/server.ts:89-108 (registration)

  MCP tool registration for 'discover_shows', defines Zod input schema and wrapper async handler that calls the core discoverShows function.

  // 注册discover_shows工具
  server.tool("discover_shows",
    {
      with_genres: z.array(z.string()).optional().describe('类型数组，如["喜剧", "科幻"]'),
      first_air_date_year: z.number().optional().describe('首播年份，如2022'),
      vote_average_gte: z.number().optional().describe('最低评分，如8.0'),
      with_networks: z.array(z.number()).optional().describe('电视网络ID数组，如[213]表示Netflix'),
      with_keywords: z.array(z.string()).optional().describe('关键词数组，如["机器人", "太空"]'),
      sort_by: z.string().optional().describe('排序方式，如"popularity.desc"'),
      page: z.number().optional().describe('页码，默认为1'),
      with_original_language: z.string().optional().describe('原始语言，如"en"表示英语')
    },
    async (params) => {
      console.log('收到高级剧集发现请求，参数:', params);
      const results = await discoverShows(params);
      return {
        content: [{ type: "text", text: JSON.stringify(results) }]
      };
    }
  );

• src/tools/discoverShowsTool.ts:178-331 (handler)

  The primary handler function implementing the tool logic: constructs TMDB discover/tv API parameters from input filters, fetches data, applies year filtering if specified, formats output, and handles errors.

  export async function discoverShows(params: DiscoverShowsParams): Promise<DiscoverShowsResponse> {
    try {
      // 构建API请求参数
      const apiParams: Record<string, string | number | boolean> = {};
      
      // 处理类型参数
      if (params.with_genres?.length) {
        apiParams.with_genres = await convertGenresToIds(params.with_genres);
      }
      
      // 注释: TMDB API的discover/tv不支持按演员或人物筛选
      // 相关代码已移除
      
      // 存储请求的年份以便后续过滤
      const requestedYear = params.first_air_date_year;
      
      // 处理年份参数 - 修正参数名称为带点号格式
      if (requestedYear) {
        apiParams['first_air_date.gte'] = `${requestedYear}-01-01`;
        apiParams['first_air_date.lte'] = `${requestedYear}-12-31`;
      }
      
      // 处理评分参数 - 修正参数名称为带点号格式
      if (params.vote_average_gte) {
        apiParams['vote_average.gte'] = params.vote_average_gte;
      }
      
      // 处理网络参数
      if (params.with_networks?.length) {
        apiParams.with_networks = params.with_networks.join(',');
      }
      
      // 处理关键词参数
      if (params.with_keywords?.length) {
        apiParams.with_keywords = await convertKeywordsToIds(params.with_keywords);
      }
      
      // 处理排序参数
      if (params.sort_by) {
        apiParams.sort_by = params.sort_by;
      } else {
        apiParams.sort_by = 'popularity.desc';
      }
      
      // 处理分页参数
      apiParams.page = params.page || 1;
      
      // 处理语言参数
      if (params.with_original_language) {
        apiParams.with_original_language = params.with_original_language;
      }
      
      // 处理成人内容参数
      if (params.include_adult !== undefined) {
        apiParams.include_adult = params.include_adult;
      }
      
      // 处理无首播日期内容参数
      if (params.include_null_first_air_dates !== undefined) {
        apiParams.include_null_first_air_dates = params.include_null_first_air_dates;
      }
      
      // 处理原产国参数
      if (params.with_origin_country) {
        apiParams.with_origin_country = params.with_origin_country;
      }
      
      // 处理状态参数
      if (params.with_status) {
        apiParams.with_status = params.with_status;
      }
      
      // 处理院线放映参数
      if (params.screened_theatrically !== undefined) {
        apiParams.screened_theatrically = params.screened_theatrically;
      }
      
      // 处理时区参数
      if (params.timezone) {
        apiParams.timezone = params.timezone;
      }
      
      // 处理观看区域参数
      if (params.watch_region) {
        apiParams.watch_region = params.watch_region;
      }
      
      // 处理制作公司参数
      if (params.with_companies) {
        apiParams.with_companies = params.with_companies;
      }
      
      // 处理观看提供商参数
      if (params.with_watch_providers) {
        apiParams.with_watch_providers = params.with_watch_providers;
      }
      
      // 处理观看货币化类型参数
      if (params.with_watch_monetization_types) {
        apiParams.with_watch_monetization_types = params.with_watch_monetization_types;
      }
      
      // 调用TMDb API
      const response = await tmdbClient.discoverTvShows(apiParams);
      
      // 如果有指定年份，进行额外的过滤确保日期准确性
      let filteredResults = response.results || [];
      if (requestedYear) {
        console.log(`过滤前剧集数量: ${filteredResults.length}`);
        
        filteredResults = filteredResults.filter((show: {
          id: number;
          name: string;
          overview?: string;
          poster_path?: string;
          vote_average?: number;
          first_air_date?: string;
        }) => {
          // 确保有首播日期
          if (!show.first_air_date) {
            console.log(`剧集 "${show.name}" (ID: ${show.id}) 缺少首播日期，已过滤`);
            return false;
          }
          
          // 解析首播年份并与请求的年份比较
          const airDateYear = new Date(show.first_air_date).getFullYear();
          const matches = airDateYear === requestedYear;
          
          if (!matches) {
            console.log(`剧集 "${show.name}" (ID: ${show.id}) 首播日期 ${show.first_air_date} (${airDateYear}年) 与请求年份 ${requestedYear} 不匹配，已过滤`);
          }
          
          return matches;
        });
        
        console.log(`过滤后剧集数量: ${filteredResults.length}`);
      }
      
      // 格式化结果
      const results = formatDiscoverResults(filteredResults);
      
      // 构建响应
      return {
        page: response.page,
        results,
        total_pages: response.total_pages,
        total_results: filteredResults.length // 更新为过滤后的总数
      };
      
    } catch (error) {
      // console.error('高级剧集发现失败:', error);
      throw new ApiError(`高级剧集发现失败: ${formatErrorMessage(error)}`, 500);
    }
  }

• src/tools/discoverShowsTool.ts:16-58 (schema)

  TypeScript type definitions for input parameters (DiscoverShowsParams), output response (DiscoverShowsResponse), and result items (DiscoverShowsResult).

  export interface DiscoverShowsResult {
    id: number;
    name: string;
    overview: string;
    poster_path: string | null;
    vote_average: number;
    first_air_date?: string;
  }
  
  /**
   * 发现剧集响应接口
   */
  export interface DiscoverShowsResponse {
    page: number;
    results: DiscoverShowsResult[];
    total_pages: number;
    total_results: number;
  }
  
  /**
   * 高级发现工具参数接口
   */
  export interface DiscoverShowsParams {
    with_genres?: string[];         // 类型名称数组，内部会转换为ID
    // with_cast参数已不再支持，TMDB API的discover/tv不提供此功能
    first_air_date_year?: number;   // 首播年份（非标准参数，内部处理）
    vote_average_gte?: number;      // 最低评分
    with_networks?: number[];       // 电视网络ID数组
    with_keywords?: string[];       // 关键词数组，内部会转换为ID
    sort_by?: string;               // 排序方式，默认为'popularity.desc'
    page?: number;                  // 页码
    with_original_language?: string;// 原始语言，如'en'表示英语
    include_adult?: boolean;        // 是否包含成人内容
    include_null_first_air_dates?: boolean; // 是否包含无首播日期的节目 
    with_origin_country?: string;   // 原产国，如'US'
    with_status?: string;           // 状态，可能值为[0,1,2,3,4,5]
    screened_theatrically?: boolean;// 是否院线放映
    timezone?: string;              // 时区
    watch_region?: string;          // 观看区域
    with_companies?: string;        // 制作公司
    with_watch_providers?: string;  // 观看提供商
    with_watch_monetization_types?: string; // 观看货币化类型
  }

• src/tools/discoverShowsTool.ts:65-75 (helper)

  Helper function to convert genre names to TMDB genre IDs for the API query.

  async function convertGenresToIds(genres: string[]): Promise<string> {
    if (!genres || !genres.length) return '';
    
    const genreIds = genres.map(genre => mapGenreToId(genre)).filter(id => id !== null);
    
    if (genreIds.length === 0) {
      throw new ApiError(`无法识别提供的类型: ${genres.join(', ')}`, 400);
    }
    
    return genreIds.join(',');
  }