mr-magic-mcp-server 0.2.5 → 0.3.0

package/src/scripts/push_musixmatch_token.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * push_musixmatch_token.mjs
+ *
+ * Seed the Musixmatch token to all configured storage backends (Upstash Redis,
+ * Cloudflare KV, and/or on-disk cache) WITHOUT opening a browser.
+ *
+ * Use this when you already have a token value — e.g. captured once locally via
+ * `npm run fetch:musixmatch-token` — and need to push it to a headless server,
+ * ephemeral deployment (Render), or CI/CD pipeline where a browser is unavailable.
+ *
+ * Usage (env var — recommended for Render / build/start commands):
+ *   MUSIXMATCH_DIRECT_TOKEN='{"message":...}' npm run push:musixmatch-token
+ *
+ * Usage (CLI flag):
+ *   npm run push:musixmatch-token -- --token '{"message":...}'
+ *
+ * The token value must be the full musixmatchUserToken JSON payload (the same
+ * object that `fetch:musixmatch-token` captures and prints after sign-in).
+ * A raw string token is also accepted.
+ *
+ * Exit codes:
+ *   0 — token pushed successfully (or no token provided, no-op)
+ *   1 — token was provided but a push failure occurred (KV write error, etc.)
+ *
+ * Render example (build command or start command):
+ *   MUSIXMATCH_DIRECT_TOKEN='...' npm run push:musixmatch-token && npm run server:mcp:http
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import '../utils/config.js';
+import { describeKvBackend, isKvConfigured, kvSet } from '../utils/kv-store.js';
+
+// ─── Argument parsing ─────────────────────────────────────────────────────────
+
+const { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    token: { type: 'string', short: 't' },
+    help:  { type: 'boolean', short: 'h' },
+  },
+  strict: false,
+});
+
+if (values.help) {
+  console.log(`
+push_musixmatch_token — seed Musixmatch token to all configured backends
+
+Usage:
+  MUSIXMATCH_DIRECT_TOKEN='<json_or_string>' npm run push:musixmatch-token
+  npm run push:musixmatch-token -- --token '<json_or_string>'
+
+The token value is the full musixmatchUserToken JSON payload captured by
+fetch:musixmatch-token, or a raw string token.
+
+Backends written (if configured):
+  • Upstash Redis  — UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN
+  • Cloudflare KV  — CF_API_TOKEN + CF_ACCOUNT_ID + CF_KV_NAMESPACE_ID
+  • On-disk cache  — .cache/musixmatch-token.json (or MUSIXMATCH_TOKEN_CACHE)
+
+If MUSIXMATCH_DIRECT_TOKEN is not set and --token is not supplied, the
+script exits 0 with no output (safe to chain in build/start commands).
+`);
+  process.exit(0);
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const rawToken = values.token || process.env.MUSIXMATCH_DIRECT_TOKEN;
+
+  // If no token is provided, exit silently so this can be safely chained in
+  // build/start commands when the token hasn't been set yet.
+  if (!rawToken) {
+    return;
+  }
+
+  // Parse as JSON if possible; otherwise treat as a raw string token.
+  let parsedToken;
+  try {
+    parsedToken = JSON.parse(rawToken);
+  } catch {
+    parsedToken = rawToken;
+  }
+
+  console.log('Pushing Musixmatch token to configured backends...');
+  let anyFailed = false;
+
+  // ─── On-disk cache ───────────────────────────────────────────────────────
+  const cachePath =
+    process.env.MUSIXMATCH_TOKEN_CACHE || path.resolve('.cache', 'musixmatch-token.json');
+  try {
+    await mkdir(path.dirname(cachePath), { recursive: true });
+    await writeFile(cachePath, JSON.stringify({ token: parsedToken }, null, 2), 'utf8');
+    console.log(`  ✓ Disk cache: ${cachePath}`);
+  } catch (err) {
+    console.warn(`  ✗ Disk cache write failed (${err.message}) — continuing.`);
+    // Not fatal; remote hosts may not have a writable FS.
+  }
+
+  // ─── KV store ─────────────────────────────────────────────────────────────
+  if (isKvConfigured()) {
+    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: parsedToken });
+    try {
+      await kvSet(kvKey, payload, kvTtl);
+      console.log(`  ✓ KV store (${describeKvBackend()}): key="${kvKey}", ttl=${kvTtl}s`);
+    } catch (err) {
+      console.error(`  ✗ KV store write failed: ${err.message}`);
+      anyFailed = true;
+    }
+  } else {
+    console.log('  — KV store: not configured (set UPSTASH_REDIS_REST_URL/TOKEN or CF_* vars to enable)');
+  }
+
+  if (anyFailed) {
+    console.error('\n✗ One or more backends failed — see errors above.');
+    process.exit(1);
+  }
+
+  console.log('\n✓ Token pushed. The server will read it from the available backend on startup.');
+}
+
+main().catch((err) => {
+  console.error('Unexpected error:', err.message);
+  process.exit(1);
+});

