nightlife-mcp

MCP-сервер для поиска событий ночной жизни на базе Supabase.

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

Продакшн-эндпоинт: https://api.nightlife.dev/mcp

1. Получите бесплатный API-ключ на nightlife.dev

2. Добавьте его в конфигурацию Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "nightlife": {
      "url": "https://api.nightlife.dev/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Информацию о curl, TypeScript SDK и других клиентах см. в CLIENT_SETUP.md.

Related MCP server: EvHenter MCP

Реализовано (v0.3)

• search_events

• get_tonight

• get_event_details

• search_venues

• get_venue_info

• search_performers

• get_performer_info

• log_unmet_request

• create_vip_booking_request

• get_vip_booking_status

• get_vip_table_availability

• get_vip_table_chart

• get_recommendations (v0.2, при MCP_ENABLE_RECOMMENDATIONS=true)

• Потоковый HTTP-эндпоинт с middleware для API-ключа

• Структурированные схемы вывода инструментов (outputSchema)

• Детерминированные полезные нагрузки ошибок инструментов со стабильными кодами ошибок

• Метрики запросов/инструментов во время выполнения доступны по адресу /health

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

• Node.js 18+

• URL проекта Supabase + ключ service role

Настройка

cp .env.example .env
npm install

Установите переменные окружения в .env:

• SUPABASE_URL

• SUPABASE_SERVICE_ROLE_KEY

Опционально:

• DEFAULT_CITY (по умолчанию: tokyo)

• MCP_TOP_LEVEL_CITIES (пример по умолчанию: tokyo,san-francisco; управляет available_cities в ответах для неподдерживаемых городов)

• DEFAULT_COUNTRY_CODE (по умолчанию: JP)

• NIGHTLIFE_BASE_URL (по умолчанию: https://nightlifetokyo.com)

• MCP_HTTP_REQUIRE_API_KEY (по умолчанию: true)

• MCP_HTTP_USE_DB_KEYS (по умолчанию: true)

• MCP_HTTP_ALLOW_ENV_KEY_FALLBACK (по умолчанию: true)

• MCP_HTTP_API_KEYS (запятая-разделенные устаревшие резервные ключи)

• MCP_ENABLE_RECOMMENDATIONS (по умолчанию: false; включает get_recommendations)

Режим API-ключей БД (Рекомендуется)

HTTP-аутентификация может использовать постоянные API-ключи из Supabase плюс отслеживание квот.

1. Выполните SQL-миграцию в редакторе SQL Supabase:

-- copy file contents from:
-- supabase/migrations/20260219094000_mcp_api_keys.sql

2. Убедитесь, что флаги аутентификации БД включены в .env:

MCP_HTTP_REQUIRE_API_KEY=true
MCP_HTTP_USE_DB_KEYS=true
MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true

3. Создайте запись API-ключа:

npm run key:create -- --name claude-desktop --tier starter --daily-quota 1000 --minute-quota 60

Это один раз выведет необработанный api_key. Сохраните его в безопасности и используйте в HTTP-вызовах MCP.

Если DB RPC недоступен, резервный вариант MCP_HTTP_API_KEYS работает только при MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true.

Журнал невыполненных запросов консьержа

Публичные потоки консьержа могут записывать неподдерживаемые намерения пользователей в Supabase.

Запустите миграцию:

-- copy file contents from:
-- supabase/migrations/20260226_concierge_unmet_requests.sql

Затем вызывайте инструмент MCP log_unmet_request, когда в доступных данных о ночной жизни нет подходящего ответа.

VIP-бронирование, этап 1

Отправка заявок на VIP-бронирование столов и отслеживание статуса поддерживаются через Supabase.

Запустите миграцию:

-- copy file contents from:
-- supabase/migrations/20260227143000_vip_phase1_requests_and_queue.sql
-- supabase/migrations/20260228124500_add_vip_booking_enabled_to_venues.sql
-- and if already deployed before 2026-02-28:
-- supabase/migrations/20260228111000_vip_outward_language_defaults.sql
-- supabase/migrations/20260301010000_vip_table_availability_chart.sql
-- supabase/migrations/20260301114000_vip_table_chart_storage_bucket.sql
-- supabase/migrations/20260303093000_vip_dashboard_admin_edits.sql

Затем вызывайте инструменты MCP:

• create_vip_booking_request

• get_vip_booking_status

• get_vip_table_availability (чтение доступности столов по дням для заведения/диапазона дат)

• get_vip_table_chart (чтение структурированной схемы столов с опциональным наложением статуса по датам и опциональным layout_image_url)

Политика общения для create_vip_booking_request:

• Подтвердите дату/время бронирования по местному времени заведения перед отправкой.

• Используйте формулировку с двойной датой, особенно для ночных прибытий (00:00-05:59).

• Обязательный шаблон подтверждения:

  • Just to confirm: you want a table for [Night Day] night ([Night Date]), arriving around [Time] on [Arrival Day], [Arrival Date] ([Timezone]). I'll submit that as [Night Day] night with [Time] arrival. Is that correct?

• Если пользователь называет время, например 2am, без указания дня, спросите:

  • Do you mean 2:00 AM after Thursday night (Friday morning), or after Friday night (Saturday morning)?

• Если пользователь меняет день, заново сгенерируйте подтверждение перед отправкой.

Сессии уровня Ops также имеют инструменты внутренней очереди:

• list_vip_reservations (все невыполненные бронирования; статусы по умолчанию: submitted, in_review, confirmed)

• list_vip_requests_for_alerting (только просроченные оповещения)

• mark_vip_request_alert_sent

• claim_vip_request_after_ack

• update_vip_booking_status (установка confirmed/rejected/cancelled с событием аудита)

• upsert_vip_venue_tables (запись определений столов заведения + координаты схемы + опциональные примечания к столам + опциональный layout_image_url)

• upsert_vip_table_availability (запись статусов по датам)

• upload_vip_table_chart_image (загрузка изображения схемы в хранилище и прикрепление layout_image_url к метаданным столов заведения)

Чтобы сначала найти заведения, доступные для бронирования, используйте:

• search_venues с vip_booking_supported_only=true

• или get_venue_info и проверьте vip_booking_supported

Для внутренних работников по бронированию заведений, забирайте задачи из очереди через функцию БД:

• public.claim_next_vip_agent_task(p_agent_id text)

VIP Ops Dashboard

Маршруты внутренней панели управления:

• GET /ops/login

• POST /ops/login

• POST /ops/logout

• GET /ops/vip-dashboard

Внутренние маршруты API администратора (защищены cookie-сессией):

• GET /api/v1/admin/vip-bookings

• GET /api/v1/admin/vip-bookings/:id

• PATCH /api/v1/admin/vip-bookings/:id

Обязательные переменные окружения:

• VIP_DASHBOARD_ADMINS (пары username:password, разделенные запятыми)

Опциональные переменные окружения:

• VIP_DASHBOARD_SESSION_TTL_MINUTES (по умолчанию: 720)

• VIP_DASHBOARD_SESSION_COOKIE_NAME (по умолчанию: vip_dashboard_session)

Запуск

Stdio (локальные десктопные клиенты):

npm run dev

Потоковый HTTP:

npm run dev:http

Для сборки продакшна:

npm run build
npm start

Для HTTP в продакшне:

npm run start:http

Аутентифицированная проверка работоспособности продакшна:

NLT_API_KEY=... npm run smoke:prod:auth

Опциональные переопределения окружения:

• NLT_MCP_URL (по умолчанию: https://api.nightlife.dev/mcp)

• NLT_REST_BASE_URL (по умолчанию: https://api.nightlife.dev/api/v1)

• NLT_SMOKE_CITY (по умолчанию: tokyo)

Отладочный веб-интерфейс для рекомендаций:

MCP_ENABLE_RECOMMENDATIONS=true npm run dev:http
# open http://127.0.0.1:3000/debug/recommendations

Примечания

• Обработка дат поддерживает tonight, this_weekend, YYYY-MM-DD и YYYY-MM-DD/YYYY-MM-DD.

• get_recommendations возвращает до 10 разнообразных слотов с динамическим резервным вариантом с учетом города.

• Инструменты для заведений и исполнителей включают снимки предстоящих событий.

• log_unmet_request записывает неразрешенные запросы пользователей в public.concierge_unmet_requests.

• VIP этап 1 записывает заявки на бронирование в public.vip_booking_requests, а задачи очереди работников в public.vip_agent_tasks.

• Инвентаризация VIP записывает определения столов в public.vip_venue_tables, а статусы по датам в public.vip_table_availability.

• search_venues и get_venue_info включают vip_booking_supported, чтобы клиенты могли точно видеть, какие заведения принимают заявки на VIP-бронирование.

• vip_booking_supported берется из public.venues.vip_booking_enabled (отдельно от guest_list_enabled).

• create_vip_booking_request принимает только те заведения, где vip_booking_supported=true.

• Обработка городов поддерживается public.cities (slug, часовой пояс и время отсечки рабочего дня).

• Поддерживаемые города верхнего уровня настраиваются в окружении (например, tokyo и san-francisco), при этом Токио может оставаться по умолчанию.

• Транспорт Stdio: проверка API-ключа отсутствует.

• Транспорт HTTP (/mcp): API-ключ требуется по умолчанию (MCP_HTTP_REQUIRE_API_KEY=true).

• Заголовки API-ключа:

  • Authorization: Bearer <key>

  • x-api-key: <key>

• HTTP-ответы включают уровень/источник ключа и заголовки ограничения скорости, когда активна аутентификация через БД:

  • X-API-Key-Tier

  • X-API-Key-Source

  • X-RateLimit-Daily-Limit

  • X-RateLimit-Daily-Remaining

  • X-RateLimit-Minute-Limit

  • X-RateLimit-Minute-Remaining

• Эндпоинт состояния: /health.

• Страница отладки для ручного тестирования инструментов: /debug/recommendations.

• Ошибки инструментов возвращаются как JSON-текстовые полезные нагрузки в result.content[0].text:

  • INVALID_DATE_FILTER

  • INVALID_EVENT_ID

  • UNSUPPORTED_EVENT_ID

  • EVENT_NOT_FOUND

  • INVALID_VENUE_ID

  • VENUE_NOT_FOUND

  • INVALID_PERFORMER_ID

  • PERFORMER_NOT_FOUND

  • INVALID_BOOKING_REQUEST

  • BOOKING_REQUEST_NOT_FOUND

  • BOOKING_STATUS_UPDATE_FAILED

  • VIP_TASK_NOT_AVAILABLE

  • VIP_ALERT_UPDATE_FAILED

  • VIP_CLAIM_FAILED

  • INVALID_REQUEST

  • REQUEST_WRITE_FAILED

  • DB_QUERY_FAILED

  • INTERNAL_ERROR

Участие и CI

См. CONTRIBUTING.md для рабочего процесса и правил. AI-агенты читают AGENTS.md. CLAUDE.md является источником истины по архитектуре.