mr-magic-mcp-server 0.2.6 → 0.3.1

package/.env.example

@@ -10,41 +10,65 @@
 #     OAuth client_credentials endpoint at runtime and refreshes the token in
 #     memory automatically. No disk, no scripts, no manual token copying needed.
 #
-#   Fallback token (env var) — static bearer token, no auto-refresh
-#     Set GENIUS_ACCESS_TOKEN. Works everywhere but the token must be
+#   Direct token (env var) — 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.
 #
-#   Cache token (on-disk) — local development only
+#   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=           # Auto-refresh: OAuth client ID  (enables runtime auto-refresh)
-GENIUS_CLIENT_SECRET=       # Auto-refresh: OAuth client secret (enables runtime auto-refresh)
-GENIUS_ACCESS_TOKEN=        # Fallback token: static bearer token (required if not using client credentials)
+GENIUS_CLIENT_ID=
+GENIUS_CLIENT_SECRET=
+GENIUS_DIRECT_TOKEN=
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # 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!
 # ───────────────────────────────────────────────────────────────────────────────
-# There are two ways to supply the Musixmatch token:
+# Token resolution priority (1 = highest):
 #
-#   Fallback token (env var) — recommended for production / ephemeral hosts
-#     Set MUSIXMATCH_FALLBACK_TOKEN or MUSIXMATCH_ALT_FALLBACK_TOKEN as an environment variable.
-#     Use this when persistent filesystem storage is not available (e.g. Render
-#     free tier, serverless, containers without a mounted volume).
-#     Resolution order: MUSIXMATCH_FALLBACK_TOKEN (1st) → MUSIXMATCH_ALT_FALLBACK_TOKEN (2nd)
+#   1. MUSIXMATCH_DIRECT_TOKEN (env var)
+#        Static bearer token. Works everywhere but must be manually updated on
+#        expiry. Use when no other option is available.
 #
-#   Cache token (on-disk) — local development only
-#     Run `npm run fetch:musixmatch-token` to sign in via Playwright and write
-#     the token to `.cache/musixmatch-token.json`. The server reads it on startup.
-#     Not suitable for ephemeral hosts where the filesystem is wiped on restart.
+#   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.
 # ═══════════════════════════════════════════════════════════════════════════════
-MUSIXMATCH_FALLBACK_TOKEN=      # Fallback token (1st priority) — set this in production
-MUSIXMATCH_ALT_FALLBACK_TOKEN=           # Fallback token (2nd priority) — alternative env var
+MUSIXMATCH_DIRECT_TOKEN=
+
+# 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.
+#
+# Upstash Redis: reuse the same creds as the export backend (see below) — no extra setup.
+# 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)
+# Optional overrides (defaults are sensible for most users)
+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)
+
+# 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
@@ -60,7 +84,7 @@ AIRTABLE_PERSONAL_ACCESS_TOKEN=
 # ───────────────────────────────────────────────────────────────────────────────
 # 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; best for production/ephemeral hosts
+# redis  — stores in Upstash Redis KV store; best for production/ephemeral hosts
 # ═══════════════════════════════════════════════════════════════════════════════
 MR_MAGIC_EXPORT_BACKEND=    # local | inline | redis
 
@@ -68,6 +92,8 @@ MR_MAGIC_EXPORT_BACKEND=    # local | inline | redis
 MR_MAGIC_EXPORT_DIR=        # Absolute path to the directory to write export files into
 
 # 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=
 
@@ -93,10 +119,6 @@ MELON_COOKIE=               # Pin a browser session cookie for consistent result
 # Advanced / Debug  (safe to leave unset in production)
 # ═══════════════════════════════════════════════════════════════════════════════
 
-# Override project root and .env file path resolution (rarely needed)
-MR_MAGIC_ROOT=
-MR_MAGIC_ENV_PATH=
-
 # 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
@@ -104,7 +126,7 @@ 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 dev only)
+# 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
 
@@ -112,6 +134,9 @@ MUSIXMATCH_TOKEN_CACHE=.cache/musixmatch-token.json
 # automatically (headless) if no token is available
 MUSIXMATCH_AUTO_FETCH=0
 
+# 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)
@@ -123,3 +148,7 @@ MR_MAGIC_SESSIONLESS=0            # Set to 1 to force sessionless mode (each req
 
 # 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=