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

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

数据库 API 密钥模式（推荐）

HTTP 身份验证可以使用来自 Supabase 的持久 API 密钥以及配额跟踪。

1. 在 Supabase SQL 编辑器中运行 SQL 迁移：

-- 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。请安全保存并在 MCP HTTP 调用中使用它。

如果数据库 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 预订第一阶段

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

• 如果用户更改了日期，请在提交前重新生成确认信息。

运营级会话还具有内部队列工具：

• 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 运营仪表板

内部仪表板路由：

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

用于推荐的调试 Web 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 第一阶段将预订提交写入 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 是架构的真理来源。