mr-magic-mcp-server 0.1.6 → 0.1.8

package/.env.example

@@ -3,13 +3,27 @@
 # At minimum one of these is needed for Genius lyrics support.
 # Get all three from https://genius.com/api-clients
 # ───────────────────────────────────────────────────────────────────────────────
-# Simplest: supply GENIUS_ACCESS_TOKEN alone (static token, no auto-refresh).
-# Better:   supply CLIENT_ID + CLIENT_SECRET — the server will auto-refresh via
-#           OAuth client_credentials, making ACCESS_TOKEN optional.
+# There are three ways to supply the Genius token (tried in order):
+#
+#   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.
+#
+#   Fallback token (env var) — static bearer token, no auto-refresh
+#     Set GENIUS_ACCESS_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
+#     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_ACCESS_TOKEN=        # Static bearer token (required if not using client credentials)
-GENIUS_CLIENT_ID=           # OAuth client ID  (enables auto-refresh)
-GENIUS_CLIENT_SECRET=       # OAuth client secret (enables auto-refresh)
+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)
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # REQUIRED (feature-specific) — Musixmatch
@@ -18,20 +32,19 @@ GENIUS_CLIENT_SECRET=       # OAuth client secret (enables auto-refresh)
 # ───────────────────────────────────────────────────────────────────────────────
 # There are two ways to supply the Musixmatch token:
 #
-# Fallback token (env var) — recommended for production / ephemeral hosts
-# Set MUSIXMATCH_USER_TOKEN or MUSIXMATCH_ALT_USER_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_USER_TOKEN (1st) → MUSIXMATCH_ALT_USER_TOKEN (2nd)
+#   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)
 #
-# 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.
+#   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.
 # ═══════════════════════════════════════════════════════════════════════════════
-MUSIXMATCH_USER_TOKEN= # Fallback token (1st priority) — set this in production
-MUSIXMATCH_ALT_USER_TOKEN= # Fallback token (2nd priority) — alternative env var
-
+MUSIXMATCH_FALLBACK_TOKEN=      # Fallback token (1st priority) — set this in production
+MUSIXMATCH_ALT_FALLBACK_TOKEN=           # Fallback token (2nd priority) — alternative env var
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # REQUIRED (feature-specific) — Airtable
@@ -91,8 +104,9 @@ 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
 
-# Musixmatch: override the on-disk token cache path (local dev only)
-MUSIXMATCH_ALT_USER_TOKEN_CACHE=.cache/musixmatch-token.json
+# Override the on-disk cache token paths (local dev only)
+GENIUS_TOKEN_CACHE=.cache/genius-token.json
+MUSIXMATCH_TOKEN_CACHE=.cache/musixmatch-token.json
 
 # Musixmatch: when 1, provider will attempt to re-run the fetch script
 # automatically (headless) if no token is available

package/README.md

@@ -84,10 +84,10 @@ MR_MAGIC_ENV_PATH= # Optional. Custom path to an env file when the default isn't
 GENIUS_CLIENT_ID= # Get from https://genius.com/api-clients, required for Genius client-credentials auth.
 GENIUS_CLIENT_SECRET= # Get from https://genius.com/api-clients, required for Genius client-credentials auth.
 GENIUS_ACCESS_TOKEN= # Get from https://genius.com/api-clients, required for Genius lyrics support when client credentials are not supplied.
-MUSIXMATCH_USER_TOKEN= # Fallback token (1st priority). Set as env var for production/ephemeral hosts where the filesystem is not persistent.
-MUSIXMATCH_ALT_USER_TOKEN= # Fallback token (2nd priority). Alternative env var; same token value, second-choice source.
+MUSIXMATCH_FALLBACK_TOKEN= # Fallback token (1st priority). Set as env var for production/ephemeral hosts where the filesystem is not persistent.
+MUSIXMATCH_ALT_FALLBACK_TOKEN= # Fallback token (2nd priority). Alternative env var; same token value, second-choice source.
 MUSIXMATCH_AUTO_FETCH=0 # Optional. When 1, provider will attempt to re-run the fetch script automatically (headless) if no token is available.
