AMC MCP Server 🎬

Ein Model Context Protocol (MCP)-Server, der ein umfassendes Filmbuchungserlebnis für AMC Theatres bietet. Dieser Server ermöglicht es KI-Assistenten im Chat, Nutzern beim Entdecken von Filmen, Finden von Vorstellungen, Buchen von Sitzplätzen und Abwickeln von Zahlungen über eine einfache API-Schnittstelle zu helfen.

Funktionen ✨

• Filmentdeckung: Aktuell laufende Filme durchsuchen und personalisierte Empfehlungen erhalten

• Vorstellungssuche: Verfügbare Vorstellungen nach Ort, Datum und Film finden

• Sitzplatzauswahl: Interaktive Sitzplankarten anzeigen und Verfügbarkeit prüfen

• Buchungsverwaltung: Sitzplätze mit Echtzeit-Verfügbarkeitsprüfung reservieren

• Zahlungsabwicklung: Simulierte Zahlungstransaktionen mit Buchungsbestätigungen verarbeiten

• Multi-Standort-Unterstützung: Suche über mehrere AMC-Theaterstandorte hinweg

Related MCP server: Travel Amadeus MCP Server

Schnellstart 🚀

Voraussetzungen

• Python 3.8+

• Docker (optional, für Container-Bereitstellung)

Installation

Option 1: Lokale Installation

1. Repository klonen:

git clone <repository-url>
cd amc-mcp

2. Abhängigkeiten installieren:

pip install -r requirements.txt

3. Paket installieren:

pip install -e .

4. Server starten:

python -m amc_mcp.fastmcp_server

Option 2: Docker-Bereitstellung

1. Mit Docker Compose erstellen und starten:

docker-compose up --build

2. Oder manuell erstellen und starten:

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

MCP-Tool-Referenz 🛠️

1. get_now_showing

Gibt eine Liste der aktuell laufenden Filme an einem bestimmten Ort zurück.

Eingabe:

{
  "location": "Boston, MA"
}

Ausgabe:

{
  "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

Schlägt Filme basierend auf Stimmung, Genre oder Vorlieben vor.

Eingabe:

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

Ausgabe:

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

3. get_showtimes

Ruft verfügbare Vorstellungen für einen bestimmten Film und Ort ab.

Eingabe:

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

Ausgabe:

{
  "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

Zeigt verfügbare und reservierte Sitzplätze für eine bestimmte Vorstellung an.

Eingabe:

{
  "showtime_id": "st001"
}

Ausgabe:

{
  "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

Reserviert ausgewählte Sitzplätze für den Nutzer.

Eingabe:

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

Ausgabe:

{
  "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

Wickelt eine simulierte Zahlungstransaktion ab.

Eingabe:

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

Ausgabe:

{
  "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
  }
}

Beispiel für einen Gesprächsablauf 💬

So könnte ein typisches Filmbuchungsgespräch ablaufen:

1. Nutzer: „Finde einen Actionfilm in meiner Nähe für heute Abend."

   • Serveraufrufe: get_now_showing + get_recommendations

   • Rückgabe: Liste von Actionfilmen mit Vorstellungszeiten

2. Nutzer: „Buche zwei Sitzplätze für Dune: Teil Zwei um 20 Uhr."

   • Serveraufrufe: get_showtimes → get_seat_map → book_seats

   • Rückgabe: Sitzplatzauswahl und Buchungsbestätigung

3. Nutzer: „Bezahle mit meiner Karte."

   • Serveraufrufe: process_payment

   • Rückgabe: Zahlungsbestätigung mit digitaler Quittung

Architektur 🏗️

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

Datenmodelle 📊

Film

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

Theater

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

Vorstellung

{
  "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
}

Entwicklung 👨💻

Neue Filme hinzufügen

Bearbeiten Sie data/movies.json, um neue Filme hinzuzufügen:

{
  "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"
}

Neue Theater hinzufügen

Bearbeiten Sie data/theaters.json:

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

Vorstellungen hinzufügen

Bearbeiten Sie data/showtimes.json und data/seats.json, um neue Vorstellungen und die zugehörigen Sitzplankarten hinzuzufügen.

Testen

Manuelles Testen

Sie können einzelne Tools mit dem MCP-Inspektor oder durch Verbindung mit einem beliebigen MCP-kompatiblen Client testen.

Testen mit Claude Desktop

1. Konfigurieren Sie Claude Desktop so, dass es eine Verbindung zu Ihrem MCP-Server herstellt

2. Verwenden Sie natürliche Sprache, um den Buchungsablauf zu testen

3. Beispiel: „Finde mir einen Sci-Fi-Film, der heute Abend in Boston läuft"

Konfiguration ⚙️

Umgebungsvariablen

• PYTHONPATH: Auf /app/src setzen für eine korrekte Modulauflösung

• PYTHONUNBUFFERED: Auf 1 setzen für Echtzeit-Logging

• MCP_LOG_LEVEL: Protokollierungsebene festlegen (DEBUG, INFO, WARNING, ERROR)

Docker-Konfiguration

Der Server läuft in einem schlanken Python-3.11-Container mit:

• Nicht-Root-Benutzer für Sicherheit

• Health Checks für Überwachung

• Volume-Mounts für Datenpersistenz

• Netzwerk-Isolation

Sicherheitshinweise 🔒

Dies ist eine Demo-Implementierung zu Demonstrationszwecken. In der Produktion:

1. Zahlungsabwicklung: Integration mit echten Zahlungsdienstleistern (Stripe, PayPal)

2. Authentifizierung: Benutzerauthentifizierung und -autorisierung hinzufügen

3. Datenvalidierung: Umfassende Eingabevalidierung implementieren

4. Ratenbegrenzung: API-Ratenbegrenzung hinzufügen

5. Verschlüsselung: HTTPS verwenden und sensible Daten verschlüsseln

6. Datenbank: JSON-Dateien durch eine echte Datenbank ersetzen

7. Protokollierung: Strukturierte Protokollierung und Überwachung implementieren

Zukünftige Erweiterungen 🔮

• Echte AMC-API-Integration: Anbindung an die tatsächliche AMC-Theatres-API

• Benutzerkonten: Dauerhafte Benutzerprofile und Buchungshistorie

• Gruppenbuchungen: Unterstützung für mehrere Nutzer, die gemeinsam buchen

• Treueprogramme: AMC-Stubs-Integration

• Mobile Tickets: QR-Codes für den mobilen Eintritt generieren

• Sitzplatzempfehlungen: KI-gestützte optimale Sitzplatzvorschläge

• Preisalarme: Benachrichtigung über Rabatte und Aktionen

• Soziale Funktionen: Filmpläne mit Freunden teilen

• Barrierefreiheit: Barrierefreie Sitzplatzauswahl gemäß ADA

• Mehrsprachigkeit: Internationale Sprachunterstützung

Mitwirken 🤝

1. Repository forken

2. Einen Feature-Branch erstellen: git checkout -b feature/neue-funktion

3. Änderungen vornehmen und Tests hinzufügen

4. Änderungen committen: git commit -am 'Neue Funktion hinzufügen'

5. Branch pushen: git push origin feature/neue-funktion

6. Einen Pull-Request einreichen

Lizenz 📄

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe die Datei LICENSE.

Support 💬

Bei Fragen, Problemen oder Funktionswünschen:

• Erstellen Sie ein Issue im GitHub-Repository

• Lesen Sie die Dokumentation für allgemeine Lösungen

• Sehen Sie sich die Beispiel-Gesprächsabläufe an

Viel Spaß beim Filmbuchen! 🍿🎬