mr-magic-mcp-server 0.3.12 → 0.5.0

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:
@@ -1161,12 +1173,22 @@ 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.
+- `--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
 
 | 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 +1202,28 @@ 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!"
+
+# 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.3.12",
+  "version": "0.5.0",
   "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
   "type": "module",
   "main": "src/index.js",
@@ -61,14 +61,14 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.61.1",
+    "@dotenvx/dotenvx": "^1.65.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "axios": "^1.15.0",
+    "axios": "^1.16.0",
     "cheerio": "^1.2.0",
     "commander": "^14.0.3"
   },
   "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",
@@ -85,7 +85,8 @@
     "hasown": "npm:@socketregistry/hasown@^1",
     "object-assign": "npm:@socketregistry/object-assign@^1",
     "safer-buffer": "npm:@socketregistry/safer-buffer@^1",
-    "side-channel": "npm:@socketregistry/side-channel@^1"
+    "side-channel": "npm:@socketregistry/side-channel@^1",
+    "encoding-sniffer": "^1.0.2"
   },
   "resolutions": {
     "entities": "^7.0.1",
@@ -98,6 +99,7 @@
     "hasown": "npm:@socketregistry/hasown@^1",
     "object-assign": "npm:@socketregistry/object-assign@^1",
     "safer-buffer": "npm:@socketregistry/safer-buffer@^1",
-    "side-channel": "npm:@socketregistry/side-channel@^1"
+    "side-channel": "npm:@socketregistry/side-channel@^1",
+    "encoding-sniffer": "^1.0.2"
   }
 }

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

@@ -3,7 +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/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,75 @@ 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');
+  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, '--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_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 and persists custom env files: ok');
+}
+
 async function run() {
   testAutoPickPrefersSynced();
   testAutoPickFallbackWhenNoSynced();
@@ -447,6 +520,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,10 @@ 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')
+  .option('--save-env-path', 'Persist --env-path for future CLI commands');
 
 function normalizeFormatOptions(value) {
   if (!value) return [];
@@ -699,6 +702,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')