nightlife-mcp

MCP-Server für die Entdeckung von Nachtleben-Events, unterstützt durch Supabase.

Schnellstart

Produktions-Endpunkt: https://api.nightlife.dev/mcp

1. Holen Sie sich einen kostenlosen API-Schlüssel unter nightlife.dev

2. Fügen Sie ihn zur Claude Desktop-Konfiguration (claude_desktop_config.json) hinzu:

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

Für curl, das TypeScript SDK und andere Clients siehe CLIENT_SETUP.md.

Related MCP server: EvHenter MCP

Implementiert (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, hinter MCP_ENABLE_RECOMMENDATIONS=true)

• Streambarer HTTP-Endpunkt mit API-Key-Middleware

• Strukturierte Tool-Ausgabeschemata (outputSchema)

• Deterministische Tool-Fehler-Payloads mit stabilen Fehlercodes

• Laufzeit-Anfrage-/Tool-Metriken verfügbar unter /health

Voraussetzungen

• Node.js 18+

• Supabase-Projekt-URL + Service-Role-Key

Einrichtung

cp .env.example .env
npm install

Setzen Sie die Umgebungsvariablen in .env:

• SUPABASE_URL

• SUPABASE_SERVICE_ROLE_KEY

Optional:

• DEFAULT_CITY (Standard: tokyo)

• MCP_TOP_LEVEL_CITIES (Standardbeispiel: tokyo,san-francisco; steuert available_cities bei Antworten für nicht unterstützte Städte)

• DEFAULT_COUNTRY_CODE (Standard: JP)