-MUSIXMATCH_ALT_USER_TOKEN_CACHE=.cache/musixmatch-token.json
+MUSIXMATCH_TOKEN_CACHE=.cache/musixmatch-token.json
 MELON_COOKIE= # Optional. Pin a session cookie for consistent Melon results; anonymous access generally works without it.
 MR_MAGIC_EXPORT_BACKEND= # local|inline|redis
 MR_MAGIC_EXPORT_DIR=/absolute/path/to/exports # Required if MR_MAGIC_EXPORT_BACKEND=local
@@ -105,25 +105,31 @@ UPSTASH_REDIS_REST_TOKEN= # Get from https://console.upstash.com/redis/rest, req
 AIRTABLE_PERSONAL_ACCESS_TOKEN= # Required for push_catalog_to_airtable tool. Get from https://airtable.com/create/tokens
 ```
 
-- **GENIUS_ACCESS_TOKEN** is required for Genius lyrics support. The
-  CLI/servers will reject Genius requests if it is unset (unless
-  `GENIUS_CLIENT_ID`/`GENIUS_CLIENT_SECRET` are set for auto-refresh).
-- **GENIUS_CLIENT_ID**/**GENIUS_CLIENT_SECRET** can be supplied as an
-  alternative Genius auth path when you want runtime token refresh instead of a
-  static access token.
+- **Genius token sources** — the server resolves the Genius token using three
+  sources (tried in order):
+  - **Auto-refresh** (`GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET`) — the server calls the
+    Genius OAuth `client_credentials` endpoint at runtime and keeps the token refreshed
+    in memory automatically. **Recommended for all deployments**, including Render/ephemeral
+    hosts. No disk, no scripts, no manual token copying.
+  - **Fallback token** (`GENIUS_ACCESS_TOKEN` env var) — a static bearer token. Works
+    everywhere but does not auto-refresh. Use only when client_credentials are unavailable;
+    redeploy with a new token when it expires.
+  - **Cache token** (on-disk `.cache/genius-token.json`) — written by
+    `npm run fetch:genius-token`. Loaded on startup when a persistent writable filesystem
+    is available. Not suitable for ephemeral hosts.
 - **Musixmatch token sources** — the server resolves the Musixmatch token using
   two named sources, tried in order:
-  - **Fallback token** (`MUSIXMATCH_USER_TOKEN`, then `MUSIXMATCH_ALT_USER_TOKEN`) — the
+  - **Fallback token** (`MUSIXMATCH_FALLBACK_TOKEN`, then `MUSIXMATCH_ALT_FALLBACK_TOKEN`) — the
     token value is set directly as an environment variable. This is the
     recommended approach for production and ephemeral hosts (e.g. Render free
     tier, containers) where the filesystem cannot be relied upon between
-    restarts. Set `MUSIXMATCH_USER_TOKEN` first; `MUSIXMATCH_ALT_USER_TOKEN` is the
+    restarts. Set `MUSIXMATCH_FALLBACK_TOKEN` first; `MUSIXMATCH_ALT_FALLBACK_TOKEN` is the
     legacy/alternative env var for the same value.
   - **Cache token** (on-disk `.cache/musixmatch-token.json`) — written by the
     `fetch:musixmatch-token` script after a browser sign-in. Used for local
     development when a persistent writable filesystem is available. Not suitable
     for ephemeral hosts.
-- **MUSIXMATCH_ALT_USER_TOKEN_CACHE** controls where the on-disk cache token file is
+- **MUSIXMATCH_TOKEN_CACHE** controls where the on-disk cache token file is
   read/written (default `<project root>/.cache/musixmatch-token.json`).
 - **MELON_COOKIE** is optional—anonymous access generally works, but pinning a
   cookie can improve consistency.
@@ -188,7 +194,7 @@ in one of two ways depending on your deployment:
   `.cache/musixmatch-token.json`. The server loads it on startup whenever a
   persistent, writable filesystem is available.
 - **Fallback token** (production/ephemeral): copy the captured token value and
-  set it as `MUSIXMATCH_USER_TOKEN` (recommended) or `MUSIXMATCH_ALT_USER_TOKEN` in your
+  set it as `MUSIXMATCH_FALLBACK_TOKEN` (recommended) or `MUSIXMATCH_ALT_FALLBACK_TOKEN` in your
   platform's environment. This is the only reliable option on ephemeral hosts
   (Render free tier, containers without a mounted volume) where the filesystem
   is wiped between restarts.
@@ -214,7 +220,7 @@ in one of two ways depending on your deployment:
    the session.
 
 4. **For remote/ephemeral deployments:** copy the `token` value from the
-   printed JSON and set it as `MUSIXMATCH_USER_TOKEN` in your platform
+   printed JSON and set it as `MUSIXMATCH_FALLBACK_TOKEN` in your platform
    environment (the fallback token). Do **not** rely on the cache file
    surviving a restart on ephemeral hosts.
    If `MUSIXMATCH_AUTO_FETCH=1`, the provider can attempt to re-run the fetch
@@ -224,7 +230,7 @@ in one of two ways depending on your deployment:
 #### Developer Accounts
 
 1. Get API access from `https://developer.musixmatch.com`
