mr-magic-mcp-server 0.1.5

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "mr-magic-mcp-server",
+  "version": "0.1.5",
+  "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "mrmagic-cli": "src/bin/cli.js",
+    "http-server": "src/bin/http-server.js",
+    "mcp-server": "src/bin/mcp-server.js",
+    "mcp-http-server": "src/bin/mcp-http-server.js"
+  },
+  "files": [
+    "src",
+    "prompts",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "cli": "node src/bin/cli.js",
+    "server:http": "node src/bin/http-server.js",
+    "server:mcp": "node src/bin/mcp-server.js",
+    "server:mcp:http": "node src/bin/mcp-http-server.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "node tests/run-tests.js",
+    "fetch:musixmatch-token": "node scripts/fetch_musixmatch_token.mjs",
+    "fetch:genius-token": "node scripts/fetch_genius_token.mjs",
+    "repro:mcp:arg-boundary": "node scripts/mcp-arg-boundary-repro.mjs",
+    "repro:mcp:arg-boundary:sdk": "node scripts/mcp-arg-boundary-sdk-repro.mjs",
+    "prepack": "npm run test"
+  },
+  "keywords": [
+    "lyrics",
+    "mcp",
+    "lrclib",
+    "genius",
+    "musixmatch",
+    "melon"
+  ],
+  "author": "Kenyatta Naji Johnson-Adams",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrnajiboy/mr-magic-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mrnajiboy/mr-magic-mcp-server/issues"
+  },
+  "homepage": "https://github.com/mrnajiboy/mr-magic-mcp-server#readme",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "axios": "^1.7.2",
+    "cheerio": "^1.0.0-rc.12",
+    "commander": "^10.0.0",
+    "dotenv": "^16.4.0",
+    "hangul-js": "^0.2.6"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "playwright-chromium": "^1.58.2",
+    "prettier": "^3.8.1"
+  }
+}

package/prompts/airtable-song-importer.md

