discover_shows
Discover personalized TV show recommendations by filtering genres, release year, ratings, networks, keywords, and more to find shows tailored to your preferences.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "discover_shows"
}
}Input 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(','); }