search_movies
Find movies by title and optionally filter by release year to get accurate results from TMDB.
Instructions
Search TMDB for movies by title, optionally filtered by release year.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Movie title or keywords. | |
| year | No | Release year filter. |
Implementation Reference
- src/tools.ts:80-92 (handler)Main handler function for the search_movies tool. Calls TMDB /search/movie endpoint with query and optional year, then maps results through summarizeMovie.
export async function searchMovies(args: { query: string; year?: number }) { const data = await tmdbGet<PaginatedResponse<MovieListItem>>("/search/movie", { query: args.query, year: args.year, include_adult: "false", language: "en-US", }); return { page: data.page, total_results: data.total_results, results: data.results.map(summarizeMovie), }; } - src/tools.ts:75-78 (schema)Zod schema defining the input parameters: query (required string) and year (optional integer between 1880-2100).
export const searchMoviesSchema = { query: z.string().min(1).describe("Movie title or keywords."), year: z.number().int().min(1880).max(2100).optional().describe("Release year filter."), }; - src/index.ts:60-65 (registration)Registration of the 'search_movies' tool on the McpServer with its schema and wrapped handler.
server.tool( "search_movies", "Search TMDB for movies by title, optionally filtered by release year.", searchMoviesSchema, wrap(searchMovies), ); - src/tools.ts:41-50 (helper)Helper function summarizeMovie used by searchMovies to format each movie result.
function summarizeMovie(m: MovieListItem) { return { id: m.id, title: m.title, year: yearOf(m.release_date), overview: m.overview ?? null, rating: m.vote_average ?? null, poster: posterUrl(m.poster_path), }; } - src/index.ts:44-52 (helper)The wrap() utility that catches errors and formats the result into a ToolResult.
function wrap<T>(fn: (args: T) => Promise<unknown>) { return async (args: T): Promise<ToolResult> => { try { return ok(await fn(args)); } catch (err) { return fail(err); } }; }