mr-magic-mcp-server 0.2.5 → 0.3.0

package/.env.example

@@ -10,8 +10,8 @@
 #     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.
 #
@@ -23,28 +23,51 @@
 # ═══════════════════════════════════════════════════════════════════════════════
 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_DIRECT_TOKEN=        # Direct token: static bearer token (used when client credentials are unavailable)
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # 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=        # Direct token — set this in production / ephemeral deployments (highest priority env var)
+
+# 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.
+# 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
@@ -68,6 +91,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,6 +118,9 @@ MELON_COOKIE=               # Pin a browser session cookie for consistent result
 # Advanced / Debug  (safe to leave unset in production)
 # ═══════════════════════════════════════════════════════════════════════════════
 
+# Playwright Headless mode toggle for fetch scripts that require browser automation (default: false)
+HEADLESS=
+
 # Override project root and .env file path resolution (rarely needed)
 MR_MAGIC_ROOT=
 MR_MAGIC_ENV_PATH=

package/README.md

@@ -37,28 +37,123 @@ automations, and CLI aficionados can all request lyrics from a single toolchain.
 
 ### Quick start — npx (no clone required)
 
-The easiest way to use Mr. Magic in an MCP client is via `npx`. No clone or local
-install needed — the package is fetched from npm on first run and cached locally:
+The easiest way to use Mr. Magic is via `npx`. No clone or local install needed —
+the package is fetched from npm on first run and cached locally.
+
+#### MCP stdio server (local MCP clients — Cline, Claude Desktop, etc.)
 
 ```bash
 npx -y mr-magic-mcp-server
 ```
 
