mr-magic-mcp-server 0.4.0 → 0.5.1

package/README.md

@@ -401,6 +401,8 @@ The `MR_MAGIC_EXPORT_BACKEND` variable controls where formatted lyrics are store
 - **`local`** (default) — writes files to `MR_MAGIC_EXPORT_DIR` (or `exports/` when
   unset). Make sure the target directory is writable. The `export_lyrics` tool also
   returns the raw `content` field so clients can inline results when file writes fail.
+  For global or npx CLI usage, the default `exports/` directory is relative to the
+  directory where you run `mrmagic-cli`, not the npm package install directory.
 
 - **`inline`** — skips disk writes entirely. Each export is returned in the tool
   response with `content` populated and `skipped: true` to signal that persistence
@@ -435,6 +437,16 @@ Or against the JSON HTTP server:
 MR_MAGIC_DOWNLOAD_BASE_URL=http://127.0.0.1:3333
 ```
 
+For global installs, start the JSON HTTP download server with the same persisted env
+file or environment variables used for export commands:
+
+```bash
+mrmagic-cli server --port 3333
+```
+
+Download URLs are only needed for the `redis` export backend. Local exports return
+`file://` URLs and write files directly to `MR_MAGIC_EXPORT_DIR` or `./exports`.
+
 ## Local Deployment
 
 Run whichever entrypoint you need via npm scripts:
@@ -1166,6 +1178,9 @@ 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.
+- `--save-env-path` — persist the provided `--env-path` to
+  `~/.config/mrmagic-cli/config.json` so future `mrmagic-cli` commands load the same
+  credentials file automatically.
 
 ### Commands
 
@@ -1190,12 +1205,25 @@ 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!"
 
+# Save that credential file path once for future global CLI commands
+mrmagic-cli --env-path /absolute/path/to/.env --save-env-path status
+
 # 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
 
+# Global install: local export files are written to ./exports relative to your shell's current directory
+mrmagic-cli export --artist "Nayeon" --title "POP!" --format srt
+
+# Global install: Redis-backed download URLs served by the JSON HTTP server
+MR_MAGIC_EXPORT_BACKEND=redis \
+MR_MAGIC_DOWNLOAD_BASE_URL=http://127.0.0.1:3333 \
+  mrmagic-cli export --artist "Nayeon" --title "POP!" --format srt
+
+mrmagic-cli server --port 3333
+
 # 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.4.0",
+  "version": "0.5.1",
   "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
   "type": "module",
   "main": "src/index.js",
