Movie Recommendation

Realiza un seguimiento de las películas que has visto y ofrece recomendaciones basadas en tus preferencias.

GitHub
1
Prueba este MCPPatrocinado

Documentación

MediaSage

Un servidor de Protocolo de Contexto de Modelo (MCP) que rastrea películas, libros y programas de televisión, proporcionando recomendaciones inteligentes basadas en tus preferencias. Construido con Bun, SQLite (a través de Drizzle ORM), y soporta conexiones tanto locales (stdio) como remotas (HTTP/SSE).

Características

  • Seguimiento Multi-Media: Rastrea películas, libros y programas de TV con calificaciones, estado y notas
  • Filtrado Inteligente: Lista medios por tipo, estado, calificación, género y más
  • Recomendaciones Cruzadas: Obtén sugerencias basadas en tus preferencias en todos los tipos de medios
  • Metadatos Enriquecidos: Obtención automática de metadatos desde OMDB (películas), Google Books (libros) y TMDB (programas de TV)
  • Análisis de Preferencias: Comprende tus géneros favoritos, creadores y lo que normalmente disfrutas
  • Almacenamiento Persistente: Base de datos SQLite con Drizzle ORM y relaciones adecuadas
  • Acceso Remoto: Servidor HTTP con soporte de Eventos Enviados por el Servidor (SSE)
  • Seguro: Autenticación con clave API para conexiones remotas

Instalación

# 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 con Claude Desktop u otros clientes MCP:

# Development (with file watching)
bun run dev

# Production
bun run start

Modo Remoto (HTTP/SSE)

Para acceso remoto a través de 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

Herramientas Disponibles

Herramientas de Películas

search_and_add_movie

Busca una película y agrégala con metadatos auto-completados desde OMDB.

Parámetros:

  • title (requerido): Título de la película a buscar
  • year: Año de estreno (ayuda a la precisión)
  • watched: Si ya la has visto (por defecto: falso)
  • rating: Tu calificación (1-10) si la has visto
  • notes: Notas personales
  • likedAspects: Lo que te gustó (separado por comas)
  • dislikedAspects: Lo que no te gustó
  • mood: Cuándo/por qué la viste
  • recommendationContext: Cómo debería influir en las recomendaciones

Herramientas de Libros

search_and_add_book

Busca un libro y agrégalo con metadatos auto-completados desde Google Books.

Parámetros:

  • title (requerido): Título del libro a buscar
  • author: Nombre del autor (ayuda a la precisión)
  • read: Si ya lo has leído (por defecto: falso)
  • rating: Tu calificación (1-10) si lo has leído
  • notes: Notas personales
  • likedAspects: Lo que te gustó (separado por comas)
  • dislikedAspects: Lo que no te gustó
  • mood: Cuándo/por qué lo leíste
  • recommendationContext: Cómo debería influir en las recomendaciones

Herramientas de Programas de TV

search_and_add_tv_show

Busca un programa de TV y agrégalo con metadatos auto-completados desde TMDB.

Parámetros:

  • title (requerido): Título del programa de TV a buscar
  • year: Año de primera emisión (ayuda a la precisión)
  • watched: Si ya lo has visto (por defecto: falso)
  • rating: Tu calificación (1-10) si lo has visto
  • notes: Notas personales
  • likedAspects: Lo que te gustó (separado por comas)
  • dislikedAspects: Lo que no te gustó
  • mood: Cuándo/por qué lo viste
  • recommendationContext: Cómo debería influir en las recomendaciones

Herramientas Generales

list_media

Lista todos los medios con opciones de filtrado avanzado.

Parámetros:

  • type: Filtrar por tipo de medio ('movie', 'book', 'tv_show')
  • watched_only: Mostrar solo elementos vistos/leídos
  • watchlist_only: Mostrar solo elementos no vistos/no leídos
  • min_rating: Filtro de calificación mínima (1-10)
  • genre: Filtrar por género
  • creator: Filtrar por director/autor/creador
  • year: Filtrar por año

add_movie_to_watchlist

Agrega una película a tu lista de pendientes (películas que quieres ver).

Parámetros:

  • title (requerido): Título de la película
  • year: Año de estreno
  • notes: Por qué quieres verla
  • recommendationContext: Por qué fue recomendada

get_smart_recommendations

Obtén recomendaciones inteligentes basadas en tus preferencias en todos los tipos de medios.

Parámetros:

  • mood: Estado de ánimo actual (ej., 'llena de acción', 'reflexiva')
  • genre_preference: Interés específico en un género
  • length_preference: Duración preferida (corta/mediana/larga/cualquiera)
  • count: Número de recomendaciones (por defecto: 5)

mark_as_watched

Marca una película de tu lista de pendientes como vista y califícala.

Parámetros:

  • id (requerido): ID de la película
  • rating: Tu calificación (1-10)
  • likedAspects: Lo que te gustó
  • dislikedAspects: Lo que no te gustó
  • notes: Tus pensamientos

analyze_preferences

Analiza tus preferencias de medios para comprender tu gusto.

update_movie

Actualiza una entrada de película existente.

Parámetros:

  • id (requerido): ID de la película
  • rating: Nueva calificación (1-10)
  • watched: Actualizar estado de visualización
  • notes: Actualizar notas
  • likedAspects: Actualizar aspectos que te gustaron
  • dislikedAspects: Actualizar aspectos que no te gustaron
  • mood: Actualizar contexto de estado de ánimo

Configuración

Claude Desktop

Agrega a tu configuración de Claude Desktop:

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

Configuración de Cliente Remoto

Conéctate al endpoint HTTP:

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

Variables de Entorno

  • PORT: Puerto del servidor HTTP (por defecto: 3000)
  • API_KEY: Clave de autenticación para acceso remoto (requerida para modo HTTP)
  • OMDB_API_KEY: Clave API para metadatos de películas OMDB (obtén una clave gratuita en omdbapi.com)

Metadatos de Películas

El servidor obtiene automáticamente metadatos de películas desde la API de OMDB, incluyendo:

  • Directores, reparto, géneros, resúmenes de trama
  • Calificaciones de IMDb, puntuaciones de Rotten Tomatoes
  • Fechas de estreno, duración, datos de taquilla
  • Imágenes de pósteres y más

Para habilitar la obtención de metadatos, obtén una clave API gratuita en omdbapi.com y configura:

export OMDB_API_KEY="your-api-key"

Flujo de Trabajo

  1. Agrega películas que has visto: Usa search_and_add_movie con watched: true y tu calificación
  2. Construye tu lista de pendientes: Usa add_movie_to_watchlist para películas que quieres ver
  3. Califica y analiza: Usa mark_as_watched cuando veas algo de tu lista
  4. Obtén recomendaciones: Usa get_smart_recommendations para sugerencias personalizadas
  5. Comprende tu gusto: Usa analyze_preferences para ver tus patrones de películas

Desarrollo

La estructura del proyecto:

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 Seguridad

  • Cambia la clave API predeterminada al implementar
  • El servidor HTTP incluye encabezados CORS para desarrollo
  • Considera usar HTTPS en producción
  • El archivo de base de datos está en gitignore por privacidad

Licencia

MIT