# ═══════════════════════════════════════════════════════════════════════════════
# REQUIRED — Genius API credentials
# At minimum one of these is needed for Genius lyrics support.
# Get all three from https://genius.com/api-clients
# ───────────────────────────────────────────────────────────────────────────────
# There are three ways to supply the Genius token (tried in order):
#
#   Direct token (env var, see debug section below)) — static bearer token, no auto-refresh
#     Set GENIUS_DIRECT_TOKEN. Works everywhere but the token must be
#     manually updated on expiry (or redeploy with a new value).
#     Use this only when client_credentials are unavailable.
#
#   Auto-refresh (recommended for all deployments, including Render/ephemeral)
#     Set GENIUS_CLIENT_ID + GENIUS_CLIENT_SECRET. The server calls the Genius
#     OAuth client_credentials endpoint at runtime and refreshes the token in
#     memory automatically. No disk, no scripts, no manual token copying needed.
#
#   Cache token (on-disk) — local instance or persistent servers only
#     Run `npm run fetch:genius-token` to write a token to
#     `.cache/genius-token.json`. The server reads it on startup when a
#     persistent, writable filesystem is available. Not suitable for
#     ephemeral hosts.
#
# ═══════════════════════════════════════════════════════════════════════════════

GENIUS_CLIENT_ID=
GENIUS_CLIENT_SECRET=

# ═══════════════════════════════════════════════════════════════════════════════
# REQUIRED (feature-specific) — Musixmatch
# At least one token source is needed for Musixmatch lyrics support.
# WARNING: Unauthorized Public API usage can result in a ban of your account!
# ───────────────────────────────────────────────────────────────────────────────
# Token resolution priority (1 = highest):
#
#   1. MUSIXMATCH_DIRECT_TOKEN (env var, see debug section below)
#        Static bearer token. Works everywhere but must be manually updated on
#        expiry. Use when no other option is available.
#
#   2. KV store — Upstash Redis or Cloudflare KV  (recommended for ephemeral / npx)
#        Run `npm run fetch:musixmatch-token` once to sign in and push the token
#        to KV automatically. The server reads it from KV on startup.
#        Works for npx installs and any deployment without a local filesystem.
#        Configure with UPSTASH_REDIS_REST_URL/TOKEN (already used by the export
#        backend) or the Cloudflare KV vars below.
#
#   3. On-disk cache token (local dev / persistent servers only)
#        Run `npm run fetch:musixmatch-token` — writes .cache/musixmatch-token.json.
#        The server reads it on startup when a writable filesystem is available.
# ═══════════════════════════════════════════════════════════════════════════════
#
# Headless / Render deployment — push a pre-captured token without opening a browser.
# run `npm run fetch:musixmatch-token` or sign into Musixmatch manually to get a token, then set it in the env to push it to the KV store without browser automation.
# Set MUSIXMATCH_DIRECT_TOKEN to the full musixmatchUserToken JSON payload (from fetch:musixmatch-token output),
#
# then run `npm run push:musixmatch-token` or prepend it to the start command:
#   npm run push:musixmatch-token && npm run server:mcp:http
# If unset, push:musixmatch-token exits silently (safe no-op in start commands).
# MUSIXMATCH_DIRECT_TOKEN also serves as the runtime token override (highest env priority).
#
# ═══════════════════════════════════════════════════════════════════════════════
# REQUIRED (feature-specific) — Airtable
# Only needed if you use the push_catalog_to_airtable tool.
# Get from https://airtable.com/create/tokens
# ═══════════════════════════════════════════════════════════════════════════════

AIRTABLE_PERSONAL_ACCESS_TOKEN=

# ═══════════════════════════════════════════════════════════════════════════════
# Export / Storage backend
# Controls where build_catalog_payload results are stored for download.
# Set MR_MAGIC_EXPORT_BACKEND to one of: local | inline | redis
# ───────────────────────────────────────────────────────────────────────────────
# local  — writes files to MR_MAGIC_EXPORT_DIR (default; requires writable FS)
# inline — embeds payload directly in the MCP response (no storage needed)
# redis  — stores in Upstash Redis KV store; best for production/ephemeral hosts
# ═══════════════════════════════════════════════════════════════════════════════

MR_MAGIC_EXPORT_BACKEND=    # local | inline | redis

# KV store for Musixmatch token persistence (ephemeral deployments / npx installs)
# Priority: Upstash Redis (priority 1) → Cloudflare KV (priority 2)
# If both are set, Upstash Redis is used and Cloudflare KV is ignored.

# Note: Upstash Redis is required when BACKEND=redis — get from https://console.upstash.com/redis/rest
# These same credentials are also used by the Musixmatch KV token store, so
# setting them once enables both features.
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