-Or install globally so the binaries are always on `PATH`:
+Credentials are passed via the `env` block in your MCP client config (see
+[MCP Client Configuration](#mcp-client-configuration)).
+
+#### MCP Streamable HTTP server (remote / browser-based MCP clients)
+
+The Streamable HTTP server is the correct choice for TypingMind, any browser-based
+client, or whenever you're hosting Mr. Magic on a remote machine.
 
 ```bash
-npm install -g mr-magic-mcp-server
+# Streamable HTTP — listens on port 3444, endpoint: /mcp
+GENIUS_DIRECT_TOKEN=your_token \
+MUSIXMATCH_DIRECT_TOKEN=your_token \
+  npx -y --package mr-magic-mcp-server mcp-http-server
+```
+
+Connect your client to `http://localhost:3444/mcp` (or your public URL + `/mcp`).
+
+The same server also exposes the **legacy SSE** endpoints for older clients:
+- `GET  /sse` — opens the event stream
+- `POST /messages?sessionId=...` — sends JSON-RPC messages
+
+Both protocols run on the same port simultaneously — no extra config needed.
+
+#### JSON HTTP automation server
+
+```bash
+# JSON HTTP — listens on port 3333, endpoint: POST /
+GENIUS_DIRECT_TOKEN=your_token \
+  npx -y --package mr-magic-mcp-server http-server
 ```
 
-When installed globally, start any server directly:
+#### Global install (binaries always on PATH)
 
 ```bash
-mcp-server           # MCP stdio server (recommended for local MCP clients)
-mcp-http-server      # Streamable HTTP MCP server
+npm install -g mr-magic-mcp-server
+
+mcp-server           # MCP stdio server
+mcp-http-server      # Streamable HTTP MCP server (+ legacy SSE on same port)
 http-server          # JSON HTTP automation server
 mrmagic-cli --help   # CLI
 ```
 
+#### Musixmatch token for npx / ephemeral / headless installs
+
+When running via `npx`, on Render free tier, or on any server without a browser or
+persistent filesystem, the Musixmatch token cannot be captured via Playwright there.
+The workflow is:
+
+1. **Capture the token locally** (one-time on any machine with a browser):
+
+   ```bash
+   git clone https://github.com/mrnajiboy/mr-magic-mcp-server.git
+   cd mr-magic-mcp-server && npm install
+   npm run fetch:musixmatch-token
+   ```
+
+   After signing in, the script prints the full token JSON payload.
+   Copy the entire printed JSON object (the `MUSIXMATCH_DIRECT_TOKEN=...` line).
+
+2. **Push to KV** so the server can read it on every cold start.
+   Set up Upstash Redis (free tier at [console.upstash.com](https://console.upstash.com/redis))
+   and run the push script with KV credentials. No browser needed:
+
+   ```bash
+   UPSTASH_REDIS_REST_URL=https://xxx.upstash.io \
+   UPSTASH_REDIS_REST_TOKEN=your_upstash_token \
+   MUSIXMATCH_DIRECT_TOKEN='<paste token JSON here>' \
+     npm run push:musixmatch-token
+   ```
+
+3. **Start the server** with the same Upstash credentials — it reads the token from
+   KV on every cold start (no `MUSIXMATCH_DIRECT_TOKEN` needed when KV is configured):
+
+   ```bash
+   GENIUS_DIRECT_TOKEN=... \
+   UPSTASH_REDIS_REST_URL=https://xxx.upstash.io \
+   UPSTASH_REDIS_REST_TOKEN=your_upstash_token \
+     npx -y --package mr-magic-mcp-server mcp-http-server
+   ```
+
+4. Re-run steps 1–2 only when the Musixmatch token expires (typically ~30 days).
+
+#### Musixmatch on Render (headless, no SSH)
+
+On Render free tier you cannot SSH in or open a browser. The recommended pattern is:
+
+1. Run `npm run fetch:musixmatch-token` locally, copy the token JSON from the output.
+
+2. In the Render Dashboard → **Environment** tab, set:
+   - `MUSIXMATCH_DIRECT_TOKEN` = `<your token JSON>` *(used as both push source and runtime override)*
+   - `UPSTASH_REDIS_REST_URL` = your Upstash endpoint
+   - `UPSTASH_REDIS_REST_TOKEN` = your Upstash token
+
+3. Set the Render **Start Command** to:
+   ```
+   npm run push:musixmatch-token && npm run server:mcp:http
+   ```
+   On every (re)start, the token is pushed to Upstash then the server reads it
+   from KV. If `MUSIXMATCH_DIRECT_TOKEN` is unset the push step is a silent no-op.
+
+4. When the token expires: update `MUSIXMATCH_DIRECT_TOKEN` from a fresh local
+   `fetch:musixmatch-token` run, trigger a redeploy on Render. Done.
+
+> **Genius on ephemeral hosts:** Genius does not need this flow.
+> Set `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET` instead — the server calls the
+> Genius OAuth `client_credentials` endpoint at runtime, auto-refreshes the token
+> in memory, and never needs a browser, a KV store, or a captured session token.
+
 ### Local repo (development / contribution)
 
 1. Clone or download the repository:
@@ -111,23 +206,36 @@ grouped below by purpose.
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `GENIUS_CLIENT_ID`     | OAuth client ID for auto-refresh (recommended). Get from [genius.com/api-clients](https://genius.com/api-clients). |
 | `GENIUS_CLIENT_SECRET` | OAuth client secret for auto-refresh (recommended).                                                                |
-| `GENIUS_ACCESS_TOKEN`  | Static fallback bearer token. Used when client credentials are unavailable.                                        |
+| `GENIUS_DIRECT_TOKEN`  | Static direct bearer token. Used when client credentials are unavailable.                                          |
 
 Token resolution order (first match wins):
 
 1. In-memory runtime cache
 2. Auto-refresh via `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET` ← **recommended**
-3. `GENIUS_ACCESS_TOKEN` env var (static, no auto-refresh)
-4. On-disk `.cache/genius-token.json` (local dev only)
+3. `GENIUS_DIRECT_TOKEN` env var (static, no auto-refresh)
+4. KV store — Upstash Redis or Cloudflare KV (written automatically by auto-refresh)
+5. On-disk `.cache/genius-token.json` (local dev only)
 
 ### Musixmatch credentials
 
-| Variable                        | Description                                                              |
-| ------------------------------- | ------------------------------------------------------------------------ |
-| `MUSIXMATCH_FALLBACK_TOKEN`     | Token env var (1st priority). Use for production / ephemeral hosts.      |
-| `MUSIXMATCH_ALT_FALLBACK_TOKEN` | Token env var (2nd priority). Alternative name for the same token.       |
-| `MUSIXMATCH_TOKEN_CACHE`        | Path to the on-disk cache file. Default: `.cache/musixmatch-token.json`. |
-| `MUSIXMATCH_AUTO_FETCH`         | Set to `1` to attempt headless token re-fetch when no token is found.    |
+Token resolution order (first match wins):
+
+1. **Env var** — `MUSIXMATCH_DIRECT_TOKEN`
+2. **KV store** — Upstash Redis (priority 1) or Cloudflare KV (priority 2)
+3. **On-disk cache** — `.cache/musixmatch-token.json` (local dev / persistent servers)
+
+| Variable                        | Description                                                                                                           |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `MUSIXMATCH_DIRECT_TOKEN`       | Static bearer token. Recommended for production / ephemeral hosts. Also used as push source by `push:musixmatch-token`. |
+| `UPSTASH_REDIS_REST_URL`        | Upstash Redis KV backend URL. Also used by the export backend — set once, used for both.                              |
+| `UPSTASH_REDIS_REST_TOKEN`      | Upstash Redis KV bearer token. Takes precedence over Cloudflare KV when both are set.                                 |
+| `CF_API_TOKEN`                  | Cloudflare API token with `KV:Edit` permission (Cloudflare KV backend).                                               |
+| `CF_ACCOUNT_ID`                 | Cloudflare account ID (Cloudflare KV backend).                                                                        |
+| `CF_KV_NAMESPACE_ID`            | Cloudflare KV namespace ID (Cloudflare KV backend).                                                                   |
+| `MUSIXMATCH_TOKEN_KV_KEY`       | KV key name for the token store. Default: `mr-magic:musixmatch-token`.                                                |
+| `MUSIXMATCH_TOKEN_KV_TTL_SECONDS` | Token TTL in the KV store (seconds). Default: `2592000` (30 days).                                                  |
+| `MUSIXMATCH_TOKEN_CACHE`        | Path to the on-disk cache file. Default: `.cache/musixmatch-token.json`.                                              |
+| `MUSIXMATCH_AUTO_FETCH`         | Set to `1` to attempt headless token re-fetch when no token is found.                                                 |
 
 ### Export and storage
 
@@ -173,7 +281,7 @@ Genius credentials are resolved in this order — the first available source win
    refreshed in memory. **Recommended for all deployments**, including Render and
    ephemeral hosts. No disk, no scripts, no manual token copying.
 
-2. **Fallback token** (`GENIUS_ACCESS_TOKEN`) — a static bearer token. Works
+2. **Direct token** (`GENIUS_DIRECT_TOKEN`) — a static bearer token. Works
    everywhere but does not auto-refresh. Update by redeploying with a new value.
 
 3. **Cache token** (`.cache/genius-token.json`) — written by `npm run fetch:genius-token`.
@@ -185,9 +293,8 @@ Musixmatch uses a captured browser session token. There is no OAuth callback.
 
 **For production / ephemeral hosts (Render, containers):**
 
-Set `MUSIXMATCH_FALLBACK_TOKEN` (first priority) or `MUSIXMATCH_ALT_FALLBACK_TOKEN`
-(second priority) directly in your environment. These are the only reliable options
-when the filesystem may be wiped between restarts.
+Set `MUSIXMATCH_DIRECT_TOKEN` directly in your environment. This is the highest-priority
+env var option and the only reliable one when the filesystem may be wiped between restarts.
 
 **For local development:**
 
@@ -205,11 +312,11 @@ The workflow:
 3. After the redirect to `https://www.musixmatch.com/discover`, the script prints
    the captured token and writes the cache file.
 4. **For remote deployments:** copy the `token` value from the printed JSON and set
-   it as `MUSIXMATCH_FALLBACK_TOKEN` in your platform environment. Do **not** rely on
+   it as `MUSIXMATCH_DIRECT_TOKEN` in your platform environment. Do **not** rely on
    the cache file surviving restarts on ephemeral hosts.
 
 > **Developer accounts:** Get API access from [developer.musixmatch.com](https://developer.musixmatch.com)
-> and set the resulting token as `MUSIXMATCH_FALLBACK_TOKEN`.
+> and set the resulting token as `MUSIXMATCH_DIRECT_TOKEN`.
 >
 > **Public accounts:** Visit [auth.musixmatch.com](https://auth.musixmatch.com), sign in,
 > and capture the token using the script above.
@@ -309,7 +416,7 @@ Recommended Render service settings:
 
 - **Start Command:** `npm run server:mcp:http`
 - **Environment:** set provider credentials (`GENIUS_CLIENT_ID`, `GENIUS_CLIENT_SECRET`,
-  `MUSIXMATCH_FALLBACK_TOKEN`, etc.) in the Render Dashboard → Environment tab
+  `MUSIXMATCH_DIRECT_TOKEN`, etc.) in the Render Dashboard → Environment tab
 - **Health Check Path:** `/health` (returns `{ "status": "ok", "providers": [...] }`)
 
 > For custom domains, add them to `MR_MAGIC_ALLOWED_HOSTS` (comma-separated) in
@@ -615,8 +722,8 @@ Works with any local MCP client that supports `command` / `args`:
       "command": "npx",
       "args": ["-y", "mr-magic-mcp-server"],
       "env": {
-        "GENIUS_ACCESS_TOKEN": "...",
-        "MUSIXMATCH_FALLBACK_TOKEN": "...",
+        "GENIUS_DIRECT_TOKEN": "...",
+        "MUSIXMATCH_DIRECT_TOKEN": "...",
         "AIRTABLE_PERSONAL_ACCESS_TOKEN": "..."
       }
     }
@@ -1055,8 +1162,8 @@ npm run server:mcp:http   # Streamable HTTP MCP  — port 3444
 
 - **LRCLIB** — Public API with synced lyric coverage. No auth required.
 - **Genius** — Requires `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET` (auto-refresh,
-  recommended) or `GENIUS_ACCESS_TOKEN` (static fallback token).
-- **Musixmatch** — Requires a token. Use `MUSIXMATCH_FALLBACK_TOKEN` for production /
+  recommended) or `GENIUS_DIRECT_TOKEN` (static direct token).
+- **Musixmatch** — Requires a token. Use `MUSIXMATCH_DIRECT_TOKEN` for production /
   ephemeral hosts; use the on-disk cache token (`npm run fetch:musixmatch-token`) for
   local dev. See [Musixmatch](#musixmatch) for the full workflow.
 - **Melon** — Works anonymously. Set `MELON_COOKIE` for pinned / reproducible sessions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-magic-mcp-server",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
   "type": "module",
   "main": "src/index.js",
@@ -30,7 +30,8 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "node src/tests/run-tests.js",
-    "fetch:musixmatch-token": "node src/scripts/fetch_MUSIXMATCH_ALT_FALLBACK_TOKEN.mjs",
+    "fetch:musixmatch-token": "node src/scripts/fetch_musixmatch_token.mjs",
+    "push:musixmatch-token": "node src/scripts/push_musixmatch_token.mjs",
     "fetch:genius-token": "node src/scripts/fetch_genius_token.mjs",
     "repro:mcp:arg-boundary": "node src/scripts/mcp-arg-boundary-repro.mjs",
     "repro:mcp:arg-boundary:sdk": "node src/scripts/mcp-arg-boundary-sdk-repro.mjs"

package/src/providers/genius.js

@@ -25,7 +25,7 @@ async function ensureGeniusAuth() {
     await getGeniusToken();
     return;
   }
-  assertEnv(['GENIUS_ACCESS_TOKEN']);
+  assertEnv(['GENIUS_DIRECT_TOKEN']);
 }
 
 function normalizeHit(hit, query) {

package/src/providers/musixmatch.js

@@ -138,12 +138,11 @@ async function macroRequest(track) {
 async function ensureMusixmatchToken() {
   const token = await getMusixmatchToken();
   if (!token) {
-    // Neither a fallback token (MUSIXMATCH_FALLBACK_TOKEN / MUSIXMATCH_ALT_USER_TOKEN env vars) nor a
+    // Neither a direct token (MUSIXMATCH_DIRECT_TOKEN env var) nor a KV token nor a
     // cache token (on-disk .cache/musixmatch-token.json) could be found.
     throw new Error(
       'Musixmatch token not found. ' +
-        'Set MUSIXMATCH_FALLBACK_TOKEN (fallback token — recommended for production/ephemeral hosts) ' +
-        'or MUSIXMATCH_ALT_USER_TOKEN as an environment variable, ' +
+        'Set MUSIXMATCH_DIRECT_TOKEN as an environment variable (recommended for production/ephemeral hosts), ' +
         'or run `npm run fetch:musixmatch-token` to populate the on-disk cache token.'
     );
   }

package/src/scripts/fetch_genius_token.mjs

@@ -3,7 +3,8 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import axios from 'axios';
-import '../src/utils/config.js';
+import '../utils/config.js';
+import { describeKvBackend, isKvConfigured, kvSet } from '../utils/kv-store.js';
 
 const TOKEN_ENDPOINT = 'https://api.genius.com/oauth/token';
 
@@ -17,10 +18,10 @@ function printDeploymentBlock(accessToken) {
   console.log('LOCAL DEVELOPMENT (cache token)');
   console.log('  Token written to the cache file above.');
   console.log('  The server reads it on startup when a writable filesystem is available.\n');
-  console.log('RENDER / EPHEMERAL DEPLOYMENTS (fallback token)');
+  console.log('RENDER / EPHEMERAL DEPLOYMENTS (direct token)');
   console.log('  If you cannot use client_credentials, set the token as an env var');
-  console.log('  in your platform dashboard. It acts as a static fallback token:\n');
-  console.log(`  GENIUS_ACCESS_TOKEN=${accessToken}\n`);
+  console.log('  in your platform dashboard. It acts as a static direct token:\n');
+  console.log(`  GENIUS_DIRECT_TOKEN=${accessToken}\n`);
   console.log("  Note: static tokens don't auto-refresh. Redeploy with a new token");
   console.log('  if/when it expires. The client_credentials path avoids this entirely.');
   console.log('─'.repeat(68) + '\n');
@@ -66,6 +67,22 @@ async function main() {
     console.log(`\nCache token written to: ${cachePath}`);
     console.log('(The server reads this file on startup when a writable filesystem is available.)');
 
+    // Write to KV store if configured (ephemeral hosts, npx installs).
+    if (isKvConfigured()) {
+      const kvKey = process.env.GENIUS_TOKEN_KV_KEY || 'mr-magic:genius-token';
+      const kvTtl = parseInt(process.env.GENIUS_TOKEN_KV_TTL_SECONDS || '3600', 10);
+      const kvPayload = JSON.stringify({
+        access_token: accessToken,
+        expires_at: Date.now() + (expiresIn || 3600) * 1000
+      });
+      try {
+        await kvSet(kvKey, kvPayload, kvTtl);
+        console.log(`Token written to KV store (${describeKvBackend()}) under key: ${kvKey}`);
+      } catch (err) {
+        console.warn(`Failed to write token to KV store: ${err.message}`);
+      }
+    }
+
     printDeploymentBlock(accessToken);
   } catch (error) {
     console.error('Failed to refresh Genius token:', error.response?.data || error.message);

package/src/scripts/fetch_musixmatch_token.mjs

@@ -2,8 +2,9 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
-import { chromium } from 'playwright';
-import '../src/utils/config.js';
+import { chromium, firefox, webkit } from 'playwright';
+import '../utils/config.js';
+import { describeKvBackend, isKvConfigured, kvSet } from '../utils/kv-store.js';
 
 const AUTH_URL = 'https://auth.musixmatch.com/';
 
@@ -17,8 +18,21 @@ async function saveToken(token, desktopCookie) {
     payload.desktopCookie = desktopCookie;
   }
   await writeFile(cachePath, JSON.stringify(payload, null, 2), 'utf8');
-  console.log(`\nCache token written to: ${cachePath}`);
-  console.log('(The server reads this file on startup when a writable filesystem is available.)');
+  console.log(`\nToken written to cache: ${cachePath}`);
+  console.log('(Local and persistent servers read this file on startup.)');
+}
+
+async function saveToKv(token, desktopCookie) {
+  if (!isKvConfigured()) return;
+  const kvKey = process.env.MUSIXMATCH_TOKEN_KV_KEY || 'mr-magic:musixmatch-token';
+  const kvTtl = parseInt(process.env.MUSIXMATCH_TOKEN_KV_TTL_SECONDS || '2592000', 10);
+  const payload = JSON.stringify({ token, ...(desktopCookie ? { desktopCookie } : {}) });
+  try {
+    await kvSet(kvKey, payload, kvTtl);
+    console.log(`Token written to KV store (${describeKvBackend()}) under key: ${kvKey}`);
+  } catch (error) {
+    console.error(`Failed to write token to KV store: ${error.message}`);
+  }
 }
 
 function printDeploymentBlock(tokenValue) {
@@ -26,32 +40,133 @@ function printDeploymentBlock(tokenValue) {
     typeof tokenValue === 'string'
       ? tokenValue
       : (tokenValue?.message?.body?.usertoken ?? JSON.stringify(tokenValue));
+  const kvBackend = isKvConfigured() ? describeKvBackend() : null;
+
   console.log('\n' + '─'.repeat(68));
   console.log('Token captured successfully!\n');
-  console.log('LOCAL DEVELOPMENT (cache token)');
-  console.log('  The token has been written to the cache file above.');
-  console.log('  The server loads it at startup — no further action needed.\n');
-  console.log('RENDER / EPHEMERAL DEPLOYMENTS (fallback token)');
-  console.log('  The filesystem is wiped on restart, so set the token as an');
-  console.log('  environment variable in your platform dashboard instead:\n');
-  console.log(`  MUSIXMATCH_FALLBACK_TOKEN=${tokenString}\n`);
-  console.log('  The server reads MUSIXMATCH_FALLBACK_TOKEN on startup (1st priority)');
-  console.log('  and never touches the cache file on ephemeral hosts.');
+
+  console.log('LOCAL & PERSISTENT SERVERS (cache token)');
+  console.log('  Token written to .cache/musixmatch-token.json (or MUSIXMATCH_TOKEN_CACHE).');
+  console.log('  Any server with a writable, persistent filesystem (local dev, VPS,');
+  console.log('  dedicated host) reads it automatically on startup.');
+  console.log('  Re-run this script only when your token expires.\n');
+
+  if (kvBackend) {
+    console.log(`EPHEMERAL / NPX INSTALLS — KV STORE (${kvBackend})`);
+    console.log(`  Token written to KV key "mr-magic:musixmatch-token".`);
+    console.log('  The server reads it on startup automatically — no extra config needed.');
+    console.log('  Re-run this script when your token expires to refresh the KV entry.\n');
+  } else {
+    console.log('EPHEMERAL / NPX INSTALLS — KV STORE (not configured)');
+    console.log('  Set UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN (Upstash Redis)');
+    console.log('  or CF_API_TOKEN + CF_ACCOUNT_ID + CF_KV_NAMESPACE_ID (Cloudflare KV)');
+    console.log('  and re-run this script to have the token stored in KV automatically.\n');
+  }
+
+  console.log('EPHEMERAL / SERVERLESS — MANUAL ENV VAR OVERRIDE');
+  console.log('  Copy the token below and set it in your platform dashboard.');
+  console.log('  The server reads MUSIXMATCH_DIRECT_TOKEN on startup (highest priority env var):\n');
+  console.log(`  MUSIXMATCH_DIRECT_TOKEN=${tokenString}\n`);
+
   console.log('─'.repeat(68) + '\n');
 }
 
+function isHeadlessEnabled() {
+  const value = (process.env.HEADLESS || '').trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes';
+}
+
 async function main() {
-  console.log('Launching Playwright to acquire Musixmatch token...');
-  const browser = await chromium.launch({ headless: process.env.HEADLESS !== 'false' });
-  const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+  const headless = isHeadlessEnabled();
+
+  // Persistent browser session — stores cookies/logins between script runs so you don't
+  // have to sign in again until your session actually expires.
+  // Override with PLAYWRIGHT_SESSION_DIR env var if you need a different location.
+  const sessionDir =
+    process.env.PLAYWRIGHT_SESSION_DIR || path.resolve('.cache', 'playwright-session');
+  await mkdir(sessionDir, { recursive: true });
+
+  console.log(`Launching Playwright (headless=${headless}) to acquire Musixmatch token...`);
+  console.log(`Browser session directory: ${sessionDir}\n`);
+
+  // Try real installed browsers in priority order so Google OAuth doesn't block the
+  // automated bundled Chromium.  Override with BROWSER=<name> to skip straight to one.
+  //   Chromium channels : chrome, brave, msedge, comet
+  //   Other engines     : firefox, safari (webkit)
+  //   Last resort       : bundled Chromium (may be blocked by Google OAuth)
+  //
+  // launchPersistentContext() is used instead of launch() + newContext() so the browser
+  // session (cookies, logins) is saved to sessionDir and reused on subsequent runs.
+  const CHROMIUM_UA =
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
+  const chromiumArgs = ['--disable-blink-features=AutomationControlled'];
+  const baseOpts = { headless, slowMo: headless ? 0 : 150, viewport: { width: 1280, height: 900 } };
+  const chromiumOpts = { ...baseOpts, args: chromiumArgs, userAgent: CHROMIUM_UA };
+
+  // Each launcher returns a BrowserContext (launchPersistentContext skips browser.newContext()).
+  const candidates = [
+    ['chrome',          () => chromium.launchPersistentContext(sessionDir, { ...chromiumOpts, channel: 'chrome' })],
+    ['brave (channel)', () => chromium.launchPersistentContext(sessionDir, { ...chromiumOpts, channel: 'brave' })],
+    ['brave (path)',    () => chromium.launchPersistentContext(sessionDir, { ...chromiumOpts, executablePath: '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser' })],
+    ['msedge',          () => chromium.launchPersistentContext(sessionDir, { ...chromiumOpts, channel: 'msedge' })],
+    ['comet',           () => chromium.launchPersistentContext(sessionDir, { ...chromiumOpts, executablePath: '/Applications/Comet.app/Contents/MacOS/Comet' })],
+    ['firefox',         () => firefox.launchPersistentContext(sessionDir, { ...baseOpts })],
+    ['safari (webkit)', () => webkit.launchPersistentContext(sessionDir, { ...baseOpts })],
+    ['bundled chromium',() => chromium.launchPersistentContext(sessionDir, { ...chromiumOpts })],
+  ];
+
+  // If BROWSER is set, move that candidate to the front.
+  const browserEnv = (process.env.BROWSER || '').trim().toLowerCase();
+  const orderedCandidates = browserEnv
+    ? [
+        ...candidates.filter(([label]) => label.startsWith(browserEnv)),
+        ...candidates.filter(([label]) => !label.startsWith(browserEnv)),
+      ]
+    : candidates;
+
+  let context;
+  let chosenLabel;
+  for (const [label, launcher] of orderedCandidates) {
+    try {
+      context = await launcher();
+      chosenLabel = label;
+      break;
+    } catch (err) {
+      console.warn(`  ${label} not available (${err.message?.split('\n')[0]}), trying next...`);
+    }
+  }
+
+  if (!context) {
+    console.error('No usable browser found. Install Chrome, Brave, Edge, Firefox, or Safari.');
+    process.exit(1);
+  }
+  console.log(`Using browser: ${chosenLabel}`);
+
+  // Remove the webdriver flag that Google uses to detect automated browsers.
+  await context.addInitScript(() => {
+    Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+  });
+
   const page = await context.newPage();
 
-  console.log('Navigate to Musixmatch login and sign in.');
-  await page.goto(AUTH_URL, { waitUntil: 'domcontentloaded' });
-  console.log('Waiting to be redirected to https://www.musixmatch.com/discover ...');
-  await page.waitForURL('**/discover', { timeout: 0 });
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') {
+      const text = msg.text();
+      // Suppress benign COOP warning emitted by the auth page itself.
+      if (text.includes('Cross-Origin-Opener-Policy')) return;
+      console.error(`[browser console error] ${text}`);
+    }
+  });
+  page.on('pageerror', (err) => console.error(`[browser page error] ${err.message}`));
+
+  console.log(`Navigating to ${AUTH_URL} — sign in in the browser window that appears.`);
+  // 'commit' fires as soon as the server response starts (before content loads), which avoids
+  // ERR_ABORTED on browsers like Comet that intercept or redirect during initial navigation.
+  await page.goto(AUTH_URL, { waitUntil: 'commit' });
+  console.log('Waiting to be redirected to https://account.musixmatch.com/ ...');
+  await page.waitForURL('https://account.musixmatch.com/**', { timeout: 0 });
 
-  const cookies = await context.cookies('https://www.musixmatch.com');
+  const cookies = await context.cookies('https://account.musixmatch.com');
   const userCookie = cookies.find((cookie) => cookie.name === 'musixmatchUserToken');
   const desktopCookie = cookies.find((cookie) => cookie.name === 'web-desktop-app-v1.0');
   if (!userCookie) {
@@ -70,14 +185,20 @@ async function main() {
   console.log('\nMusixmatch token payload:');
   console.log(JSON.stringify(parsed, null, 2));
 
-  await saveToken(parsed, desktopCookie ? decodeURIComponent(desktopCookie.value) : null);
+  const decodedDesktopCookie = desktopCookie ? decodeURIComponent(desktopCookie.value) : null;
+
+  // Write to all configured storage backends in parallel.
+  await Promise.allSettled([
+    saveToken(parsed, decodedDesktopCookie),
+    saveToKv(parsed, decodedDesktopCookie),
+  ]);
 
   // Extract the raw token string for the deployment hint.
   // The parsed payload is the full musixmatchUserToken JSON object; the server
   // stores and reads the entire parsed object as the `token` field.
   printDeploymentBlock(parsed);
 
-  await browser.close();
+  await context.close();
 }
 
 main().catch((error) => {