mr-magic-mcp-server 0.3.11 → 0.4.0

package/.env.example

@@ -94,7 +94,7 @@ CF_ACCOUNT_ID=             # Cloudflare account ID (CF KV only)
 CF_KV_NAMESPACE_ID=        # KV namespace ID to store the token in (CF KV only)
 
 # Required when BACKEND=local
-MR_MAGIC_EXPORT_DIR=/Users/naji/Downloads/magic-export/        # Absolute path to the directory to write export files into
+MR_MAGIC_EXPORT_DIR=/Users/yourusername/Downloads/magic-export/        # Absolute path to the directory to write export files into
 
 # Base URL the server uses to build download links returned to the MCP client.
 # Examples: https://yourserver.com  |  http://localhost:3444 | http://localhost:3333

package/README.md

@@ -1161,12 +1161,19 @@ A single CLI entrypoint (`mrmagic-cli`) is published with the package. Inside th
 local repo use `npm run cli -- <subcommand>` unless you have run `npm link` or
 installed globally.
 
+Global CLI options:
+
+- `--env-path <path>` / `--env-file <path>` — load credentials from a custom `.env` file
+  before running the command. This is useful for global installs, `npm link`, and `npx`
+  usage where the package install directory is not your project directory.
+
 ### Commands
 
 | Command                       | Purpose                                                 | Notable flags                                                                                              |
 | ----------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
 | `mrmagic-cli search`          | List candidates across providers without downloading.   | `--artist`, `--title`, `--provider`, `--duration`, `--show-all`, `--pick`                                  |
 | `mrmagic-cli find`            | Resolve best lyric (prefers synced) and print / export. | `--providers`, `--synced-only`, `--export`, `--format`, `--output`, `--no-romanize`, `--choose`, `--index` |
+| `mrmagic-cli export`          | Resolve best lyric and write export files directly.     | `--providers`, `--synced-only`, `--format`, `--output`, `--no-romanize`                                    |
 | `mrmagic-cli select`          | Pick first match from a prioritized provider list.      | `--providers`, `--artist`, `--title`, `--require-synced`                                                   |
 | `mrmagic-cli server`          | Start the JSON automation API.                          | `--host`, `--port`, `--remote`                                                                             |
 | `mrmagic-cli server:mcp`      | Start the MCP stdio server.                             | —                                                                                                          |
@@ -1180,9 +1187,15 @@ installed globally.
 # Search all providers
 npm run cli -- search --artist "BLACKPINK" --title "Kill This Love"
 
+# Global/custom install with an explicit credential file
+mrmagic-cli --env-path /absolute/path/to/.env find --artist "Nayeon" --title "POP!"
+
 # Find best lyric (prefers synced LRC)
 npm run cli -- find --artist "Nayeon" --title "POP!"
 
+# Export plain text and SRT files for the best match
+npm run cli -- export --artist "Nayeon" --title "POP!" --format plain --format srt --output ./exports
+
 # Pick first synced match from a prioritized provider list
 npm run cli -- select --providers lrclib,genius --artist "Nayeon" --title "POP!" --require-synced
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-magic-mcp-server",
-  "version": "0.3.11",
+  "version": "0.4.0",
   "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
   "type": "module",
   "main": "src/index.js",
