where_to_stream
Look up streaming, rental, and purchase options for a movie via TMDB ID. Optionally set a country code to view local availability.
Instructions
Show streaming, rental, and purchase options for a movie in a given country (defaults to US).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| movie_id | Yes | TMDB movie ID. | |
| country_code | No | ISO 3166-1 alpha-2 country code (defaults to US). |
Implementation Reference
- src/tools.ts:260-288 (handler)Core handler function that fetches watch provider data from TMDB API for a given movie and country, returning streaming/rent/buy/free options.
export async function whereToStream(args: { movie_id: number; country_code?: string }) { const country = (args.country_code ?? "US").toUpperCase(); const data = await tmdbGet<WatchProvidersResponse>( `/movie/${args.movie_id}/watch/providers`, ); const region = data.results[country]; if (!region) { return { movie_id: args.movie_id, country: country, link: null, stream: [], rent: [], buy: [], free: [], message: `No watch provider data for country '${country}'.`, }; } const names = (list?: ProviderEntry[]) => (list ?? []).map((p) => p.provider_name); return { movie_id: args.movie_id, country, link: region.link ?? null, stream: names(region.flatrate), rent: names(region.rent), buy: names(region.buy), free: [...names(region.free), ...names(region.ads)], }; } - src/tools.ts:251-258 (schema)Zod schema for the tool's input: movie_id (required positive int) and country_code (optional 2-letter ISO code).
export const whereToStreamSchema = { movie_id: z.number().int().positive().describe("TMDB movie ID."), country_code: z .string() .length(2) .optional() .describe("ISO 3166-1 alpha-2 country code (defaults to US)."), }; - src/index.ts:102-107 (registration)Registers the 'where_to_stream' tool on the MCP server with its schema and wrapped handler.
server.tool( "where_to_stream", "Show streaming, rental, and purchase options for a movie in a given country (defaults to US).", whereToStreamSchema, wrap(whereToStream), ); - src/tools.ts:230-249 (helper)TypeScript interfaces (ProviderEntry and WatchProvidersResponse) used as helper types for the whereToStream function.
interface ProviderEntry { provider_id: number; provider_name: string; logo_path?: string | null; } interface WatchProvidersResponse { id: number; results: Record< string, { link?: string; flatrate?: ProviderEntry[]; rent?: ProviderEntry[]; buy?: ProviderEntry[]; ads?: ProviderEntry[]; free?: ProviderEntry[]; } >; }