MongoDB Movie Database FastMCP Tools

Um servidor para consultar e analisar o banco de dados de filmes sample_mflix do MongoDB.

GitHubExperimente este MCPPatrocinado

Documentação

MongoDB Movie Database FastMCP Tools

Este projeto fornece um script Python que expõe um conjunto de ferramentas poderosas para consultar e analisar um banco de dados MongoDB de filmes (especificamente o conjunto de dados sample_mflix) usando a biblioteca fastmcp. Essas ferramentas são projetadas para serem facilmente integradas a grandes modelos de linguagem (LLMs), agentes de IA ou qualquer outro sistema que exija acesso estruturado e programático a dados de filmes.

Sumário

Recursos

  • Busca Abrangente de Filmes: Encontre filmes por título, gênero, atores, diretores, roteiristas, ano ou vários limites de classificação.
  • Recuperação Flexível de Dados: Especifique campos a retornar (projection_fields) e controle a ordenação (sort_by, sort_order_asc).
  • Contagem de Filmes: Conte rapidamente filmes que correspondem a critérios específicos.
  • Cálculo de Classificação Média: Calcule classificações médias do IMDb, Metacritic ou Rotten Tomatoes para conjuntos de filmes filtrados.
  • Amigável para LLMs: Projetado com fastmcp para criar uma API robusta e autodocumentada facilmente consumível por LLMs. Inclui tratamento especial para argumentos de lista em formato de string, abordando formatos de saída comuns de LLMs.
  • Integração Robusta com MongoDB: Utiliza pymongo para operações de banco de dados eficientes e confiáveis.

Pré-requisitos

Antes de executar este projeto, certifique-se de ter o seguinte:

  • Python 3.7+: Baixar Python
  • Instância MongoDB: Uma instância MongoDB em execução (local ou hospedada na nuvem, como MongoDB Atlas).
  • Conjunto de Dados sample_mflix: O banco de dados sample_mflix e sua coleção movies devem ser carregados na sua instância MongoDB.

Opcionalmente

  • Claude Desktop
{
  "mcpServers": {
    "Movie Database": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp, pymongo",
        "fastmcp",
        "run",
        "<path to>/movie-mcp/movie-mcp.py",
        "<mongo connection string URI>"
      ]
    }
  }
}

Configuração do MongoDB

Este aplicativo se conecta ao banco de dados sample_mflix e especificamente à coleção movies.

Se você estiver usando MongoDB Atlas:

  1. Faça login na sua conta MongoDB Atlas.
  2. Navegue até o seu cluster.
  3. Vá para a aba "..." (geralmente Data ou Load Sample Data).
  4. Clique em "Carregar Conjunto de Dados de Exemplo" e selecione sample_mflix. Isso importará automaticamente os dados necessários.

Se você estiver usando uma instância MongoDB local: Você pode baixar o conjunto de dados sample_mflix dos recursos oficiais do MongoDB (por exemplo, como parte dos materiais do curso MongoDB University ou diretamente de seus repositórios de dados de exemplo) e importá-lo usando mongoimport.

Instalação

  1. Clone o repositório:
git clone https://github.com/patw/movie-mcp.git
cd movie-mcp
  1. Instale as dependências:
pip install -r requirements.txt

Uso

O script espera a URI de conexão do MongoDB como um argumento de linha de comando.

  1. Execute o script:
python movie_tools.py "mongodb://localhost:27017/"

Ou, se estiver usando uma string de conexão MongoDB Atlas:

python movie_tools.py "mongodb+srv://user:pass@clusterdomain/?retryWrites=true&w=majority"

Substitua user, pass e clusterdomain pelas suas credenciais reais do MongoDB Atlas e detalhes do cluster.

  1. Servidor FastMCP: Após a execução, o script iniciará um servidor fastmcp. Este servidor expõe as ferramentas definidas (por exemplo, find_movies, count_movies) em um endpoint HTTP local (por padrão http://127.0.0.1:8000/tools). Você pode então interagir com essas ferramentas programaticamente, geralmente a partir de um agente LLM ou outro script Python.

Exemplo de como um LLM ou outro programa pode chamar essas ferramentas (conceitualmente):

# This is pseudo-code representing how an LLM agent might interact
# In a real scenario, you'd use a client library for fastmcp or direct HTTP requests.

# Example: Find movies by Bill Murray
tool_call = {
"tool_name": "find_movies",
"args": {
"actors": ["Bill Murray"],
"limit": 5,
"projection_fields": ["title", "year", "imdb.rating"]
}
}
# result = make_tool_call(tool_call)
# print(result)

# Example: Count romantic comedies from the 90s
tool_call = {
"tool_name": "count_movies",
"args": {
"genres": ["Comedy", "Romance"],
"start_year": 1990,
"end_year": 1999
}
}
# result = make_tool_call(tool_call)
# print(result)

Ferramentas FastMCP

Esta seção detalha as funções expostas como ferramentas pelo fastmcp.

find_movies

Encontra filmes com base em uma variedade de critérios, com opções de ordenação e limitação de resultados.

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]]:

