Labsco
patw logo

MongoDB Movie Database FastMCP Tools

from patw

A server for querying and analyzing the MongoDB sample_mflix movie database.

🔥🔥✓ VerifiedFreeAdvanced setup
#automation#database#git

MongoDB Movie Database FastMCP Tools

This project provides a Python script that exposes a set of powerful tools for querying and analyzing a MongoDB movie database (specifically the sample_mflix dataset) using the fastmcp library. These tools are designed to be easily integrated with large language models (LLMs), AI agents, or any other system requiring structured, programmatic access to movie data.

Table of Contents

Features

  • Comprehensive Movie Search: Find movies by title, genre, actors, directors, writers, year, or various rating thresholds.
  • Flexible Data Retrieval: Specify fields to return (projection_fields) and control sorting (sort_by, sort_order_asc).
  • Movie Counting: Quickly count movies matching specific criteria.
  • Average Rating Calculation: Compute average IMDb, Metacritic, or Rotten Tomatoes ratings for filtered movie sets.
  • LLM-Friendly: Designed with fastmcp to create a robust, self-documenting API easily consumable by LLMs. Includes special handling for stringified list arguments, addressing common LLM output formats.
  • Robust MongoDB Integration: Utilizes pymongo for efficient and reliable database operations.

FastMCP Tools

This section details the functions exposed as tools by fastmcp.

find_movies

Finds movies based on a variety of criteria, with options for sorting and limiting results.

def find_movies(
title: Optional[str] = None,
genres: Optional[Union[List[str], str]] = None,
actors: Optional[Union[List[str], str]] = None,
directors: Optional[Union[List[str], str]] = None,
writers: Optional[Union[List[str], str]] = None,
year: Optional[int] = None,
start_year: Optional[int] = None,
end_year: Optional[int] = None,
min_imdb_rating: Optional[float] = None,
min_metacritic_rating: Optional[int] = None,
min_tomatoes_viewer_rating: Optional[float] = None,
min_tomatoes_critic_rating: Optional[float] = None,
rated_mpaa: Optional[str] = None,
sort_by: Optional[str] = "imdb.rating",
sort_order_asc: bool = False,
limit: int = 10,
projection_fields: Optional[List[str]] = None
) -> List[Dict[str, Any]]:

Args:

  • title (str, optional): Movie title (case-insensitive partial match).
  • genres (List[str] or str, optional): List of genres; movie must match all specified genres. If a single string is passed (e.g., "Comedy"), it's treated as a list of one.
  • actors (List[str] or str, optional): List of actor names; movie must feature all specified actors (case-insensitive partial match for each name within the cast list). If a single string is passed, it's treated as a list of one.
  • directors (List[str] or str, optional): List of director names; movie must be directed by all specified directors (case-insensitive partial match for each name). If a single string is passed, it's treated as a list of one.
  • writers (List[str] or str, optional): List of writer names; movie must include all specified writers (case-insensitive partial match for each name). If a single string is passed, it's treated as a list of one.
  • year (int, optional): Exact release year.
  • start_year (int, optional): Start of a release year range (inclusive).
  • end_year (int, optional): End of a release year range (inclusive).
  • min_imdb_rating (float, optional): Minimum IMDb rating (e.g., 7.5).
  • min_metacritic_rating (int, optional): Minimum Metacritic score (e.g., 70).
  • min_tomatoes_viewer_rating (float, optional): Minimum Rotten Tomatoes viewer rating (e.g., 3.5).
  • min_tomatoes_critic_rating (float, optional): Minimum Rotten Tomatoes critic rating (e.g., 7.0).
  • rated_mpaa (str, optional): MPAA rating (e.g., "R", "PG-13"). Case-insensitive exact match.
  • sort_by (str, optional): Field to sort results by. Can be a MongoDB path (e.g., "imdb.rating", "year", "title") or a short key ("imdb", "metacritic", "tomatoes_viewer", "tomatoes_critic", "imdb_votes", "tomatoes_viewer_num_reviews", "tomatoes_critic_num_reviews"). Defaults to 'imdb.rating'.
  • sort_order_asc (bool, optional): Sort order. False for descending (default, e.g., highest rated first), True for ascending (e.g., lowest rated first).
  • limit (int, optional): Maximum number of results to return. Defaults to 10. Use 0 for no limit.
  • projection_fields (List[str], optional): Specific fields to return for each movie (e.g., ["title", "year"]). Defaults to a standard set (title, year, plot, imdb.rating, genres).

Returns:

  • List[Dict[str, Any]]: A list of movie documents (or specified fields). Returns an empty list if no movies match the criteria or an error occurs.

count_movies

Counts movies based on the specified criteria.

def count_movies(
title: Optional[str] = None,
genres: Optional[Union[List[str], str]] = None,
actors: Optional[Union[List[str], str]] = None,
directors: Optional[Union[List[str], str]] = None,
writers: Optional[Union[List[str], str]] = None,
year: Optional[int] = None,
start_year: Optional[int] = None,
end_year: Optional[int] = None,
min_imdb_rating: Optional[float] = None,
min_metacritic_rating: Optional[int] = None,
min_tomatoes_viewer_rating: Optional[float] = None,
min_tomatoes_critic_rating: Optional[float] = None,
rated_mpaa: Optional[str] = None
) -> int:

Args: (Same as the filtering arguments for the find_movies tool)

Returns:

  • int: The number of movies matching the criteria. Returns 0 if an error occurs.

get_average_rating

Calculates the average rating for movies matching the criteria, for a specific rating type.

def get_average_rating(
rating_field_key: str,
genres: Optional[Union[List[str], str]] = None,
actors: Optional[Union[List[str], str]] = None,
directors: Optional[Union[List[str], str]] = None,
writers: Optional[Union[List[str], str]] = None,
year: Optional[int] = None,
start_year: Optional[int] = None,
end_year: Optional[int] = None
) -> Optional[Dict[str, Any]]:

Args:

  • rating_field_key (str): The key for the rating source (e.g., "imdb", "metacritic", "tomatoes_viewer", "tomatoes_critic").
  • (Other filtering arguments are similar to those in find_movies/count_movies, excluding title, min_ratings, and rated_mpaa as they are less common for broad average calculations).

Returns:

  • Optional[Dict[str, Any]]: A dictionary containing 'average_rating' (float, rounded to 2 decimal places) and 'movie_count' (int). Returns None if the rating_field_key is invalid, or a dict with None average_rating and 0 count if no movies match or an error occurs.