Movie Recommendation

Acompanha os filmes que você assistiu e fornece recomendações baseadas nas suas preferências.

GitHub
1
Experimente este MCPPatrocinado

Documentação

MediaSage

Um servidor Model Context Protocol (MCP) que acompanha filmes, livros e séries de TV, fornecendo recomendações inteligentes com base nas suas preferências. Construído com Bun, SQLite (via Drizzle ORM), e suporta conexões locais (stdio) e remotas (HTTP/SSE).

Recursos

  • Acompanhamento Multi-Mídia: Acompanhe filmes, livros e séries de TV com avaliações, status e notas
  • Filtragem Inteligente: Liste mídias por tipo, status, avaliação, gênero e mais
  • Recomendações Entre Mídias: Obtenha sugestões com base nas suas preferências em todos os tipos de mídia
  • Metadados Ricos: Busca automática de metadados do OMDB (filmes), Google Books (livros) e TMDB (séries de TV)
  • Análise de Preferências: Entenda seus gêneros favoritos, criadores e o que você normalmente aprecia
  • Armazenamento Persistente: Banco de dados SQLite com Drizzle ORM e relações adequadas
  • Acesso Remoto: Servidor HTTP com suporte a Server-Sent Events (SSE)
  • Seguro: Autenticação por chave de API para conexões remotas

Instalação

# Clone the repository
git clone <your-repo-url>
cd mediasage

# Install dependencies
bun install

# Set up API keys (required for metadata enrichment)
cp .env.example .env
# Edit .env and add your API keys:
# - OMDB_API_KEY (required for movies): Get from http://www.omdbapi.com/apikey.aspx
# - TMDB_API_KEY (required for TV shows): Get from https://www.themoviedb.org/settings/api
# - GOOGLE_BOOKS_API_KEY (optional for books): Get from Google Cloud Console

# Run migration if you have existing movie data
bun run src/migrate-to-media.ts

Uso

Modo Local (stdio)

Para uso com Claude Desktop ou outros clientes MCP:

# Development (with file watching)
bun run dev

# Production
bun run start

Modo Remoto (HTTP/SSE)

Para acesso remoto via HTTP:

# Set environment variables
export API_KEY="your-secure-api-key"
export PORT=3000  # optional, defaults to 3000

# Development (with file watching)
bun run dev:http

# Production
bun run start:http

Ferramentas Disponíveis

Ferramentas de Filme

search_and_add_movie

Busque um filme e adicione-o com metadados preenchidos automaticamente do OMDB.

Parâmetros:

  • title (obrigatório): Título do filme a ser buscado
  • year: Ano de lançamento (ajuda na precisão)
  • watched: Se você já assistiu (padrão: falso)
  • rating: Sua avaliação (1-10) se assistiu
  • notes: Notas pessoais
  • likedAspects: O que você gostou (separado por vírgulas)
  • dislikedAspects: O que você não gostou
  • mood: Quando/por que você assistiu
  • recommendationContext: Como isso deve influenciar as recomendações

Ferramentas de Livro

search_and_add_book

Busque um livro e adicione-o com metadados preenchidos automaticamente do Google Books.

Parâmetros:

  • title (obrigatório): Título do livro a ser buscado
  • author: Nome do autor (ajuda na precisão)
  • read: Se você já leu (padrão: falso)
  • rating: Sua avaliação (1-10) se leu
  • notes: Notas pessoais
  • likedAspects: O que você gostou (separado por vírgulas)
  • dislikedAspects: O que você não gostou
  • mood: Quando/por que você leu
  • recommendationContext: Como isso deve influenciar as recomendações

Ferramentas de Séries de TV

search_and_add_tv_show

Busque uma série de TV e adicione-a com metadados preenchidos automaticamente do TMDB.

Parâmetros:

  • title (obrigatório): Título da série de TV a ser buscada
  • year: Ano da primeira exibição (ajuda na precisão)
  • watched: Se você já assistiu (padrão: falso)
  • rating: Sua avaliação (1-10) se assistiu
  • notes: Notas pessoais
  • likedAspects: O que você gostou (separado por vírgulas)
  • dislikedAspects: O que você não gostou
  • mood: Quando/por que você assistiu
  • recommendationContext: Como isso deve influenciar as recomendações

Ferramentas Gerais

list_media

Liste todas as mídias com opções avançadas de filtragem.

