where_to_stream

Instructions

Implementation Reference

• src/index.ts:142-161 (registration)

  Registration of the 'where_to_stream' MCP tool using server.tool(). Defines input schema (movie_id, optional country_code) and calls the handler.

  server.tool(
    "where_to_stream",
    "Find streaming, rental, and purchase providers for a movie in a given country (default US). Data sourced from JustWatch via TMDB.",
    {
      movie_id: z.number().int().positive(),
      country_code: z
        .string()
        .length(2, "country_code must be a 2-letter ISO 3166-1 code")
        .optional(),
    },
    async ({ movie_id, country_code }) => {
      try {
        const country = (country_code ?? "US").toUpperCase();
        const data = await tmdbFetch(`/movie/${movie_id}/watch/providers`);
        return jsonResult(summarizeProviders(data as any, country));
      } catch (err) {
        return errorResult(err);
      }
    }
  );

• src/index.ts:152-160 (handler)

  Handler function for 'where_to_stream'. Fetches watch providers from TMDB API (/movie/{id}/watch/providers) and formats the response using summarizeProviders.

  async ({ movie_id, country_code }) => {
    try {
      const country = (country_code ?? "US").toUpperCase();
      const data = await tmdbFetch(`/movie/${movie_id}/watch/providers`);
      return jsonResult(summarizeProviders(data as any, country));
    } catch (err) {
      return errorResult(err);
    }
  }

• src/shape.ts:93-106 (schema)

  Type definition (RawProviders) for the TMDB watch providers API response shape, including flatrate, rent, buy, free, and ads provider arrays per country.

  interface RawProviders {
    id?: number;
    results?: Record<
      string,
      {
        link?: string;
        flatrate?: { provider_name: string }[];
        rent?: { provider_name: string }[];
        buy?: { provider_name: string }[];
        free?: { provider_name: string }[];
        ads?: { provider_name: string }[];
      }
    >;
  }

• src/shape.ts:108-129 (helper)

  Helper function summarizeProviders that extracts and formats streaming/rental/buy/free/ads provider names for a given country from the raw TMDB data.

  export function summarizeProviders(data: RawProviders, country: string) {
    const region = data.results?.[country.toUpperCase()];
    if (!region) {
      return {
        country: country.toUpperCase(),
        available: false,
        message: `No watch provider data for country ${country.toUpperCase()}.`,
      };
    }
    const names = (arr?: { provider_name: string }[]) =>
      (arr ?? []).map((p) => p.provider_name);
    return {
      country: country.toUpperCase(),
      available: true,
      link: region.link ?? null,
      stream: names(region.flatrate),
      free: names(region.free),
      ads: names(region.ads),
      rent: names(region.rent),
      buy: names(region.buy),
    };
  }