Movie Search MCP Server

Implementation Reference

• src/index.ts:96-171 (handler)

  MCP tool handler for 'get_movie_details': fetches movie details via API wrapper, handles errors, and formats a rich text response with movie info.

  async ({ id, source }) => {
    try {
      const details = await getMovieDetails(id, source);
  
      if (!details) {
        return {
          content: [
            {
              type: "text",
              text: `❌ No details found for movie with ID "${id}" in ${source.toUpperCase()}.`,
            },
          ],
        };
      }
  
      let response = `🎬 **${details.title}** (${details.year})\n\n`;
      response += `📝 **Plot:** ${details.plot}\n\n`;
      response += `🎭 **Genre:** ${details.genre}\n`;
      response += `⭐ **Rating:** ${details.rating}\n`;
      response += `⏱️ **Runtime:** ${details.runtime || "N/A"}\n`;
  
      if (details.director) {
        response += `🎬 **Director:** ${details.director}\n`;
      }
  
      if (details.actors) {
        response += `👥 **Main Cast:** ${details.actors}\n`;
      }
  
      if (details.language) {
        response += `🌍 **Language:** ${details.language}\n`;
      }
  
      if (details.country) {
        response += `🏴 **Country:** ${details.country}\n`;
      }
  
      if (details.awards && details.awards !== "N/A") {
        response += `🏆 **Awards:** ${details.awards}\n`;
      }
  
      if (details.boxOffice && details.boxOffice !== "N/A") {
        response += `💰 **Box Office:** ${details.boxOffice}\n`;
      }
  
      if (details.imdbId) {
        response += `🔗 **IMDB ID:** ${details.imdbId}\n`;
      }
  
      response += `\n📊 **Source:** ${details.source.toUpperCase()}`;
  
      if (details.poster !== "N/A") {
        response += `\n\n🖼️ **Poster:** ${details.poster}`;
      }
  
      return {
        content: [
          {
            type: "text",
            text: response,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `❌ Error getting details: ${
              error instanceof Error ? error.message : "Unknown error"
            }`,
          },
        ],
      };
    }
  }

• src/index.ts:89-95 (schema)

  Zod schema for input validation of 'get_movie_details' tool parameters: id (string) and source (enum omdb|tmdb, default omdb).

  {
    id: z.string().describe("Movie ID (IMDB ID or TMDb ID)"),
    source: z
      .enum(["omdb", "tmdb"])
      .default("omdb")
      .describe("Data source (omdb or tmdb)"),
  },

• src/index.ts:87-172 (registration)

  Registration of the 'get_movie_details' MCP tool on the server using server.tool(name, inputSchema, handlerFn).

  server.tool(
    "get_movie_details",
    {
      id: z.string().describe("Movie ID (IMDB ID or TMDb ID)"),
      source: z
        .enum(["omdb", "tmdb"])
        .default("omdb")
        .describe("Data source (omdb or tmdb)"),
    },
    async ({ id, source }) => {
      try {
        const details = await getMovieDetails(id, source);
  
        if (!details) {
          return {
            content: [
              {
                type: "text",
                text: `❌ No details found for movie with ID "${id}" in ${source.toUpperCase()}.`,
              },
            ],
          };
        }
  
        let response = `🎬 **${details.title}** (${details.year})\n\n`;
        response += `📝 **Plot:** ${details.plot}\n\n`;
        response += `🎭 **Genre:** ${details.genre}\n`;
        response += `⭐ **Rating:** ${details.rating}\n`;
        response += `⏱️ **Runtime:** ${details.runtime || "N/A"}\n`;
  
        if (details.director) {
          response += `🎬 **Director:** ${details.director}\n`;
        }
  
        if (details.actors) {
          response += `👥 **Main Cast:** ${details.actors}\n`;
        }
  
        if (details.language) {
          response += `🌍 **Language:** ${details.language}\n`;
        }
  
        if (details.country) {
          response += `🏴 **Country:** ${details.country}\n`;
        }
  
        if (details.awards && details.awards !== "N/A") {
          response += `🏆 **Awards:** ${details.awards}\n`;
        }
  
        if (details.boxOffice && details.boxOffice !== "N/A") {
          response += `💰 **Box Office:** ${details.boxOffice}\n`;
        }
  
        if (details.imdbId) {
          response += `🔗 **IMDB ID:** ${details.imdbId}\n`;
        }
  
        response += `\n📊 **Source:** ${details.source.toUpperCase()}`;
  
        if (details.poster !== "N/A") {
          response += `\n\n🖼️ **Poster:** ${details.poster}`;
        }
  
        return {
          content: [
            {
              type: "text",
              text: response,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `❌ Error getting details: ${
                error instanceof Error ? error.message : "Unknown error"
              }`,
            },
          ],
        };
      }
    }
  );