Parâmetros:

  • type: Filtrar por tipo de mídia ('movie', 'book', 'tv_show')
  • watched_only: Mostrar apenas itens assistidos/lidos
  • watchlist_only: Mostrar apenas itens não assistidos/não lidos
  • min_rating: Filtro de avaliação mínima (1-10)
  • genre: Filtrar por gênero
  • creator: Filtrar por diretor/autor/criador
  • year: Filtrar por ano

add_movie_to_watchlist

Adicione um filme à sua lista de desejos (filmes que você quer assistir).

Parâmetros:

  • title (obrigatório): Título do filme
  • year: Ano de lançamento
  • notes: Por que você quer assisti-lo
  • recommendationContext: Por que foi recomendado

get_smart_recommendations

Obtenha recomendações inteligentes com base nas suas preferências em todos os tipos de mídia.

Parâmetros:

  • mood: Humor atual (ex.: 'cheio de ação', 'reflexivo')
  • genre_preference: Interesse específico em gênero
  • length_preference: Duração preferida (curta/média/longa/qualquer)
  • count: Número de recomendações (padrão: 5)

mark_as_watched

Marque um filme da sua lista de desejos como assistido e avalie-o.

Parâmetros:

  • id (obrigatório): ID do filme
  • rating: Sua avaliação (1-10)
  • likedAspects: O que você gostou
  • dislikedAspects: O que você não gostou
  • notes: Seus pensamentos

analyze_preferences

Analise suas preferências de mídia para entender seu gosto.

update_movie

Atualize uma entrada de filme existente.

Parâmetros:

  • id (obrigatório): ID do filme
  • rating: Nova avaliação (1-10)
  • watched: Atualizar status de assistido
  • notes: Atualizar notas
  • likedAspects: Atualizar aspectos que você gostou
  • dislikedAspects: Atualizar aspectos que você não gostou
  • mood: Atualizar contexto de humor

Configuração

Claude Desktop

Adicione à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "mediasage": {
      "command": "bun",
      "args": ["run", "/path/to/mediasage/index.ts"]
    }
  }
}

Configuração do Cliente Remoto

Conecte-se ao endpoint HTTP:

Endpoint: http://localhost:3000/mcp
Method: POST
Headers:
  - Content-Type: text/event-stream
  - Authorization: Bearer YOUR_API_KEY

Variáveis de Ambiente

  • PORT: Porta do servidor HTTP (padrão: 3000)
  • API_KEY: Chave de autenticação para acesso remoto (obrigatória para modo HTTP)
  • OMDB_API_KEY: Chave de API para metadados de filmes do OMDB (obtenha chave gratuita em omdbapi.com)

Metadados de Filmes

O servidor busca automaticamente metadados de filmes da API OMDB, incluindo:

  • Diretores, elenco, gêneros, resumos de enredo
  • Avaliações IMDb, pontuações Rotten Tomatoes
  • Datas de lançamento, duração, dados de bilheteria
  • Imagens de pôsteres e mais

Para habilitar a busca de metadados, obtenha uma chave de API gratuita em omdbapi.com e defina:

export OMDB_API_KEY="your-api-key"

Fluxo de Trabalho

  1. Adicione filmes que você assistiu: Use search_and_add_movie com watched: true e sua avaliação
  2. Construa sua lista de desejos: Use add_movie_to_watchlist para filmes que você quer ver
  3. Avalie e analise: Use mark_as_watched quando assistir algo da sua lista
  4. Obtenha recomendações: Use get_smart_recommendations para sugestões personalizadas
  5. Entenda seu gosto: Use analyze_preferences para ver seus padrões de filmes

Desenvolvimento

A estrutura do projeto:

movie-rec-mcp/
├── index.ts              # Main stdio server
├── src/
│   ├── http-server.ts    # HTTP/SSE server
│   ├── sse-transport.ts  # SSE transport implementation
│   └── db/
│       ├── index.ts      # Database operations
│       └── schema.ts     # Drizzle schema definitions
├── movies.db            # SQLite database (auto-created)
└── package.json

Notas de Segurança

  • Altere a chave de API padrão ao implantar
  • O servidor HTTP inclui cabeçalhos CORS para desenvolvimento
  • Considere usar HTTPS em produção
  • O arquivo do banco de dados é ignorado pelo git por privacidade

Licença

MIT