get_recommendations
Retrieve movie recommendations based on a specific movie's ID.
Instructions
Get TMDB recommendations for a given movie.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| movie_id | Yes |
Implementation Reference
- src/index.ts:91-105 (registration)The 'get_recommendations' tool is registered via server.tool() with a Zod schema for movie_id (positive integer). The handler calls TMDB /movie/{movie_id}/recommendations and returns summarized results.
server.tool( "get_recommendations", "Get TMDB recommendations for a given movie.", { movie_id: z.number().int().positive() }, async ({ movie_id }) => { try { const data = await tmdbFetch<{ results: any[] }>( `/movie/${movie_id}/recommendations` ); return jsonResult({ results: summarizeList(data.results) }); } catch (err) { return errorResult(err); } } ); - src/index.ts:92-105 (handler)The handler function that executes the tool logic: fetches recommendations from TMDB API and summarizes the list.
"get_recommendations", "Get TMDB recommendations for a given movie.", { movie_id: z.number().int().positive() }, async ({ movie_id }) => { try { const data = await tmdbFetch<{ results: any[] }>( `/movie/${movie_id}/recommendations` ); return jsonResult({ results: summarizeList(data.results) }); } catch (err) { return errorResult(err); } } ); - src/tmdb.ts:21-67 (helper)tmdbFetch is the helper used by the handler to make the API call to TMDB.
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)summarizeList transforms raw API results into a summarized format (used by the handler to format output).
export function summarizeList(items: RawMovie[] | undefined, limit = 20) { return (items ?? []).slice(0, limit).map(summarizeMovie); }