• src/movie-apis.ts:222-231 (helper)

  Helper function getMovieDetails: dispatches to specific OMDb or TMDb detail fetchers based on source.

  export async function getMovieDetails(
    id: string,
    source: "omdb" | "tmdb" = "omdb"
  ): Promise<MovieInfo | null> {
    if (source === "omdb") {
      return await getMovieDetailsOMDb(id);
    } else {
      return await getMovieDetailsTMDb(id);
    }
  }

• src/movie-apis.ts:59-97 (helper)

  OMDb-specific implementation: fetches and maps movie details from OMDb API using IMDB ID.

  export async function getMovieDetailsOMDb(
    imdbId: string
  ): Promise<MovieInfo | null> {
    try {
      const params = new URLSearchParams({
        apikey: OMDB_API_KEY,
        i: imdbId,
        plot: "full",
      });
  
      const response = await fetch(`${OMDB_BASE_URL}?${params}`);
      const data = (await response.json()) as OMDbMovie;
  
      if (data.Response === "False") {
        return null;
      }
  
      return {
        title: data.Title,
        year: data.Year,
        director: data.Director,
        actors: data.Actors,
        plot: data.Plot,
        genre: data.Genre,
        rating: data.imdbRating,
        poster: data.Poster,
        imdbId: data.imdbID,
        runtime: data.Runtime,
        language: data.Language,
        country: data.Country,
        awards: data.Awards,
        boxOffice: data.BoxOffice,
        source: "omdb",
      };
    } catch (error) {
      console.error("Error getting movie details from OMDb:", error);
      return null;
    }
  }

• src/movie-apis.ts:143-194 (helper)

  TMDb-specific implementation: fetches movie details from TMDb API using TMDb ID, appends credits for cast/director.

  export async function getMovieDetailsTMDb(
    tmdbId: string
  ): Promise<MovieInfo | null> {
    if (!TMDB_API_KEY) {
      return null;
    }
  
    try {
      const params = new URLSearchParams({
        api_key: TMDB_API_KEY,
        language: "en-US",
        append_to_response: "credits",
      });
  
      const response = await fetch(`${TMDB_BASE_URL}/movie/${tmdbId}?${params}`);
      const data = (await response.json()) as TMDbMovieDetails & {
        credits?: any;
      };
  
      const director =
        data.credits?.crew?.find((person: any) => person.job === "Director")
          ?.name || "N/A";
      const actors =
        data.credits?.cast
          ?.slice(0, 5)
          .map((actor: any) => actor.name)
          .join(", ") || "N/A";
  
      return {
        title: data.title,
        year: data.release_date ? data.release_date.split("-")[0] : "",
        director: director,
        actors: actors,
        plot: data.overview,
        genre: data.genres.map((g) => g.name).join(", "),
        rating: data.vote_average.toString(),
        poster: data.poster_path
          ? `https://image.tmdb.org/t/p/w500${data.poster_path}`
          : "N/A",
        imdbId: data.imdb_id,
        runtime: data.runtime ? `${data.runtime} min` : "N/A",
        language: data.original_language,
        country: data.production_countries.map((c) => c.name).join(", "),
        awards: "N/A", // TMDb no proporciona premios directamente
        boxOffice: data.revenue ? `$${data.revenue.toLocaleString()}` : "N/A",
        source: "tmdb",
      };
    } catch (error) {
      console.error("Error getting movie details from TMDb:", error);
      return null;
    }
  }