Argumentos:

  • title (str, opcional): Título do filme (correspondência parcial sem diferenciar maiúsculas de minúsculas).
  • genres (List[str] ou str, opcional): Lista de gêneros; o filme deve corresponder a todos os gêneros especificados. Se uma única string for passada (por exemplo, "Comédia"), ela é tratada como uma lista de um elemento.
  • actors (List[str] ou str, opcional): Lista de nomes de atores; o filme deve apresentar todos os atores especificados (correspondência parcial sem diferenciar maiúsculas de minúsculas para cada nome na lista de elenco). Se uma única string for passada, ela é tratada como uma lista de um elemento.
  • directors (List[str] ou str, opcional): Lista de nomes de diretores; o filme deve ser dirigido por todos os diretores especificados (correspondência parcial sem diferenciar maiúsculas de minúsculas para cada nome). Se uma única string for passada, ela é tratada como uma lista de um elemento.
  • writers (List[str] ou str, opcional): Lista de nomes de roteiristas; o filme deve incluir todos os roteiristas especificados (correspondência parcial sem diferenciar maiúsculas de minúsculas para cada nome). Se uma única string for passada, ela é tratada como uma lista de um elemento.
  • year (int, opcional): Ano de lançamento exato.
  • start_year (int, opcional): Início de um intervalo de anos de lançamento (inclusivo).
  • end_year (int, opcional): Fim de um intervalo de anos de lançamento (inclusivo).
  • min_imdb_rating (float, opcional): Classificação mínima do IMDb (por exemplo, 7,5).
  • min_metacritic_rating (int, opcional): Pontuação mínima do Metacritic (por exemplo, 70).
  • min_tomatoes_viewer_rating (float, opcional): Classificação mínima do público do Rotten Tomatoes (por exemplo, 3,5).
  • min_tomatoes_critic_rating (float, opcional): Classificação mínima dos críticos do Rotten Tomatoes (por exemplo, 7,0).
  • rated_mpaa (str, opcional): Classificação MPAA (por exemplo, "R", "PG-13"). Correspondência exata sem diferenciar maiúsculas de minúsculas.
  • sort_by (str, opcional): Campo para ordenar os resultados. Pode ser um caminho MongoDB (por exemplo, "imdb.rating", "year", "title") ou uma chave curta ("imdb", "metacritic", "tomatoes_viewer", "tomatoes_critic", "imdb_votes", "tomatoes_viewer_num_reviews", "tomatoes_critic_num_reviews"). O padrão é 'imdb.rating'.
  • sort_order_asc (bool, opcional): Ordem de classificação. False para decrescente (padrão, por exemplo, mais bem avaliados primeiro), True para crescente (por exemplo, menos bem avaliados primeiro).
  • limit (int, opcional): Número máximo de resultados a retornar. O padrão é 10. Use 0 para sem limite.
  • projection_fields (List[str], opcional): Campos específicos a retornar para cada filme (por exemplo, ["title", "year"]). O padrão é um conjunto padrão (title, year, plot, imdb.rating, genres).

Retorna:

  • List[Dict[str, Any]]: Uma lista de documentos de filmes (ou campos especificados). Retorna uma lista vazia se nenhum filme corresponder aos critérios ou ocorrer um erro.

count_movies

Conta filmes com base nos critérios especificados.

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:

Argumentos: (O mesmo que os argumentos de filtragem para a ferramenta find_movies)

Retorna:

  • int: O número de filmes que correspondem aos critérios. Retorna 0 se ocorrer um erro.

get_average_rating

Calcula a classificação média para filmes que correspondem aos critérios, para um tipo específico de classificação.

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]]:

Argumentos:

  • rating_field_key (str): A chave para a fonte de classificação (por exemplo, "imdb", "metacritic", "tomatoes_viewer", "tomatoes_critic").
  • (Outros argumentos de filtragem são semelhantes aos de find_movies/count_movies, excluindo title, min_ratings e rated_mpaa, pois são menos comuns para cálculos amplos de média).

Retorna:

  • Optional[Dict[str, Any]]: Um dicionário contendo 'average_rating' (float, arredondado para 2 casas decimais) e 'movie_count' (int). Retorna None se o rating_field_key for inválido, ou um dicionário com None average_rating e 0 count se nenhum filme corresponder ou ocorrer um erro.

Contribuição

Contribuições são bem-vindas! Se você tiver sugestões de melhorias, novos recursos ou correções de bugs, abra uma issue ou envie um pull request.

Licença

Este projeto é de código aberto sob a Licença MIT. Consulte o arquivo LICENSE para mais detalhes.