tv-recommender-mcp-server

Implementation Reference

• src/tools/reviewsTool.ts:69-100 (handler)

  The core handler function `getShowReviews` that implements the tool logic: searches for TV show by title via TMDB, fetches reviews for the first matching show, and returns paginated reviews with metadata.

  export async function getShowReviews(params: GetShowReviewsParams): Promise<ShowReviewsResponse> {
    const { show_title, page = 1 } = 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 reviewsData = await tmdbClient.getTvShowReviews(tvId, page);
      
      return {
        show_id: tvId,
        page: reviewsData.page,
        results: reviewsData.results || [],
        total_pages: reviewsData.total_pages || 0,
        total_results: reviewsData.total_results || 0
      };
    } catch (error) {
      if (error instanceof ApiError) {
        throw error;
      }
      throw new Error(`获取剧集"${show_title}"的评论失败: ${error instanceof Error ? error.message : String(error)}`);
    }
  } 

• src/server.ts:156-171 (registration)

  MCP server tool registration for 'get_show_reviews', defining Zod input schema, logging, calling the handler, and formatting response as MCP content.

  server.tool("get_show_reviews",
    { 
      show_title: z.string().describe('剧集名称，用于获取评论'),
      page: z.number().optional().default(1).describe('页码，默认为1')
    },
    async (params) => {
      console.log(`收到获取剧集评论请求，剧集名称: ${params.show_title}，页码: ${params.page || 1}`);
      const results = await getShowReviews({
        show_title: params.show_title,
        page: params.page
      });
      return {
        content: [{ type: "text", text: JSON.stringify(results) }]
      };
    }
  );

• src/tools/reviewsTool.ts:7-12 (schema)

  TypeScript interface for input parameters of the getShowReviews handler.

  export interface GetShowReviewsParams {
    /** 剧集名称 */
    show_title: string;
    /** 页码，默认为1 */
    page?: number;
  }

• src/tools/reviewsTool.ts:51-62 (schema)

  TypeScript interfaces defining the response structure and supporting types (AuthorDetails, ReviewItem) for show reviews.

  export interface ShowReviewsResponse {
    /** 剧集ID */
    show_id: number;
    /** 当前页 */
    page: number;
    /** 评论列表 */
    results: ReviewItem[];
    /** 总页数 */
    total_pages: number;
    /** 总评论数 */
    total_results: number;
  }

• src/tools/index.ts:48-55 (registration)

  Re-export of the getShowReviews handler and types from reviewsTool.ts for convenient import in server.ts.

  // 导出评论工具
  export {
    getShowReviews,
    type GetShowReviewsParams,
    type ShowReviewsResponse,
    type ReviewItem,
    type AuthorDetails
  } from './reviewsTool';