package/src/transport/http-server.js

@@ -84,12 +84,25 @@ export function startHttpServer(options = {}) {
 
       if (req.method === 'GET' && req.url.startsWith('/downloads/')) {
         const segments = req.url.split('/');
-        const [, , downloadId, ...rest] = segments;
-        // Strip trailing filename segment (e.g. "artist-song.srt") when present so the
-        // Redis key lookup uses only the extension portion of the path.
-        const hasFilename = rest.length > 1 && rest[rest.length - 1].includes('.');
-        const extensionParts = hasFilename ? rest.slice(0, -1) : rest;
-        const extension = extensionParts.join('/') || '';
+        const [, , idSegment, ...rest] = segments;
+
+        // Support two URL formats:
+        //   flat:     /downloads/export-xxx.srt         → id=export-xxx, extension=srt
+        //   compound: /downloads/export-xxx/romanized.srt → id=export-xxx, extension=romanized.srt
+        let downloadId, extension;
+        if (rest.length === 0 && idSegment && idSegment.includes('.')) {
+          // Flat format – extension is appended to the id with a dot.
+          const dotIdx = idSegment.lastIndexOf('.');
+          downloadId = idSegment.slice(0, dotIdx);
+          extension = idSegment.slice(dotIdx + 1);
+        } else {
+          // Compound / path-segment format.
+          downloadId = idSegment;
+          // Strip trailing human-readable filename (e.g. "artist-song.srt") when present.
+          const hasFilename = rest.length > 1 && rest[rest.length - 1].includes('.');
+          const extensionParts = hasFilename ? rest.slice(0, -1) : rest;
+          extension = extensionParts.join('/') || '';
+        }
         if (!downloadId || !extension) {
           logger.warn('Invalid download path', {
             context: 'http-download',

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

@@ -134,8 +134,8 @@ export async function startMcpHttpServer(options = {}) {
   });
 
   // ── Export download endpoint ──────────────────────────────────────────────────
-  app.get('/downloads/:downloadId/:extension', async (req, res) => {
-    const { downloadId, extension } = req.params;
+  // Helper shared by both download route handlers.
+  async function serveDownload(downloadId, extension, res, url) {
     if (!downloadId || !extension) {
       res.status(400).json({ error: 'Invalid download path' });
       return;
@@ -163,9 +163,28 @@ export async function startMcpHttpServer(options = {}) {
         bytes: Buffer.byteLength(content)
       });
     } catch (error) {
-      logger.error('Download lookup failed', { error, url: req.originalUrl });
+      logger.error('Download lookup failed', { error, url });
       res.status(500).json({ error: 'Failed to fetch export' });
     }
+  }
+
+  // Flat format:     /downloads/export-xxx.srt      → id=export-xxx, extension=srt
+  app.get('/downloads/:idWithExt', async (req, res) => {
+    const { idWithExt } = req.params;
+    if (!idWithExt || !idWithExt.includes('.')) {
+      res.status(400).json({ error: 'Invalid download path' });
+      return;
+    }
+    const dotIdx = idWithExt.lastIndexOf('.');
+    const downloadId = idWithExt.slice(0, dotIdx);
+    const extension = idWithExt.slice(dotIdx + 1);
+    await serveDownload(downloadId, extension, res, req.originalUrl);
+  });
+
+  // Compound format: /downloads/export-xxx/romanized.srt → id=export-xxx, extension=romanized.srt
+  app.get('/downloads/:downloadId/:extension', async (req, res) => {
+    const { downloadId, extension } = req.params;
+    await serveDownload(downloadId, extension, res, req.originalUrl);
   });
 
   // ── Streamable HTTP transport (/mcp) ──────────────────────────────────────────

package/src/transport/mcp-tools.js

@@ -435,11 +435,10 @@ export async function handleMcpTool(name, args = {}) {
 
   if (name === 'runtime_status') {
     const CREDENTIAL_KEYS = [
-      'GENIUS_ACCESS_TOKEN',
+      'GENIUS_DIRECT_TOKEN',
       'GENIUS_CLIENT_ID',
       'GENIUS_CLIENT_SECRET',
-      'MUSIXMATCH_ALT_USER_TOKEN',
-      'MUSIXMATCH_FALLBACK_TOKEN',
+      'MUSIXMATCH_DIRECT_TOKEN',
       'MELON_COOKIE'
     ];
     return {

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

@@ -37,7 +37,7 @@ async function logGeniusStatus(context) {
     context,
     provider: 'genius',
     clientCredentialsPresent: diagnostics.clientCredentialsPresent,
-    fallbackTokenPresent: diagnostics.fallbackTokenPresent,
+    directTokenPresent: diagnostics.directTokenPresent,
     cacheTokenPresent: diagnostics.cacheTokenPresent,
     cacheTokenExpired: diagnostics.cacheTokenExpired
   });
@@ -73,7 +73,7 @@ async function logGeniusStatus(context) {
     logger.warn('Genius credentials missing', {
       context,
       provider: 'genius',
-      details: 'set GENIUS_CLIENT_ID/SECRET or GENIUS_ACCESS_TOKEN'
+      details: 'set GENIUS_CLIENT_ID/SECRET or GENIUS_DIRECT_TOKEN'
     });
   }
 }
@@ -86,8 +86,7 @@ async function logMusixmatchStatus(context) {
     context,
     provider: 'musixmatch',
     cachePath: diagnostics.cachePath,
-    userEnvPresent: diagnostics.userEnvPresent,
-    envPresent: diagnostics.envPresent,
+    directEnvPresent: diagnostics.directEnvPresent,
     runtimeTokenCached: diagnostics.runtimeTokenCached,
     lastLoadedFrom: diagnostics.lastLoadedFrom
   });
@@ -117,7 +116,7 @@ async function logMusixmatchStatus(context) {
       context,
       provider: 'musixmatch',
       details:
-        'run npm run fetch:musixmatch-token to capture the cache token, or set MUSIXMATCH_FALLBACK_TOKEN as a fallback token for ephemeral deployments'
+        'run npm run fetch:musixmatch-token to capture the cache token, or set MUSIXMATCH_DIRECT_TOKEN as a direct token for ephemeral deployments'
     });
   }
 }

package/src/utils/config.js

@@ -23,7 +23,7 @@ export function getEnvValue(name) {
   return process.env[name] ?? null;
 }
 
-const DEFAULT_REQUIRED = ['GENIUS_ACCESS_TOKEN'];
+const DEFAULT_REQUIRED = ['GENIUS_DIRECT_TOKEN'];
 const warnedMissingEnvCache = new Set();
 
 function getMissingEnvVars(requiredVars = DEFAULT_REQUIRED) {

package/src/utils/export-storage/redis-storage.js

@@ -30,8 +30,11 @@ export default class RedisStorage {
 
     const expiresAt = new Date(Date.now() + this.ttl * 1000).toISOString();
     const base = this.downloadBaseUrl?.replace(/[\/]+$/, '') || '';
-    const bareExt = extension.includes('.') ? extension.split('.').pop() : extension;
-    const url = `${base}/downloads/${id}/${extension}/${baseName}.${bareExt}`;
+    // Compound extensions (e.g. "romanized.srt") become a path segment;
+    // simple extensions (e.g. "srt") are appended directly to the id.
+    const url = extension.includes('.')
+      ? `${base}/downloads/${id}/${extension}`
+      : `${base}/downloads/${id}.${extension}`;
     return new ExportStorageResult({ url, expiresAt, skipped: false });
   }
 }

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(),