@@ -0,0 +1,239 @@
+You are an Airtable Song Importing Assistant. You are helping the user add songs to an Airtable catalog.
+
+The user will provide:
+
+- a list of songs
+- and either a base name or base ID, if available
+
+If you are not sure you have all required information, ask the user before proceeding.
+
+For each batch of songs in the user's list, follow this workflow.
+
+## 1) Resolve Airtable destination
+
+Use Airtable tools to determine the correct:
+
+- base ID
+- table ID
+- target field IDs or field names
+
+Always verify field IDs against field names before inserting or updating records.
+
+## 2) Required Airtable fields
+
+For every song, populate only these Airtable fields:
+
+- Song (Video)
+- Listen Link
+- Lyrics
+
+Never send extra metadata or unused fields to Airtable.
+
+## 3) Song (Video) formatting rules
+
+`Song (Video)` must always be formatted exactly as:
+`{Artist 1}, {Artist 2} - {Title} (Lyrics)`
+
+Examples:
+
+- `BLACKPINK, Doja Cat, Absolutely - Crazy (Lyrics)`
+- `Joji - Glimpse of Us (Lyrics)`
+- `[GANG$] - Money (Remix) (Lyrics)`
+
+Artist names may contain brackets or special characters. Preserve them exactly.
+
+## 4) Listen Link rules
+
+Use the Spotify song lookup tool.
+Use the `URL` value for the Airtable `Listen Link` field.
+Spotify link resolution must always be handled separately from lyric resolution.
+
+## 5) Lyrics resolution rules
+
+Use the `build_catalog_payload` tool to resolve lyrics for each song.
+
+Call it with:
+
+- `preferRomanized: true`
+
+The response will include:
+
+- `lyricsCacheKey` — a short slug identifying the cached lyrics server-side
+- `songVideoTitle` — use this to cross-check the `Song (Video)` field formatting
+
+Do **not** copy any lyric text out of `build_catalog_payload`. The full lyrics are handled server-side by `push_catalog_to_airtable`. Never relay lyrics text through tool-call arguments.
+
+### Lyric priority (handled automatically by push_catalog_to_airtable)
+
+1. Romanized plain lyrics, if available (default when `preferRomanized: true`)
+2. Otherwise plain lyrics
+
+## 6) Airtable record write rules
+
+Use Airtable MCP tools (`create_records_for_table` / `update_records_for_table`) for **Song (Video)** and **Listen Link** fields. These tools support bulk writes of up to 10 records per call — use that fully.
+
+**STRICTLY FORBIDDEN:** Never use `create_records_for_table` or `update_records_for_table` to write or update the `Lyrics` field. Those tools cannot handle long multiline lyric text without JSON truncation errors.
+
+**Always use `push_catalog_to_airtable` to write the Lyrics field.** This tool makes the Airtable API call server-side — lyrics are fetched from the internal cache and the lyric text never passes through your tool-call arguments.
+
+### How to call push_catalog_to_airtable
+
+Pass:
+
+- `baseId` — from Airtable MCP `search_bases` result
+- `tableId` — from Airtable MCP `list_tables_for_base` result
+- `recordId` — the record ID returned from the create step (required to update the Lyrics field)
+- `fields` — pass an **empty object `{}`** (no non-lyrics fields; those were already written in the create step)
+- `lyricsFieldId` — the field ID for the Lyrics field
+- `lyricsCacheKey` — the value returned by `build_catalog_payload`
+- `preferRomanized: true`
+
+Do NOT include the lyrics text itself in `fields`. Do NOT include `lyricsFieldId` in `fields`.
+
+### Example push_catalog_to_airtable call shape (lyrics-only update)
+
+```json
+{
+  "baseId": "appeBUkVEp3N4RT0C",
+  "tableId": "tbl0y5XHFXpjUJXHu",
+  "recordId": "rec1234567890abcd",
+  "fields": {},
+  "lyricsFieldId": "fldHV1qmPYmsvglff",
+  "lyricsCacheKey": "kda-feat-twice-bekuh-boom-annika-wells-league-of-legends-ill-show-you",
+  "preferRomanized": true
+}
+```
+
+### If push_catalog_to_airtable fails
+
+If the lyrics write fails, retry with `splitLyricsUpdate: true`. This updates the Lyrics field in a separate second call — entirely server-side.
+
+## 7) Bulk execution order
+
+Process all songs in the user's list together as a batch, not one at a time.
+
+### Phase 1 — Resolve all data in parallel
+
+For every song in the batch (up to all at once):
+
+1. Resolve Airtable destination info (`search_bases`, `list_tables_for_base`) — do this once per base/table, not per song.
+2. Resolve Spotify link (`search-spotify`) for each song.
+3. Resolve lyrics (`build_catalog_payload` with `preferRomanized: true`) for each song. Save each song's `lyricsCacheKey`.
+
+### Phase 2 — Bulk create/update records (Song (Video) + Listen Link only)
+
+Use `create_records_for_table` (or `update_records_for_table` if updating existing records) to write **Song (Video)** and **Listen Link** for all songs in the batch.
+
+- Send up to **10 records per call**.
+- If the batch has more than 10 songs, split into multiple calls of up to 10 each.
+- Capture the `recordId` returned for each newly created record — you will need these in Phase 3.
+
+Example batch create body (Song (Video) + Listen Link only — no Lyrics):
+
+```json
+{
+  "records": [
+    {
+      "fields": {
+        "fldM1p1Ou01SQlDrN": "K/DA - POP/STARS (Lyrics)",
+        "fld0NIKYPaokLjj1G": "https://open.spotify.com/track/497qmwcUsCv5hmMU0K8Hik"
+      }
+    },
+    {
+      "fields": {
+        "fldM1p1Ou01SQlDrN": "Joji - Glimpse of Us (Lyrics)",
+        "fld0NIKYPaokLjj1G": "https://open.spotify.com/track/1BxfuPKGuaTgP7aM0Bbdwr"
+      }
+    }
+  ]
+}
+```
+
+### Phase 3 — Write lyrics for each record via push_catalog_to_airtable
+
+For each record created in Phase 2, call `push_catalog_to_airtable` with:
+
+- The `recordId` from Phase 2
+- `fields: {}` (non-lyrics fields already written)
+- `lyricsFieldId` for the Lyrics field
+- `lyricsCacheKey` from Phase 1 for that song
+- `preferRomanized: true`
+
+**One `push_catalog_to_airtable` call per song** (lyrics are per-track, not batchable).
+
+### Phase 4 — SRT export
+
+After all Airtable inserts and lyrics writes succeed:
+
+- Export `.SRT` lyrics using the `export_lyrics` tool for each song.
+- Confirm the user has received at least one of the following:
+  - SRT download link
+  - SRT file path
+  - export folder location
+  - inline SRT content as fallback
+
+## 8) Required export step after Airtable succeeds
+
+After all Airtable inserts succeed, the agent must export synced lyrics as `.SRT`.
+This export step is required and must be handled separately from Airtable insertion.
+
+### Export priority
+
+For SRT export, use this priority order:
+
+1. romanized synced lyrics, if available
+2. otherwise synced lyrics
+
+### Export delivery requirement
+
+The agent must make sure the user receives at least one of the following:
+
+- an SRT download link
+- an exported SRT file path
+- an exported folder location containing the SRT file
+
+If file export succeeds, report exactly where the SRT can be retrieved.
+At minimum, provide one of:
+
+- `exports.srt.url`
+- `exports.srt.filePath`
+- the output folder path used for export
+
+If the export backend does not provide a downloadable file or writable folder, the agent must still complete the export step and then provide the inline SRT content returned by the tool.
+
+### Export tool rules
+
+Use the `export_lyrics` tool to export `.SRT` output after Airtable insertion is complete.
+Prefer synced romanized output when available; otherwise use synced lyrics.
+Do not confuse Airtable lyric insertion with export output:
+
+- Airtable `Lyrics` must contain only plain-text lyrics (handled server-side)
+- export output may be synced `.SRT`
+
+If the tool returns a URL, present that URL clearly.
+If the tool returns a file path, present that file path clearly.
+If the tool returns inline content because persistence was skipped or failed, provide the SRT content in the conversation and clearly explain that no downloadable file/link was available.
+
+## 9) Progress reporting rules
+
+When reporting progress:
+
+- show how many songs are being processed in the current batch
+- confirm each Airtable bulk create/update result (report record IDs created)
+- confirm each lyrics write separately (report `success`, `recordId`, `lyricsWritten` from `push_catalog_to_airtable`)
+- clearly separate Airtable insertion phases from SRT export
+- if a fallback or retry was required, state exactly which step failed and what workaround was used
+
+## 10) Tool responsibility summary
+
+| Step                                 | Tool (MCP Server)                                                          | Bulk?                 |
+| ------------------------------------ | -------------------------------------------------------------------------- | --------------------- |
+| Find base/table                      | `search_bases`, `list_tables_for_base` (Airtable MCP)                      | Once per base         |
+| Spotify link                         | `search-spotify` (Spotify MCP)                                             | Per song              |
+| Lyrics resolution                    | `build_catalog_payload` (mr-magic)                                         | Per song              |
+| **Song (Video) + Listen Link write** | **`create_records_for_table` / `update_records_for_table` (Airtable MCP)** | **Up to 10 per call** |
+| **Lyrics write**                     | **`push_catalog_to_airtable` (mr-magic) — always**                         | Per song              |
+| SRT export                           | `export_lyrics` (mr-magic)                                                 | Per song              |
+
+**Never use `create_records_for_table` or `update_records_for_table` for the Lyrics field.**
+Always use `push_catalog_to_airtable` for Lyrics — no exceptions.

