Movies MCP Server

Un servidor completo de base de datos de películas que admite búsqueda avanzada, operaciones CRUD y gestión de imágenes a través de una base de datos PostgreSQL.

GitHub

Prueba este MCPPatrocinado

Documentación

Movies MCP Server

Un servidor Model Context Protocol (MCP) listo para producción para la gestión inteligente de bases de datos de películas, construido con principios de Clean Architecture y optimizado para entornos asistidos por IA.

🎉 Impulsado por el SDK Oficial de Golang MCP v1.1.0 Construido con el SDK oficial de MCP mantenido por Anthropic y Google, que proporciona seguridad de tipos, generación automática de esquemas y fiabilidad lista para producción. Consulta Migración del SDK para más detalles sobre la migración.

✅ Implementación Solo con SDK El servidor personalizado heredado ha sido archivado. Este proyecto ahora utiliza únicamente el servidor basado en el SDK oficial en cmd/server-sdk/. Consulta Estado del Servidor para más detalles.

¿Qué es Movies MCP Server?

Movies MCP Server es un sofisticado sistema de gestión de bases de datos de películas que se comunica a través del Model Context Protocol, diseñado específicamente para la integración con asistentes de IA como Claude. A diferencia de las API HTTP tradicionales, utiliza JSON-RPC sobre stdin/stdout para proporcionar operaciones de datos de películas y actores fluidas e inteligentes.

Perfecto para:

Sistemas de recomendación de películas impulsados por IA
Integraciones con Claude Desktop
Análisis y exploración inteligente de películas
Investigación de carreras de directores
Gestión de bases de datos de películas con asistencia de IA

¿Por Qué Elegir Movies MCP Server?

Nativo del Protocolo MCP: Construido específicamente para el Model Context Protocol utilizando el SDK oficial de Golang
Seguro y Moderno: Aprovecha el SDK oficial para validación en tiempo de compilación y generación automática de esquemas
Clean Architecture: Separación ejemplar de responsabilidades con diseño dirigido por dominio
Funciones Inteligentes: Recomendaciones impulsadas por IA, análisis de carreras de directores y búsquedas de similitud
Gestión Integral de Actores: Base de datos completa de actores con asociaciones de películas y seguimiento de carreras
Listo para Producción: Comprobaciones de salud, métricas de Prometheus, paneles de Grafana y monitoreo integral
Búsqueda Avanzada: Búsqueda de texto completo, filtrado por décadas, rangos de calificación, coincidencia de géneros y puntuación de similitud
Soporte de Imágenes: Almacena y recupera carteles de películas a través de recursos MCP con codificación base64
Pruebas BDD: Cobertura integral de pruebas con escenarios de comportamiento Cucumber/Godog
Optimizado para Docker: Construcciones de múltiples etapas, imágenes distroless, ejecución sin root

Métricas Clave de Rendimiento

Rendimiento: >50 operaciones por segundo bajo carga
Concurrencia: Maneja de forma segura más de 50 solicitudes concurrentes
Tiempo de Respuesta: <100ms para operaciones típicas
Cobertura de Pruebas: Pruebas unitarias e integrales con escenarios BDD
Eficiencia de Código: 26% menos código con la migración al SDK (se eliminaron ~1,200 líneas)

Capacidades MCP

23 Herramientas Disponibles

Gestión de Películas (8 herramientas)

get_movie - Recuperar película por ID
add_movie - Crear película con título, director, año, calificación, géneros, cartel
update_movie - Actualizar detalles de una película existente
delete_movie - Eliminar película por ID
list_top_movies - Obtener las películas mejor calificadas con límite configurable
search_movies - Búsqueda multicriterio (título, director, género, rango de años, calificación)
search_by_decade - Encontrar películas de décadas específicas (1990s, 2000s, etc.)
search_by_rating_range - Filtrar películas por límites de calificación

Gestión de Actores (9 herramientas)

add_actor - Crear actor con nombre, año de nacimiento, biografía
get_actor - Recuperar actor por ID
update_actor - Actualizar información del actor
delete_actor - Eliminar actor
link_actor_to_movie - Asociar actor con película
unlink_actor_from_movie - Eliminar asociación actor-película
get_movie_cast - Obtener todos los actores de una película
get_actor_movies - Obtener todas las películas de un actor
search_actors - Buscar actores por nombre con filtrado por año de nacimiento

Inteligencia y Análisis (3 herramientas compuestas)

bulk_movie_import - Importar múltiples películas con seguimiento de errores
movie_recommendation_engine - Recomendaciones impulsadas por IA con puntuación de preferencias
director_career_analysis - Trayectoria profesional con análisis de fases temprana/media/tardía

