wizzy-mcp-tmdb

Instructions

Implementation Reference

• mcp-tmdb-server.js:343-357 (handler)

  The main handler function for the search_tmdb_tv tool. It fetches TV show search results from TMDB API endpoint '/search/tv', normalizes the results using mapSearchResult, and returns a formatted JSON response with pagination info.

  handler: async ({query, page, language, first_air_date_year, include_adult}) => {
      const data = await tmdbFetch('/search/tv', {query, page, language, first_air_date_year, include_adult});
      const 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:331-342 (schema)

  Input schema for validating parameters to the search_tmdb_tv tool, including required 'query' and optional filters.

  inputSchema: {
      type: "object",
      properties: {
          query: {type: "string", description: "Search query for TV shows"},
          page: {type: "number", minimum: 1, description: "Page number"},
          language: {type: "string", description: "ISO 639-1 code (e.g., en-US)"},
          first_air_date_year: {type: "number", description: "Filter by first air date year"},
          include_adult: {type: "boolean", description: "Include adult results"},
      },
      required: ["query"],
      additionalProperties: false,
  },

• mcp-tmdb-server.js:328-358 (registration)

  The tool registration object in the 'tools' array, defining name, description, inputSchema, and handler for search_tmdb_tv.

  {
      name: "search_tmdb_tv",
      description: "Searches specifically for TV shows in TMDB. Input: query (required search string), page (optional), language (optional ISO 639-1), first_air_date_year (optional year filter), include_adult (optional boolean). Output: JSON with paginated normalized results. Purpose: Targeted TV show discovery for AI-driven content queries.",
      inputSchema: {
          type: "object",
          properties: {
              query: {type: "string", description: "Search query for TV shows"},
              page: {type: "number", minimum: 1, description: "Page number"},
              language: {type: "string", description: "ISO 639-1 code (e.g., en-US)"},
              first_air_date_year: {type: "number", description: "Filter by first air date year"},
              include_adult: {type: "boolean", description: "Include adult results"},
          },
          required: ["query"],
          additionalProperties: false,
      },
      handler: async ({query, page, language, first_air_date_year, include_adult}) => {
          const data = await tmdbFetch('/search/tv', {query, page, language, first_air_date_year, include_adult});
          const 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:41-55 (helper)

  Helper function to normalize TMDB search results into a compact format (id, media_type, title, etc.) used in the tool handler.

  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:18-38 (helper)

  Core helper function that performs HTTP requests to the TMDB API, handles authentication with API key, and parses JSON responses. Used by the tool handler.

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