Servidor MCP de AMC 🎬

Un servidor de Model Context Protocol (MCP) que proporciona una experiencia completa de reserva de entradas para AMC Theatres. Este servidor permite a los asistentes de IA conversacionales ayudar a los usuarios a descubrir películas, encontrar horarios de proyección, reservar asientos y procesar pagos a través de una interfaz API sencilla.

Características ✨

• Descubrimiento de películas: Explora las películas en cartelera y recibe recomendaciones personalizadas

• Búsqueda de horarios: Encuentra horarios de proyección disponibles por ubicación, fecha y película

• Selección de asientos: Visualiza mapas de asientos interactivos y comprueba la disponibilidad

• Gestión de reservas: Reserva asientos con verificación de disponibilidad en tiempo real

• Procesamiento de pagos: Gestiona transacciones de pago simuladas con confirmación y recibo

• Soporte multiubicación: Busca en múltiples ubicaciones de AMC

Related MCP server: Travel Amadeus MCP Server

Inicio rápido 🚀

Requisitos previos

• Python 3.8+

• Docker (opcional, para implementación en contenedores)

Instalación

Opción 1: Instalación local

1. Clona el repositorio:

git clone <repository-url>
cd amc-mcp

2. Instala las dependencias:

pip install -r requirements.txt

3. Instala el paquete:

pip install -e .

4. Ejecuta el servidor:

python -m amc_mcp.fastmcp_server

Opción 2: Implementación con Docker

1. Compila y ejecuta con Docker Compose:

docker-compose up --build

2. O compila y ejecuta manualmente:

docker build -t amc-mcp .
docker run -it amc-mcp

Referencia de herramientas MCP 🛠️

1. get_now_showing

Devuelve una lista de películas actualmente en cartelera en una ubicación determinada.

Entrada:

{
  "location": "Boston, MA"
}

Salida:

{
  "location": "Boston, MA",
  "movies": [
    {
      "movie_id": "mv001",
      "title": "Dune: Part Two",
      "rating": "PG-13",
      "duration": 166,
      "genre": "Sci-Fi/Action",
      "description": "Paul Atreides unites with Chani..."
    }
  ]
}

2. get_recommendations

Sugiere películas según el estado de ánimo, el género o las preferencias.

Entrada:

{
  "genre": "action",
  "mood": "exciting"
}

Salida:

{
  "criteria": {"genre": "action", "mood": "exciting"},
  "recommendations": [...]
}

3. get_showtimes

Obtiene los horarios de proyección disponibles para una película y ubicación específicas.

Entrada:

{
  "movie_id": "mv001",
  "date": "2025-10-28",
  "location": "Boston, MA"
}

Salida:

{
  "movie": {"id": "mv001", "title": "Dune: Part Two"},
  "date": "2025-10-28",
  "location": "Boston, MA",
  "showtimes": [
    {
      "showtime_id": "st001",
      "theater_name": "AMC Boston Common 19",
      "theater_address": "175 Tremont Street",
      "time": "14:00",
      "format": "IMAX",
      "price": 18.50
    }
  ]
}

4. get_seat_map

Muestra los asientos disponibles y reservados para una proyección específica.

Entrada:

{
  "showtime_id": "st001"
}

Salida:

{
  "showtime_id": "st001",
  "movie": "Dune: Part Two",
  "theater": "AMC Boston Common 19",
  "date": "2025-10-28",
  "time": "14:00",
  "seat_map": [
    {
      "seat_number": "A5",
      "row": "A",
      "column": 5,
      "is_available": true,
      "price_tier": "Standard",
      "price": 18.50
    }
  ]
}

5. book_seats

Reserva los asientos seleccionados para el usuario.

Entrada:

{
  "showtime_id": "st001",
  "seats": ["A5", "A6"],
  "user_id": "user123"
}

Salida:

{
  "booking_id": "booking-uuid",
  "status": "pending",
  "movie": "Dune: Part Two",
  "theater": "AMC Boston Common 19",
  "date": "2025-10-28",
  "time": "14:00",
  "seats": ["A5", "A6"],
  "total_price": 37.00
}

6. process_payment

Gestiona la transacción de pago simulada.

Entrada:

{
  "booking_id": "booking-uuid",
  "payment_method": "card",
  "amount": 37.00
}

Salida:

{
  "payment_id": "payment-uuid",
  "payment_status": "success",
  "booking_id": "booking-uuid",
  "receipt_url": "https://amc.com/receipts/payment-uuid",
  "confirmation": {
    "movie": "Dune: Part Two",
    "theater": "AMC Boston Common 19",
    "date": "2025-10-28",
    "time": "14:00",
    "seats": ["A5", "A6"],
    "total_paid": 37.00
  }
}

Ejemplo de flujo de conversación 💬

Así es como sería una conversación típica de reserva de entradas:

1. Usuario: "Encuentra una película de acción cerca de mí esta noche."

   • Llamadas al servidor: get_now_showing + get_recommendations

   • Respuesta: Lista de películas de acción con horarios de proyección

