mr-magic-mcp-server 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-magic-mcp-server",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -43,7 +43,9 @@ function rankRecord(record) {
 async function tryProviders(track, { syncedOnly = false, providerNames = [] } = {}) {
   const matches = [];
   let bestSynced = null;
-  let bestOverall = null;
+  // Only track candidates that have actual lyric text — metadata-only stubs
+  // (e.g. Melon returning a record with plainLyrics: null) never become best.
+  let bestWithContent = null;
   const chosenProviders =
     providerNames.length > 0
       ? providers.filter((provider) => providerNames.includes(provider.name))
@@ -56,15 +58,23 @@ async function tryProviders(track, { syncedOnly = false, providerNames = [] } =
     const scored = { provider: provider.name, result: candidate, score: rankRecord(candidate) };
     matches.push(scored);
 
-    if (!bestOverall || scored.score > bestOverall.score) {
-      bestOverall = scored;
+    // Only promote as best when the candidate actually has lyric content.
+    if (lyricContentScore(candidate) > 0) {
+      if (!bestWithContent || scored.score > bestWithContent.score) {
+        bestWithContent = scored;
+      }
     }
-    if (candidate.synced && (!bestSynced || scored.score > bestSynced.score)) {
+    if (
+      candidate.synced &&
+      lyricContentScore(candidate) > 0 &&
+      (!bestSynced || scored.score > bestSynced.score)
+    ) {
       bestSynced = scored;
     }
   }
 
-  const best = syncedOnly ? (bestSynced ?? null) : (bestSynced ?? bestOverall ?? null);
+  // best is null when no provider returned actual lyric content for this track.
+  const best = syncedOnly ? (bestSynced ?? null) : (bestSynced ?? bestWithContent ?? null);
   return {
     matches,
     best

package/src/services/lyrics-service.js

@@ -114,6 +114,21 @@ export async function buildPayloadFromResult(result, context) {
     if (context.shouldExport) {
       payload.exports = await exportBestResult(result, context);
     }
+
+    // Populate the in-memory catalog cache so push_catalog_to_airtable can be
+    // used immediately after find_lyrics / find_synced_lyrics / export_lyrics —
+    // the agent does NOT have to call build_catalog_payload first.
+    const best = result.best;
+    const plainLyrics = payload.formatted?.plainLyrics || best.plainLyrics || '';
+    if (plainLyrics) {
+      const key = catalogCacheKey({ artist: best.artist, title: best.title });
+      catalogCache.set(key, {
+        plainLyrics,
+        romanizedPlainLyrics: payload.formatted?.romanizedPlain || null,
+        preferRomanized: context.includeRomanization
+      });
+      payload.lyricsCacheKey = key;
+    }
   }
   return payload;
 }

package/src/tests/mcp-search-find-verify.mjs

@@ -19,6 +19,7 @@ matchSummary.forEach((m) => console.log(' ', JSON.stringify(m)));
 console.log('best provider:', findResult.best?.provider ?? 'none');
 console.log('best hasPlain:', Boolean(findResult.best?.plainLyrics?.trim()));
 console.log('best hasSynced:', Boolean(findResult.best?.syncedLyrics?.trim()));
+console.log('lyricsCacheKey:', findResult.lyricsCacheKey ?? '(none)');
 
 const emptyMatches = matchSummary.filter((m) => !m.hasPlain && !m.hasSynced);
 if (emptyMatches.length > 0) {
@@ -28,6 +29,17 @@ if (emptyMatches.length > 0) {
   console.log('PASS: all matches have lyric content');
 }
 
+const hasBestLyrics =
+  Boolean(findResult.best?.plainLyrics?.trim()) || Boolean(findResult.best?.syncedLyrics?.trim());
+if (hasBestLyrics && !findResult.lyricsCacheKey) {
+  console.error('FAIL: find_lyrics resolved lyrics but did not return lyricsCacheKey');
+  process.exitCode = 1;
+} else if (hasBestLyrics) {
+  console.log('PASS: lyricsCacheKey present when lyrics resolved');
+} else {
+  console.log('NOTE: no lyrics resolved, lyricsCacheKey expected to be absent');
+}
+
 // ── search_lyrics ─────────────────────────────────────────────────────────────
 console.log('');
 console.log('=== search_lyrics (raw catalog stubs — no hydration by design) ===');

package/src/tests/run-tests.js

@@ -9,6 +9,12 @@ import {
   lyricContentScore,
   countLyricLines
 } from '../provider-result-schema.js';
+import {
+  buildPayloadFromResult,
+  buildActionContext,
+  catalogCacheKey,
+  catalogCache
+} from '../services/lyrics-service.js';
 import { mcpToolDefinitions, handleMcpTool } from '../transport/mcp-tools.js';
 
 const divider = () => console.log('\n---');
@@ -253,6 +259,100 @@ function testAutoPickSyncedWithContentBeatsSyncedEmpty() {
   console.log('autoPick: synced+content beats synced+empty even with lower confidence: ok');
 }
 
+function testEmptyRecordNeverBecomesBest() {
+  // Simulate the tryProviders bestWithContent guard directly.
+  // When all candidates are metadata-only (no lyric text), bestWithContent must stay null.
+  const emptyRecords = [
+    { plainLyrics: null, syncedLyrics: null, synced: false, confidence: 0.5 }, // Melon stub
+    { plainLyrics: '', syncedLyrics: null, synced: false, confidence: 0.3 } // empty string
+  ];
+  let bestWithContent = null;
+  for (const candidate of emptyRecords) {
+    if (lyricContentScore(candidate) > 0) {
+      bestWithContent = candidate;
+    }
+  }
+  assert.ok(
+    bestWithContent === null,
+    'metadata-only records must not be promoted as best — bestWithContent should remain null'
+  );
+
+  // Contrast: a record with actual text IS selected
+  const withLyrics = { plainLyrics: 'line one\nline two', syncedLyrics: null, confidence: 0.1 };
+  let bestWithContentFromMixed = null;
+  for (const candidate of [...emptyRecords, withLyrics]) {
+    if (lyricContentScore(candidate) > 0) {
+      bestWithContentFromMixed = candidate;
+    }
+  }
+  assert.ok(
+    bestWithContentFromMixed === withLyrics,
+    'when a content-bearing record is present, it should be promoted over empty ones'
+  );
+
+  divider();
+  console.log('empty records never become best — content guard works: ok');
+}
+
+async function testBuildPayloadFromResultReturnsCacheKey() {
+  // build a minimal find result with plain lyrics — no network call needed
+  const best = {
+    provider: 'genius',
+    title: 'Cigarette',
+    artist: 'Dylan Cotrone',
+    plainLyrics: 'I was always a mean kid\nCould not hold my tongue',
+    syncedLyrics: null,
+    synced: false
+  };
+  const result = { matches: [{ provider: 'genius', result: best }], best };
+  const context = buildActionContext({});
+  const payload = await buildPayloadFromResult(result, context);
+
+  assert.ok(
+    payload.lyricsCacheKey,
+    'buildPayloadFromResult should include lyricsCacheKey when best has plain lyrics'
+  );
+  assert.equal(typeof payload.lyricsCacheKey, 'string', 'lyricsCacheKey should be a string');
+
+  // Verify the cache was actually populated
+  const cached = catalogCache.get(payload.lyricsCacheKey);
+  assert.ok(cached, 'catalog cache should have an entry for the returned key');
+  assert.ok(cached.plainLyrics, 'cached entry should include plain lyrics');
+
+  // Verify key stability — same artist/title always yields the same key
+  const expectedKey = catalogCacheKey({ artist: 'Dylan Cotrone', title: 'Cigarette' });
+  assert.equal(
+    payload.lyricsCacheKey,
+    expectedKey,
+    'lyricsCacheKey should match catalogCacheKey for the track'
+  );
+
+  divider();
+  console.log('buildPayloadFromResult returns lyricsCacheKey and populates cache: ok');
+}
+
+async function testBuildPayloadFromResultNoCacheKeyWhenNoLyrics() {
+  const best = {
+    provider: 'melon',
+    title: 'Cigarette',
+    artist: 'Dylan Cotrone',
+    plainLyrics: null,
+    syncedLyrics: null,
+    synced: false
+  };
+  const result = { matches: [], best };
+  const context = buildActionContext({});
+  const payload = await buildPayloadFromResult(result, context);
+
+  assert.ok(
+    !payload.lyricsCacheKey,
+    'buildPayloadFromResult should NOT include lyricsCacheKey when best has no lyrics'
+  );
+
+  divider();
+  console.log('buildPayloadFromResult omits lyricsCacheKey when best has no lyrics: ok');
+}
+
 async function run() {
   testAutoPickPrefersSynced();
   testAutoPickFallbackWhenNoSynced();
@@ -265,6 +365,9 @@ async function run() {
   testAutoPickPrefersContentOverEmpty();
   testAutoPickRicherContentWins();
   testAutoPickSyncedWithContentBeatsSyncedEmpty();
+  testEmptyRecordNeverBecomesBest();
+  await testBuildPayloadFromResultReturnsCacheKey();
+  await testBuildPayloadFromResultNoCacheKeyWhenNoLyrics();
   const toolNames = mcpToolDefinitions.map((tool) => tool.name);
   console.log('MCP tooling available:', toolNames.join(', '));
   console.log('All sanity checks passed');

package/src/transport/mcp-tools.js

@@ -8,7 +8,8 @@ import {
   buildCatalogPayload,
   exportBestResult,
   formatRecord,
-  catalogCache
+  catalogCache,
+  catalogCacheKey
 } from '../services/lyrics-service.js';
 import { pushCatalogToAirtable } from '../services/airtable-writer.js';
 import { getProviderStatus } from '../index.js';
@@ -171,7 +172,10 @@ const matchSchema = {
 export const mcpToolDefinitions = [
   {
     name: 'find_lyrics',
-    description: 'Find the best lyric match across providers (prefers synced when available).',
+    description:
+      'Find the best lyric match across providers (prefers synced when available). ' +
+      'Returns lyricsCacheKey when lyrics are resolved — pass this to push_catalog_to_airtable ' +
+      'without calling build_catalog_payload first.',
     inputSchema: {
       type: 'object',
       description: 'Provide a track description (and optional hints) to look up lyrics.',
@@ -202,7 +206,9 @@ export const mcpToolDefinitions = [
   },
   {
     name: 'find_synced_lyrics',
-    description: 'Find lyrics but reject any candidates that lack timestamps.',
+    description:
+      'Find lyrics but reject any candidates that lack timestamps. ' +
+      'Returns lyricsCacheKey when synced lyrics are resolved.',
     inputSchema: {
       type: 'object',
       description:
@@ -253,7 +259,9 @@ export const mcpToolDefinitions = [
   },
   {
     name: 'export_lyrics',
-    description: 'Find lyrics and save plain/LRC/SRT plus romanized variants to disk.',
+    description:
+      'Find lyrics and save plain/LRC/SRT plus romanized variants to disk. ' +
+      'Also returns lyricsCacheKey so push_catalog_to_airtable can be called immediately.',
     inputSchema: {
       type: 'object',
       description: 'Provide the track and export options to write files to disk.',
@@ -266,7 +274,9 @@ export const mcpToolDefinitions = [
   },
   {
     name: 'format_lyrics',
-    description: 'Find lyrics and return formatted text (with optional romanization) in-memory.',
+    description:
+      'Find lyrics and return formatted text (with optional romanization) in-memory. ' +
+      'Also returns lyricsCacheKey so push_catalog_to_airtable can be called immediately.',
     inputSchema: {
       type: 'object',
       description: 'Provide the track and formatting options for in-memory rendering.',
@@ -407,7 +417,19 @@ export async function handleMcpTool(name, args = {}) {
       includeRomanization: !options?.noRomanize,
       includeSynced: options?.includeSynced ?? true
     });
-    return { formatted, best };
+    // Populate the catalog cache so push_catalog_to_airtable can be used
+    // immediately without a separate build_catalog_payload call.
+    let lyricsCacheKey = null;
+    const plainLyrics = formatted.plainLyrics || best.plainLyrics || '';
+    if (plainLyrics) {
+      lyricsCacheKey = catalogCacheKey({ artist: best.artist, title: best.title });
+      catalogCache.set(lyricsCacheKey, {
+        plainLyrics,
+        romanizedPlainLyrics: formatted.romanizedPlain || null,
+        preferRomanized: !options?.noRomanize
+      });
+    }
+    return { formatted, best, lyricsCacheKey };
   }
 
   if (name === 'build_catalog_payload') {