# Cloudflare KV: set the three CF_* vars; create a namespace at dash.cloudflare.com.
CF_API_TOKEN=              # Cloudflare API token with KV:Edit permission (CF KV only)
CF_ACCOUNT_ID=             # Cloudflare account ID (CF KV only)
CF_KV_NAMESPACE_ID=        # KV namespace ID to store the token in (CF KV only)

# Required when BACKEND=local
MR_MAGIC_EXPORT_DIR=/Users/yourusername/Downloads/magic-export/        # Absolute path to the directory to write export files into

# Base URL the server uses to build download links returned to the MCP client.
# Examples: https://yourserver.com  |  http://localhost:3444 | http://localhost:3333
# See README for details.
MR_MAGIC_DOWNLOAD_BASE_URL=

# ═══════════════════════════════════════════════════════════════════════════════
# Server & Runtime
# ═══════════════════════════════════════════════════════════════════════════════

PORT=                       # Override all server ports (default: 3444 MCP / 3333 HTTP automation)
LOG_LEVEL=                  # error | warn | info | debug  (default: info)
MR_MAGIC_QUIET_STDIO=0      # Set to 1 to suppress non-error stdout logs (recommended under stdio MCP clients)
MR_MAGIC_HTTP_TIMEOUT_MS=10000  # Global outbound HTTP timeout in ms (default: 10000)

# ═══════════════════════════════════════════════════════════════════════════════
# Optional — Melon provider
# ═══════════════════════════════════════════════════════════════════════════════

MELON_COOKIE=               # Pin a browser session cookie for consistent results; anonymous access usually works without it

# ═══════════════════════════════════════════════════════════════════════════════
# Advanced / Debug  (safe to leave unset in production)
# ═══════════════════════════════════════════════════════════════════════════════

# Inline payload size threshold: auto-promotes to reference transport when
# lyrics exceed this many characters and omitInlineLyrics is true (default: 1500)
MR_MAGIC_INLINE_PAYLOAD_MAX_CHARS=1500

# Export TTL in seconds for local and redis backends (default: 3600 / 1 hour)
MR_MAGIC_EXPORT_TTL_SECONDS=3600

# Override the on-disk cache token paths (local instances/ persistent servers only)
GENIUS_TOKEN_CACHE=.cache/genius-token.json
MUSIXMATCH_TOKEN_CACHE=.cache/musixmatch-token.json

#   Direct tokens — Use these as temp overrides for testing or debugging, but for long-term use the auto-refresh or KV options are recommended to avoid manual token management.
#   Set GENIUS_DIRECT_TOKEN and MUSIXMATCH_DIRECT_TOKEN to the full token payloads (from fetch-genius-token and fetch-musixmatch-token output), then restart the server.
GENIUS_DIRECT_TOKEN=
MUSIXMATCH_DIRECT_TOKEN=

# Musixmatch: when 1, provider will attempt to re-run the fetch script
# automatically (headless) if no token is available
MUSIXMATCH_AUTO_FETCH=0

# Optional overrides for Musixmatch KV token storage (only needed if using KV storage and want to customize beyond the defaults)
MUSIXMATCH_TOKEN_KV_KEY=           # KV key name (default: mr-magic:musixmatch-token)
MUSIXMATCH_TOKEN_KV_TTL_SECONDS=   # Token TTL in seconds (default: 2592000 = 30 days)

# Playwright Headless mode toggle for fetch scripts that require browser automation (default: false)
HEADLESS=

# MCP tool argument chunk logging — enable to debug truncation issues
MR_MAGIC_LOG_TOOL_ARGS_CHUNKS=0   # Set to 1 to emit per-chunk MCP tool argument previews
MR_MAGIC_TOOL_ARG_CHUNK_SIZE=400  # Chunk size in chars (only used when LOG_TOOL_ARGS_CHUNKS=1)

# Streamable HTTP MCP transport diagnostics
MR_MAGIC_MCP_HTTP_DIAGNOSTICS=0  # Set to 1 to log enriched request diagnostics at transport ingress
MR_MAGIC_ALLOWED_HOSTS=           # Optional. Comma-separated extra allowed hostnames for DNS rebinding protection when binding to 0.0.0.0 (e.g. custom domains). RENDER_EXTERNAL_HOSTNAME is auto-included on Render.
MR_MAGIC_SESSIONLESS=0            # Set to 1 to force sessionless mode (each request handled by a fresh server/transport, no in-memory session). Auto-enabled on Render. Set manually on ECS, Fly.io, Railway, etc.

# SDK repro harness verbose HTTP logging
MR_MAGIC_SDK_REPRO_HTTP_DEBUG=0  # Set to 1 for verbose HTTP previews in the SDK repro harness script

# Override project root and .env file path resolution (rarely needed)
MR_MAGIC_ROOT=
MR_MAGIC_ENV_PATH=