wizzy-mcp-tmdb

Instructions

Implementation Reference

• mcp-tmdb-server.js:241-260 (handler)

  The core handler function for the 'search_tmdb' tool. It validates the query input, fetches multi-search results from TMDB's /search/multi endpoint, normalizes the results using mapSearchResult, and returns a formatted JSON response wrapped in MCP content.
  handler: async ({query, page, language, include_adult, region}) => { if (!query || typeof query !== "string") { throw new Error("query must be a non-empty string"); } const data = await tmdbFetch("/search/multi", {query, page, language, include_adult, region}); const results = Array.isArray(data.results) ? data.results.map(mapSearchResult) : []; return { content: [ { type: "text", text: JSON.stringify({ page: data.page, total_pages: data.total_pages, total_results: data.total_results, results }, null, 2), }, ], }; },
• mcp-tmdb-server.js:229-240 (schema)

  The input schema for the 'search_tmdb' tool, defining the expected parameters, types, descriptions, and validation rules.
  inputSchema: { type: "object", properties: { query: {type: "string", description: "Search text query"}, page: {type: "number", minimum: 1, description: "Page number (1-1000)"}, language: {type: "string", description: "ISO 639-1 code (e.g., en-US)"}, include_adult: {type: "boolean", description: "Include adult results"}, region: {type: "string", description: "ISO 3166-1 code (e.g., US)"}, }, required: ["query"], additionalProperties: false, },
• mcp-tmdb-server.js:41-55 (helper)

  Helper function used by the search_tmdb handler (and similar tools) to normalize TMDB search results into a compact format with id, media_type, title, date, etc., for easier AI consumption.
  function mapSearchResult(item) { const media_type = item.media_type || (item.title ? "movie" : item.name ? "tv" : "unknown"); const title = item.title || item.name || ""; const date = item.release_date || item.first_air_date || ""; return { id: item.id, media_type, title, date, original_language: item.original_language, popularity: item.popularity, vote_average: item.vote_average, overview: item.overview, }; }
• mcp-tmdb-server.js:771-789 (registration)

  The MCP server request handler for tool calls. It looks up the tool by name from the 'tools' array (which includes search_tmdb), executes its handler, handles logging and errors, and returns the result. This registers all tools including search_tmdb for invocation.
  server.setRequestHandler(CallToolRequestSchema, async (req) => { const {name, arguments: args} = req.params || {}; const tool = tools.find(t => t.name === name); if (!tool) { await sendLog("error", `Unknown tool called: ${name || "<missing>"} with args: ${JSON.stringify(args || {})}`); throw new Error(`Unknown tool: ${name}`); } await sendLog("info", `Calling tool: ${name} with args: ${JSON.stringify(args || {})}`); try { const start = Date.now(); const res = await tool.handler(args || {}); const ms = Date.now() - start; await sendLog("info", `Tool success: ${name} in ${ms}ms`); return res; } catch (err) { await sendLog("error", `Tool error: ${name} -> ${err && err.message ? err.message : String(err)}`); throw err; } });
• mcp-tmdb-server.js:18-38 (helper)

  Core helper function for making authenticated API requests to TMDB, used by the search_tmdb handler to fetch data from /search/multi.
  async function tmdbFetch(path, params = {}) { if (!TMDB_AUTH_TOKEN) { throw new Error("TMDB authorization token is not configured"); } const url = new URL(TMDB_BASE + path); Object.entries(params).forEach(([k, v]) => { if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v)); }); const res = await fetch(url, { headers: { Accept: "application/json", Authorization: TMDB_AUTH_TOKEN, }, }); if (!res.ok) { const text = await res.text().catch(() => ""); throw new Error(`TMDB request failed ${res.status}: ${text}`); } return res.json(); }