nightlife-mcp

Servidor MCP para el descubrimiento de eventos de vida nocturna respaldado por Supabase.

Inicio rápido

Endpoint de producción: https://api.nightlife.dev/mcp

1. Obtén una clave API gratuita en nightlife.dev

2. Añádela a la configuración de Claude Desktop (claude_desktop_config.json):

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

Para curl, el SDK de TypeScript y otros clientes, consulta CLIENT_SETUP.md.

Related MCP server: EvHenter MCP

Implementado (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, bajo MCP_ENABLE_RECOMMENDATIONS=true)

• Endpoint HTTP transmitible con middleware de clave API

• Esquemas de salida de herramientas estructurados (outputSchema)

• Cargas útiles de error de herramienta deterministas con códigos de error estables

• Métricas de solicitud/herramienta en tiempo de ejecución expuestas en /health

Requisitos previos

• Node.js 18+

• URL del proyecto Supabase + clave de rol de servicio

Configuración

cp .env.example .env
npm install

Establece las variables de entorno en .env:

• SUPABASE_URL

• SUPABASE_SERVICE_ROLE_KEY

Opcional:

• DEFAULT_CITY (predeterminado: tokyo)

• MCP_TOP_LEVEL_CITIES (ejemplo predeterminado: tokyo,san-francisco; controla available_cities en respuestas de ciudades no admitidas)

• DEFAULT_COUNTRY_CODE (predeterminado: JP)

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

• MCP_HTTP_REQUIRE_API_KEY (predeterminado: true)

• MCP_HTTP_USE_DB_KEYS (predeterminado: true)

• MCP_HTTP_ALLOW_ENV_KEY_FALLBACK (predeterminado: true)

• MCP_HTTP_API_KEYS (claves de respaldo heredadas separadas por comas)

• MCP_ENABLE_RECOMMENDATIONS (predeterminado: false; habilita get_recommendations)

Modo de clave API de base de datos (recomendado)

La autenticación HTTP puede utilizar claves API persistentes de Supabase además del seguimiento de cuotas.

1. Ejecuta la migración SQL en tu editor SQL de Supabase:

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

2. Asegúrate de que las banderas de autenticación de DB estén habilitadas en .env:

MCP_HTTP_REQUIRE_API_KEY=true
MCP_HTTP_USE_DB_KEYS=true
MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true

3. Crea un registro de clave API:

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

Esto imprime la api_key sin procesar una vez. Guárdala de forma segura y úsala en las llamadas HTTP de MCP.

Si el RPC de la base de datos no está disponible, el respaldo a MCP_HTTP_API_KEYS solo funciona cuando MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true.

Registro de solicitudes no satisfechas del conserje

Los flujos de conserjería públicos pueden registrar intenciones de usuario no admitidas en Supabase.

Ejecuta la migración:

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

Luego llama a la herramienta MCP log_unmet_request cuando no exista una buena respuesta a partir de los datos de vida nocturna disponibles.

Fase 1 de reserva VIP

El envío de reservas de mesas VIP y el seguimiento del estado están respaldados por Supabase.

Ejecuta la migración:

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

Luego llama a las herramientas MCP:

• create_vip_booking_request

• get_vip_booking_status

• get_vip_table_availability (leer disponibilidad de mesas por día según lugar/rango de fechas)

• get_vip_table_chart (leer gráfico de mesas estructurado con superposición opcional de estado por fecha y layout_image_url opcional)

Política de conversación para create_vip_booking_request:

• Confirma la fecha/hora de la reserva en la hora local del lugar antes de enviarla.

• Usa una redacción de confirmación de doble fecha, especialmente para llegadas a altas horas de la noche (00:00-05:59).

• Plantilla de confirmación requerida:

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

• Si el usuario da una hora como 2am sin un día, pregunta:

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

• Si el usuario cambia el día, regenera la confirmación antes de enviarla.

Las sesiones de nivel operativo también tienen herramientas de cola internas:

• list_vip_reservations (todas las reservas pendientes; estados predeterminados: submitted, in_review, confirmed)

• list_vip_requests_for_alerting (solo alertas pendientes)

• mark_vip_request_alert_sent

• claim_vip_request_after_ack