package/src/bin/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+// 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.
+if (!process.env.LOG_LEVEL) process.env.LOG_LEVEL = 'warn';
+if (!process.env.MR_MAGIC_QUIET_STDIO) process.env.MR_MAGIC_QUIET_STDIO = '1';
+
+await import('../tools/cli.js');

package/src/bin/http-server.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startHttpServer } from '../transport/http-server.js';
+
+startHttpServer().catch((error) => {
+  console.error('Failed to start HTTP server', error);
+  process.exit(1);
+});

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

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startMcpHttpServer } from '../transport/mcp-http-server.js';
+
+startMcpHttpServer().catch((error) => {
+  console.error('Failed to start MCP HTTP server', error);
+  process.exit(1);
+});

package/src/bin/mcp-server.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+if (!process.env.MR_MAGIC_QUIET_STDIO) {
+  process.env.MR_MAGIC_QUIET_STDIO = '1';
+}
+const { startMcpServer } = await import('../transport/mcp-server.js');
+await startMcpServer();

package/src/core/export.js

@@ -0,0 +1,83 @@
+import {
+  buildLrc,
+  buildSrt,
+  formatPlainStanzas,
+  romanizePlainLyrics,
+  romanizeSyncedLyrics,
+  romanizeSrtLyrics,
+  containsHangul
+} from '../utils/lyrics-format.js';
+import { slugify } from '../utils/slugify.js';
+import { createStorageCache } from '../utils/storage-cache.js';
+
+const getStorage = createStorageCache(`${process.env.MR_MAGIC_EXPORT_BACKEND || 'local'}:`);
+
+async function storeExport(outputDir, baseName, extension, contents) {
+  if (!contents) return null;
+  const safe = slugify(baseName || 'lyrics', 'lyrics');
+  const storage = await getStorage(outputDir);
+  return storage.store({ content: contents, extension, baseName: safe });
+}
+
+export async function exportLyrics(record, options) {
+  const exports = {};
+  if (!record.plainLyrics) {
+    return exports;
+  }
+  const baseName = `${record.artist || 'unknown'}-${record.title || 'song'}`;
+  if (options.formats.includes('plain')) {
+    exports.plain = await storeExport(
+      options.output,
+      baseName,
+      'txt',
+      formatPlainStanzas(record.plainLyrics)
+    );
+  }
+  if (options.formats.includes('lrc')) {
+    exports.lrc = await storeExport(options.output, baseName, 'lrc', buildLrc(record.syncedLyrics));
+  }
+  if (options.formats.includes('srt')) {
+    exports.srt = await storeExport(options.output, baseName, 'srt', buildSrt(record.syncedLyrics));
+  }
+  if (options.includeRomanization !== false) {
+    const hasHangulPlain = containsHangul(record.plainLyrics);
+    const hasHangulSynced = record.syncedLyrics && containsHangul(record.syncedLyrics);
+
+    if (hasHangulPlain && options.formats.includes('plain')) {
+      exports.romanizedPlain = await storeExport(
+        options.output,
+        baseName,
+        'romanized.txt',
+        romanizePlainLyrics(record.plainLyrics, { formatted: true })
+      );
+    }
+
+    if (hasHangulSynced && options.formats.includes('lrc')) {
+      exports.romanizedLrc = await storeExport(
+        options.output,
+        baseName,
+        'romanized.lrc',
+        romanizeSyncedLyrics(record.syncedLyrics)
+      );
+    }
+
+    if (hasHangulSynced && options.formats.includes('srt')) {
+      exports.romanizedSrt = await storeExport(
+        options.output,
+        baseName,
+        'romanized.srt',
+        romanizeSrtLyrics(record.syncedLyrics)
+      );
+    }
+  }
+  return exports;
+}
+
+export function deriveFormatSet(requestedFormats, defaultFormats = ['plain', 'srt']) {
+  const base = ['plain', 'lrc', 'srt'];
+  if (requestedFormats && requestedFormats.length > 0) {
+    const normalized = requestedFormats.map((format) => format?.toLowerCase()).filter(Boolean);
+    return Array.from(new Set(normalized.filter((format) => base.includes(format))));
+  }
+  return [...defaultFormats];
+}

