get_movie_details

Instructions

Implementation Reference

• src/tools.ts:143-179 (handler)

  The main handler function for the 'get_movie_details' tool. It fetches movie details from TMDB API (including credits and videos), extracts directors, top-10 cast (sorted by order), trailer URL, and returns a structured response.

  export async function getMovieDetails(args: { movie_id: number }) {
    const data = await tmdbGet<MovieDetails>(`/movie/${args.movie_id}`, {
      append_to_response: "credits,videos",
      language: "en-US",
    });
  
    const directors =
      data.credits?.crew?.filter((c) => c.job === "Director").map((c) => c.name) ?? [];
    const cast =
      data.credits?.cast
        ?.slice()
        .sort((a, b) => (a.order ?? 999) - (b.order ?? 999))
        .slice(0, 10)
        .map((c) => ({ name: c.name, character: c.character ?? null })) ?? [];
  
    const trailer = data.videos?.results?.find(
      (v) => v.site === "YouTube" && v.type === "Trailer" && v.official !== false,
    );
  
    return {
      id: data.id,
      title: data.title,
      year: yearOf(data.release_date),
      tagline: data.tagline ?? null,
      overview: data.overview ?? null,
      rating: data.vote_average ?? null,
      vote_count: data.vote_count ?? null,
      runtime_minutes: data.runtime ?? null,
      genres: data.genres?.map((g) => g.name) ?? [],
      directors,
      cast,
      poster: posterUrl(data.poster_path),
      homepage: data.homepage ?? null,
      imdb_id: data.imdb_id ?? null,
      trailer_url: trailer ? `https://www.youtube.com/watch?v=${trailer.key}` : null,
    };
  }

• src/tools.ts:139-141 (schema)

  Input schema for the 'get_movie_details' tool. Defines a single required parameter 'movie_id' as a positive integer.

  export const getMovieDetailsSchema = {
    movie_id: z.number().int().positive().describe("TMDB movie ID."),
  };

• src/tools.ts:111-137 (schema)

  TypeScript interface 'MovieDetails' describing the raw TMDB API response shape including credits (cast/crew) and videos.

  interface MovieDetails {
    id: number;
    title: string;
    release_date?: string | null;
    overview?: string | null;
    vote_average?: number | null;
    vote_count?: number | null;
    runtime?: number | null;
    poster_path?: string | null;
    genres?: Array<{ id: number; name: string }>;
    tagline?: string | null;
    homepage?: string | null;
    imdb_id?: string | null;
    credits?: {
      cast?: Array<{ id: number; name: string; character?: string; order?: number }>;
      crew?: Array<{ id: number; name: string; job?: string; department?: string }>;
    };
    videos?: {
      results?: Array<{
        key: string;
        site: string;
        type: string;
        name: string;
        official?: boolean;
      }>;
    };
  }

• src/index.ts:74-79 (registration)

  Registration of the 'get_movie_details' tool with the MCP server, binding the schema and wrapped handler.

  server.tool(
    "get_movie_details",
    "Fetch full details for a movie including cast, director, and trailer URL.",
    getMovieDetailsSchema,
    wrap(getMovieDetails),
  );

• src/tmdb.ts:66-68 (helper)

  Helper function 'posterUrl' used by the handler to construct full poster image URLs.

  export function posterUrl(path: string | null | undefined): string | null {
    return path ? `${IMAGE_BASE}${path}` : null;
  }