• update_vip_booking_status (establecer confirmed/rejected/cancelled con evento de auditoría)

• upsert_vip_venue_tables (escribir definiciones de mesas del lugar + coordenadas del gráfico + notas de mesa opcionales + layout_image_url opcional)

• upsert_vip_table_availability (escribir estados de mesa por fecha)

• upload_vip_table_chart_image (subir imagen del gráfico al almacenamiento y adjuntar layout_image_url a los metadatos de la mesa del lugar)

Para descubrir primero los lugares reservables, usa:

• search_venues con vip_booking_supported_only=true

• o get_venue_info y verifica vip_booking_supported

Para los trabajadores internos de reserva de lugares, reclama tareas de cola a través de la función de base de datos:

• public.claim_next_vip_agent_task(p_agent_id text)

Panel de control de operaciones VIP

Rutas internas del panel de control:

• GET /ops/login

• POST /ops/login

• POST /ops/logout

• GET /ops/vip-dashboard

Rutas internas de la API de administración (protegidas por sesión de cookie):

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

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

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

Variables de entorno requeridas:

• VIP_DASHBOARD_ADMINS (pares username:password separados por comas)

Variables de entorno opcionales:

• VIP_DASHBOARD_SESSION_TTL_MINUTES (predeterminado: 720)

• VIP_DASHBOARD_SESSION_COOKIE_NAME (predeterminado: vip_dashboard_session)

Ejecución

Stdio (clientes de escritorio locales):

npm run dev

HTTP transmitible:

npm run dev:http

Para compilación de producción:

npm run build
npm start

Para HTTP en producción:

npm run start:http

Verificación de humo de producción autenticada:

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

Sobrescrituras de entorno opcionales:

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

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

• NLT_SMOKE_CITY (predeterminado: tokyo)

Interfaz web de depuración para recomendaciones:

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

Notas

• El manejo de fechas admite tonight, this_weekend, YYYY-MM-DD y YYYY-MM-DD/YYYY-MM-DD.

• get_recommendations devuelve hasta 10 espacios modales diversos con respaldo dinámico consciente de la ciudad.

• Las herramientas de lugar y artista incluyen instantáneas de próximos eventos.

• log_unmet_request escribe las solicitudes de usuario no resueltas en public.concierge_unmet_requests.

• La fase 1 VIP escribe los envíos de reserva en public.vip_booking_requests y las tareas de cola de trabajadores en public.vip_agent_tasks.

• El inventario VIP escribe las definiciones de mesa en public.vip_venue_tables y los estados específicos de fecha en public.vip_table_availability.

• search_venues y get_venue_info incluyen vip_booking_supported para que los clientes puedan mostrar exactamente qué lugares aceptan envíos de reserva VIP.

• vip_booking_supported proviene de public.venues.vip_booking_enabled (separado de guest_list_enabled).

• create_vip_booking_request solo acepta lugares donde vip_booking_supported=true.

• El manejo de la ciudad está respaldado por public.cities (slug, zona horaria y corte de día de servicio).

• Las ciudades de nivel superior admitidas son configurables por el entorno (por ejemplo, tokyo y san-francisco), mientras que Tokio puede seguir siendo el predeterminado.

• Transporte Stdio: sin verificación de clave API.

• Transporte HTTP (/mcp): clave API requerida de forma predeterminada (MCP_HTTP_REQUIRE_API_KEY=true).

• Encabezados de clave API:

  • Authorization: Bearer <key>

  • x-api-key: <key>

• Las respuestas HTTP incluyen encabezados de nivel/fuente de clave y límite de tasa cuando la autenticación respaldada por DB está activa:

  • X-API-Key-Tier

  • X-API-Key-Source

  • X-RateLimit-Daily-Limit

  • X-RateLimit-Daily-Remaining

  • X-RateLimit-Minute-Limit

  • X-RateLimit-Minute-Remaining

• Endpoint de salud: /health.

• Página de depuración para pruebas manuales de herramientas: /debug/recommendations.

• Los errores de la herramienta se devuelven como cargas útiles de texto JSON en 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

Contribución y CI

Consulta CONTRIBUTING.md para el flujo de trabajo y las reglas. Los agentes de IA leen AGENTS.md. CLAUDE.md es la fuente de verdad de la arquitectura.