-2. Run the script above and set the resulting token as `MUSIXMATCH_USER_TOKEN`
+2. Run the script above and set the resulting token as `MUSIXMATCH_FALLBACK_TOKEN`
    (fallback token) in your environment, or keep the on-disk cache token in sync
    for local development.
 
@@ -233,7 +239,7 @@ in one of two ways depending on your deployment:
 1. Visit `https://auth.musixmatch.com/`
 2. Sign in with a Musixmatch account and allow the app. When redirected, the
    helper script above will capture the session and write the cache token.
-3. Copy the `token` value and set it as `MUSIXMATCH_USER_TOKEN` for any remote
+3. Copy the `token` value and set it as `MUSIXMATCH_FALLBACK_TOKEN` for any remote
    environment that needs it.
 
 **WARNING: CALLING THE API FROM AN UNAUTHORIZED ACCOUNT MAY RESULT IN A BAN.**
@@ -594,7 +600,7 @@ Add env vars inline if your client supports the `env` field:
       "args": ["-y", "mr-magic-mcp-server"],
       "env": {
         "GENIUS_ACCESS_TOKEN": "...",
-        "MUSIXMATCH_USER_TOKEN": "...",
+        "MUSIXMATCH_FALLBACK_TOKEN": "...",
         "AIRTABLE_PERSONAL_ACCESS_TOKEN": "..."
       }
     }
@@ -1118,13 +1124,12 @@ For direct binary usage, use `mrmagic-cli search --artist ... --title ...`.
 ## Provider notes
 
 - **LRCLIB**: Public API with synced lyric coverage; no auth required.
-- **Genius**: Requires `GENIUS_ACCESS_TOKEN`. Provides metadata-rich plain
-  lyrics.
+- **Genius**: Requires credentials — either `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET`
+  for auto-refresh (recommended) or `GENIUS_ACCESS_TOKEN` as a static fallback token.
 - **Musixmatch**: Requires a token — either a **fallback token** set via
-  `MUSIXMATCH_USER_TOKEN` (recommended for production) or `MUSIXMATCH_ALT_USER_TOKEN`
-  env vars, or a **cache token** written to disk by
-  `scripts/fetch_MUSIXMATCH_ALT_USER_TOKEN.mjs` (local dev). See "Getting the Musixmatch
-  token" above for the full workflow.
+  `MUSIXMATCH_FALLBACK_TOKEN` (recommended for production) or `MUSIXMATCH_ALT_FALLBACK_TOKEN` env var,
+  or a **cache token** written to disk by `npm run fetch:musixmatch-token` (local dev).
+  See "Getting the Musixmatch token" above for the full workflow.
 - **Melon**: Works anonymously but benefits from `MELON_COOKIE` for reliability
   if needed.
 

package/package.json

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

package/src/providers/musixmatch.js

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

package/src/transport/mcp-http-server.js

@@ -13,6 +13,7 @@ import { mcpToolDefinitions, handleMcpTool } from './mcp-tools.js';
 import { buildMcpResponse } from './mcp-response.js';
 import { logTokenStatus } from './token-startup-log.js';
 import { normalizeToolArgs } from './tool-args.js';