2. Usuario: "Reserva dos asientos para Dune: Parte Dos a las 8 p. m."

   • Llamadas al servidor: get_showtimes → get_seat_map → book_seats

   • Respuesta: Selección de asientos y confirmación de reserva

3. Usuario: "Paga con mi tarjeta."

   • Llamadas al servidor: process_payment

   • Respuesta: Confirmación de pago con recibo digital

Arquitectura 🏗️

amc-mcp/
├── src/
│   └── amc_mcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── data/
│   ├── movies.json           # Movie catalog
│   ├── theaters.json         # Theater locations
│   ├── showtimes.json        # Showtime schedules
│   └── seats.json           # Seat maps by showtime
├── config/
│   └── nginx.conf           # Web server configuration
├── Dockerfile               # Container configuration
├── docker-compose.yml       # Multi-service orchestration
├── requirements.txt         # Python dependencies
├── pyproject.toml          # Package configuration
└── README.md               # This file

Modelos de datos 📊

Película

{
  "movie_id": str,
  "title": str,
  "rating": str,         # PG, PG-13, R, etc.
  "duration": int,       # Minutes
  "genre": str,
  "description": str,
  "poster_url": str
}

Cine

{
  "theater_id": str,
  "name": str,
  "address": str,
  "city": str,
  "state": str,
  "zip_code": str
}

Proyección

{
  "showtime_id": str,
  "movie_id": str,
  "theater_id": str,
  "date": str,           # YYYY-MM-DD
  "time": str,           # HH:MM
  "format": str,         # Standard, IMAX, 3D, Dolby
  "price": float
}

Desarrollo 👨💻

Añadir nuevas películas

Edita data/movies.json para añadir nuevas películas:

{
  "movie_id": "mv011",
  "title": "New Movie Title",
  "rating": "PG-13",
  "duration": 120,
  "genre": "Action",
  "description": "Description of the movie...",
  "poster_url": "https://example.com/poster.jpg"
}

Añadir nuevos cines

Edita data/theaters.json:

{
  "theater_id": "th011",
  "name": "AMC New Location 15",
  "address": "123 Main Street",
  "city": "New City",
  "state": "NY",
  "zip_code": "12345"
}

Añadir proyecciones

Edita data/showtimes.json y data/seats.json para añadir nuevas proyecciones y sus mapas de asientos correspondientes.

Pruebas

Pruebas manuales

Puedes probar las herramientas individualmente usando el inspector de MCP o conectándote a cualquier cliente compatible con MCP.

Pruebas con Claude Desktop

1. Configura Claude Desktop para que se conecte a tu servidor MCP

2. Usa lenguaje natural para probar el flujo de reserva

3. Ejemplo: "Encuéntrame una película de ciencia ficción en cartelera esta noche en Boston"

Configuración ⚙️

Variables de entorno

• PYTHONPATH: Establécelo en /app/src para la resolución correcta de módulos

• PYTHONUNBUFFERED: Establécelo en 1 para el registro en tiempo real

• MCP_LOG_LEVEL: Establece el nivel de registro (DEBUG, INFO, WARNING, ERROR)

Configuración de Docker

El servidor se ejecuta en un contenedor ligero de Python 3.11 con:

• Usuario no root por seguridad

• Comprobaciones de salud para monitorización

• Volúmenes montados para la persistencia de datos

• Aislamiento de red

Consideraciones de seguridad 🔒

Esta es una implementación simulada con fines de demostración. En producción:

1. Procesamiento de pagos: Integra pasarelas de pago reales (Stripe, PayPal)

2. Autenticación: Añade autenticación y autorización de usuarios

3. Validación de datos: Implementa una validación exhaustiva de las entradas

4. Limitación de velocidad: Añade límites de frecuencia a la API

5. Cifrado: Usa HTTPS y cifra los datos sensibles

6. Base de datos: Sustituye los archivos JSON por una base de datos real

7. Registro: Implementa registro estructurado y monitorización

Mejoras futuras 🔮

• Integración con la API real de AMC: Conexión con la API real de AMC Theatres

• Cuentas de usuario: Historial de reservas y perfiles de usuario persistentes

• Reservas grupales: Soporte para que varios usuarios reserven juntos

• Programas de fidelización: Integración con AMC Stubs

• Entradas móviles: Generación de códigos QR para el acceso al cine

• Recomendaciones de asientos: Sugerencias de asientos óptimos mediante IA

• Alertas de precios: Notificaciones de descuentos y promociones

• Funciones sociales: Compartir planes de cine con amigos

• Accesibilidad: Selección de asientos conforme a la ADA

Contribuciones 🤝

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad: git checkout -b feature/nueva-funcionalidad

3. Haz tus cambios y añade pruebas

4. Confirma tus cambios: git commit -am 'Añade nueva funcionalidad'

5. Sube la rama: git push origin feature/nueva-funcionalidad

6. Envía una solicitud de extracción

Licencia 📄

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Soporte 💬

Para preguntas, problemas o solicitudes de funciones:

• Crea un issue en el repositorio de GitHub

• Consulta la documentación para ver las soluciones habituales

• Revisa los ejemplos de flujos de conversación

¡Feliz reserva de entradas! 🍿🎬