search_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();
  }