AMC MCP Server 🎬

Сервер Model Context Protocol (MCP), который обеспечивает комплексный опыт бронирования билетов в кино для AMC Theatres. Этот сервер позволяет разговорным ИИ-ассистентам помогать пользователям находить фильмы, узнавать расписание сеансов, бронировать места и обрабатывать платежи через простой API-интерфейс.

Возможности ✨

• Поиск фильмов: Просмотр текущих фильмов в прокате и получение персональных рекомендаций

• Поиск сеансов: Поиск доступных сеансов по местоположению, дате и фильму

• Выбор мест: Просмотр интерактивных карт зала и проверка доступности

• Управление бронированием: Бронирование мест с проверкой доступности в реальном времени

• Обработка платежей: Обработка имитированных платёжных транзакций с подтверждающими квитанциями

• Поддержка нескольких локаций: Поиск по нескольким кинотеатрам AMC

Related MCP server: Travel Amadeus MCP Server

Быстрый старт 🚀

Предварительные требования

• Python 3.8+

• Docker (опционально, для развёртывания в контейнере)

Установка

Вариант 1: Локальная установка

1. Клонируйте репозиторий:

git clone <repository-url>
cd amc-mcp

2. Установите зависимости:

pip install -r requirements.txt

3. Установите пакет:

pip install -e .

4. Запустите сервер:

python -m amc_mcp.fastmcp_server

Вариант 2: Развёртывание через Docker

1. Соберите и запустите с помощью Docker Compose:

docker-compose up --build

2. Или соберите и запустите вручную:

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

Справочник MCP-инструментов 🛠️

1. get_now_showing

Возвращает список фильмов, которые сейчас идут в указанном месте.

Входные данные:

{
  "location": "Boston, MA"
}

Выходные данные:

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

Предлагает фильмы на основе настроения, жанра или предпочтений.

Входные данные:

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

Выходные данные:

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

3. get_showtimes

Получает доступные сеансы для конкретного фильма и местоположения.

Входные данные:

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

Выходные данные:

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

Отображает доступные и забронированные места для конкретного сеанса.

Входные данные:

{
  "showtime_id": "st001"
}

Выходные данные:

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

Бронирует выбранные места для пользователя.

Входные данные:

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

Выходные данные:

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

Обрабатывает имитированную платёжную транзакцию.

Входные данные:

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

Выходные данные:

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

Пример сценария разговора 💬

Вот как выглядит типичный разговор о бронировании билетов в кино:

1. Пользователь: «Найди боевик рядом со мной на сегодня вечером».

   • Сервер вызывает: get_now_showing + get_recommendations

   • Возвращает: Список боевиков с сеансами

2. Пользователь: «Забронируй два места на "Дюну: Часть вторую" на 20:00».

   • Сервер вызывает: get_showtimes → get_seat_map → book_seats

   • Возвращает: Выбор мест и подтверждение бронирования

3. Пользователь: «Оплати моей картой».

   • Сервер вызывает: process_payment

   • Возвращает: Подтверждение оплаты с электронной квитанцией

Архитектура 🏗️

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

Модели данных 📊

Фильм

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

Кинотеатр

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

Сеанс

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

Разработка 👨💻

Добавление новых фильмов

Отредактируйте data/movies.json, чтобы добавить новые фильмы:

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

Добавление новых кинотеатров

Отредактируйте data/theaters.json:

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

Добавление сеансов

Отредактируйте data/showtimes.json и data/seats.json, чтобы добавить новые сеансы и соответствующие карты мест.

Тестирование

Ручное тестирование

Вы можете протестировать отдельные инструменты с помощью MCP-инспектора или подключившись к любому MCP-совместимому клиенту.

Тестирование с Claude Desktop

1. Настройте Claude Desktop для подключения к вашему MCP-серверу

2. Используйте естественный язык для проверки процесса бронирования

3. Пример: «Найди научно-фантастический фильм, который идёт сегодня вечером в Бостоне»

Конфигурация ⚙️

Переменные окружения

• PYTHONPATH: Установите значение /app/src для корректного разрешения модулей

• PYTHONUNBUFFERED: Установите значение 1 для логирования в реальном времени

• MCP_LOG_LEVEL: Устанавливает уровень логирования (DEBUG, INFO, WARNING, ERROR)

Конфигурация Docker

Сервер работает в лёгком контейнере Python 3.11 со следующими характеристиками:

• Не-root пользователь для безопасности

• Проверки работоспособности для мониторинга

• Монтирование томов для сохранения данных

• Изоляция сети

Вопросы безопасности 🔒

Это имитированная реализация для демонстрационных целей. В производственной среде:

1. Обработка платежей: Интеграция с реальными платёжными шлюзами (Stripe, PayPal)

2. Аутентификация: Добавление аутентификации и авторизации пользователей

3. Проверка данных: Внедрение комплексной проверки входных данных

4. Ограничение запросов: Добавление ограничения частоты API-запросов

5. Шифрование: Использование HTTPS и шифрование конфиденциальных данных

6. База данных: Замена JSON-файлов на настоящую базу данных

7. Логирование: Внедрение структурированного логирования и мониторинга

Будущие улучшения 🔮

• Интеграция с реальным AMC API: Подключение к настоящему API AMC Theatres

• Учётные записи пользователей: Постоянные профили пользователей и история бронирований

• Групповые бронирования: Поддержка совместного бронирования несколькими пользователями

• Программы лояльности: Интеграция с AMC Stubs

• Мобильные билеты: Генерация QR-кодов для входа по мобильному устройству

• Рекомендации по местам: ИИ-подсказки оптимальных мест

• Оповещения о ценах: Уведомление пользователей о скидках и акциях

• Социальные функции: Возможность делиться планами похода в кино с друзьями

• Доступность: Выбор мест с учётом требований ADA

• Многоязычность: Поддержка международных языков

Участие в разработке 🤝

1. Сделайте форк репозитория

2. Создайте ветку для функции: git checkout -b feature/new-feature

3. Внесите изменения и добавьте тесты

4. Зафиксируйте изменения: git commit -am 'Add new feature'

5. Отправьте изменения в ветку: git push origin feature/new-feature

6. Отправьте pull request

Лицензия 📄

Этот проект распространяется под лицензией MIT — подробности см. в файле LICENSE.

Поддержка 💬

По вопросам, проблемам или запросам новых функций:

• Создайте issue в репозитории GitHub

• Ознакомьтесь с документацией для поиска типовых решений

• Изучите примеры сценариев разговора

Приятного просмотра! 🍿🎬