Gestión de Contexto (3 herramientas)

create_search_context - Crear contexto de búsqueda paginado para grandes conjuntos de resultados
get_context_page - Recuperar página específica del contexto de búsqueda
get_context_info - Obtener metadatos del contexto e información de páginas

5 Prompts Integrados

movie_recommendation - Generar recomendaciones personalizadas basadas en preferencias
movie_analysis - Analizar temas, cinematografía y características
director_filmography - Explorar la obra y evolución de un director
genre_exploration - Profundizar en la historia de un género y películas influyentes
movie_comparison - Comparar dos películas en múltiples dimensiones

3 Recursos MCP

movies://database/all - Base de datos completa de películas en formato JSON
movies://database/stats - Estadísticas y análisis de la base de datos
movies://posters/collection - Todos los carteles de películas (codificados en base64)
Dinámico: movies://posters/{movie-id} - Carteles de películas individuales

Arquitectura y Tecnología

Implementación de Clean Architecture

Construido con una estricta separación de responsabilidades:

internal/
├── domain/          # Pure business logic (entities, value objects)
├── application/     # Use cases and orchestration
├── infrastructure/  # Database and external integrations
├── mcp/            # MCP SDK tools and handlers
└── composition/     # Dependency injection

Beneficios:

Independencia del framework
Lógica de negocio comprobable
Agnóstico de base de datos (actualmente PostgreSQL)
Fácil de mantener y extender

Stack Tecnológico

Núcleo:

Go 1.23.0+ con toolchain Go 1.24.4
SDK Oficial de Golang MCP v1.1.0 - Implementación de protocolo con seguridad de tipos
PostgreSQL 17 con indexación avanzada
Model Context Protocol (MCP) vía JSON-RPC

Bibliotecas Clave:

github.com/modelcontextprotocol/go-sdk - SDK oficial de MCP
github.com/lib/pq - Controlador de PostgreSQL
github.com/cucumber/godog - Pruebas BDD
github.com/testcontainers/testcontainers-go - Pruebas de integración
github.com/sirupsen/logrus - Registro estructurado
OpenTelemetry - Trazado distribuido

Características de la Base de Datos:

Búsqueda de texto completo (índices GIN)
Filtrado de géneros basado en arrays
Relaciones muchos-a-muchos actor-película
Gestión automática de marcas de tiempo
Almacenamiento de imágenes (columnas BYTEA)

Inicio Rápido

Requisitos Previos

Go 1.24.4 o posterior
Docker y Docker Compose (opcional, para la base de datos)
PostgreSQL 17 (o usar la configuración basada en Docker)
Make (opcional, para comandos más fáciles)

Instalación

Clonar el Repositorio:

git clone https://github.com/francknouama/movies-mcp-server.git
cd movies-mcp-server

Configurar el Entorno:

cp .env.example .env
# Edit .env with your database settings

Iniciar la Base de Datos (si se usa Docker):
```
make docker-up
```

Inicializar la Base de Datos:

make db-setup      # Create database
make db-migrate    # Run migrations
make db-seed       # Load sample data

Compilar el Servidor SDK (recomendado):

go build -o movies-mcp-server-sdk ./cmd/server-sdk/

Ejecutar el Servidor SDK:

# With environment variables
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=movies_user
export DB_PASSWORD=movies_password
export DB_NAME=movies_mcp
export DB_SSLMODE=disable

./movies-mcp-server-sdk

O con banderas:

./movies-mcp-server-sdk --version        # Show version
./movies-mcp-server-sdk --help           # Show help
./movies-mcp-server-sdk --skip-migrations # Skip DB migrations

Despliegue con Docker

Desarrollo (solo bases de datos):

docker-compose -f docker-compose.dev.yml up

Producción (con monitoreo):

docker-compose -f docker-compose.clean.yml up

Servicios Incluidos:

PostgreSQL 17 (puerto 5432)
Movies MCP Server
Grafana (puerto 3000)
pgAdmin (puerto 5050)
Prometheus (puerto 9090)

Integración con Claude Desktop

Configura Claude Desktop para usar Movies MCP Server con el servidor basado en SDK:

Ubicación del Archivo de Configuración:

SO	Ruta
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Configuración:

{
  "mcpServers": {
    "movies": {
      "command": "/absolute/path/to/movies-mcp-server-sdk",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USER": "movies_user",
        "DB_PASSWORD": "movies_password",
        "DB_NAME": "movies_mcp",
        "DB_SSLMODE": "disable"
      }
    }
  }
}

Reinicia Claude Desktop para activar la integración.

Lo Que Puedes Hacer con Claude