@@ -61,18 +61,18 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.59.1",
+    "@dotenvx/dotenvx": "^1.61.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "axios": "^1.14.0",
+    "axios": "^1.15.0",
     "cheerio": "^1.2.0",
     "commander": "^14.0.3"
   },
   "devDependencies": {
-    "eslint": "^10.1.0",
+    "eslint": "^10.2.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import-x": "^4.16.2",
-    "playwright": "^1.59.0",
-    "prettier": "^3.8.1"
+    "playwright": "^1.59.1",
+    "prettier": "^3.8.3"
   },
   "overrides": {
     "entities": "^7.0.1",

package/prompts/airtable-song-importer.md

@@ -54,7 +54,7 @@ Examples:
 - `BLACKPINK, Doja Cat, Absolutely - Crazy (Lyrics)`
 - `Joji - Glimpse of Us (Lyrics)`
 - `[GANG$] - Money (Remix) (Lyrics)`
-- WRONG:`John Wick - This Song Is Lit (feat. BANKS) \\ RIGHT:`John Wick, BANKS - This Song Is Lit`
+- WRONG:`John Wick - This Song Is Lit (feat. BANKS) \\ RIGHT: `John Wick, BANKS - This Song Is Lit`
 
 Artist names may contain brackets or special characters. Preserve them exactly.
 
@@ -85,6 +85,9 @@ Artist names may contain brackets or special characters. Preserve them exactly.
 
 `build_catalog_payload` is the **required and exclusive lyric-resolution / lyric-preparation step for any Airtable entry**.
 
+If you have an issue finding a lyric for a song with all the artists given, fallback to just using the first written artist, or the native language equivalent if found on Spotify.
+
+If you have an issue finding a lyric for a song with the english title, use the native language version native language equivalent title of the song found from Spotify.
 For every song that will be written to Airtable:
 
 1. You **must** call `build_catalog_payload` before the Lyrics field can be written.

package/src/bin/cli.js

@@ -6,4 +6,12 @@
 if (!process.env.LOG_LEVEL) process.env.LOG_LEVEL = 'warn';
 if (!process.env.MR_MAGIC_QUIET_STDIO) process.env.MR_MAGIC_QUIET_STDIO = '1';
 
+const envPathFlagIndex = process.argv.findIndex(
+  (arg) => arg === '--env-path' || arg === '--env-file'
+);
+if (envPathFlagIndex >= 0 && process.argv[envPathFlagIndex + 1]) {
+  process.env.MR_MAGIC_ENV_PATH = process.argv[envPathFlagIndex + 1];
+  process.argv.splice(envPathFlagIndex, 2);
+}
+
 await import('../tools/cli.js');

package/src/index.js

@@ -45,6 +45,10 @@ function rankRecord(record) {
   return contentScore + syncedBonus + confidenceScore;
 }
 
+function isBlockedRecord(record) {
+  return record?.status === 'captcha_blocked' || record?.status === 'blocked';
+}
+
 async function tryProviders(track, { syncedOnly = false, providerNames = [] } = {}) {
   const matches = [];
   let bestSynced = null;
@@ -88,22 +92,23 @@ async function tryProviders(track, { syncedOnly = false, providerNames = [] } =
 
 export async function findLyrics(track, options = {}) {
   const { matches, best } = await tryProviders(track, options);
+  const visibleMatches = matches.filter(
+    ({ result }) => lyricContentScore(result) > 0 || isBlockedRecord(result)
+  );
   return {
-    // Filter out candidates with no actual lyric content (empty / unhydrated stubs).
-    // This keeps the matches list clean for all consumers: CLI, MCP tools, HTTP server.
-    matches: matches
-      .filter(({ result }) => lyricContentScore(result) > 0)
-      .map(({ provider, result }) => ({ provider, result })),
+    // Keep lyric-bearing matches plus explicit provider-block states.
+    matches: visibleMatches.map(({ provider, result }) => ({ provider, result })),
     best: best?.result ?? null
   };
 }
 
 export async function findSyncedLyrics(track, options = {}) {
   const { matches, best } = await tryProviders(track, { ...options, syncedOnly: true });
+  const visibleMatches = matches.filter(
+    ({ result }) => lyricContentScore(result) > 0 || isBlockedRecord(result)
+  );
   return {
-    matches: matches
-      .filter(({ result }) => lyricContentScore(result) > 0)
-      .map(({ provider, result }) => ({ provider, result })),
+    matches: visibleMatches.map(({ provider, result }) => ({ provider, result })),
     best: best?.result ?? null
   };
 }

package/src/providers/musixmatch.js

@@ -4,6 +4,7 @@ import { normalizeLyricRecord } from '../provider-result-schema.js';
 import { createLogger } from '../utils/logger.js';
 import {
   getMusixmatchToken,
+  getMusixmatchDesktopCookie,
   invalidateMusixmatchToken
 } from '../utils/tokens/musixmatch-token-manager.js';
 
@@ -15,9 +16,60 @@ const DEFAULT_HEADERS = {
   authority: 'apic-desktop.musixmatch.com',
   'User-Agent': MOZILLA_USER_AGENT
 };
+const MXM_COOKIE_FALLBACK = 'x-mxm-token-guid=';
 
 const logger = createLogger('provider:musixmatch');
 
+function formatSubtitleTimestamp(item) {
+  if (!item || typeof item !== 'object') return null;
+
+  const text =
+    typeof item.text === 'string'
+      ? item.text
+      : typeof item.subtitle_body === 'string'
+        ? item.subtitle_body
+        : '';
+
+  const candidates = [
+    item.time,
+    item.timestamp,
+    item.ts,
+    item.line_time,
+    item.lineTime,
+    item.time_total,
+    item.timeTotal
+  ].filter((value) => value !== null && value !== undefined);
+
+  const numericCandidate = candidates.find((value) => typeof value === 'number');
+  if (typeof numericCandidate === 'number' && Number.isFinite(numericCandidate)) {
+    const totalCentiseconds = Math.max(0, Math.round(numericCandidate * 100));
+    const minutes = Math.floor(totalCentiseconds / 6000);
+    const seconds = Math.floor((totalCentiseconds % 6000) / 100);
+    const hundredths = totalCentiseconds % 100;
+    return `[${minutes.toString().padStart(2, '0')}:${seconds
+      .toString()
+      .padStart(2, '0')}.${hundredths.toString().padStart(2, '0')}] ${text}`.trim();
+  }
+
+  const timeObject = candidates.find((value) => value && typeof value === 'object');
+  if (timeObject) {
+    const minutes = Number(timeObject.minutes ?? timeObject.min ?? 0);
+    const seconds = Number(timeObject.seconds ?? timeObject.sec ?? 0);
+    const hundredths = Number(
+      timeObject.hundredths ?? timeObject.hundredth ?? timeObject.cs ?? timeObject.milliseconds ?? 0
+    );
+    if ([minutes, seconds, hundredths].every(Number.isFinite)) {
+      const normalizedHundredths =
+        hundredths > 99 ? Math.floor(hundredths / 10) : Math.max(0, hundredths);
+      return `[${minutes.toString().padStart(2, '0')}:${seconds
+        .toString()
+        .padStart(2, '0')}.${normalizedHundredths.toString().padStart(2, '0')}] ${text}`.trim();
+    }
+  }
+
+  return null;
+}
+
 function buildParams(track, token) {
   const durationSeconds = track.duration ? Math.round(track.duration / 1000) : '';
   return new URLSearchParams({
@@ -36,13 +88,56 @@ function buildParams(track, token) {
   });
 }
 
+function summarizeMacroStatus(body = {}) {
+  return {
+    matcher: body['matcher.track.get']?.message?.header ?? null,
+    lyrics: body['track.lyrics.get']?.message?.header ?? null,
+    subtitles: body['track.subtitles.get']?.message?.header ?? null
+  };
+}
+
+function buildBlockedRecord(track = {}, body = {}, reason = 'captcha') {
+  return normalizeLyricRecord({
+    provider: 'musixmatch',
+    id: null,
+    trackName: track.title || null,
+    artistName: track.artist || null,
+    albumName: track.album || null,
+    duration: track.duration ? Math.round(track.duration / 1000) : null,
+    plainLyrics: null,
+    syncedLyrics: null,
+    sourceUrl: null,
+    confidence: 0,
+    synced: false,
+    status: reason === 'captcha' ? 'captcha_blocked' : 'blocked',
+    raw: body
+  });
+}
+
+function classifyUnauthorizedPayload(payload) {
+  const hint = payload?.message?.header?.hint;
+  if (hint === 'renew') {
+    return 'MUSIXMATCH_TOKEN_RENEW';
+  }
+  return 'MUSIXMATCH_CAPTCHA';
+}
+
 function normalizeBody(body) {
   const matcher = body['matcher.track.get']?.message?.body;
   if (!matcher) {
+    logger.warn('Musixmatch matcher body missing', { macroStatus: summarizeMacroStatus(body) });
     return null;
   }
 
   const meta = matcher.track || {};
+  if (!meta.track_id) {
+    logger.warn('Musixmatch matcher returned no track', {
+      macroStatus: summarizeMacroStatus(body),
+      matcherBodyType: Array.isArray(matcher) ? 'array' : typeof matcher,
+      matcherPreview: Array.isArray(matcher) ? matcher.slice(0, 2) : matcher
+    });
+    return null;
+  }
   const lyricsBody = body['track.lyrics.get']?.message?.body?.lyrics?.lyrics_body || '';
   const subtitlesRoot = body['track.subtitles.get']?.message?.body;
   const subtitleEntry =
@@ -73,18 +168,38 @@ function normalizeBody(body) {
     }
   }
 
-  const syncedLyrics = syncedLines
-    .map((item) => {
-      const time = item?.time || {};
-      return `[${time.minutes.toString().padStart(2, '0')}:${time.seconds.toString().padStart(2, '0')}.${(
-        time.hundredths || 0
-      )
-        .toString()
-        .padStart(2, '0')}] ${item.text}`.trim();
-    })
-    .join('\n');
+  const syncedLyricLines = [];
+  let skippedSubtitleItems = 0;
+  for (const item of Array.isArray(syncedLines) ? syncedLines : []) {
+    const formattedLine = formatSubtitleTimestamp(item);
+    if (formattedLine) {
+      syncedLyricLines.push(formattedLine);
+    } else {
+      skippedSubtitleItems += 1;
+    }
+  }
+
+  if (skippedSubtitleItems > 0) {
+    logger.warn('Musixmatch subtitle items skipped due to unrecognized shape', {
+      skippedSubtitleItems,
+      sample: Array.isArray(syncedLines) ? syncedLines.slice(0, 2) : syncedLines,
+      trackId: meta.track_id,
+      trackName: meta.track_name,
+      artistName: meta.artist_name
+    });
+  }
+
+  const syncedLyrics = syncedLyricLines.join('\n');
 
   const plainLyrics = lyricsBody.split('\n').filter(Boolean).join('\n');
+  if (!plainLyrics && !syncedLyrics) {
+    logger.warn('Musixmatch matched track but returned no lyric content', {
+      trackId: meta.track_id,
+      trackName: meta.track_name,
+      artistName: meta.artist_name,
+      macroStatus: summarizeMacroStatus(body)
+    });
+  }
   const sourceUrl = meta.share_url || '';
 
   return normalizeLyricRecord({
@@ -107,25 +222,122 @@ function normalizeBody(body) {
 async function macroRequest(track) {
   await ensureMusixmatchToken();
   let token = await getMusixmatchToken();
-  const attempt = async (tok) => {
+  let desktopCookie = await getMusixmatchDesktopCookie();
+  const topLevel401 = (payload) => payload?.message?.header?.status_code === 401;
+  const attempt = async (tok, cookie) => {
     const params = buildParams(track, tok);
+    const requestHeaders = {
+      ...DEFAULT_HEADERS,
+      Cookie: cookie || MXM_COOKIE_FALLBACK
+    };
     const response = await axios.get(`${BASE_URL}?${params.toString()}`, {
       timeout: HTTP_TIMEOUT_MS,
-      headers: DEFAULT_HEADERS
+      headers: requestHeaders,
+      validateStatus: () => true,
+      responseType: 'text',
+      transformResponse: [(value) => value]
+    });
+    const contentType = response.headers?.['content-type'] || null;
+    const bodyPreview =
+      typeof response.data === 'string' ? response.data.slice(0, 240) : (response.data ?? null);
+
+    logger.debug('Musixmatch raw response received', {
+      httpStatus: response.status,
+      contentType,
+      dataType: typeof response.data,
+      bodyPreview,
+      trackTitle: track?.title || null,
+      trackArtist: track?.artist || null,
+      desktopCookiePresent: Boolean(cookie),
+      usingFallbackCookie: !cookie
     });
-    return response.data?.message?.body?.macro_calls || response.data?.message?.body || {};
+
+    if (typeof response.data !== 'string') {
+      logger.warn('Musixmatch returned non-text raw payload', {
+        httpStatus: response.status,
+        contentType,
+        dataType: typeof response.data
+      });
+    }
+
+    if (typeof response.data === 'string') {
+      const trimmed = response.data.trim();
+      const looksLikeHtml =
+        contentType?.includes('text/html') ||
+        /^<!doctype html/i.test(trimmed) ||
+        /^<html[\s>]/i.test(trimmed);
+      if (looksLikeHtml) {
+        const error = new Error('Musixmatch returned HTML instead of JSON');
+        error.code = 'MUSIXMATCH_HTML_RESPONSE';
+        error.response = {
+          status: response.status,
+          data: response.data,
+          headers: response.headers
+        };
+        throw error;
+      }
+    }
+
+    let payload;
+    try {
+      payload = typeof response.data === 'string' ? JSON.parse(response.data) : response.data;
+    } catch (parseError) {
+      logger.error('Failed to parse Musixmatch response as JSON', {
+        httpStatus: response.status,
+        contentType,
+        bodyPreview,
+        error: parseError
+      });
+      const error = new Error('Musixmatch returned invalid JSON');
+      error.code = 'MUSIXMATCH_INVALID_JSON';
+      error.response = {
+        status: response.status,
+        data: response.data,
+        headers: response.headers
+      };
+      throw error;
+    }
+
+    if (response.status === 401 || response.status === 403) {
+      const error = new Error(`Musixmatch HTTP ${response.status}`);
+      error.code =
+        response.status === 401 ? classifyUnauthorizedPayload(payload) : 'MUSIXMATCH_BLOCKED';
+      error.response = {
+        status: response.status,
+        data: payload,
+        headers: response.headers
+      };
+      throw error;
+    }
+
+    if (topLevel401(payload)) {
+      const error = new Error('Musixmatch unauthorized response');
+      error.code = classifyUnauthorizedPayload(payload);
+      error.response = {
+        status: 401,
+        data: payload,
+        headers: response.headers
+      };
+      throw error;
+    }
+    return payload?.message?.body?.macro_calls || payload?.message?.body || {};
   };
 
   try {
-    return await attempt(token);
+    return await attempt(token, desktopCookie);
   } catch (error) {
     if (error.response?.status === 401 || error.response?.status === 403) {
-      logger.warn('Musixmatch token rejected, invalidating', { status: error.response.status });
+      logger.warn('Musixmatch token rejected, invalidating', {
+        status: error.response.status,
+        desktopCookiePresent: Boolean(desktopCookie),
+        errorCode: error.code
+      });
       invalidateMusixmatchToken();
       token = await getMusixmatchToken();
+      desktopCookie = await getMusixmatchDesktopCookie();
       if (token) {
         try {
-          return await attempt(token);
+          return await attempt(token, desktopCookie);
         } catch (retryError) {
           logger.error('Musixmatch retry failed', { error: retryError });
         }
@@ -154,6 +366,29 @@ export async function fetchFromMusixmatch(track) {
     const record = normalizeBody(body);
     return record;
   } catch (error) {
+    if (error.code === 'MUSIXMATCH_CAPTCHA' || error.code === 'MUSIXMATCH_HTML_RESPONSE') {
+      logger.warn('Musixmatch blocked by captcha challenge', {
+        trackTitle: track?.title || null,
+        trackArtist: track?.artist || null,
+        httpStatus: error.response?.status ?? null,
+        contentType: error.response?.headers?.['content-type'] ?? null
+      });
+      return buildBlockedRecord(track, error.response?.data, 'captcha');
+    }
+    if (
+      error.code === 'MUSIXMATCH_BLOCKED' ||
+      error.code === 'MUSIXMATCH_INVALID_JSON' ||
+      error.code === 'MUSIXMATCH_TOKEN_RENEW'
+    ) {
+      logger.warn('Musixmatch returned blocked or invalid response', {
+        trackTitle: track?.title || null,
+        trackArtist: track?.artist || null,
+        httpStatus: error.response?.status ?? null,
+        contentType: error.response?.headers?.['content-type'] ?? null,
+        errorCode: error.code
+      });
+      return buildBlockedRecord(track, error.response?.data, 'blocked');
+    }
     logger.error('Musixmatch request failed', { error });
     return null;
   }
@@ -166,5 +401,10 @@ export async function searchMusixmatch(track) {
 
 export async function checkMusixmatchTokenReady() {
   const token = await getMusixmatchToken();
+  const desktopCookie = await getMusixmatchDesktopCookie();
+  logger.debug('Musixmatch credential readiness checked', {
+    tokenPresent: Boolean(token),
+    desktopCookiePresent: Boolean(desktopCookie)
+  });
   return Boolean(token);
 }

package/src/scripts/fetch_musixmatch_token.mjs

@@ -7,13 +7,35 @@ import '../utils/config.js';
 import { describeKvBackend, isKvConfigured, kvSet } from '../utils/kv-store.js';
 
 const AUTH_URL = 'https://auth.musixmatch.com/';
+const ACCOUNT_URL = 'https://account.musixmatch.com';
 
-async function saveToken(token, desktopCookie) {
+async function waitForDesktopCookie(context, { attempts = 10, delayMs = 500 } = {}) {
+  let latestCookies = [];
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    latestCookies = await context.cookies(ACCOUNT_URL);
+    const desktopCookie = latestCookies.find((cookie) => cookie.name === 'web-desktop-app-v1.0');
+    if (desktopCookie) {
+      return { desktopCookie, cookies: latestCookies, attempts: attempt };
+    }
+
+    if (attempt < attempts) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  return { desktopCookie: null, cookies: latestCookies, attempts };
+}
+
+async function saveToken(token, desktopCookie, tokenPayload) {
   // Uses the same env var as the server runtime so both read/write the same path.
   const cachePath =
     process.env.MUSIXMATCH_TOKEN_CACHE || path.resolve('.cache', 'musixmatch-token.json');
   await mkdir(path.dirname(cachePath), { recursive: true });
   const payload = { token };
+  if (tokenPayload && typeof tokenPayload === 'object') {
+    payload.tokenPayload = tokenPayload;
+  }
   if (desktopCookie) {
     payload.desktopCookie = desktopCookie;
   }
@@ -22,11 +44,15 @@ async function saveToken(token, desktopCookie) {
   console.log('(Local and persistent servers read this file on startup.)');
 }
 
-async function saveToKv(token, desktopCookie) {
+async function saveToKv(token, desktopCookie, tokenPayload) {
   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 } : {}) });
+  const payload = JSON.stringify({
+    token,
+    ...(tokenPayload && typeof tokenPayload === 'object' ? { tokenPayload } : {}),
+    ...(desktopCookie ? { desktopCookie } : {})
+  });
   try {
     await kvSet(kvKey, payload, kvTtl);
     console.log(`Token written to KV store (${describeKvBackend()}) under key: ${kvKey}`);
@@ -35,11 +61,7 @@ async function saveToKv(token, desktopCookie) {
   }
 }
 
-function printDeploymentBlock(tokenValue) {
-  const tokenString =
-    typeof tokenValue === 'string'
-      ? tokenValue
-      : (tokenValue?.message?.body?.usertoken ?? JSON.stringify(tokenValue));
+function printDeploymentBlock(tokenString) {
   const kvBackend = isKvConfigured() ? describeKvBackend() : null;
 
   console.log('\n' + '─'.repeat(68));
@@ -47,6 +69,7 @@ function printDeploymentBlock(tokenValue) {
 
   console.log('LOCAL & PERSISTENT SERVERS (cache token)');
   console.log('  Token written to .cache/musixmatch-token.json (or MUSIXMATCH_TOKEN_CACHE).');
+  console.log('  When available, the desktop cookie is written alongside the token.');
   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');
@@ -78,6 +101,29 @@ function isHeadlessEnabled() {
   return value === '1' || value === 'true' || value === 'yes';
 }
 
+function resolveTokenFromPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return null;
+  }
+
+  if (
+    typeof payload?.message?.body?.usertoken === 'string' &&
+    payload.message.body.usertoken.trim()
+  ) {
+    return payload.message.body.usertoken;
+  }
+
+  if (typeof payload?.tokens?.['web-desktop-app-v1.0'] === 'string') {
+    return payload.tokens['web-desktop-app-v1.0'].trim() || null;
+  }
+
+  if (typeof payload?.tokens?.['mxm-com-v1.0'] === 'string') {
+    return payload.tokens['mxm-com-v1.0'].trim() || null;
+  }
+
+  return null;
+}
+
 async function main() {
   const headless = isHeadlessEnabled();
 
@@ -189,11 +235,17 @@ async function main() {
   // 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 });
+  await page.waitForURL(`${ACCOUNT_URL}/**`, { timeout: 0 });
+  await page.waitForLoadState('domcontentloaded');
+  try {
+    await page.waitForLoadState('networkidle', { timeout: 5000 });
+  } catch {
+    // Best-effort stabilization: some pages keep background connections open.
+  }
 
-  const cookies = await context.cookies('https://account.musixmatch.com');
+  const { desktopCookie, cookies, attempts } = await waitForDesktopCookie(context);
+  console.log(`Checked account.musixmatch.com cookies ${attempts} time(s) after login.`);
   const userCookie = cookies.find((cookie) => cookie.name === 'musixmatchUserToken');
-  const desktopCookie = cookies.find((cookie) => cookie.name === 'web-desktop-app-v1.0');
   if (!userCookie) {
     console.error('musixmatchUserToken cookie not found; ensure you completed login.');
     process.exit(1);
@@ -210,18 +262,25 @@ async function main() {
   console.log('\nMusixmatch token payload:');
   console.log(JSON.stringify(parsed, null, 2));
 
+  const resolvedToken = resolveTokenFromPayload(parsed);
+  if (typeof resolvedToken !== 'string' || !resolvedToken.trim()) {
+    console.error('Unable to extract raw usertoken string from musixmatchUserToken payload.');
+    process.exit(1);
+  }
+
   const decodedDesktopCookie = desktopCookie ? decodeURIComponent(desktopCookie.value) : null;
+  console.log(`Desktop cookie captured: ${decodedDesktopCookie ? 'yes' : 'no'}`);
 
   // Write to all configured storage backends in parallel.
   await Promise.allSettled([
-    saveToken(parsed, decodedDesktopCookie),
-    saveToKv(parsed, decodedDesktopCookie)
+    saveToken(resolvedToken, decodedDesktopCookie, parsed),
+    saveToKv(resolvedToken, decodedDesktopCookie, parsed)
   ]);
 
   // 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);
+  printDeploymentBlock(resolvedToken);
 
   await context.close();
 }

package/src/tests/run-tests.js

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
 import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 
 import { selectMatch } from '../index.js';
 import { buildChooserEntries, autoPick } from '../core/find-service.js';
@@ -431,6 +435,54 @@ async function testBuildPayloadFromResultNoCacheKeyWhenNoLyrics() {
   console.log('buildPayloadFromResult omits lyricsCacheKey when best has no lyrics: ok');
 }
 
+function testCliExportCommandHelp() {
+  const output = execFileSync(process.execPath, ['src/bin/cli.js', 'export', '--help'], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      LOG_LEVEL: 'error',
+      MR_MAGIC_QUIET_STDIO: '1'
+    }
+  });
+
+  assert.ok(output.includes('Find lyrics and write plain/LRC/SRT exports'));
+  assert.ok(output.includes('--format <format>'));
+  assert.ok(output.includes('--output <dir>'));
+
+  divider();
+  console.log('CLI export command help is available: ok');
+}
+
+function testCliEnvPathLoadsCustomEnvFile() {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mrmagic-cli-env-'));
+  const envPath = path.join(tempDir, '.env.custom');
+  fs.writeFileSync(envPath, 'GENIUS_DIRECT_TOKEN=cli-env-path-token\n', 'utf8');
+
+  try {
+    const output = execFileSync(
+      process.execPath,
+      ['src/bin/cli.js', '--env-path', envPath, 'status'],
+      {
+        encoding: 'utf8',
+        env: {
+          PATH: process.env.PATH,
+          NODE_ENV: process.env.NODE_ENV,
+          LOG_LEVEL: 'error',
+          MR_MAGIC_QUIET_STDIO: '1'
+        }
+      }
+    );
+
+    assert.ok(output.includes('genius'));
+    assert.ok(output.includes('Ready'), 'custom env file should make Genius status ready');
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+
+  divider();
+  console.log('CLI --env-path loads custom env files: ok');
+}
+
 async function run() {
   testAutoPickPrefersSynced();
   testAutoPickFallbackWhenNoSynced();
@@ -447,6 +499,8 @@ async function run() {
   testRomanization();
   await testBuildPayloadFromResultReturnsCacheKey();
   await testBuildPayloadFromResultNoCacheKeyWhenNoLyrics();
+  testCliExportCommandHelp();
+  testCliEnvPathLoadsCustomEnvFile();
   const toolNames = mcpToolDefinitions.map((tool) => tool.name);
   console.log('MCP tooling available:', toolNames.join(', '));
   console.log('All sanity checks passed');

package/src/tools/cli.js

@@ -107,7 +107,9 @@ const program = new Command();
 program
   .name('mrmagic-cli')
   .description('Lyrics MCP server CLI powered by LRCLIB, Genius, Musixmatch, and Melon')
-  .version('0.1.3');
+  .version('0.1.3')
+  .option('--env-path <path>', 'Path to a .env file to load before running a CLI command')
+  .option('--env-file <path>', 'Alias for --env-path');
 
 function normalizeFormatOptions(value) {
   if (!value) return [];
@@ -699,6 +701,67 @@ program
     }
   });
 
+program
+  .command('export')
+  .description('Find lyrics and write plain/LRC/SRT exports')
+  .requiredOption('--artist <name>', 'Artist name')
+  .requiredOption('--title <name>', 'Song title')
+  .option('--album <name>', 'Album name')
+  .option('--duration <ms>', 'Track duration in milliseconds')
+  .option('--providers <list>', 'Comma-separated provider list')
+  .option('--synced-only', 'Require synced lyrics', false)
+  .option(
+    '--format <format>',
+    'Export format (plain|lrc|srt). repeatable',
+    (value, acc) => {
+      acc.push(value);
+      return acc;
+    },
+    []
+  )
+  .option('--output <dir>', 'Directory for exports (defaults to MR_MAGIC_EXPORT_DIR or ./exports)')
+  .option('--no-romanize', 'Disable romanized lyrics', false)
+  .action(async (options) => {
+    const track = buildTrackFromOptions(options);
+    const searchLabel = [track.artist, track.title].filter(Boolean).join(' - ');
+    process.stderr.write(`Searching: ${searchLabel}...\n`);
+    const providerNames = options.providers
+      ? options.providers.split(',').map((value) => value.trim())
+      : [];
+    const result = await runFind(track, {
+      providerNames,
+      syncedOnly: options.syncedOnly
+    });
+
+    if (!result.best) {
+      console.error('No best match available');
+      process.exitCode = 1;
+      return;
+    }
+
+    const includeRomanization = options.noRomanize ? false : true;
+    const exports = await exportLyrics(result.best, {
+      formats: deriveFormatSet(options.format),
+      output: options.output,
+      includeRomanization
+    });
+    console.log(
+      JSON.stringify(
+        {
+          picked: {
+            provider: result.best.provider || 'unknown',
+            synced: Boolean(result.best.synced),
+            artist: result.best.artist || track.artist || 'unknown',
+            title: result.best.title || track.title || 'song'
+          },
+          exports
+        },
+        null,
+        2
+      )
+    );
+  });
+
 program
   .command('search-provider')
   .description('Search a specific provider only')

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

@@ -31,6 +31,36 @@ let cachedToken = null;
 let lastLoadedFrom = 'unknown';
 let cachedDesktopCookie = null;
 
+function resolveStoredToken(parsed) {
+  if (!parsed) return null;
+
+  if (typeof parsed.token === 'string' && parsed.token.trim()) {
+    return parsed.token;
+  }
+
+  const nestedToken = parsed.token?.message?.body?.usertoken;
+  if (typeof nestedToken === 'string' && nestedToken.trim()) {
+    return nestedToken;
+  }
+
+  const payloadToken = parsed.tokenPayload?.message?.body?.usertoken;
+  if (typeof payloadToken === 'string' && payloadToken.trim()) {
+    return payloadToken;
+  }
+
+  const payloadDesktopToken = parsed.tokenPayload?.tokens?.['web-desktop-app-v1.0'];
+  if (typeof payloadDesktopToken === 'string' && payloadDesktopToken.trim()) {
+    return payloadDesktopToken;
+  }
+
+  const nestedDesktopToken = parsed.token?.tokens?.['web-desktop-app-v1.0'];
+  if (typeof nestedDesktopToken === 'string' && nestedDesktopToken.trim()) {
+    return nestedDesktopToken;
+  }
+
+  return null;
+}
+
 function getCacheDir() {
   return path.dirname(TOKEN_CACHE_PATH);
 }
@@ -50,8 +80,9 @@ async function readCachedToken() {
   try {
     const raw = await fs.readFile(TOKEN_CACHE_PATH, 'utf8');
     const parsed = JSON.parse(raw);
-    if (parsed?.token) {
-      cachedToken = parsed.token;
+    const resolvedToken = resolveStoredToken(parsed);
+    if (resolvedToken) {
+      cachedToken = resolvedToken;
       cachedDesktopCookie = parsed.desktopCookie || null;
       lastLoadedFrom = 'cache';
       return cachedToken;
@@ -91,8 +122,9 @@ async function readKvToken() {
     const raw = await kvGet(KV_KEY);
     if (!raw) return null;
     const parsed = JSON.parse(raw);
-    if (parsed?.token) {
-      cachedToken = parsed.token;
+    const resolvedToken = resolveStoredToken(parsed);
+    if (resolvedToken) {
+      cachedToken = resolvedToken;
       cachedDesktopCookie = parsed.desktopCookie || null;
       lastLoadedFrom = `kv:${describeKvBackend()}`;
       return cachedToken;
@@ -145,6 +177,15 @@ export async function getMusixmatchToken() {
   return readCachedToken();
 }
 
+export async function getMusixmatchDesktopCookie() {
+  if (cachedDesktopCookie) {
+    return cachedDesktopCookie;
+  }
+
+  await getMusixmatchToken();
+  return cachedDesktopCookie;
+}
+
 export async function setMusixmatchToken(token, { desktopCookie } = {}) {
   if (!token) return;
   cachedToken = token;
@@ -196,7 +237,7 @@ export async function getMusixmatchTokenDiagnostics() {
     diagnostics.cacheFound = true;
     diagnostics.cacheBytes = raw.length;
     const parsed = JSON.parse(raw.toString('utf8'));
-    diagnostics.cacheTokenPresent = Boolean(parsed?.token);
+    diagnostics.cacheTokenPresent = Boolean(resolveStoredToken(parsed));
   } catch (error) {
     diagnostics.cacheError = error?.code === 'ENOENT' ? null : (error?.message ?? null);
   }