search_tv

Instructions

Implementation Reference

• src/index.ts:58-73 (registration)

  Registration of the 'search_tv' tool using server.tool() with name, description, schema, and handler. It calls tmdbFetch to /search/tv and returns summarized results via summarizeList.

  server.tool(
    "search_tv",
    "Search TMDB for TV shows by title.",
    { query: z.string().min(1, "query is required") },
    async ({ query }) => {
      try {
        const data = await tmdbFetch<{ results: any[] }>("/search/tv", {
          query,
          include_adult: "false",
        });
        return jsonResult({ results: summarizeList(data.results) });
      } catch (err) {
        return errorResult(err);
      }
    }
  );

• src/index.ts:62-72 (handler)

  Handler for 'search_tv': async function that takes { query }, calls tmdbFetch to /search/tv endpoint, formats results with summarizeList, and returns JSON content or an error.

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

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

  Input schema for 'search_tv': expects a required string 'query' validated via Zod (z.string().min(1)).

  { query: z.string().min(1, "query is required") },

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

  The tmdbFetch helper that makes authenticated HTTP requests to TMDB API. Used by the search_tv handler to call /search/tv.

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

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

  The summarizeList helper used to format and limit search results returned by search_tv.

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