get_movie_details

Instructions

Implementation Reference

• src/index.ts:75-89 (handler)

  The tool handler for 'get_movie_details'. It calls TMDB /movie/{movie_id} with credits and videos appended, then formats the result via summarizeDetails.

  server.tool(
    "get_movie_details",
    "Get full details for a movie, including top cast, directors, and trailer.",
    { movie_id: z.number().int().positive() },
    async ({ movie_id }) => {
      try {
        const data = await tmdbFetch(`/movie/${movie_id}`, {
          append_to_response: "credits,videos",
        });
        return jsonResult(summarizeDetails(data as any));
      } catch (err) {
        return errorResult(err);
      }
    }
  );

• src/index.ts:78-78 (schema)

  Zod schema for the tool's input: movie_id is a positive integer.

  { movie_id: z.number().int().positive() },

• src/shape.ts:60-91 (helper)

  summarizeDetails function that transforms raw TMDB movie details into a structured response with title, year, tagline, overview, rating, runtime, genres, status, homepage, imdb_id, poster, directors (top 10 cast), and YouTube trailer link.

  export function summarizeDetails(d: RawDetails) {
    const cast = (d.credits?.cast ?? [])
      .slice(0, 10)
      .map((c) => ({ name: c.name, character: c.character ?? null }));
    const directors = (d.credits?.crew ?? [])
      .filter((c) => c.job === "Director")
      .map((c) => c.name);
    const trailer = (d.videos?.results ?? []).find(
      (v) => v.site === "YouTube" && v.type === "Trailer" && v.official !== false
    );
  
    return {
      id: d.id,
      title: d.title ?? d.original_title ?? "",
      year: yearOf(d.release_date),
      tagline: d.tagline || null,
      overview: d.overview ?? "",
      rating: d.vote_average ?? null,
      vote_count: d.vote_count ?? null,
      runtime_minutes: d.runtime ?? null,
      genres: (d.genres ?? []).map((g) => g.name),
      status: d.status ?? null,
      homepage: d.homepage || null,
      imdb_id: d.imdb_id ?? null,
      poster: posterUrl(d.poster_path),
      directors,
      cast,
      trailer: trailer
        ? { name: trailer.name, youtube_url: `https://www.youtube.com/watch?v=${trailer.key}` }
        : null,
    };
  }

• src/tmdb.ts:69-77 (helper)

  posterUrl helper constructs the full image URL from TMDB's poster path.

  export function posterUrl(path: string | null | undefined): string | null {
    return path ? `${IMAGE_BASE}${path}` : null;
  }
  
  export function yearOf(date: string | null | undefined): number | null {
    if (!date) return null;
    const y = Number(date.slice(0, 4));
    return Number.isFinite(y) ? y : null;
  }

• src/tmdb.ts:73-77 (helper)

  yearOf helper extracts a 4-digit year from a date string.

  export function yearOf(date: string | null | undefined): number | null {
    if (!date) return null;
    const y = Number(date.slice(0, 4));
    return Number.isFinite(y) ? y : null;
  }