search_movies

Instructions

Implementation Reference

• src/index.ts:44-55 (handler)

  The async handler function for the search_movies tool. It receives { query, year }, calls tmdbFetch to TMDB's /search/movie endpoint, summarizes the results via summarizeList, and returns them as JSON.

  async ({ query, year }) => {
    try {
      const data = await tmdbFetch<{ results: any[] }>("/search/movie", {
        query,
        year,
        include_adult: "false",
      });
      return jsonResult({ results: summarizeList(data.results) });
    } catch (err) {
      return errorResult(err);
    }
  }

• src/index.ts:40-43 (schema)

  Zod schema for search_movies input: 'query' (required string, min length 1) and 'year' (optional integer 1800-2100).

  {
    query: z.string().min(1, "query is required"),
    year: z.number().int().min(1800).max(2100).optional(),
  },

• src/index.ts:37-56 (registration)

  Registration of the 'search_movies' tool via server.tool(), including its description string, input schema, and handler callback.

  server.tool(
    "search_movies",
    "Search TMDB for movies by title. Optionally filter by release year.",
    {
      query: z.string().min(1, "query is required"),
      year: z.number().int().min(1800).max(2100).optional(),
    },
    async ({ query, year }) => {
      try {
        const data = await tmdbFetch<{ results: any[] }>("/search/movie", {
          query,
          year,
          include_adult: "false",
        });
        return jsonResult({ results: summarizeList(data.results) });
      } catch (err) {
        return errorResult(err);
      }
    }
  );

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

  summarizeList helper function that takes raw movie results, limits to 20 items, and maps each through summarizeMovie to produce clean output.

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

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

  tmdbFetch helper function that makes authenticated HTTP requests to the TMDB API, with error handling for 401, 404, 429, and other HTTP errors.

  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;
  }