tv-recommender-mcp-server

Implementation Reference

• src/tools/videosTool.ts:66-133 (handler)

  The main handler function that implements the get_show_videos tool logic: searches for TV show by title, fetches videos from TMDB, builds URLs using helper, sorts by official/trailer priority, and returns formatted response.

  export async function getShowVideos(params: GetShowVideosParams): Promise<ShowVideosResponse> {
    const { show_title } = params;
  
    try {
      // 通过剧集名称查找剧集ID
      const searchResults = await tmdbClient.searchTvShowByTitle(show_title);
      
      // 如果没有找到任何结果，抛出错误
      if (!searchResults.results || searchResults.results.length === 0) {
        throw new ApiError(`未找到名为"${show_title}"的剧集`, 404);
      }
      
      // 使用第一个搜索结果
      const tvId = searchResults.results[0].id;
      
      // 获取该剧集的视频
      const videosData = await tmdbClient.getTvShowVideos(tvId);
      
      // 格式化视频信息
      const videos: VideoInfo[] = (videosData.results || []).map((video: {
        id: string;
        name: string;
        key: string;
        site: string;
        type: string;
        official: boolean;
        published_at: string;
      }) => ({
        name: video.name,
        key: video.key,
        site: video.site,
        type: video.type,
        official: video.official,
        url: buildVideoUrl(video.site, video.key),
        published_at: video.published_at,
        id: video.id
      }));
      
      // 对视频排序：优先官方预告片
      videos.sort((a, b) => {
        // 优先官方
        if (a.official !== b.official) {
          return a.official ? -1 : 1;
        }
        
        // 其次按类型：Trailer > Teaser > 其他
        if (a.type !== b.type) {
          if (a.type === 'Trailer') return -1;
          if (b.type === 'Trailer') return 1;
          if (a.type === 'Teaser') return -1;
          if (b.type === 'Teaser') return 1;
        }
        
        // 最后按发布日期降序
        return (b.published_at || '') > (a.published_at || '') ? 1 : -1;
      });
      
      return {
        show_id: tvId,
        videos
      };
    } catch (error) {
      if (error instanceof ApiError) {
        throw error;
      }
      throw new Error(`获取剧集"${show_title}"的预告片和视频失败: ${error instanceof Error ? error.message : String(error)}`);
    }
  } 

• src/server.ts:202-213 (registration)

  MCP server registration of the 'get_show_videos' tool, including Zod input schema validation and handler invocation.

  server.tool("get_show_videos",
    { 
      show_title: z.string().describe('剧集名称，用于获取预告片和视频')
    },
    async (params) => {
      console.log(`收到获取剧集视频请求，剧集名称: ${params.show_title}`);
      const results = await getShowVideos(params);
      return {
        content: [{ type: "text", text: JSON.stringify(results) }]
      };
    }
  );

• src/tools/videosTool.ts:7-10 (schema)

  TypeScript interface defining input parameters for the getShowVideos handler (matches Zod schema in registration).

  export interface GetShowVideosParams {
    /** 剧集名称 */
    show_title: string;
  }

• src/tools/videosTool.ts:37-42 (schema)

  TypeScript interface defining the output response structure of the getShowVideos tool.

  export interface ShowVideosResponse {
    /** 剧集ID */
    show_id: number;
    /** 视频列表 */
    videos: VideoInfo[];
  }

• src/tools/videosTool.ts:50-59 (helper)

  Helper utility function used by the handler to construct full video URLs from site and key.

  function buildVideoUrl(site: string, key: string): string {
    switch (site.toLowerCase()) {
      case 'youtube':
        return `https://www.youtube.com/watch?v=${key}`;
      case 'vimeo':
        return `https://vimeo.com/${key}`;
      default:
        return `https://${site.toLowerCase()}.com/video/${key}`;
    }
  }