package/src/core/find-service.js

@@ -0,0 +1,66 @@
+import { findLyrics, findSyncedLyrics, searchProvider, searchSources } from '../index.js';
+
+export function normalizeTrack(track = {}) {
+  if (!track || typeof track !== 'object') {
+    return { title: '', artist: '', album: null, duration: null };
+  }
+  return {
+    title: track.title?.trim() || '',
+    artist: track.artist?.trim() || '',
+    album: track.album?.trim() || null,
+    duration:
+      typeof track.duration === 'number'
+        ? track.duration
+        : Number.isFinite(Number(track.duration))
+          ? Number(track.duration)
+          : null
+  };
+}
+
+export async function runFind(track, options = {}) {
+  const providerNames = options.providerNames || [];
+  const finder = options.syncedOnly ? findSyncedLyrics : findLyrics;
+  const normalizedTrack = normalizeTrack(track);
+  const result = await finder(normalizedTrack, {
+    providerNames,
+    syncedOnly: options.syncedOnly
+  });
+  return result;
+}
+
+export async function runSearch(track) {
+  return searchSources(normalizeTrack(track));
+}
+
+export async function runProviderSearch(providerName, track) {
+  return searchProvider(providerName, normalizeTrack(track));
+}
+
+export function buildChooserEntries(matches) {
+  return matches.map((entry, idx) => ({
+    index: idx + 1,
+    provider: entry.provider,
+    result: entry.result
+  }));
+}
+
+export function pickIndex(entries, index) {
+  if (!entries.length) return null;
+  if (!index) return entries[0].result;
+  const parsedIndex = Number(index);
+  if (!Number.isInteger(parsedIndex) || parsedIndex < 1 || parsedIndex > entries.length) {
+    throw new Error(`Invalid index. Provide an integer between 1 and ${entries.length}.`);
+  }
+  return entries[parsedIndex - 1].result;
+}
+
+export function autoPick(entries, preferSynced = true) {
+  if (!entries.length) return null;
+  if (preferSynced) {
+    const synced = entries.find((entry) => entry.result?.synced);
+    if (synced) {
+      return synced.result;
+    }
+  }
+  return entries[0].result;
+}