+import { getProviderStatus } from '../index.js';
 
 function getBodyShape(body) {
   if (body == null) return 'nullish';
@@ -91,6 +92,10 @@ export async function startMcpHttpServer(options = {}) {
   await logTokenStatus({ context: 'http-mcp' });
 
   const app = createMcpExpressApp({ host });
+  app.get('/health', async (_req, res) => {
+    res.json({ status: 'ok', providers: await getProviderStatus() });
+  });
+
   app.all('/mcp', async (req, res) => {
     const normalizedBody = normalizeIncomingRpcBody(req.body);
     const requestId = randomUUID();

package/src/transport/mcp-tools.js

@@ -439,7 +439,7 @@ export async function handleMcpTool(name, args = {}) {
       'GENIUS_CLIENT_ID',
       'GENIUS_CLIENT_SECRET',
       'MUSIXMATCH_ALT_USER_TOKEN',
-      'MUSIXMATCH_USER_TOKEN',
+      'MUSIXMATCH_FALLBACK_TOKEN',
       'MELON_COOKIE'
     ];
     return {

package/src/transport/token-startup-log.js

@@ -29,7 +29,7 @@ export async function logTokenStatus({ context }) {
 }
 
 async function logGeniusStatus(context) {
-  const diagnostics = getGeniusDiagnostics();
+  const diagnostics = await getGeniusDiagnostics();
   const ready = hasValidGeniusAuth();
   const mode = describeGeniusAuthMode();
 
@@ -37,7 +37,9 @@ async function logGeniusStatus(context) {
     context,
     provider: 'genius',
     clientCredentialsPresent: diagnostics.clientCredentialsPresent,
-    fallbackTokenPresent: diagnostics.fallbackTokenPresent
+    fallbackTokenPresent: diagnostics.fallbackTokenPresent,
+    cacheTokenPresent: diagnostics.cacheTokenPresent,
+    cacheTokenExpired: diagnostics.cacheTokenExpired
   });
 
   if (diagnostics.runtimeTokenCached) {
@@ -114,7 +116,8 @@ async function logMusixmatchStatus(context) {
     logger.warn('Musixmatch token missing', {
       context,
       provider: 'musixmatch',
-      details: 'run scripts/fetch_MUSIXMATCH_ALT_USER_TOKEN.mjs to capture cookies'
+      details:
+        'run npm run fetch:musixmatch-token to capture the cache token, or set MUSIXMATCH_FALLBACK_TOKEN as a fallback token for ephemeral deployments'
     });
   }
 }

package/src/utils/tokens/genius-token-manager.js

@@ -1,11 +1,32 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
 import axios from 'axios';
 
-import { getEnvValue } from '../config.js';
+import { getEnvValue, getProjectRoot } from '../config.js';
 import { createLogger } from '../logger.js';
 
 const GENIUS_TOKEN_ENDPOINT = 'https://api.genius.com/oauth/token';
 const logger = createLogger('genius-token-manager');
 
+// Token source terminology used throughout this module:
+//   • Auto-refresh   — GENIUS_CLIENT_ID + GENIUS_CLIENT_SECRET env vars.
+//                      The server calls the Genius OAuth client_credentials endpoint
+//                      at runtime and keeps the token refreshed in memory automatically.
+//                      This is the recommended approach for all deployments: no disk,
+//                      no scripts, and no manual token copying needed.
+//   • Fallback token — GENIUS_ACCESS_TOKEN env var.  A static bearer token set directly
+//                      in the environment.  Does not auto-refresh; redeploy when expired.
+//                      Use this only when client_credentials are unavailable.
+//   • Cache token    — on-disk .cache/genius-token.json written by the fetch script.
+//                      Only reliable when a persistent, writable filesystem is available
+//                      (i.e. local development). Ephemeral hosts (Render free tier, etc.)
+//                      should use the auto-refresh or fallback token paths instead.
+
+// Token cache path — must match the path used by scripts/fetch_genius_token.mjs.
+const TOKEN_CACHE_PATH =
+  process.env.GENIUS_TOKEN_CACHE || path.join(getProjectRoot(), '.cache', 'genius-token.json');
+
 let cachedToken = null;
 let cachedExpiry = 0;
 let lastAuthMode = 'unknown';
@@ -20,6 +41,21 @@ function tokenExpired() {
   return now >= cachedExpiry - 60_000; // refresh one minute early
 }
 
+async function readCachedToken() {
+  try {
+    const raw = await fs.readFile(TOKEN_CACHE_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    const { access_token: accessToken, expires_at: expiresAt } = parsed ?? {};
+    if (!accessToken) return null;
+    // Skip if the cache token has already expired (with a 1-minute buffer).
+    if (expiresAt && Date.now() >= expiresAt - 60_000) return null;
+    return { accessToken, expiresAt };
+  } catch {
+    // Cache file absent or unreadable — not an error in remote environments.
+    return null;
+  }
+}
+
 async function fetchClientCredentialsToken() {
   const clientId = getEnvValue('GENIUS_CLIENT_ID');
   const clientSecret = getEnvValue('GENIUS_CLIENT_SECRET');
@@ -55,22 +91,44 @@ async function fetchClientCredentialsToken() {
   }
 }
 
+/**
+ * Resolve the Genius token using the following priority order:
+ *   1. In-memory runtime cache (already resolved this session)
+ *   2. Auto-refresh via GENIUS_CLIENT_ID + GENIUS_CLIENT_SECRET (client_credentials)
+ *   3. GENIUS_ACCESS_TOKEN env var — fallback token
+ *   4. On-disk .cache/genius-token.json — cache token, local dev only
+ */
 export async function getGeniusToken({ forceRefresh = false } = {}) {
   if (!forceRefresh && !tokenExpired()) {
     return cachedToken;
   }
+
+  // 2. Auto-refresh via client_credentials (ideal for all deployments)
   const token = await fetchClientCredentialsToken();
   if (token) {
     return token;
   }
+
+  // 3. Fallback token from env var (static, no auto-refresh)
   const fallback = getFallbackToken();
   if (fallback && fallback !== cachedToken) {
-    logger.warn('Using fallback Genius access token from environment');
+    logger.warn('Using Genius fallback token from GENIUS_ACCESS_TOKEN env var');
     cachedToken = fallback;
     cachedExpiry = Date.now() + 86_400_000; // 1 day placeholder
     lastAuthMode = 'env_access_token';
     return cachedToken;
   }
+
+  // 4. Cache token from disk (local dev convenience only)
+  const cached = await readCachedToken();
+  if (cached) {
+    logger.info('Using Genius cache token from disk', { cachePath: TOKEN_CACHE_PATH });
+    cachedToken = cached.accessToken;
+    cachedExpiry = cached.expiresAt ?? Date.now() + 86_400_000;
+    lastAuthMode = 'cache';
+    return cachedToken;
+  }
+
   return cachedToken;
 }
 
@@ -103,17 +161,34 @@ export function describeGeniusAuthMode() {
   return 'none';
 }
 
-export function getGeniusDiagnostics() {
+export async function getGeniusDiagnostics() {
   const clientId = getEnvValue('GENIUS_CLIENT_ID');
   const clientSecret = getEnvValue('GENIUS_CLIENT_SECRET');
   const fallback = getFallbackToken();
   const ttlMs = Math.max(cachedExpiry - Date.now(), 0);
 
-  return {
+  const diagnostics = {
     clientCredentialsPresent: Boolean(clientId && clientSecret),
     fallbackTokenPresent: Boolean(fallback),
     runtimeTokenCached: Boolean(cachedToken),
     runtimeTokenExpiresInMs: cachedToken ? ttlMs : 0,
-    lastAuthMode: describeGeniusAuthMode()
+    lastAuthMode: describeGeniusAuthMode(),
+    cachePath: TOKEN_CACHE_PATH,
+    cacheTokenPresent: false,
+    cacheTokenExpired: false,
+    cacheError: null
   };
+
+  try {
+    const raw = await fs.readFile(TOKEN_CACHE_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    diagnostics.cacheTokenPresent = Boolean(parsed?.access_token);
+    if (parsed?.expires_at) {
+      diagnostics.cacheTokenExpired = Date.now() >= parsed.expires_at - 60_000;
+    }
+  } catch (error) {
+    diagnostics.cacheError = error?.code === 'ENOENT' ? null : (error?.message ?? null);
+  }
+
+  return diagnostics;
 }

package/src/utils/tokens/musixmatch-token-manager.js

@@ -11,7 +11,7 @@ const logger = createLogger('musixmatch-token-manager');
 //                     Only reliable when a persistent, writable filesystem is available
 //                     (i.e. local development). Ephemeral hosts (Render free tier, etc.)
 //                     may not have a writable FS, so the cache token is unavailable there.
-//   • Fallback token — the token value supplied directly via MUSIXMATCH_USER_TOKEN or
+//   • Fallback token — the token value supplied directly via MUSIXMATCH_FALLBACK_TOKEN or
 //                     MUSIXMATCH_ALT_USER_TOKEN environment variables.  This is the recommended
 //                     approach for production and remote deployments where the filesystem
 //                     cannot be relied upon for persistence.
@@ -60,7 +60,7 @@ async function writeCachedToken(token, desktopCookie) {
   if (!dirOk) {
     logger.warn(
       'Musixmatch token cache directory unavailable (read-only or restricted filesystem). ' +
-        'Token was NOT persisted to disk. Set MUSIXMATCH_USER_TOKEN as an environment variable ' +
+        'Token was NOT persisted to disk. Set MUSIXMATCH_FALLBACK_TOKEN as an environment variable ' +
         'to ensure the token survives restarts in remote/ephemeral deployments.',
       { cachePath: TOKEN_CACHE_PATH }
     );
@@ -78,7 +78,7 @@ async function writeCachedToken(token, desktopCookie) {
 /**
  * Resolve the Musixmatch token using the following priority order:
  *   1. In-memory runtime cache (already resolved this session)
- *   2. MUSIXMATCH_USER_TOKEN env var  — fallback token, first-priority env source
+ *   2. MUSIXMATCH_FALLBACK_TOKEN env var  — fallback token, first-priority env source
  *   3. MUSIXMATCH_ALT_USER_TOKEN env var       — fallback token, second-priority env source
  *   4. On-disk cache file             — cache token, local dev only
  */
@@ -88,10 +88,10 @@ export async function getMusixmatchToken() {
   }
 
   // Prioritize env vars — these survive restarts on ephemeral hosts
-  const userToken = getEnvValue('MUSIXMATCH_USER_TOKEN');
+  const userToken = getEnvValue('MUSIXMATCH_FALLBACK_TOKEN');
   if (userToken) {
     cachedToken = userToken;
-    lastLoadedFrom = 'env:MUSIXMATCH_USER_TOKEN';
+    lastLoadedFrom = 'env:MUSIXMATCH_FALLBACK_TOKEN';
     cachedDesktopCookie = null;
     return cachedToken;
   }
@@ -129,7 +129,7 @@ export function describeMusixmatchTokenSource() {
 }
 
 export async function getMusixmatchTokenDiagnostics() {
-  const userEnvToken = getEnvValue('MUSIXMATCH_USER_TOKEN');
+  const userEnvToken = getEnvValue('MUSIXMATCH_FALLBACK_TOKEN');
   const envToken = getEnvValue('MUSIXMATCH_ALT_USER_TOKEN');
 
   const diagnostics = {
@@ -161,7 +161,7 @@ export async function getMusixmatchTokenDiagnostics() {
   if (cachedToken) {
     diagnostics.resolvedSource = lastLoadedFrom;
   } else if (userEnvToken) {
-    diagnostics.resolvedSource = 'env:MUSIXMATCH_USER_TOKEN';
+    diagnostics.resolvedSource = 'env:MUSIXMATCH_FALLBACK_TOKEN';
   } else if (envToken) {
     diagnostics.resolvedSource = 'env:MUSIXMATCH_ALT_USER_TOKEN';
   } else if (diagnostics.cacheTokenPresent) {