discover_shows
Discover personalized TV show recommendations by filtering genres, release year, ratings, networks, keywords, and more to find shows tailored to your preferences.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| first_air_date_year | No | 首播年份，如2022 | |
| page | No | 页码，默认为1 | |
| sort_by | No | 排序方式，如"popularity.desc" | |
| vote_average_gte | No | 最低评分，如8.0 | |
| with_genres | No | 类型数组，如["喜剧", "科幻"] | |
| with_keywords | No | 关键词数组，如["机器人", "太空"] | |
| with_networks | No | 电视网络ID数组，如[213]表示Netflix | |
| with_original_language | No | 原始语言，如"en"表示英语 |
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(','); }