get_similar

Instructions

Implementation Reference

• src/index.ts:107-121 (registration)

  The server.tool() call that registers 'get_similar' with its schema and handler function.

  server.tool(
    "get_similar",
    "Get movies similar to a given movie.",
    { movie_id: z.number().int().positive() },
    async ({ movie_id }) => {
      try {
        const data = await tmdbFetch<{ results: any[] }>(
          `/movie/${movie_id}/similar`
        );
        return jsonResult({ results: summarizeList(data.results) });
      } catch (err) {
        return errorResult(err);
      }
    }
  );

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

  Zod schema for get_similar: requires movie_id as a positive integer.

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

• src/index.ts:107-121 (handler)

  The async handler for get_similar: calls TMDB /movie/{movie_id}/similar endpoint and returns summarized results.

  server.tool(
    "get_similar",
    "Get movies similar to a given movie.",
    { movie_id: z.number().int().positive() },
    async ({ movie_id }) => {
      try {
        const data = await tmdbFetch<{ results: any[] }>(
          `/movie/${movie_id}/similar`
        );
        return jsonResult({ results: summarizeList(data.results) });
      } catch (err) {
        return errorResult(err);
      }
    }
  );

• src/shape.ts:32-34 (helper)

  summarizeList helper used by get_similar to format the movie results array (limited to 20 items).

  export function summarizeList(items: RawMovie[] | undefined, limit = 20) {
    return (items ?? []).slice(0, limit).map(summarizeMovie);
  }

• src/tmdb.ts:21-67 (helper)

  tmdbFetch helper used by get_similar to make authenticated HTTP requests to the TMDB API.

  export async function tmdbFetch<T = unknown>(
    path: string,
    query: Record<string, string | number | undefined> = {}
  ): Promise<T> {
    const url = new URL(BASE_URL + path);
    for (const [k, v] of Object.entries(query)) {
      if (v !== undefined && v !== null && v !== "") {
        url.searchParams.set(k, String(v));
      }
    }
  
    const res = await fetch(url, {
      headers: {
        Authorization: `Bearer ${getToken()}`,
        Accept: "application/json",
      },
    });
  
    if (!res.ok) {
      const text = await res.text().catch(() => "");
      if (res.status === 401) {
        throw new TmdbError(
          "TMDB rejected the request (401). Check that TMDB_API_KEY is your v4 read access token, not a v3 API key.",
          401
        );
      }
      if (res.status === 404) {
        throw new TmdbError(
          `TMDB resource not found (404) for ${path}. Verify the ID exists.`,
          404
        );
      }
      if (res.status === 429) {
        const retry = res.headers.get("retry-after");
        throw new TmdbError(
          `TMDB rate limit exceeded (429).${retry ? ` Retry after ${retry}s.` : " Slow down requests and retry."}`,
          429
        );
      }
      throw new TmdbError(
        `TMDB request failed (${res.status}) for ${path}: ${text || res.statusText}`,
        res.status
      );
    }
  
    return (await res.json()) as T;
  }