"Encuéntrame películas de suspenso de los años 1990 con calificaciones superiores a 8"
"Agrega una nueva película: Inception, dirigida por Christopher Nolan, estrenada en 2010"
"Muéstrame todas las películas protagonizadas por Leonardo DiCaprio"
"Analiza la trayectoria profesional de Quentin Tarantino"
"Recomiéndame películas similares a El Padrino"
"Importa esta lista de películas en lote"

Migración del SDK

¡Migración Completada! 🎉

Este proyecto ha sido migrado por completo de una implementación de protocolo MCP personalizada al SDK oficial de Golang MCP v1.1.0.

Mejoras Clave:

✅ 26% menos código - Se eliminaron ~1,200 líneas de capa de protocolo personalizada
✅ Manejadores con seguridad de tipos - Validación en tiempo de compilación con tipos de Go
✅ Generación automática de esquemas - Sin definiciones manuales de esquemas JSON
✅ Pruebas simplificadas - 37% menos código de prueba con mayor claridad
✅ Soporte oficial - Mantenido por Anthropic y Google
✅ Cero cambios en la lógica de negocio - Clean Architecture preservada

Lo Que Se Migró:

23 herramientas MCP (todas las herramientas planificadas)
Servidor principal basado en SDK (cmd/server-sdk/main.go)
Pruebas unitarias integrales
Documentación completa

Documentación:

Comparación de Migración del SDK - Ejemplos de código antes/después
Comparación de Pruebas - Mejoras en las pruebas
Migración Completada - Resumen completo de la migración

✅ Estado del Servidor: Implementación Solo con SDK

Servidor Activo: cmd/server-sdk/ - Implementación basada en el SDK oficial

Movies MCP Server ahora utiliza solo el SDK oficial de Golang MCP v1.1.0, que proporciona:

✅ SDK oficial mantenido por Anthropic y Google
✅ 26% menos código con mejor seguridad de tipos
✅ Generación automática de esquemas
✅ Mejor mantenibilidad y pruebas
✅ Listo para producción y completamente probado

Servidor Heredado Archivado: El servidor personalizado obsoleto ha sido archivado en el directorio legacy/. Consulta legacy/README.md para detalles del archivo.

Funciones Avanzadas

Motor de Recomendación Inteligente

Algoritmo de puntuación multifactorial:

Coincidencia de género (40% de peso)
Puntuación de calificación (30% de peso)
Relevancia del año (20% de peso)
Impulso de popularidad (10% de peso)

Devuelve recomendaciones clasificadas con puntuaciones de coincidencia y razonamiento.

Análisis de Carrera de Directores

El análisis automático incluye:

Detección de fase profesional (temprana/media/tardía)
Calificación promedio por fase
Seguimiento de especialización en géneros
Trayectoria profesional (ascendente/descendente/pico/resurgimiento)
Obras notables (mejor y peor calificadas)

Operaciones de Importación Masiva

Importa múltiples películas a la vez con:

Seguimiento de errores por elemento
Estadísticas de éxito/fracaso
Manejo de éxito parcial
Informes de errores detallados

Capacidades de Búsqueda Avanzada

Búsqueda de texto completo: Título, director, descripción usando índices GIN de PostgreSQL
Análisis de décadas: Maneja inteligentemente formatos "1990s", "90s", "1990"
Puntuación de similitud: Recomendaciones basadas en género y calificación
Filtrado multicriterio: Combina título, género, rango de años, rango de calificación
Soporte de paginación: Maneja eficientemente grandes conjuntos de resultados

Monitoreo y Observabilidad

Métricas de Prometheus

Disponibles en el puerto 9090 con métricas integrales:

Tiempos de solicitud/respuesta
Operaciones concurrentes
Estadísticas del pool de conexiones de la base de datos
Rendimiento de consultas
Utilización de memoria y CPU

Paneles de Grafana

Accede a Grafana en el puerto 3000 para:

Monitoreo de rendimiento en tiempo real
Visualización de la salud de la base de datos
Reglas de alerta personalizadas
Seguimiento de recursos del sistema

Comprobaciones de Salud

Comprobaciones de salud integradas con:

Intervalos configurables (predeterminado: 30s)
Verificación de conectividad de la base de datos
Degradación gradual
Informes de estado

Reglas de Alerta

Alertas preconfiguradas para:

Altas tasas de error
Rendimiento lento de consultas
Problemas de conexión de la base de datos
Umbrales de memoria/CPU

Configuración: monitoring/alert_rules.yml

Guía para Desarrolladores

Pruebas

Ejecutar Todas las Pruebas:

make test                  # Unit tests
make test-integration      # Integration tests with testcontainers
make test-coverage         # Coverage report
make test-bdd              # BDD scenarios with Godog

