mr-magic-mcp-server 0.2.6 → 0.3.1

package/src/utils/kv-store.js

@@ -0,0 +1,157 @@
+/**
+ * Zero-dependency KV store abstraction.
+ *
+ * Auto-detects the backend from environment variables.  Both backends call
+ * their respective REST APIs using the built-in `fetch()` — no extra packages
+ * required.
+ *
+ * Supported backends (in priority order — first configured wins):
+ *
+ *   1. Upstash Redis (recommended for ephemeral/serverless deployments)
+ *        UPSTASH_REDIS_REST_URL   — e.g. https://xxxxx.upstash.io
+ *        UPSTASH_REDIS_REST_TOKEN — Upstash REST bearer token
+ *        → Also used by the export backend; set once, used everywhere.
+ *        → Takes precedence over Cloudflare KV if both are configured.
+ *
+ *   2. Cloudflare KV
+ *        CF_API_TOKEN       — Cloudflare API token with KV:Edit permission
+ *        CF_ACCOUNT_ID      — Cloudflare account ID
+ *        CF_KV_NAMESPACE_ID — KV namespace ID
+ *
+ * If neither backend is configured, all operations are silent no-ops.
+ * If both are configured, Upstash Redis is used and Cloudflare KV is ignored.
+ */
+
+// ─── Backend detection ────────────────────────────────────────────────────────
+
+function getUpstashConfig() {
+  const url = (process.env.UPSTASH_REDIS_REST_URL || '').replace(/\/$/, '');
+  const token = process.env.UPSTASH_REDIS_REST_TOKEN;
+  if (!url || !token) return null;
+  return { url, token };
+}
+
+function getCfConfig() {
+  const apiToken = process.env.CF_API_TOKEN;
+  const accountId = process.env.CF_ACCOUNT_ID;
+  const namespaceId = process.env.CF_KV_NAMESPACE_ID;
+  if (!apiToken || !accountId || !namespaceId) return null;
+  return { apiToken, accountId, namespaceId };
+}
+
+export function isKvConfigured() {
+  return Boolean(getUpstashConfig() || getCfConfig());
+}
+
+/** Returns a human-readable label for the active KV backend. */
+export function describeKvBackend() {
+  if (getUpstashConfig()) return 'upstash-redis';
+  if (getCfConfig()) return 'cloudflare-kv';
+  return 'none';
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Get a value from the KV store.
+ * Returns the stored string, or `null` if the key is missing, not configured,
+ * or an error occured.
+ * @param {string} key
+ * @returns {Promise<string|null>}
+ */
+export async function kvGet(key) {
+  const upstash = getUpstashConfig();
+  if (upstash) return upstashGet(upstash, key);
+
+  const cf = getCfConfig();
+  if (cf) return cfGet(cf, key);
+
+  return null;
+}
+
+/**
+ * Store a string value in the KV store. No-op if no backend is configured.
+ * @param {string} key
+ * @param {string} value
+ * @param {number} [ttlSeconds] — optional TTL; defaults to no expiry if omitted
+ * @returns {Promise<void>}
+ */
+export async function kvSet(key, value, ttlSeconds) {
+  const upstash = getUpstashConfig();
+  if (upstash) return upstashSet(upstash, key, value, ttlSeconds);
+
+  const cf = getCfConfig();
+  if (cf) return cfSet(cf, key, value, ttlSeconds);
+}
+
+// ─── Upstash Redis backend ────────────────────────────────────────────────────
+// Uses the Upstash Redis REST API (POST / with a Redis command array).
+
+async function upstashCmd({ url, token }, command) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(command)
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Upstash Redis ${command[0]} failed (${res.status}): ${text}`);
+  }
+  return res.json();
+}
+
+async function upstashGet(cfg, key) {
+  try {
+    const json = await upstashCmd(cfg, ['GET', key]);
+    return json?.result ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function upstashSet(cfg, key, value, ttlSeconds) {
+  const cmd = ttlSeconds
+    ? ['SET', key, value, 'EX', String(Math.round(ttlSeconds))]
+    : ['SET', key, value];
+  await upstashCmd(cfg, cmd);
+}
+
+// ─── Cloudflare KV backend ────────────────────────────────────────────────────
+// Uses the Cloudflare Workers KV REST API.
+
+function cfValuesUrl({ accountId, namespaceId }, key) {
+  return `https://api.cloudflare.com/client/v4/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(key)}`;
+}
+
+async function cfGet(cfg, key) {
+  try {
+    const res = await fetch(cfValuesUrl(cfg, key), {
+      headers: { Authorization: `Bearer ${cfg.apiToken}` }
+    });
+    if (res.status === 404) return null;
+    if (!res.ok) return null;
+    return res.text();
+  } catch {
+    return null;
+  }
+}
+
+async function cfSet(cfg, key, value, ttlSeconds) {
+  const url =
+    cfValuesUrl(cfg, key) + (ttlSeconds ? `?expiration_ttl=${Math.round(ttlSeconds)}` : '');
+  const res = await fetch(url, {
+    method: 'PUT',
+    headers: {
+      Authorization: `Bearer ${cfg.apiToken}`,
+      'Content-Type': 'text/plain'
+    },
+    body: value
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Cloudflare KV PUT failed (${res.status}): ${text}`);
+  }
+}

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

@@ -5,23 +5,32 @@ import axios from 'axios';
 
 import { getEnvValue, getProjectRoot } from '../config.js';
 import { createLogger } from '../logger.js';
+import { describeKvBackend, isKvConfigured, kvGet, kvSet } from '../kv-store.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.
+//   • 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.
+//                       On success the token is also persisted to KV + disk cache.
+//   • Direct token    — GENIUS_DIRECT_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.
+//   • KV token        — stored in a remote KV store (Upstash Redis or Cloudflare KV).
+//                       Written automatically when client_credentials refresh succeeds.
+//                       Ideal for ephemeral/serverless deployments and npx installs.
+//   • Cache token     — on-disk .cache/genius-token.json written by the fetch script or
+//                       by a successful client_credentials refresh.  Only reliable when
+//                       a persistent, writable filesystem is available (local dev).
+//                       Ephemeral hosts should use auto-refresh, direct token, or KV.
+
+// KV key and TTL — configurable via env vars.
+const KV_KEY = process.env.GENIUS_TOKEN_KV_KEY || 'mr-magic:genius-token';
+const KV_TTL_SECONDS = parseInt(process.env.GENIUS_TOKEN_KV_TTL_SECONDS || '3600', 10); // 1 hour
 
 // Token cache path — must match the path used by src/scripts/fetch_genius_token.mjs.
 const TOKEN_CACHE_PATH =
@@ -32,7 +41,7 @@ let cachedExpiry = 0;
 let lastAuthMode = 'unknown';
 
 function getFallbackToken() {
-  return getEnvValue('GENIUS_ACCESS_TOKEN');
+  return getEnvValue('GENIUS_DIRECT_TOKEN');
 }
 
 function tokenExpired() {
@@ -56,6 +65,59 @@ async function readCachedToken() {
   }
 }
 
+async function writeCachedToken(accessToken, expiresIn) {
+  if (!accessToken) return;
+  try {
+    await fs.mkdir(path.dirname(TOKEN_CACHE_PATH), { recursive: true });
+    await fs.writeFile(
+      TOKEN_CACHE_PATH,
+      JSON.stringify({
+        access_token: accessToken,
+        expires_at: Date.now() + (Number(expiresIn) || 3600) * 1000
+      }),
+      'utf8'
+    );
+  } catch (error) {
+    logger.warn('Failed to persist Genius token cache', { error: error?.message });
+  }
+}
+
+// ─── KV store helpers ─────────────────────────────────────────────────────────
+
+async function readKvToken() {
+  if (!isKvConfigured()) return null;
+  try {
+    const raw = await kvGet(KV_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (parsed?.access_token) {
+      cachedToken = parsed.access_token;
+      cachedExpiry = parsed.expires_at ?? Date.now() + 3_600_000;
+      lastAuthMode = `kv:${describeKvBackend()}`;
+      return cachedToken;
+    }
+  } catch {
+    // KV read error — not fatal; fall through to disk cache
+  }
+  return null;
+}
+
+async function writeKvToken(accessToken, expiresIn) {
+  if (!isKvConfigured() || !accessToken) return;
+  try {
+    const payload = JSON.stringify({
+      access_token: accessToken,
+      expires_at: Date.now() + (Number(expiresIn) || 3600) * 1000
+    });
+    await kvSet(KV_KEY, payload, KV_TTL_SECONDS);
+  } catch (error) {
+    logger.warn('Failed to persist Genius token to KV store', {
+      backend: describeKvBackend(),
+      error: error?.message
+    });
+  }
+}
+
 async function fetchClientCredentialsToken() {
   const clientId = getEnvValue('GENIUS_CLIENT_ID');
   const clientSecret = getEnvValue('GENIUS_CLIENT_SECRET');
@@ -82,6 +144,8 @@ async function fetchClientCredentialsToken() {
     cachedExpiry = Date.now() + ttl * 1000;
     lastAuthMode = 'client_credentials';
     logger.info('Genius token refreshed', { ttlSeconds: ttl });
+    // Persist to durable backends in parallel so ephemeral hosts survive restarts.
+    await Promise.allSettled([writeCachedToken(accessToken, ttl), writeKvToken(accessToken, ttl)]);
     return cachedToken;
   } catch (error) {
     logger.error('Failed to refresh Genius token', {
@@ -95,8 +159,10 @@ 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
+ *      → on success, writes to KV store + disk cache
+ *   3. GENIUS_DIRECT_TOKEN env var — static bearer token override
+ *   4. KV store — Upstash Redis or Cloudflare KV (ephemeral/npx)
+ *   5. On-disk .cache/genius-token.json — cache token, local dev only
  */
 export async function getGeniusToken({ forceRefresh = false } = {}) {
   if (!forceRefresh && !tokenExpired()) {
@@ -109,17 +175,21 @@ export async function getGeniusToken({ forceRefresh = false } = {}) {
     return token;
   }
 
-  // 3. Fallback token from env var (static, no auto-refresh)
+  // 3. Direct token from env var (static override, no auto-refresh)
   const fallback = getFallbackToken();
   if (fallback && fallback !== cachedToken) {
-    logger.warn('Using Genius fallback token from GENIUS_ACCESS_TOKEN env var');
+    logger.warn('Using Genius direct token from GENIUS_DIRECT_TOKEN env var');
     cachedToken = fallback;
     cachedExpiry = Date.now() + 86_400_000; // 1 day placeholder
-    lastAuthMode = 'env_access_token';
+    lastAuthMode = 'env_direct_token';
     return cachedToken;
   }
 
-  // 4. Cache token from disk (local dev convenience only)
+  // 4. KV store — ideal for ephemeral deployments and npx installs
+  const kvToken = await readKvToken();
+  if (kvToken) return kvToken;
+
+  // 5. 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 });
@@ -156,7 +226,10 @@ export function describeGeniusAuthMode() {
     return 'client_credentials';
   }
   if (getFallbackToken()) {
-    return 'env_access_token';
+    return 'env_direct_token';
+  }
+  if (isKvConfigured()) {
+    return 'kv_store';
   }
   return 'none';
 }
@@ -164,12 +237,14 @@ export function describeGeniusAuthMode() {
 export async function getGeniusDiagnostics() {
   const clientId = getEnvValue('GENIUS_CLIENT_ID');
   const clientSecret = getEnvValue('GENIUS_CLIENT_SECRET');
-  const fallback = getFallbackToken();
+  const directToken = getFallbackToken();
   const ttlMs = Math.max(cachedExpiry - Date.now(), 0);
 
   const diagnostics = {
     clientCredentialsPresent: Boolean(clientId && clientSecret),
-    fallbackTokenPresent: Boolean(fallback),
+    directTokenPresent: Boolean(directToken),
+    kvConfigured: isKvConfigured(),
+    kvBackend: describeKvBackend(),
     runtimeTokenCached: Boolean(cachedToken),
     runtimeTokenExpiresInMs: cachedToken ? ttlMs : 0,
     lastAuthMode: describeGeniusAuthMode(),

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

@@ -3,20 +3,28 @@ import path from 'node:path';
 
 import { getEnvValue, getProjectRoot } from '../config.js';
 import { createLogger } from '../logger.js';
+import { describeKvBackend, isKvConfigured, kvGet, kvSet } from '../kv-store.js';
 
 const logger = createLogger('musixmatch-token-manager');
 
 // Token source terminology used throughout this module:
-//   • Cache token   — loaded from the on-disk cache file written by the fetch script.
-//                     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_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.
+//   • Direct token   — MUSIXMATCH_DIRECT_TOKEN env var.  A static bearer token set
+//                      directly in the environment.  Recommended for production and
+//                      remote deployments where the filesystem cannot be relied upon
+//                      for persistence.  Highest priority after in-memory cache.
+//   • KV token       — stored in a remote KV store (Upstash Redis or Cloudflare KV).
+//                      Ideal for ephemeral/serverless deployments and npx installs
+//                      where there is no local filesystem at all.
+//   • Cache token    — loaded from the on-disk cache file written by the fetch script.
+//                      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.
+
+// KV key and TTL — configurable via env vars.
+const KV_KEY = process.env.MUSIXMATCH_TOKEN_KV_KEY || 'mr-magic:musixmatch-token';
+const KV_TTL_SECONDS = parseInt(process.env.MUSIXMATCH_TOKEN_KV_TTL_SECONDS || '2592000', 10); // 30 days
 const TOKEN_CACHE_PATH =
-  process.env.MUSIXMATCH_ALT_USER_TOKEN_CACHE ||
+  process.env.MUSIXMATCH_TOKEN_CACHE ||
   path.join(getProjectRoot(), '.cache', 'musixmatch-token.json');
 
 let cachedToken = null;
@@ -60,7 +68,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_FALLBACK_TOKEN as an environment variable ' +
+        'Token was NOT persisted to disk. Set MUSIXMATCH_DIRECT_TOKEN as an environment variable ' +
         'to ensure the token survives restarts in remote/ephemeral deployments.',
       { cachePath: TOKEN_CACHE_PATH }
     );
@@ -75,36 +83,65 @@ async function writeCachedToken(token, desktopCookie) {
   }
 }
 
+// ─── KV store helpers ─────────────────────────────────────────────────────────
+
+async function readKvToken() {
+  if (!isKvConfigured()) return null;
+  try {
+    const raw = await kvGet(KV_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (parsed?.token) {
+      cachedToken = parsed.token;
+      cachedDesktopCookie = parsed.desktopCookie || null;
+      lastLoadedFrom = `kv:${describeKvBackend()}`;
+      return cachedToken;
+    }
+  } catch {
+    // KV read error — not fatal; fall through to disk cache
+  }
+  return null;
+}
+
+async function writeKvToken(token, desktopCookie) {
+  if (!isKvConfigured() || !token) return;
+  try {
+    const payload = JSON.stringify({ token, ...(desktopCookie ? { desktopCookie } : {}) });
+    await kvSet(KV_KEY, payload, KV_TTL_SECONDS);
+  } catch (error) {
+    logger.warn('Failed to persist Musixmatch token to KV store', {
+      backend: describeKvBackend(),
+      error: error?.message
+    });
+  }
+}
+
 /**
  * Resolve the Musixmatch token using the following priority order:
  *   1. In-memory runtime cache (already resolved this session)
- *   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
+ *   2. MUSIXMATCH_DIRECT_TOKEN env var — direct/static bearer token (highest env priority)
+ *   3. KV store                        — Upstash Redis or Cloudflare KV (ephemeral/npx)
+ *   4. On-disk cache file              — local dev / persistent server only
  */
 export async function getMusixmatchToken() {
   if (cachedToken) {
     return cachedToken;
   }
 
-  // Prioritize env vars — these survive restarts on ephemeral hosts
-  const userToken = getEnvValue('MUSIXMATCH_FALLBACK_TOKEN');
-  if (userToken) {
-    cachedToken = userToken;
-    lastLoadedFrom = 'env:MUSIXMATCH_FALLBACK_TOKEN';
+  // 2. Direct token from env var — survives restarts on ephemeral hosts without any external service
+  const directToken = getEnvValue('MUSIXMATCH_DIRECT_TOKEN');
+  if (directToken) {
+    cachedToken = directToken;
+    lastLoadedFrom = 'env:MUSIXMATCH_DIRECT_TOKEN';
     cachedDesktopCookie = null;
     return cachedToken;
   }
 
-  const envToken = getEnvValue('MUSIXMATCH_ALT_USER_TOKEN');
-  if (envToken) {
-    cachedToken = envToken;
-    lastLoadedFrom = 'env:MUSIXMATCH_ALT_USER_TOKEN';
-    cachedDesktopCookie = null;
-    return cachedToken;
-  }
+  // 3. KV store — ideal for ephemeral deployments and npx installs with no local filesystem
+  const kvToken = await readKvToken();
+  if (kvToken) return kvToken;
 
-  // Fall back to disk cache for local development
+  // 4. On-disk cache — local dev / persistent hosts with a writable filesystem
   return readCachedToken();
 }
 
@@ -113,10 +150,16 @@ export async function setMusixmatchToken(token, { desktopCookie } = {}) {
   cachedToken = token;
   lastLoadedFrom = 'runtime';
   cachedDesktopCookie = desktopCookie || null;
-  await writeCachedToken(token, desktopCookie);
+  // Write to both storage backends in parallel; failures are logged, not thrown.
+  await Promise.allSettled([
+    writeCachedToken(token, desktopCookie),
+    writeKvToken(token, desktopCookie)
+  ]);
   logger.info('Musixmatch token updated', {
     source: 'runtime',
-    desktopCookiePresent: Boolean(desktopCookie)
+    desktopCookiePresent: Boolean(desktopCookie),
+    kvConfigured: isKvConfigured(),
+    kvBackend: describeKvBackend()
   });
 }
 
@@ -129,8 +172,7 @@ export function describeMusixmatchTokenSource() {
 }
 
 export async function getMusixmatchTokenDiagnostics() {
-  const userEnvToken = getEnvValue('MUSIXMATCH_FALLBACK_TOKEN');
-  const envToken = getEnvValue('MUSIXMATCH_ALT_USER_TOKEN');
+  const directEnvToken = getEnvValue('MUSIXMATCH_DIRECT_TOKEN');
 
   const diagnostics = {
     cachePath: TOKEN_CACHE_PATH,
@@ -140,8 +182,9 @@ export async function getMusixmatchTokenDiagnostics() {
     cacheBytes: 0,
     cacheTokenPresent: false,
     cacheError: null,
-    userEnvPresent: Boolean(userEnvToken),
-    envPresent: Boolean(envToken),
+    directEnvPresent: Boolean(directEnvToken),
+    kvConfigured: isKvConfigured(),
+    kvBackend: describeKvBackend(),
     runtimeTokenCached: Boolean(cachedToken),
     lastLoadedFrom,
     resolvedSource: 'none'
@@ -160,10 +203,8 @@ export async function getMusixmatchTokenDiagnostics() {
 
   if (cachedToken) {
     diagnostics.resolvedSource = lastLoadedFrom;
-  } else if (userEnvToken) {
-    diagnostics.resolvedSource = 'env:MUSIXMATCH_FALLBACK_TOKEN';
-  } else if (envToken) {
-    diagnostics.resolvedSource = 'env:MUSIXMATCH_ALT_USER_TOKEN';
+  } else if (directEnvToken) {
+    diagnostics.resolvedSource = 'env:MUSIXMATCH_DIRECT_TOKEN';
   } else if (diagnostics.cacheTokenPresent) {
     diagnostics.resolvedSource = 'cache';
   } else {