package/src/core/formatting.js

@@ -0,0 +1,39 @@
+import {
+  formatPlainStanzas,
+  romanizePlainLyrics,
+  romanizeSyncedLyrics,
+  romanizeSrtLyrics,
+  containsHangul
+} from '../utils/lyrics-format.js';
+
+export function formatRecord(record, options = {}) {
+  const includeRomanization = options.includeRomanization !== false;
+  const includeSynced = options.includeSynced !== false;
+  const plain = formatPlainStanzas(record.plainLyrics);
+
+  const response = {
+    provider: record.provider,
+    title: record.title,
+    artist: record.artist,
+    album: record.album,
+    sourceUrl: record.sourceUrl,
+    synced: record.synced,
+    confidence: record.confidence,
+    plainLyrics: plain
+  };
+
+  if (includeRomanization && containsHangul(record.plainLyrics)) {
+    response.romanizedPlain = romanizePlainLyrics(record.plainLyrics, { formatted: true });
+  }
+
+  if (includeRomanization && record.syncedLyrics && containsHangul(record.syncedLyrics)) {
+    response.romanizedLrc = romanizeSyncedLyrics(record.syncedLyrics);
+    response.romanizedSrt = romanizeSrtLyrics(record.syncedLyrics);
+  }
+
+  if (includeSynced && record.syncedLyrics) {
+    response.syncedLyrics = record.syncedLyrics;
+  }
+
+  return response;
+}

package/src/core/preview.js

@@ -0,0 +1,54 @@
+const PREVIEW_MAX_LENGTH = 140;
+
+function truncatePreview(text) {
+  if (!text) return '';
+  if (text.length <= PREVIEW_MAX_LENGTH) {
+    return text;
+  }
+  return `${text.slice(0, PREVIEW_MAX_LENGTH - 1)}…`;
+}
+
+export function extractPlainPreview(record) {
+  if (!record?.plainLyrics) return '';
+  const lines = record.plainLyrics.split('\n').map((entry) => entry && entry.trim());
+  const primary = lines.find(
+    (entry) =>
+      entry &&
+      !entry.toLowerCase().includes('lyrics”') &&
+      !entry.toLowerCase().startsWith('read more') &&
+      !entry.toLowerCase().startsWith('[verse') &&
+      !entry.toLowerCase().startsWith('[hook') &&
+      !entry.toLowerCase().startsWith('[chorus')
+  );
+  const fallback = lines.find((entry) => entry);
+  return truncatePreview(primary || fallback || '');
+}
+
+export function extractSyncedPreview(record) {
+  if (!record?.syncedLyrics || !record?.synced) return '';
+
+  const lines = record.syncedLyrics
+    .split('\n')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .filter(
+      (entry) => !entry.startsWith('[ar:') && !entry.startsWith('[ti:') && !entry.startsWith('[by:')
+    );
+
+  const preview = [];
+  for (const rawLine of lines) {
+    const timestampMatches = rawLine.match(/(\[[0-9.:]+\])/g);
+    if (!timestampMatches) continue;
+
+    const text = rawLine.replace(/(\[[0-9.:]+\])/g, '').trim();
+    const timestamps = timestampMatches.slice(0, 2);
+    timestamps.forEach((timestamp) => {
+      if (preview.length < 2) {
+        preview.push(text ? `${timestamp} ${text}` : timestamp);
+      }
+    });
+    if (preview.length >= 2) break;
+  }
+
+  return truncatePreview(preview.join(' | '));
+}