Pruebas de Funciones BDD:

Más de 40 escenarios de comportamiento en Gherkin
PostgreSQL real vía testcontainers
Pruebas de contrato para el protocolo MCP
Pruebas de rendimiento y carga

Migraciones de Base de Datos

make db-migrate            # Apply migrations
make db-migrate-down       # Rollback last migration
make db-migrate-reset      # Reset database
make db-create-migration   # Create new migration

Calidad del Código

make fmt                   # Format code
make vet                   # Run go vet
make lint                  # Run golangci-lint

Opciones de Compilación

# Build SDK server (recommended)
go build -o movies-mcp-server-sdk ./cmd/server-sdk/

# Build legacy custom server
make build

# Build all variants
make build-all

# Build Docker image
make docker-build

# Create release
make release               # Create release with goreleaser

Variables de Entorno

Base de Datos:

DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSLMODE
DATABASE_URL - Cadena de conexión completa (servidor heredado)
DB_MAX_CONNECTIONS=100, DB_MAX_IDLE_CONNECTIONS=10

Servidor:

PORT=8080, METRICS_PORT=9090
READ_TIMEOUT=30s, WRITE_TIMEOUT=30s
LOG_LEVEL (debug/info/warn/error)

Seguridad:

JWT_SECRET, API_KEY
RATE_LIMIT=1000 (por minuto por IP)
TLS_ENABLED, TLS_CERT_FILE, TLS_KEY_FILE

Monitoreo:

PROMETHEUS_ENABLED=true
HEALTH_CHECK_INTERVAL=30s

Consulta .env.example para opciones de configuración completas.

Documentación

Documentación integral disponible en el directorio /docs: Primeros pasos:

Guías:

Guía de usuario - Recorrido por las funciones
Ejemplos - Ejemplos de código

Arquitectura:

Descripción general de la arquitectura - Detalles de Clean Architecture
Guía de Docker - Configuración y ajustes de Docker
Guía de despliegue - Despliegue en producción
Soporte de imágenes - Manejo de imágenes mediante MCP

Migración del SDK:

Comparativa de migración del SDK - Ejemplos de código antes/después
Comparativa de pruebas - Mejoras en las pruebas
Migración completada - Resumen completo de la migración

Referencia:

Referencia de la API - Documentación completa de la API
Solución de problemas - Problemas comunes
Preguntas frecuentes - Preguntas frecuentes

Estructura del proyecto

movies-mcp-server/
├── cmd/
│   └── server-sdk/          # ✅ Official SDK-based server (ACTIVE)
├── internal/
│   ├── domain/              # Business logic (entities, value objects)
│   ├── application/         # Use cases and services
│   ├── infrastructure/      # Database and integrations
│   ├── mcp/                # ✅ MCP SDK tools and handlers (58 tests)
│   └── config/              # Configuration management
├── legacy/                  # 📦 Archived legacy server code
│   ├── cmd/server/          # Deprecated custom server
│   ├── internal/            # Deprecated handlers and schemas
│   └── tests/integration/   # Legacy integration tests
├── migrations/              # Database migrations
├── tests/
│   └── bdd/                # BDD feature files (tests SDK server)
├── docs/                    # Documentation
├── monitoring/              # Prometheus and Grafana configs
└── docker/                  # Docker configurations

Contribuciones

¡Agradecemos las contribuciones! Consulta la Guía de contribuciones para conocer:

Código de conducta
Configuración del entorno de desarrollo
Proceso de solicitudes de extracción (pull requests)
Estándares de codificación
Requisitos de pruebas

Soporte y comunidad

¿Encontraste un error? Reporta un problema
¿Tienes preguntas? Consulta las Preguntas frecuentes
¿Necesitas ayuda? Consulta la Guía de solución de problemas
¿Quieres contribuir? Lee la Guía de desarrollo

Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENCIA para más detalles.

Agradecimientos

Un agradecimiento especial a:

Model Context Protocol por el ecosistema MCP
Anthropic por Claude y el desarrollo de MCP
Google por co-mantener el SDK oficial de Golang para MCP
La comunidad de PostgreSQL por la robusta base de datos
La comunidad de Go por las excelentes herramientas y bibliotecas
Todos los contribuyentes y usuarios de este proyecto

¿Qué sigue?

Consulta IMPLEMENTATION_PLAN.md para conocer la hoja de ruta, que incluye:

Integración con GraphQL
Estrategias avanzadas de caché
Algoritmos mejorados de recomendación
Soporte multilingüe
Notificaciones en tiempo real

Construido con principios de Clean Architecture y el SDK oficial de Golang para MCP, pensado para la mantenibilidad, la testabilidad y la escalabilidad.