nightlife-mcp

Supabase 기반의 나이트라이프 이벤트 탐색을 위한 MCP 서버입니다.

빠른 시작

프로덕션 엔드포인트: https://api.nightlife.dev/mcp

1. nightlife.dev에서 무료 API 키를 받으세요.

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: Eventfinda 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 설정 시)

• API 키 미들웨어가 포함된 스트리밍 가능한 HTTP 엔드포인트

• 구조화된 도구 출력 스키마 (outputSchema)

• 안정적인 오류 코드를 포함한 결정론적 도구 오류 페이로드

• /health에서 노출되는 런타임 요청/도구 메트릭

사전 요구 사항

• Node.js 18+

• Supabase 프로젝트 URL + 서비스 역할 키

설정

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 활성화)

DB API 키 모드 (권장)

HTTP 인증은 Supabase의 영구 API 키와 할당량 추적을 사용할 수 있습니다.

1. Supabase SQL 편집기에서 SQL 마이그레이션을 실행하세요:

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

2. .env에서 DB 인증 플래그가 활성화되어 있는지 확인하세요:

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를 한 번 출력합니다. 안전하게 저장하고 MCP HTTP 호출 시 사용하세요.

DB RPC를 사용할 수 없는 경우, MCP_HTTP_ALLOW_ENV_KEY_FALLBACK=true일 때만 MCP_HTTP_API_KEYS로 대체됩니다.

컨시어지 미충족 요청 백로그

공용 컨시어지 흐름은 지원되지 않는 사용자 의도를 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 첨부)

예약 가능한 장소를 먼저 찾으려면 다음을 사용하세요:

• vip_booking_supported_only=true와 함께 search_venues 사용

• 또는 get_venue_info를 사용하여 vip_booking_supported 확인

내부 장소 예약 작업자의 경우 DB 함수를 통해 대기열 작업을 요청하세요:

• public.claim_next_vip_agent_task(p_agent_id text)

VIP 운영 대시보드

내부 대시보드 경로:

• GET /ops/login

• POST /ops/login

• POST /ops/logout

• GET /ops/vip-dashboard

내부 관리자 API 경로 (쿠키 세션 보호):

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

추천을 위한 디버그 웹 UI:

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 응답에는 DB 기반 인증이 활성화된 경우 키 계층/소스 및 속도 제한 헤더가 포함됩니다:

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

• 도구 오류는 result.content[0].text에 JSON 텍스트 페이로드로 반환됩니다:

  • 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는 아키텍처의 진실된 소스입니다.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• cancel_vip_booking_requestA
• create_vip_booking_requestA
• get_event_detailsC
• get_guest_list_entry_statusA
• get_performer_infoA
• get_tonightB
• get_venue_infoB
• get_vip_booking_statusB