mr-magic-mcp-server 0.3.3 → 0.3.5

package/package.json

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

package/src/core/find-service.js

@@ -1,4 +1,5 @@
 import { findLyrics, findSyncedLyrics, searchProvider, searchSources } from '../index.js';
+import { lyricContentScore } from '../provider-result-schema.js';
 
 export function normalizeTrack(track = {}) {
   if (!track || typeof track !== 'object') {
@@ -54,13 +55,46 @@ export function pickIndex(entries, index) {
   return entries[parsedIndex - 1].result;
 }
 
+/**
+ * Rank a chooser entry for auto-picking.
+ *
+ * Priority (highest first):
+ *  1. Has actual lyric content (score > 0) beats empty/unhydrated entries.
+ *  2. Synced beats plain when both have real content.
+ *  3. Richer content (more lyric lines) wins when both are non-empty.
+ *  4. Original list order is preserved as the final tie-breaker (lower index wins).
+ */
+function entryRankScore(entry, index) {
+  const result = entry?.result;
+  const content = lyricContentScore(result) * 10; // 0 or 5..10
+  const syncedBonus = result?.synced ? 0.5 : 0;
+  // Use a small negative index term so earlier list positions win ties
+  const positionPenalty = index * 0.0001;
+  return content + syncedBonus - positionPenalty;
+}
+
 export function autoPick(entries, preferSynced = true) {
   if (!entries.length) return null;
+
+  // Sort a shallow copy by rank, descending
+  const ranked = entries
+    .map((entry, idx) => ({ entry, rank: entryRankScore(entry, idx) }))
+    .sort((a, b) => b.rank - a.rank);
+
   if (preferSynced) {
-    const synced = entries.find((entry) => entry.result?.synced);
-    if (synced) {
-      return synced.result;
+    // Prefer synced among results that actually have content
+    const syncedWithContent = ranked.find(
+      ({ entry }) => entry.result?.synced && lyricContentScore(entry.result) > 0
+    );
+    if (syncedWithContent) {
+      return syncedWithContent.entry.result;
+    }
+    // Fall back to synced without content check (legacy behaviour preserved)
+    const anySynced = ranked.find(({ entry }) => entry.result?.synced);
+    if (anySynced) {
+      return anySynced.entry.result;
     }
   }
-  return entries[0].result;
+
+  return ranked[0].entry.result;
 }

package/src/index.js

@@ -7,6 +7,7 @@ import {
 } from './providers/musixmatch.js';
 import { fetchFromMelon, searchMelon } from './providers/melon.js';
 import { getEnvValue } from './utils/config.js';
+import { lyricContentScore } from './provider-result-schema.js';
 
 const providers = [
   { name: 'lrclib', fetch: fetchFromLrclib, search: searchLrclib },
@@ -19,10 +20,24 @@ const providerIndex = providers.reduce(
   new Map()
 );
 
+/**
+ * Score a candidate result for ranking.
+ *
+ * Priority order (highest wins):
+ *  1. Results with actual lyric content beat empty / unhydrated ones.
+ *     lyricContentScore returns 0 for empties, 0.5-1.0 for results that have text,
+ *     with a continuous richness bonus proportional to the line count.
+ *  2. Among results that both have lyric text, synced content beats plain.
+ *  3. Provider confidence score is a secondary tie-breaker.
+ *
+ * Multiplying lyricContentScore by 10 ensures it always dominates the confidence
+ * score (which lives in the 0-1 range) and the synced bonus (0.5).
+ */
 function rankRecord(record) {
-  const confidenceScore = record?.confidence ?? 0;
+  const contentScore = lyricContentScore(record) * 10; // 0 or 5..10
   const syncedBonus = record?.synced ? 0.5 : 0;
-  return confidenceScore + syncedBonus;
+  const confidenceScore = record?.confidence ?? 0;
+  return contentScore + syncedBonus + confidenceScore;
 }
 
 async function tryProviders(track, { syncedOnly = false, providerNames = [] } = {}) {
@@ -59,7 +74,11 @@ async function tryProviders(track, { syncedOnly = false, providerNames = [] } =
 export async function findLyrics(track, options = {}) {
   const { matches, best } = await tryProviders(track, options);
   return {
-    matches: matches.map(({ provider, result }) => ({ provider, result })),
+    // 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 })),
     best: best?.result ?? null
   };
 }
@@ -67,7 +86,9 @@ export async function findLyrics(track, options = {}) {
 export async function findSyncedLyrics(track, options = {}) {
   const { matches, best } = await tryProviders(track, { ...options, syncedOnly: true });
   return {
-    matches: matches.map(({ provider, result }) => ({ provider, result })),
+    matches: matches
+      .filter(({ result }) => lyricContentScore(result) > 0)
+      .map(({ provider, result }) => ({ provider, result })),
     best: best?.result ?? null
   };
 }

package/src/provider-result-schema.js

@@ -15,6 +15,47 @@ export function detectSyncedState(syncedLyrics) {
   return { hasSynced: timestampCount > 1, timestampCount };
 }
 
+/**
+ * Count non-empty lines in a lyric string, after stripping LRC timestamps.
+ * Used for ranking results by lyric richness.
+ */
+export function countLyricLines(text) {
+  if (!text || typeof text !== 'string') return 0;
+  return text
+    .split('\n')
+    .map((line) => line.replace(/^\[\d{1,2}:\d{2}[.:]\d{1,3}\]/, '').trim())
+    .filter(Boolean).length;
+}
+
+/**
+ * Returns a numeric "content score" for a lyric record:
+ *   - 0   → no lyric text at all (empty / unhydrated)
+ *   - 0.5 → has some lyric text (plain or synced)
+ *   - 0…1 continuous bonus added for richness (normalized line count, capped at 1)
+ *
+ * The function only inspects the actual lyric strings so that placeholder
+ * records that happen to have `plainLyrics: ""` still score 0.
+ */
+export function lyricContentScore(record) {
+  if (!record) return 0;
+
+  const plainText = typeof record.plainLyrics === 'string' ? record.plainLyrics.trim() : '';
+  const syncedText = typeof record.syncedLyrics === 'string' ? record.syncedLyrics.trim() : '';
+
+  const hasAny = Boolean(plainText || syncedText);
+  if (!hasAny) return 0;
+
+  // Base score for having any content
+  let score = 0.5;
+
+  // Richness bonus: cap at 200 lines → bonus up to 0.5
+  const lines = Math.max(countLyricLines(plainText), countLyricLines(syncedText));
+  const richnessBonus = Math.min(lines / 200, 0.5);
+  score += richnessBonus;
+
+  return score;
+}
+
 export function normalizeLyricRecord({
   provider,
   id,

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import '../utils/config.js';
+import { handleMcpTool } from '../transport/mcp-tools.js';
+
+const track = { artist: 'Dylan Cotrone', title: 'Cigarette' };
+
+// ── find_lyrics ──────────────────────────────────────────────────────────────
+console.log('=== find_lyrics ===');
+const findResult = await handleMcpTool('find_lyrics', { track });
+const matchSummary = (findResult.matches ?? []).map((m) => ({
+  provider: m.provider,
+  synced: Boolean(m.result?.synced),
+  hasPlain: Boolean(m.result?.plainLyrics?.trim()),
+  hasSynced: Boolean(m.result?.syncedLyrics?.trim()),
+  plainLines: (m.result?.plainLyrics || '').split('\n').filter(Boolean).length
+}));
+console.log(`matches (${matchSummary.length}):`);
+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) {
+  console.error('FAIL: find_lyrics returned empty-content matches:', emptyMatches);
+  process.exitCode = 1;
+} else {
+  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) ===');
+const searchResult = await handleMcpTool('search_lyrics', { track });
+for (const entry of searchResult) {
+  const withContent = entry.results.filter(
+    (r) => (r.plainLyrics || '').trim() || (r.syncedLyrics || '').trim()
+  ).length;
+  console.log(
+    `  ${entry.provider}: ${entry.results.length} results, ${withContent} already have lyric text`
+  );
+}
+console.log('NOTE: search_lyrics returns raw stubs intentionally — hydration is not applied here.');

package/src/tests/run-tests.js

@@ -3,7 +3,18 @@ import assert from 'node:assert/strict';
 
 import { selectMatch } from '../index.js';
 import { buildChooserEntries, autoPick } from '../core/find-service.js';
-import { normalizeLyricRecord, detectSyncedState } from '../provider-result-schema.js';
+import {
+  normalizeLyricRecord,
+  detectSyncedState,
+  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---');
@@ -88,11 +99,229 @@ function testNormalizationDetectsSyncedState() {
   console.log('normalize/detect synced state: ok');
 }
 
+function testLyricContentScoreEmpty() {
+  const empty = { plainLyrics: null, syncedLyrics: null };
+  assert.equal(lyricContentScore(empty), 0, 'empty record should score 0');
+  assert.equal(lyricContentScore(null), 0, 'null record should score 0');
+  const blankString = { plainLyrics: '   ', syncedLyrics: '' };
+  assert.equal(lyricContentScore(blankString), 0, 'whitespace-only record should score 0');
+  divider();
+  console.log('lyricContentScore empty records → 0: ok');
+}
+
+function testLyricContentScoreWithContent() {
+  const plain = { plainLyrics: 'line one\nline two\nline three', syncedLyrics: null };
+  const score = lyricContentScore(plain);
+  assert.ok(score > 0, 'record with plain lyrics should score > 0');
+  assert.ok(score >= 0.5, 'base score should be at least 0.5');
+  divider();
+  console.log('lyricContentScore with content > 0: ok');
+}
+
+function testLyricContentScoreRichness() {
+  const short = { plainLyrics: 'line one', syncedLyrics: null };
+  const longLines = Array.from({ length: 100 }, (_, i) => `line ${i}`).join('\n');
+  const long = { plainLyrics: longLines, syncedLyrics: null };
+  assert.ok(
+    lyricContentScore(long) > lyricContentScore(short),
+    'longer lyrics should score higher'
+  );
+  divider();
+  console.log('lyricContentScore richness (longer > shorter): ok');
+}
+
+function testCountLyricLines() {
+  assert.equal(countLyricLines(null), 0, 'null input → 0');
+  assert.equal(countLyricLines(''), 0, 'empty string → 0');
+  assert.equal(countLyricLines('line one\nline two\nline three'), 3, 'three lines');
+  // LRC timestamps should be stripped before counting
+  assert.equal(
+    countLyricLines('[00:01.00] first line\n[00:02.00] second line'),
+    2,
+    'LRC lines strip timestamps'
+  );
+  divider();
+  console.log('countLyricLines: ok');
+}
+
+function testAutoPickPrefersContentOverEmpty() {
+  // melon-like entry: found in search but lyrics not yet fetched (empty)
+  const emptyMelon = {
+    provider: 'melon',
+    result: {
+      provider: 'melon',
+      synced: false,
+      confidence: 0.5,
+      title: 'Song',
+      artist: 'Artist',
+      plainLyrics: null,
+      syncedLyrics: null
+    }
+  };
+  // genius-like entry: has actual plain lyrics
+  const geniusWithLyrics = {
+    provider: 'genius',
+    result: {
+      provider: 'genius',
+      synced: false,
+      confidence: 0.3,
+      title: 'Song',
+      artist: 'Artist',
+      plainLyrics: 'I, I was always a mean kid\nCouldnt hold my tongue',
+      syncedLyrics: null
+    }
+  };
+
+  // Melon comes first in the list (simulating provider priority order) but is empty
+  const chooser = buildChooserEntries([emptyMelon, geniusWithLyrics]);
+  const picked = autoPick(chooser, true);
+  assert.equal(
+    picked.provider,
+    'genius',
+    'content beats empty records even when empty provider is listed first'
+  );
+  divider();
+  console.log('autoPick: content beats empty (Melon-like empty loses to Genius with lyrics): ok');
+}
+
+function testAutoPickRicherContentWins() {
+  const shortLyrics = {
+    provider: 'providerA',
+    result: {
+      provider: 'providerA',
+      synced: false,
+      confidence: 0.9,
+      title: 'Song',
+      artist: 'Artist',
+      plainLyrics: 'one line',
+      syncedLyrics: null
+    }
+  };
+  const richLyrics = {
+    provider: 'providerB',
+    result: {
+      provider: 'providerB',
+      synced: false,
+      confidence: 0.1,
+      title: 'Song',
+      artist: 'Artist',
+      plainLyrics: Array.from({ length: 50 }, (_, i) => `line ${i}`).join('\n'),
+      syncedLyrics: null
+    }
+  };
+
+  // providerA has higher confidence but fewer lines; providerB has more content
+  const chooser = buildChooserEntries([shortLyrics, richLyrics]);
+  const picked = autoPick(chooser, false);
+  assert.equal(
+    picked.provider,
+    'providerB',
+    'richer lyric content wins even when confidence score is lower'
+  );
+  divider();
+  console.log('autoPick: richer content wins over higher-confidence sparse result: ok');
+}
+
+function testAutoPickSyncedWithContentBeatsSyncedEmpty() {
+  const syncedEmpty = {
+    provider: 'syncedEmpty',
+    result: {
+      provider: 'syncedEmpty',
+      synced: true,
+      confidence: 0.8,
+      title: 'Song',
+      artist: 'Artist',
+      plainLyrics: null,
+      syncedLyrics: null // synced flag set but no actual lyrics string
+    }
+  };
+  const syncedWithContent = {
+    provider: 'syncedFull',
+    result: {
+      provider: 'syncedFull',
+      synced: true,
+      confidence: 0.5,
+      title: 'Song',
+      artist: 'Artist',
+      plainLyrics: null,
+      syncedLyrics: '[00:00.00] real line\n[00:02.00] another line\n[00:04.00] more'
+    }
+  };
+
+  const chooser = buildChooserEntries([syncedEmpty, syncedWithContent]);
+  const picked = autoPick(chooser, true);
+  assert.equal(
+    picked.provider,
+    'syncedFull',
+    'synced result with actual lyrics beats synced result with no lyrics'
+  );
+  divider();
+  console.log('autoPick: synced+content beats synced+empty even with lower confidence: 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();
   testSelectMatchRespectsProviderAndSynced();
   testNormalizationDetectsSyncedState();
+  testLyricContentScoreEmpty();
+  testLyricContentScoreWithContent();
+  testLyricContentScoreRichness();
+  testCountLyricLines();
+  testAutoPickPrefersContentOverEmpty();
+  testAutoPickRicherContentWins();
+  testAutoPickSyncedWithContentBeatsSyncedEmpty();
+  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/tools/cli.js

@@ -22,6 +22,7 @@ import {
 import { exportLyrics, deriveFormatSet } from '../core/export.js';
 import { fetchFromMelon } from '../providers/melon.js';
 import { fetchFromGenius } from '../providers/genius.js';
+import { lyricContentScore } from '../provider-result-schema.js';
 
 async function hydrateSearchResult(provider, result, cache) {
   if (result.plainLyrics || result.syncedLyrics) {
@@ -389,20 +390,56 @@ program
       })
     );
 
-    let globalIndex = 1;
-    const table = enriched.flatMap((entry) =>
-      entry.results.map((result) => ({
-        index: globalIndex++,
-        provider: entry.provider,
-        synced: result.synced,
-        syncedRaw: result.synced,
-        title: result.title,
-        artist: result.artist,
-        plainPreview: extractPlainPreview(result),
-        syncedPreview: extractSyncedPreview(result),
-        rawResult: result
-      }))
-    );
+    // Build rows without final indices first so we can filter/sort before numbering.
+    // Filter out any result that has no lyric content at all (empty stubs from lazy providers
+    // like Melon or Genius that were not successfully hydrated should not appear in results).
+    const unsortedRows = enriched
+      .flatMap((entry) =>
+        entry.results.map((result) => ({
+          provider: entry.provider,
+          synced: result.synced,
+          syncedRaw: result.synced,
+          title: result.title,
+          artist: result.artist,
+          plainPreview: extractPlainPreview(result),
+          syncedPreview: extractSyncedPreview(result),
+          rawResult: result
+        }))
+      )
+      .filter((row) => lyricContentScore(row.rawResult) > 0);
+
+    /**
+     * Score how well a result matches the user's query (0–2).
+     *  +1.0 for title match (substring, case-insensitive)
+     *  +1.0 for artist match (substring, case-insensitive)
+     * This is the strongest factor so that relevant results always lead,
+     * even if an irrelevant result from the same search happens to have more lyric text.
+     */
+    function queryRelevance(row) {
+      const qTitle = (track.title || '').toLowerCase();
+      const qArtist = (track.artist || '').toLowerCase();
+      const rTitle = (row.title || '').toLowerCase();
+      const rArtist = (row.artist || '').toLowerCase();
+      let score = 0;
+      if (qTitle && (rTitle.includes(qTitle) || qTitle.includes(rTitle))) score += 1;
+      if (qArtist && (rArtist.includes(qArtist) || qArtist.includes(rArtist))) score += 1;
+      return score;
+    }
+
+    // Sort priority:
+    //  1. Relevance to query (weight ×100) — ensures on-target results always lead
+    //  2. Has actual lyric content (weight ×10) — content beats empty stubs
+    //  3. Synced bonus (0.5) + content richness — finer tie-breaking
+    // Stable JS sort preserves original provider order within equal-scoring rows.
+    unsortedRows.sort((a, b) => {
+      const relevanceA = queryRelevance(a) * 100;
+      const relevanceB = queryRelevance(b) * 100;
+      const contentA = lyricContentScore(a.rawResult) * 10 + (a.syncedRaw ? 0.5 : 0);
+      const contentB = lyricContentScore(b.rawResult) * 10 + (b.syncedRaw ? 0.5 : 0);
+      return relevanceB + contentB - (relevanceA + contentA);
+    });
+
+    const table = unsortedRows.map((row, idx) => ({ index: idx + 1, ...row }));
 
     if (table.length === 0) {
       console.log('No matches found');
@@ -594,7 +631,13 @@ program
         providerNames,
         syncedOnly: options.syncedOnly
       });
-      chooserEntries = buildChooserEntries(Array.isArray(result.matches) ? result.matches : []);
+      // Filter out matches with no lyric content before building the chooser so that
+      // empty provider stubs (e.g. Melon returning a shell record with no lyrics) don't
+      // appear as selectable options.
+      const contentMatches = (Array.isArray(result.matches) ? result.matches : []).filter(
+        (entry) => lyricContentScore(entry.result) > 0
+      );
+      chooserEntries = buildChooserEntries(contentMatches);
       totalResults = chooserEntries.length;
 
       if ((options.choose || options.index) && totalResults === 0) {

package/src/transport/mcp-tools.js

@@ -1,13 +1,15 @@
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 
 import { runFind, runSearch, runProviderSearch } from '../core/find-service.js';
+import { lyricContentScore } from '../provider-result-schema.js';
 import {
   buildActionContext,
   buildPayloadFromResult,
   buildCatalogPayload,
   exportBestResult,
   formatRecord,
-  catalogCache
+  catalogCache,
+  catalogCacheKey
 } from '../services/lyrics-service.js';
 import { pushCatalogToAirtable } from '../services/airtable-writer.js';
 import { getProviderStatus } from '../index.js';
@@ -170,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.',
@@ -201,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:
@@ -252,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.',
@@ -265,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.',
@@ -406,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') {
@@ -422,7 +445,12 @@ export async function handleMcpTool(name, args = {}) {
       return { error: 'No matches provided' };
     }
     const { provider, requireSynced, index } = args.criteria || {};
-    let filtered = matches;
+    // Strip entries with no actual lyric content (e.g. unhydrated search stubs)
+    // so the caller never accidentally selects an empty result.
+    let filtered = matches.filter((entry) => lyricContentScore(entry.result) > 0);
+    if (filtered.length === 0) {
+      return { error: 'No matches with lyric content found' };
+    }
     if (provider) {
       filtered = filtered.filter((entry) => entry.provider === provider);
     }