• NIGHTLIFE_BASE_URL (Standard: https://nightlifetokyo.com)

• MCP_HTTP_REQUIRE_API_KEY (Standard: true)

• MCP_HTTP_USE_DB_KEYS (Standard: true)

• MCP_HTTP_ALLOW_ENV_KEY_FALLBACK (Standard: true)

• MCP_HTTP_API_KEYS (durch Kommas getrennte Legacy-Fallback-Schlüssel)

• MCP_ENABLE_RECOMMENDATIONS (Standard: false; aktiviert get_recommendations)

DB-API-Key-Modus (Empfohlen)

Die HTTP-Authentifizierung kann persistente API-Schlüssel von Supabase sowie eine Kontingentverfolgung nutzen.

1. Führen Sie die SQL-Migration in Ihrem Supabase SQL-Editor aus:

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

2. Stellen Sie sicher, dass die DB-Auth-Flags in .env aktiviert sind:

MCP_HTTP_REQUIRE_API_KEY=true
MCP_HTTP_USE_DB_KEYS=true
MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true

3. Erstellen Sie einen API-Key-Datensatz:

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

Dies gibt den rohen api_key einmalig aus. Speichern Sie ihn sicher und verwenden Sie ihn bei MCP-HTTP-Aufrufen.

Wenn der DB-RPC nicht verfügbar ist, funktioniert der Fallback auf MCP_HTTP_API_KEYS nur, wenn MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true gesetzt ist.

Concierge-Backlog für nicht erfüllte Anfragen

Öffentliche Concierge-Abläufe können nicht unterstützte Benutzerabsichten in Supabase protokollieren.

Migration ausführen:

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

Rufen Sie dann das MCP-Tool log_unmet_request auf, wenn keine gute Antwort aus den verfügbaren Nachtleben-Daten existiert.

VIP-Buchung Phase 1

Die Einreichung von VIP-Tischbuchungen und die Statusverfolgung werden durch Supabase unterstützt.

Migration ausführen:

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

Rufen Sie dann die MCP-Tools auf:

• create_vip_booking_request

• get_vip_booking_status

• get_vip_table_availability (Tischverfügbarkeit pro Tag nach Veranstaltungsort/Datumsbereich lesen)

• get_vip_table_chart (Strukturiertes Tischdiagramm mit optionalem Status-Overlay pro Datum und optionalem layout_image_url lesen)

Konversationsrichtlinie für create_vip_booking_request:

• Bestätigen Sie das Buchungsdatum/-uhrzeit in der Ortszeit des Veranstaltungsortes vor dem Absenden.

• Verwenden Sie eine Bestätigungsformulierung mit zwei Daten, insbesondere bei Ankünften spät in der Nacht (00:00-05:59).

• Erforderliche Bestätigungsvorlage:

  • 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?

• Wenn der Benutzer eine Uhrzeit wie 2am ohne Tag angibt, fragen Sie:

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

• Wenn der Benutzer den Tag ändert, generieren Sie die Bestätigung vor dem Absenden neu.

Ops-Tier-Sitzungen verfügen auch über interne Warteschlangen-Tools:

• list_vip_reservations (alle ausstehenden Reservierungen; Standardstatus: submitted, in_review, confirmed)

• list_vip_requests_for_alerting (nur fällige Alarme)

• mark_vip_request_alert_sent

• claim_vip_request_after_ack

• update_vip_booking_status (setzt confirmed/rejected/cancelled mit Audit-Ereignis)

• upsert_vip_venue_tables (schreibt Definitionen für Veranstaltungsort-Tische + Diagrammkoordinaten + optionale Tischnotizen + optionales layout_image_url)

• upsert_vip_table_availability (schreibt Tischstatus pro Datum)

• upload_vip_table_chart_image (lädt Diagrammbild in den Speicher hoch und fügt layout_image_url zu den Metadaten des Veranstaltungsort-Tisches hinzu)

Um zuerst buchbare Veranstaltungsorte zu entdecken, verwenden Sie:

• search_venues mit vip_booking_supported_only=true

• oder get_venue_info und prüfen Sie vip_booking_supported

Für interne Mitarbeiter bei der Veranstaltungsort-Buchung, fordern Sie Warteschlangenaufgaben über die DB-Funktion an:

• public.claim_next_vip_agent_task(p_agent_id text)

VIP-Ops-Dashboard

Interne Dashboard-Routen:

• GET /ops/login

• POST /ops/login

• POST /ops/logout

• GET /ops/vip-dashboard

Interne Admin-API-Routen (Cookie-Sitzung geschützt):

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

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

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

Erforderliche Umgebungsvariablen:

• VIP_DASHBOARD_ADMINS (durch Kommas getrennte username:password-Paare)

Optionale Umgebungsvariablen:

• VIP_DASHBOARD_SESSION_TTL_MINUTES (Standard: 720)

• VIP_DASHBOARD_SESSION_COOKIE_NAME (Standard: vip_dashboard_session)

Ausführen

Stdio (lokale Desktop-Clients):

npm run dev

Streambares HTTP:

npm run dev:http

Für Produktions-Build:

npm run build
npm start

Für HTTP in der Produktion:

npm run start:http

Authentifizierter Produktions-Smoke-Check:

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

Optionale Umgebungs-Overrides:

• NLT_MCP_URL (Standard: https://api.nightlife.dev/mcp)

• NLT_REST_BASE_URL (Standard: https://api.nightlife.dev/api/v1)

• NLT_SMOKE_CITY (Standard: tokyo)

Debug-Web-UI für Empfehlungen:

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

Hinweise

• Die Datumsbehandlung unterstützt tonight, this_weekend, YYYY-MM-DD und YYYY-MM-DD/YYYY-MM-DD.

• get_recommendations gibt bis zu 10 verschiedene modale Slots mit dynamischem stadtbewusstem Fallback zurück.

• Veranstaltungsort- und Performer-Tools enthalten Snapshots kommender Events.

• log_unmet_request schreibt ungelöste Benutzeranfragen in public.concierge_unmet_requests.

• VIP Phase 1 schreibt Buchungseinreichungen in public.vip_booking_requests und Warteschlangenaufgaben für Mitarbeiter in public.vip_agent_tasks.

• VIP-Inventar schreibt Tischdefinitionen in public.vip_venue_tables und datumsspezifische Status in public.vip_table_availability.

• search_venues und get_venue_info enthalten vip_booking_supported, damit Clients genau anzeigen können, welche Veranstaltungsorte VIP-Buchungseinreichungen akzeptieren.

• vip_booking_supported stammt aus public.venues.vip_booking_enabled (getrennt von guest_list_enabled).

• create_vip_booking_request akzeptiert nur Veranstaltungsorte, bei denen vip_booking_supported=true ist.

• Die Stadtverwaltung wird durch public.cities (slug, Zeitzone und Service-Tages-Cutoff) unterstützt.

• Unterstützte Städte auf oberster Ebene sind umgebungskonfigurierbar (zum Beispiel tokyo und san-francisco), während Tokio der Standard bleiben kann.

• Stdio-Transport: keine API-Key-Prüfung.

• HTTP-Transport (/mcp): API-Key standardmäßig erforderlich (MCP_HTTP_REQUIRE_API_KEY=true).

• API-Key-Header:

  • Authorization: Bearer <key>

  • x-api-key: <key>

• HTTP-Antworten enthalten Key-Tier/Quelle und Ratenbegrenzungs-Header, wenn DB-gestützte Authentifizierung aktiv ist:

  • 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-Endpunkt: /health.

• Debug-Seite für manuelles Tool-Testen: /debug/recommendations.

• Tool-Fehler werden als JSON-Text-Payloads in result.content[0].text zurückgegeben:

  • 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

Mitwirken & CI

Siehe CONTRIBUTING.md für den Workflow und die Regeln. KI-Agenten lesen AGENTS.md. CLAUDE.md ist die Quelle der Wahrheit für die Architektur.