@@ -61,14 +61,16 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.61.1",
+    "@dotenvx/dotenvx": "^1.65.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "axios": "^1.15.0",
-    "cheerio": "^1.2.0",
-    "commander": "^14.0.3"
+    "axios": "^1.16.0",
+    "commander": "^14.0.3",
+    "css-select": "^6.0.0",
+    "domutils": "^3.2.2",
+    "htmlparser2": "^10.1.0"
   },
   "devDependencies": {
-    "eslint": "^10.2.1",
+    "eslint": "^10.3.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import-x": "^4.16.2",
     "playwright": "^1.59.1",

package/src/bin/cli.js

@@ -3,15 +3,54 @@
 // Reduce structured-log noise and env-missing warnings for interactive CLI usage.
 // These must be set before any module that reads them is evaluated, so we use
 // a dynamic import below instead of a static one.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
 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 configPath = process.env.MR_MAGIC_CLI_CONFIG_PATH
+  ? path.resolve(process.env.MR_MAGIC_CLI_CONFIG_PATH)
+  : path.join(os.homedir(), '.config', 'mrmagic-cli', 'config.json');
+const configDir = path.dirname(configPath);
+
+function readPersistedEnvPath() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return typeof parsed.envPath === 'string' && parsed.envPath.trim() ? parsed.envPath : null;
+  } catch {
+    return null;
+  }
+}
+
+function persistEnvPath(envPath) {
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(configPath, `${JSON.stringify({ envPath }, null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600
+  });
+}
+
 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);
+  if (process.argv.includes('--save-env-path')) {
+    persistEnvPath(process.env.MR_MAGIC_ENV_PATH);
+  }
+} else if (!process.env.MR_MAGIC_ENV_PATH) {
+  const persistedEnvPath = readPersistedEnvPath();
+  if (persistedEnvPath) {
+    process.env.MR_MAGIC_ENV_PATH = persistedEnvPath;
+  }
+}
+
+const saveEnvPathFlagIndex = process.argv.indexOf('--save-env-path');
+if (saveEnvPathFlagIndex >= 0) {
+  process.argv.splice(saveEnvPathFlagIndex, 1);
 }
 
 await import('../tools/cli.js');

package/src/providers/genius.js

@@ -1,5 +1,7 @@
 import axios from 'axios';
-import * as cheerio from 'cheerio';
+import { selectAll } from 'css-select';
+import * as DomUtils from 'domutils';
+import { parseDocument } from 'htmlparser2';
 
 import { normalizeLyricRecord } from '../provider-result-schema.js';
 import { assertEnv, getEnvValue } from '../utils/config.js';
@@ -119,7 +121,7 @@ export async function fetchFromGenius(track) {
   return primary;
 }
 
-function normalizeNodeText($node) {
+function normalizeNodeText(node) {
   const lines = [];
   const traverse = (node) => {
     if (!node) return;
@@ -145,7 +147,7 @@ function normalizeNodeText($node) {
     }
   };
 
-  traverse($node[0]);
+  traverse(node);
 
   return lines
     .join(' ')
@@ -155,18 +157,19 @@ function normalizeNodeText($node) {
     .trim();
 }
 
-function extractFromNodes(nodes, $) {
+function removeUnwantedNodes(node) {
+  const unwanted = selectAll(
+    'script,noscript,img,style,aside,.song_media_dropdown,.header_with_cover_art-primary_info',
+    node
+  );
+  unwanted.forEach((element) => DomUtils.removeElement(element));
+}
+
+function extractFromNodes(nodes) {
   const blocks = [];
   nodes.forEach((element) => {
-    const cleaned = $(element)
-      .clone()
-      .find(
-        'script,noscript,img,style,aside,.song_media_dropdown,.header_with_cover_art-primary_info'
-      )
-      .remove()
-      .end();
-
-    const text = normalizeNodeText(cleaned);
+    removeUnwantedNodes(element);
+    const text = normalizeNodeText(element);
     const stripped = stripSummaryText(text);
 
     if (stripped) {
@@ -224,15 +227,18 @@ export async function fetchLyricsForGeniusSong(url) {
       }
     });
 
-    const $ = cheerio.load(response.data);
-    let blocks = extractFromNodes($('div[data-lyrics-container="true"]').toArray(), $);
+    const document = parseDocument(response.data);
+    let blocks = extractFromNodes(selectAll('div[data-lyrics-container="true"]', document));
 
     if (!blocks.length) {
-      blocks = extractFromNodes($('div[class^="Lyrics__Container"]').toArray(), $);
+      blocks = extractFromNodes(selectAll('div[class^="Lyrics__Container"]', document));
     }
 
     if (!blocks.length) {
-      const fallback = $('.lyrics').text().trim();
+      const fallback = selectAll('.lyrics', document)
+        .map((node) => DomUtils.textContent(node))
+        .join('\n')
+        .trim();
       if (fallback) {
         blocks.push(fallback);
       }

package/src/providers/melon.js

@@ -1,5 +1,7 @@
 import axios from 'axios';
-import * as cheerio from 'cheerio';
+import { selectAll } from 'css-select';
+import * as DomUtils from 'domutils';
+import { parseDocument } from 'htmlparser2';
 
 import { normalizeLyricRecord, recomputeSyncFlags } from '../provider-result-schema.js';
 import { MELON_COOKIE, warnMissingEnv } from '../utils/config.js';
@@ -99,25 +101,30 @@ function extractSongId(value) {
 }
 
 function parseSearchPage(html) {
-  const $ = cheerio.load(html);
+  const document = parseDocument(html);
   const seenIds = new Set();
-  return $('#frm_defaultList > div > table > tbody > tr')
-    .map((_, row) => {
-      const $row = $(row);
-      const cells = $row.find('td');
-      const titleAnchor = cells.eq(2).find('a.fc_gray').first();
-      const artistAnchor = cells.eq(3).find('#artistName > a').first();
-      const albumAnchor = cells.eq(4).find('a').first();
-      const titleHref = titleAnchor.attr('href') || titleAnchor.attr('onclick') || '';
-      const artistHref = artistAnchor.attr('href') || artistAnchor.attr('onclick') || '';
+  return selectAll('#frm_defaultList > div > table > tbody > tr', document)
+    .map((row) => {
+      const cells = selectAll('td', row);
+      const titleAnchor = selectAll('a.fc_gray', cells[2] || [])[0];
+      const artistAnchor = selectAll('#artistName > a', cells[3] || [])[0];
+      const albumAnchor = selectAll('a', cells[4] || [])[0];
+      const titleHref =
+        DomUtils.getAttributeValue(titleAnchor, 'href') ||
+        DomUtils.getAttributeValue(titleAnchor, 'onclick') ||
+        '';
+      const artistHref =
+        DomUtils.getAttributeValue(artistAnchor, 'href') ||
+        DomUtils.getAttributeValue(artistAnchor, 'onclick') ||
+        '';
       let songId = extractSongId(titleHref) || extractSongId(artistHref);
-      if (!songId) songId = extractSongId($row.html() || '');
+      if (!songId) songId = extractSongId(DomUtils.getOuterHTML(row) || '');
       if (!songId || seenIds.has(songId)) {
         return null;
       }
-      const title = titleAnchor.text().trim().replace(/\s+/g, ' ');
-      const artist = artistAnchor.text().trim().replace(/\s+/g, ' ');
-      const album = albumAnchor.text().trim().replace(/\s+/g, ' ');
+      const title = DomUtils.textContent(titleAnchor).trim().replace(/\s+/g, ' ');
+      const artist = DomUtils.textContent(artistAnchor).trim().replace(/\s+/g, ' ');
+      const album = DomUtils.textContent(albumAnchor).trim().replace(/\s+/g, ' ');
       seenIds.add(songId);
       if (!title && !artist) return null;
       return { songId, title, artist, album };

package/src/tests/run-tests.js

@@ -456,31 +456,52 @@ function testCliExportCommandHelp() {
 function testCliEnvPathLoadsCustomEnvFile() {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mrmagic-cli-env-'));
   const envPath = path.join(tempDir, '.env.custom');
+  const configPath = path.join(tempDir, 'config.json');
   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'],
+      ['src/bin/cli.js', '--env-path', envPath, '--save-env-path', 'status'],
       {
         encoding: 'utf8',
         env: {
           PATH: process.env.PATH,
           NODE_ENV: process.env.NODE_ENV,
           LOG_LEVEL: 'error',
-          MR_MAGIC_QUIET_STDIO: '1'
+          MR_MAGIC_QUIET_STDIO: '1',
+          MR_MAGIC_CLI_CONFIG_PATH: configPath
         }
       }
     );
 
     assert.ok(output.includes('genius'));
     assert.ok(output.includes('Ready'), 'custom env file should make Genius status ready');
+
+    const saved = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    assert.equal(saved.envPath, envPath, '--save-env-path should persist the selected env file');
+
+    const persistedOutput = execFileSync(process.execPath, ['src/bin/cli.js', 'status'], {
+      encoding: 'utf8',
+      env: {
+        PATH: process.env.PATH,
+        NODE_ENV: process.env.NODE_ENV,
+        LOG_LEVEL: 'error',
+        MR_MAGIC_QUIET_STDIO: '1',
+        MR_MAGIC_CLI_CONFIG_PATH: configPath
+      }
+    });
+
+    assert.ok(
+      persistedOutput.includes('Ready'),
+      'CLI should reuse the persisted env path on later commands'
+    );
   } finally {
     fs.rmSync(tempDir, { recursive: true, force: true });
   }
 
   divider();
-  console.log('CLI --env-path loads custom env files: ok');
+  console.log('CLI --env-path loads and persists custom env files: ok');
 }
 
 async function run() {

package/src/tools/cli.js

@@ -109,7 +109,8 @@ program
   .description('Lyrics MCP server CLI powered by LRCLIB, Genius, Musixmatch, and Melon')
   .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');
+  .option('--env-file <path>', 'Alias for --env-path')
+  .option('--save-env-path', 'Persist --env-path for future CLI commands');
 
 function normalizeFormatOptions(value) {
   if (!value) return [];