tv-recommender-mcp-server

Implementation Reference

• src/tools/discoverShowsTool.ts:386-411 (handler)

  The core handler function implementing the logic for get_recommendations_by_actor: finds actor ID, retrieves TV credits via TMDB API, sorts results by vote_average descending, applies limit, and formats the DiscoverShowsResponse.

  export async function getRecommendationsByActor(actorName: string, limit = 10): Promise<DiscoverShowsResponse> {
    try {
      // 获取演员ID
      const actorId = await findPersonId(actorName);
      if (!actorId) {
        throw new ApiError(`未找到演员: ${actorName}`, 404);
      }
      
      // 获取演员的电视剧作品
      const response = await getPersonTvCredits(actorId);
      
      // 按流行度排序并限制结果数量
      let sortedResults = [...response.results];
      sortedResults.sort((a, b) => (b.vote_average || 0) - (a.vote_average || 0));
      sortedResults = sortedResults.slice(0, limit);
      
      return {
        page: 1,
        results: sortedResults,
        total_pages: 1,
        total_results: sortedResults.length
      };
    } catch (error) {
      throw new ApiError(`获取演员推荐电视剧失败: ${formatErrorMessage(error)}`, 500);
    }
  } 

• src/server.ts:126-139 (registration)

  Registers the get_recommendations_by_actor tool with the MCP server, defines Zod input schema (actor_name required string, limit optional number default 10), and provides async handler that requires and invokes the implementation function.

  server.tool("get_recommendations_by_actor",
    { 
      actor_name: z.string().describe('演员名称，如"布莱恩·科兰斯顿"、"安东尼·斯塔尔"等'),
      limit: z.number().optional().default(10).describe('返回结果数量限制，默认为10')
    },
    async (params) => {
      console.log(`收到获取演员推荐请求，演员名称: ${params.actor_name}，限制: ${params.limit || 10}`);
      const { getRecommendationsByActor } = require('./tools/discoverShowsTool');
      const results = await getRecommendationsByActor(params.actor_name, params.limit);
      return {
        content: [{ type: "text", text: JSON.stringify(results) }]
      };
    }
  );

• src/tools/discoverShowsTool.ts:339-357 (helper)

  Key helper function called by the handler to fetch TV credits for a given person ID from TMDB API and format them into DiscoverShowsResponse.

  export async function getPersonTvCredits(personId: number): Promise<DiscoverShowsResponse> {
    try {
      // 调用person/{person_id}/tv_credits API获取此人参与的所有电视剧
      const response = await tmdbClient.getPersonTvCredits(personId);
      
      // 格式化结果以匹配DiscoverShowsResponse格式
      const results = response.cast || [];
      const formattedResults = formatDiscoverResults(results);
      
      return {
        page: 1,
        results: formattedResults,
        total_pages: 1,
        total_results: formattedResults.length
      };
    } catch (error) {
      throw new ApiError(`获取人物电视作品失败: ${formatErrorMessage(error)}`, 500);
    }
  }

• src/tools/discoverShowsTool.ts:82-92 (helper)

  Helper function to search for a person by name in TMDB and return the first matching ID, used to resolve actorName to actorId in the handler.

  export async function findPersonId(personName: string): Promise<number | null> {
    try {
      const response = await tmdbClient.searchPerson(personName);
      if (response.results && response.results.length > 0) {
        return response.results[0].id;
      }
      return null;
    } catch (error) {
      return null;
    }
  }

• src/tools/discoverShowsTool.ts:28-33 (schema)

  TypeScript interface defining the output structure returned by getRecommendationsByActor and related functions.

  export interface DiscoverShowsResponse {
    page: number;
    results: DiscoverShowsResult[];
    total_pages: number;
    total_results: number;
  }