get_actor_details_and_credits

Retrieve detailed information and credits for a specific actor to enhance TV show recommendations and insights. Input the actor's name to access their profile and role history.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`actor_name`	Yes	演员名称，如"布莱恩·科兰斯顿"、"安东尼·斯塔尔"等

Implementation Reference

src/tools/actorInfoTool.ts:69-127 (handler)

The handler function that implements the tool logic: searches for actor by name, fetches details and TV credits from TMDB API, formats and sorts credits by vote average, returns ActorInfoResponse.

export async function getActorDetailsAndCredits(params: GetActorInfoParams): Promise<ActorInfoResponse> {
  const { actor_name } = params;

  try {
    // 通过演员姓名查找演员ID
    const searchResults = await tmdbClient.searchPerson(actor_name);
    
    // 如果没有找到任何结果，抛出错误
    if (!searchResults.results || searchResults.results.length === 0) {
      throw new ApiError(`未找到名为"${actor_name}"的演员`, 404);
    }
    
    // 使用第一个搜索结果
    const personId = searchResults.results[0].id;
    
    // 并行获取演员详情和参演作品列表
    const [personDetails, personCredits] = await Promise.all([
      tmdbClient.getPersonDetails(personId),
      tmdbClient.getPersonTvCredits(personId)
    ]);
    
    // 格式化演员信息
    const actorInfo: ActorInfo = {
      id: personDetails.id,
      name: personDetails.name,
      biography: personDetails.biography || '暂无简介',
      profile_path: personDetails.profile_path,
      popularity: personDetails.popularity || 0,
      birthday: personDetails.birthday,
      place_of_birth: personDetails.place_of_birth,
      homepage: personDetails.homepage,
      also_known_as: personDetails.also_known_as
    };
    
    // 格式化参演作品列表
    // 优先展示主演角色（cast）而非幕后角色（crew）
    const credits: CreditInfo[] = (personCredits.cast || []).map((credit: any) => ({
      show_id: credit.id,
      show_title: credit.name || credit.original_name,
      character: credit.character || '未知角色',
      poster_path: credit.poster_path,
      vote_average: credit.vote_average || 0,
      first_air_date: credit.first_air_date
    }));
    
    // 按评分降序排序
    credits.sort((a, b) => b.vote_average - a.vote_average);
    
    return {
      actor: actorInfo,
      credits
    };
  } catch (error) {
    if (error instanceof ApiError) {
      throw error;
    }
    throw new Error(`获取演员"${actor_name}"的信息失败: ${error instanceof Error ? error.message : String(error)}`);
  }
}

src/server.ts:141-153 (registration)

Registers the MCP tool 'get_actor_details_and_credits' with Zod input schema for actor_name and calls the handler function.

// 注册获取演员信息和作品的工具
server.tool("get_actor_details_and_credits",
  { 
    actor_name: z.string().describe('演员名称，如"布莱恩·科兰斯顿"、"安东尼·斯塔尔"等')
  },
  async (params) => {
    console.log(`收到获取演员信息和作品请求，演员名称: ${params.actor_name}`);
    const results = await getActorDetailsAndCredits(params);
    return {
      content: [{ type: "text", text: JSON.stringify(results) }]
    };
  }
);

src/tools/actorInfoTool.ts:7-62 (schema)

TypeScript interfaces defining input parameters (GetActorInfoParams), actor details (ActorInfo), credit info (CreditInfo), and response structure (ActorInfoResponse).

export interface GetActorInfoParams {
  /** 演员姓名 */
  actor_name: string;
}

/**
 * 演员基本信息接口
 */
export interface ActorInfo {
  /** 演员ID */
  id: number;
  /** 演员姓名 */
  name: string;
  /** 演员简介 */
  biography: string;
  /** 演员照片路径 */
  profile_path: string | null;
  /** 演员人气 */
  popularity: number;
  /** 生日 */
  birthday?: string;
  /** 出生地 */
  place_of_birth?: string;
  /** 官方主页 */
  homepage?: string | null;
  /** 也被称为 */
  also_known_as?: string[];
}

/**
 * 演员参演作品接口
 */
export interface CreditInfo {
  /** 剧集ID */
  show_id: number;
  /** 剧集标题 */
  show_title: string;
  /** 角色名称 */
  character: string;
  /** 剧集海报路径 */
  poster_path: string | null;
  /** 剧集评分 */
  vote_average: number;
  /** 首播日期 */
  first_air_date?: string;
}

/**
 * 演员信息与作品响应接口
 */
export interface ActorInfoResponse {
  /** 演员基本信息 */
  actor: ActorInfo;
  /** 演员参演作品列表 */
  credits: CreditInfo[];
}

src/tools/index.ts:40-46 (registration)

Re-exports the handler function and types from actorInfoTool.ts for use in other modules like server.ts.

export {
  getActorDetailsAndCredits,
  type GetActorInfoParams,
  type ActorInfoResponse,
  type ActorInfo,
  type CreditInfo
} from './actorInfoTool';

tv-recommender-mcp-server