mr-magic-mcp-server 0.3.9 → 0.3.11

package/prompts/airtable-song-importer.md

@@ -9,11 +9,13 @@ The user will provide:
 
 If you are not sure you have all required information, ask the user before proceeding.
 
+Once the user has provided enough initial information to identify the Airtable destination and process the requested songs, continue through the main run autonomously. Do **not** stop between passes to ask the user for permission, confirmation, or manual intervention unless a required dependency is missing or a hard failure blocks progress.
+
 For each batch of songs in the user's list, follow this workflow.
 
 ## 1) Resolve Airtable destination
 
-Use Airtable tools to determine the correct:
+Use your Airtable tools to determine the correct:
 
 - base ID
 - table ID
@@ -22,6 +24,11 @@ Use Airtable tools to determine the correct:
 
 Always verify field IDs against field names before inserting or updating records.
 
+Recommended tools for finding base IDs and table IDs:
+search_bases
+list_bases
+list_tables_for_base
+
 ## 2) Required Airtable fields
 
 For every song, populate only these Airtable fields:
@@ -39,14 +46,15 @@ Never send extra metadata or unused fields to Airtable.
 `Song (Video)` must always be formatted exactly as:
 `{Artist 1}, {Artist 2} - {Title} (Lyrics)`
 
-If the song title has featuring, ft., feat. or remix, or any other similar differentiation, put it at the right before (Lyrics) in Parentheses.
+If the song title has featuring, ft., feat, take that out.
+If the song has remix, or any other differentiation, put it at the right before (Lyrics) in Parentheses.
 
 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.
 
@@ -59,28 +67,52 @@ Artist names may contain brackets or special characters. Preserve them exactly.
 
 ## 5) Listen Link rules
 
-- Use the Spotify song lookup tool.
+- You may only use your Spotify song lookup tool from `s4168377_get_spotify_song` (Make.com) or `search-spotify` (Spotify MCP) to find the links to fill in the entries.
+- Do NOT try to search for links via `search_provider` or `search_lyrics`; those are lyrics-search tools only.
+- `search_provider` / `search_lyrics` return preview-only lyric candidates plus reusable `reference` objects. They do **not** return Spotify links, full lyrics, or raw provider payloads.
 - Use the `URL` value for the Airtable `Listen Link` field.
 - Spotify link resolution must always be handled separately from lyric resolution.
+- Use the titles provided exactly unless the user asks you to find an alternate version.
+- When multiple releases exist, use the most popular/official upload for the exact title user provides.
 
 ## 6) Ready for Generation rules
 
-Always fill value as true or 1, if there's a problem with input, do not input anything.
+- Wait until lyrics and artist fields have been fully populated, then run a ready for generation update pass. If you attempt to fill them all at once, the automation in the table will fail. This may only be set after there is content in both Lyrics and Artists.
+- Always fill value as true or 1, if there's a problem with input, do not input anything.
+- Again, procure lyrics, fill in all metadata, and once fully filled out, then you may send the ready for generation value.
 
 ## 7) Lyrics resolution rules
 
-Use the `build_catalog_payload` tool to resolve lyrics for each song.
+`build_catalog_payload` is the **required and exclusive lyric-resolution / lyric-preparation step for any Airtable entry**.
+
+For every song that will be written to Airtable:
+
+1. You **must** call `build_catalog_payload` before the Lyrics field can be written.
+2. You may call `build_catalog_payload` either:
+   - directly with track metadata
+   - or with a previously selected `match` / reusable `reference` from `search_lyrics` or `search_provider`
+3. You **must** keep the returned `lyricsCacheKey` and use that exact value later with `push_catalog_to_airtable`.
+
+If you need to inspect lyric candidates before resolving one exactly:
 
-Call it with:
+1. Use `search_lyrics` (all providers) or `search_provider` (one provider) to get preview-only candidates and reusable references.
+2. Use `select_match` if you need to choose one candidate from grouped `items`, flat `matches`, or a direct `match`.
+3. Pass the selected `match` or `reference` into `build_catalog_payload`.
+
+`search_lyrics`, `search_provider`, and `select_match` are **optional helpers for choosing the exact song**. They are **not replacements** for `build_catalog_payload`, and they do **not** complete Airtable lyric preparation by themselves.
+
+Do **not** assume the search tools return full lyrics or raw provider payloads. They return previews plus reusable references only.
+
+Call `build_catalog_payload` with:
 
 - `preferRomanized: true`
 
 The response will include:
 
-- `lyricsCacheKey` — a short slug identifying the cached lyrics server-side
+- `lyricsCacheKey` — the cache key that must later be passed to `push_catalog_to_airtable`
 - `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.
+Do **not** copy lyric text out of `build_catalog_payload`. `build_catalog_payload` prepares the cached lyric payload server-side; it does **not** write Airtable lyrics by itself. The actual Lyrics-field write happens later through `push_catalog_to_airtable` using the returned `lyricsCacheKey`. Never relay lyric text through tool-call arguments.
 
 ### Lyric priority (handled automatically by push_catalog_to_airtable)
 
@@ -89,11 +121,26 @@ Do **not** copy any lyric text out of `build_catalog_payload`. The full lyrics a
 
 ## 8) Airtable record write rules
 
+Create new records by default, or update existing ones if they already exist.
+
+Split Airtable writing responsibilities exactly as follows:
+
+- `create_records_for_table` / `update_records_for_table` are for **Song (Video)**, **Artists**, **Listen Link**, and **Ready for Generation** only.
+- `push_catalog_to_airtable` is for the **Lyrics** field only.
+
 Use Airtable MCP tools (`create_records_for_table` / `update_records_for_table`) for **Song (Video)**, **Artists**, **Listen Link**, and **Ready for Generation** 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.
+**STRICTLY FORBIDDEN:** Never use `create_records_for_table` or `update_records_for_table` to write, carry, relay, or update lyric text for the `Lyrics` field. Never place lyric text into those tool arguments. Never include the `Lyrics` field in those writes.
+
+**Always use `push_catalog_to_airtable` to write the Lyrics field.** This is the only tool that actually writes Lyrics into Airtable. It makes the Airtable API call server-side, resolves lyrics from the cached payload identified by `lyricsCacheKey`, and keeps lyric text out of your tool-call arguments.
+
+The required chain is:
 
-**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.
+1. `build_catalog_payload` resolves/prepares the lyrics and returns `lyricsCacheKey`
+2. `create_records_for_table` / `update_records_for_table` write the non-lyrics Airtable fields only
+3. `push_catalog_to_airtable` writes the Lyrics field using the `lyricsCacheKey` from `build_catalog_payload`
+
+Do **not** skip `build_catalog_payload`. Do **not** treat search tools, selection tools, or export tools as Airtable lyric-write tools.
 
 ### How to call push_catalog_to_airtable
 
@@ -104,10 +151,11 @@ Pass:
 - `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`
+- `lyricsCacheKey` — the value returned by `build_catalog_payload` (required source of lyric data for Airtable)
 - `preferRomanized: true`
 
-Do NOT include the lyrics text itself in `fields`. Do NOT include `lyricsFieldId` in `fields`.
+Do NOT include the lyric text itself in `fields`. Do NOT include `lyricsFieldId` in `fields`.
+Do NOT call `push_catalog_to_airtable` without first obtaining `lyricsCacheKey` from `build_catalog_payload`.
 
 ### Example push_catalog_to_airtable call shape (lyrics-only update)
 
@@ -131,21 +179,55 @@ If the lyrics write fails, retry with `splitLyricsUpdate: true`. This updates th
 
 Process all songs in the user's list together as a batch, not one at a time.
 
-### Phase 1 — Resolve all data in parallel
+After the initial inputs are sufficient, execute the main processing flow without pausing for user intervention between passes unless a required dependency is missing or a hard failure prevents continuation.
+
+The batch run must happen in **four explicit passes**, in this order:
+
+1. **First pass — catalog pass:** ensure songs exist in the catalog by creating or identifying the target Airtable records.
+2. **Second pass — normalization + Spotify pass:** normalize artist values and populate Spotify listen links.
+3. **Third pass — lyrics pass:** populate Lyrics using the required `build_catalog_payload` → `push_catalog_to_airtable` chain.
+4. **Fourth pass — Ready for Generation pass:** push Ready for Generation only after the prior data requirements are satisfied.
+
+### First pass — ensure songs exist in the catalog / identify target Airtable records
+
+Before record writes, resolve shared Airtable destination data once per batch:
+
+- resolve Airtable destination info (`search_bases`, `list_tables_for_base`)
+- verify field IDs against field names
+- resolve the view ID if available for final record links
+
+Then, for every song in the batch:
+
+- determine whether the song already exists and should be updated, or whether a new Airtable record must be created later
+- identify any existing target `recordId` values that later passes will update
+- prepare a per-song plan for `create` vs `update`, but keep this first pass **read-only**
+
+Do **not** create new Airtable records in this first pass. If a song's Spotify lookup or lyric preparation later fails, you must avoid creating a new incomplete catalog row for that song.
+
+This first pass is only for destination resolution, duplicate detection, and deciding which songs are safe to create later.
+
+### Second pass — normalize artist values and populate Spotify listen links
 
 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.
+1. Normalize artist values into the Airtable `Artists` input format required above.
 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`.
+3. Only after the non-lyrics metadata for a song is ready, write the non-lyrics Airtable fields needed for this pass:
+   - `Song (Video)`
+   - `Artists`
+   - `Listen Link`
+4. For songs identified as existing in the first pass, use `update_records_for_table`.
+5. For songs identified as new in the first pass, use `create_records_for_table` only now, after the non-lyrics metadata is ready.
+
+Use `create_records_for_table` / `update_records_for_table` for these non-lyrics fields only, with `typecast: true` so Artists can successfully be inserted.
 
-### Phase 2 — Bulk create/update records (Song (Video), Artists, Listen Link, and Ready for Generation fields only)
+Do **not** include the `Lyrics` field in this pass. Do **not** include lyric text anywhere in these Airtable MCP tool arguments. Do **not** set `Ready for Generation` yet.
 
-Use `create_records_for_table` (or `update_records_for_table` if updating existing records) to write **Song (Video)**, **Artists**, **Listen Link**, and **Ready for Generation** fields for all songs in the batch. use typecast: true, so Artists can successfully be inserted.
+If a song cannot be resolved well enough to produce the required non-lyrics metadata for this pass, do **not** create a new Airtable record for that song.
 
 - 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.
+- Capture or preserve the `recordId` for each song — use the existing `recordId` identified in the first pass or the new `recordId` returned by the create step in this second pass.
 
 Example batch create body (Song (Video), Artists, Listen Link, and Ready for Generation fields only — no Lyrics):
 
@@ -168,23 +250,46 @@ Example batch create body (Song (Video), Artists, Listen Link, and Ready for Gen
 }
 ```
 
-### Phase 3 — Write lyrics for each record via push_catalog_to_airtable
+### Third pass — populate lyrics for each record via push_catalog_to_airtable
 
-For each record created in Phase 2, call `push_catalog_to_airtable` with:
+For each target record established in the first pass, resolve lyrics and then call `push_catalog_to_airtable` with:
 
-- The `recordId` from Phase 2
+- required Airtable-preparation path: call `build_catalog_payload` with direct track metadata and `preferRomanized: true`
+- optional search-first helper path: call `search_lyrics` or `search_provider`, then `select_match` if needed, then call `build_catalog_payload` with the chosen `match` or `reference`
+- save each song's `lyricsCacheKey`
+- do **not** treat `search_lyrics`, `search_provider`, or `select_match` as completing Airtable lyric preparation; `build_catalog_payload` is still required
+
+Then call `push_catalog_to_airtable` with:
+
+- The `recordId` from the first pass
 - `fields: {}` (non-lyrics fields already written)
 - `lyricsFieldId` for the Lyrics field
-- `lyricsCacheKey` from Phase 1 for that song
+- `lyricsCacheKey` from `build_catalog_payload` for that song
 - `preferRomanized: true`
 
+This is the **only Airtable lyric-write step**.
+
 **One `push_catalog_to_airtable` call per song** (lyrics are per-track, not batchable).
 
-### Phase 4 — SRT export
+### Fourth pass — push Ready for Generation
+
+Only after the earlier passes have succeeded enough to satisfy the table automation requirements, run a final Ready for Generation update pass.
+
+In this pass:
+
+- update `Ready for Generation` to `true` or `1`
+- do this only for records whose `Artists` field is populated and whose `Lyrics` field has already been written
+- never combine this with the lyric-write step
+
+This fourth pass must happen after the catalog pass, the normalization + Spotify pass, and the lyrics pass.
+
+### Post-pass export step — SRT export
 
 After all Airtable inserts and lyrics writes succeed:
 
 - Export `.SRT` lyrics using the `export_lyrics` tool for each song.
+- `export_lyrics` may be called with direct track metadata, or with the same selected `match` / `reference` used earlier so the export resolves the exact same lyric result.
+- `export_lyrics` is a post-Airtable export step only. It is **not** part of Airtable lyric insertion and must never be described as the tool that writes Lyrics into Airtable.
 - Confirm the user has received at least one of the following:
   - SRT download link
   - SRT file path
@@ -193,7 +298,7 @@ After all Airtable inserts and lyrics writes succeed:
 
 ## 10) Required export step after Airtable succeeds
 
-After all Airtable inserts succeed, the agent must export synced lyrics as `.SRT`.
+After all Airtable passes succeed, the agent must export synced lyrics as `.SRT`.
 This export step is required and must be handled separately from Airtable insertion.
 
 ### Export priority
@@ -224,10 +329,12 @@ If the export backend does not provide a downloadable file or writable folder, t
 
 Use the `export_lyrics` tool to export `.SRT` output after Airtable insertion is complete.
 Prefer synced romanized output when available; otherwise use synced lyrics.
+If you already selected a lyric candidate via `search_lyrics` / `search_provider`, reuse that `match` or `reference` in `export_lyrics` for exact-result recall.
 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`
+- `export_lyrics` does **not** insert Airtable lyrics
 
 If the tool returns a URL, present that URL clearly.
 If the tool returns a file path, present that file path clearly.
@@ -262,14 +369,16 @@ If the view ID could not be resolved, omit it from the URL rather than guessing.
 
 ## 12) 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), Artists, Listen Link, and Ready for Generation fields 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              |
+| Step                                                                           | Tool (MCP Server)                                                                                       | Bulk?                 |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------- |
+| Find base/table                                                                | `search_bases`, `list_tables_for_base` (Airtable MCP)                                                   | Once per base         |
+| Spotify link                                                                   | `s4168377_get_spotify_song` (Make.com) or `search-spotify` (Spotify MCP).                               | Per song              |
+| Optional lyric candidate preview / selection                                   | `search_lyrics` / `search_provider`, then `select_match` (mr-magic)                                     | Per song              |
+| Required Airtable lyric preparation                                            | `build_catalog_payload` with track, `match`, or `reference` (mr-magic)                                  | Per song              |
+| **(Song (Video), Artists, Listen Link, and Ready for Generation fields 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, using `lyricsCacheKey` from `build_catalog_payload`** | Per song              |
+| Post-write SRT export                                                          | `export_lyrics` with track, `match`, or `reference` (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.
+**Never use `search_lyrics`, `search_provider`, `select_match`, or `export_lyrics` as substitutes for Airtable lyric preparation or Airtable lyric writing.**
+Always use `build_catalog_payload` first, then use `push_catalog_to_airtable` for Lyrics — no exceptions.

package/src/index.js

@@ -1,13 +1,18 @@
 import { fetchFromLrclib, searchLrclib } from './providers/lrclib.js';
-import { fetchFromGenius, searchGenius, checkGeniusTokenReady } from './providers/genius.js';
+import {
+  fetchFromGenius,
+  searchGenius,
+  checkGeniusTokenReady,
+  fetchLyricsForGeniusSong
+} from './providers/genius.js';
 import {
   fetchFromMusixmatch,
   searchMusixmatch,
   checkMusixmatchTokenReady
 } from './providers/musixmatch.js';
-import { fetchFromMelon, searchMelon } from './providers/melon.js';
+import { fetchFromMelon, searchMelon, fetchMelonBySongId } from './providers/melon.js';
 import { getEnvValue } from './utils/config.js';
-import { lyricContentScore } from './provider-result-schema.js';
+import { buildProviderReferenceFingerprint, lyricContentScore } from './provider-result-schema.js';
 
 const providers = [
   { name: 'lrclib', fetch: fetchFromLrclib, search: searchLrclib },
@@ -121,6 +126,87 @@ export async function searchProvider(providerName, track) {
   return provider.search(track);
 }
 
+function buildLookupTrack(track = {}, reference = {}) {
+  return {
+    title: track.title || reference.title || '',
+    artist: track.artist || reference.artist || '',
+    album: track.album || reference.album || null,
+    duration: track.duration ?? reference.duration ?? null
+  };
+}
+
+function recordMatchesReference(record, reference = {}) {
+  if (!record || !reference) return false;
+
+  if (reference.providerId && record.providerId === reference.providerId.toString()) {
+    return true;
+  }
+
+  const referenceIds = reference.ids || {};
+  const recordIds = record.ids || {};
+  if (
+    Object.entries(referenceIds).some(
+      ([key, value]) => value !== null && value !== undefined && recordIds[key] === value.toString()
+    )
+  ) {
+    return true;
+  }
+
+  if (reference.sourceUrl && record.sourceUrl === reference.sourceUrl) {
+    return true;
+  }
+
+  if (reference.fingerprint) {
+    return buildProviderReferenceFingerprint(record) === reference.fingerprint;
+  }
+
+  return false;
+}
+
+export async function resolveProviderReference(reference, track = {}) {
+  if (!reference?.provider) {
+    return null;
+  }
+
+  const lookupTrack = buildLookupTrack(track, reference);
+
+  if (reference.provider === 'melon') {
+    const songId = reference.ids?.songId || reference.providerId;
+    return fetchMelonBySongId(songId, lookupTrack);
+  }
+
+  if (reference.provider === 'lrclib') {
+    const results = await searchLrclib(lookupTrack);
+    return results.find((record) => recordMatchesReference(record, reference)) ?? null;
+  }
+
+  if (reference.provider === 'musixmatch') {
+    const results = await searchMusixmatch(lookupTrack);
+    return results.find((record) => recordMatchesReference(record, reference)) ?? null;
+  }
+
+  if (reference.provider === 'genius') {
+    const results = await searchGenius(lookupTrack);
+    const exact = results.find((record) => recordMatchesReference(record, reference)) ?? null;
+    if (!exact) {
+      return null;
+    }
+    if (exact.sourceUrl) {
+      try {
+        const plainLyrics = await fetchLyricsForGeniusSong(exact.sourceUrl);
+        if (plainLyrics) {
+          exact.plainLyrics = plainLyrics;
+        }
+      } catch {
+        // Best effort hydration; return the exact metadata match even when scraping fails.
+      }
+    }
+    return exact;
+  }
+
+  return null;
+}
+
 export function selectMatch(matches, { providerName, requireSynced = false } = {}) {
   const filtered = providerName
     ? matches.filter((match) => match.provider === providerName)

package/src/provider-result-schema.js

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto';
+
 export function detectSyncedState(syncedLyrics) {
   if (!syncedLyrics) return { hasSynced: false, timestampCount: 0 };
   const lines = syncedLyrics
@@ -56,6 +58,40 @@ export function lyricContentScore(record) {
   return score;
 }
 
+function compactIds(entries) {
+  const ids = Object.fromEntries(
+    entries
+      .filter(([, value]) => value !== null && value !== undefined && value !== '')
+      .map(([key, value]) => [key, value.toString()])
+  );
+  return Object.keys(ids).length > 0 ? ids : null;
+}
+
+export function extractProviderIds(provider, raw = null, providerId = null) {
+  switch (provider) {
+    case 'melon':
+      return compactIds([['songId', raw?.songId ?? providerId]]);
+    case 'genius':
+      return compactIds([
+        ['songId', raw?.id ?? providerId],
+        ['apiPath', raw?.api_path],
+        ['iq', raw?.iq ?? raw?.stats?.iq]
+      ]);
+    case 'musixmatch':
+      return compactIds([
+        [
+          'trackId',
+          raw?.['matcher.track.get']?.message?.body?.track?.track_id ?? raw?.track_id ?? providerId
+        ],
+        ['commontrackId', raw?.['matcher.track.get']?.message?.body?.track?.commontrack_id]
+      ]);
+    case 'lrclib':
+      return compactIds([['trackId', raw?.id ?? providerId]]);
+    default:
+      return compactIds([['id', providerId]]);
+  }
+}
+
 export function normalizeLyricRecord({
   provider,
   id,
@@ -77,6 +113,7 @@ export function normalizeLyricRecord({
   return {
     provider,
     providerId: id?.toString() ?? null,
+    ids: extractProviderIds(provider, raw, id),
     title: trackName || null,
     artist: artistName || null,
     album: albumName || null,
@@ -102,3 +139,54 @@ export function recomputeSyncFlags(record) {
   record.timestampCount = timestampCount;
   return record;
 }
+
+function normalizeFingerprintValue(value) {
+  if (value === null || value === undefined) return '';
+  return value.toString().trim().replace(/\s+/g, ' ');
+}
+
+function compactFingerprintIds(ids = {}) {
+  return Object.entries(ids)
+    .filter(([, value]) => value !== null && value !== undefined && value !== '')
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) => `${key}:${normalizeFingerprintValue(value)}`)
+    .join('|');
+}
+
+function buildFingerprintSnippet(record = {}) {
+  const lyricText = [
+    record.plainLyrics,
+    record.syncedLyrics,
+    record.plainPreview,
+    record.syncedPreview
+  ]
+    .map((value) => normalizeFingerprintValue(value))
+    .find(Boolean);
+  return lyricText ? lyricText.slice(0, 100) : '';
+}
+
+export function buildProviderReferenceFingerprint(record = {}) {
+  if (!record || typeof record !== 'object') {
+    return null;
+  }
+
+  const provider = normalizeFingerprintValue(record.provider);
+  const providerId = normalizeFingerprintValue(record.providerId);
+  const ids = compactFingerprintIds(record.ids || {});
+  const sourceUrl = normalizeFingerprintValue(record.sourceUrl);
+  const title = normalizeFingerprintValue(record.title);
+  const artist = normalizeFingerprintValue(record.artist);
+  const album = normalizeFingerprintValue(record.album);
+  const duration = normalizeFingerprintValue(record.duration);
+  const snippet = !providerId && !ids && !sourceUrl ? buildFingerprintSnippet(record) : '';
+
+  const source = [provider, providerId, ids, sourceUrl, title, artist, album, duration, snippet]
+    .filter(Boolean)
+    .join('||');
+
+  if (!source) {
+    return null;
+  }
+
+  return createHash('sha256').update(source).digest('hex');
+}

package/src/providers/lrclib.js

@@ -1,6 +1,6 @@
 import axios from 'axios';
 
-import { normalizeLyricRecord } from '../provider-result-schema.js';
+import { normalizeLyricRecord, lyricContentScore } from '../provider-result-schema.js';
 import { createLogger } from '../utils/logger.js';
 
 const logger = createLogger('provider:lrclib');
@@ -40,6 +40,22 @@ async function querySearch(track) {
   }
 }
 
+/**
+ * Pick the best candidate from a list: prefer synced over plain, then prefer
+ * richer lyric content. This ensures fetchFromLrclib always returns a synced
+ * result when one is available rather than the first incidentally-ordered one.
+ */
+function chooseBestCandidate(candidates) {
+  if (!candidates.length) return null;
+  return candidates.slice().sort((a, b) => {
+    // Synced results come first
+    const syncedDiff = (b.synced ? 1 : 0) - (a.synced ? 1 : 0);
+    if (syncedDiff !== 0) return syncedDiff;
+    // Among equally-synced results, prefer richer content
+    return lyricContentScore(b) - lyricContentScore(a);
+  })[0];
+}
+
 export async function fetchFromLrclib(track) {
   try {
     const results = await querySearch(track);
@@ -47,16 +63,19 @@ export async function fetchFromLrclib(track) {
       logger.debug('LRCLIB: no results found', { track });
       return null;
     }
-    const exactMatch = results.find((record) => {
+    const exactMatches = results.filter((record) => {
       const sameTitle = record.title?.toLowerCase() === track.title?.toLowerCase();
       const sameArtist = record.artist?.toLowerCase() === track.artist?.toLowerCase();
       return sameTitle && sameArtist;
     });
-    const result = exactMatch ?? results[0];
+    // Prefer exact matches; if none, fall back to all results.
+    // Within each group, prefer synced then richer content.
+    const result = chooseBestCandidate(exactMatches) ?? chooseBestCandidate(results);
     logger.debug('LRCLIB: match selected', {
-      exact: Boolean(exactMatch),
-      title: result.title,
-      artist: result.artist
+      exact: exactMatches.length > 0,
+      synced: result?.synced,
+      title: result?.title,
+      artist: result?.artist
     });
     return result;
   } catch (error) {

package/src/providers/melon.js

@@ -163,6 +163,46 @@ function toLyricStrings(lyricInfo) {
   return { plain: plain || null, synced: null };
 }
 
+export async function fetchMelonBySongId(songId, track = {}) {
+  const normalizedSongId = songId?.toString().trim();
+  if (!normalizedSongId) {
+    return null;
+  }
+
+  const record = normalizeLyricRecord({
+    provider: 'melon',
+    id: normalizedSongId,
+    trackName: track.title || null,
+    artistName: track.artist || null,
+    albumName: track.album || null,
+    duration: null,
+    plainLyrics: null,
+    syncedLyrics: null,
+    sourceUrl: `https://www.melon.com/song/detail.htm?songId=${normalizedSongId}`,
+    confidence: 0.5,
+    synced: false,
+    status: 'ok',
+    raw: {
+      songId: normalizedSongId,
+      title: track.title || null,
+      artist: track.artist || null,
+      album: track.album || null
+    }
+  });
+
+  try {
+    const lyricInfo = await fetchLyricInfo(normalizedSongId);
+    const { plain, synced } = toLyricStrings(lyricInfo);
+    record.plainLyrics = plain;
+    record.syncedLyrics = synced;
+    recomputeSyncFlags(record);
+  } catch (error) {
+    logger.error('Melon lyricInfo request failed', { error, songId: normalizedSongId });
+  }
+
+  return record;
+}
+
 export async function searchMelon(track) {
   const pageHtml = await fetchSearchPage(track);
   return parseSearchPage(pageHtml).map((record) =>
@@ -185,17 +225,13 @@ export async function searchMelon(track) {
 }
 
 export async function fetchFromMelon(track) {
+  const requestedSongId = track?.songId || track?.providerId || track?.ids?.songId;
+  if (requestedSongId) {
+    return fetchMelonBySongId(requestedSongId, track);
+  }
+
   const candidates = await searchMelon(track);
   const primary = candidates[0];
   if (!primary) return null;
-  try {
-    const lyricInfo = await fetchLyricInfo(primary.providerId);
-    const { plain, synced } = toLyricStrings(lyricInfo);
-    primary.plainLyrics = plain;
-    primary.syncedLyrics = synced;
-    recomputeSyncFlags(primary);
-  } catch (error) {
-    logger.error('Melon lyricInfo request failed', { error, songId: primary.providerId });
-  }
-  return primary;
+  return fetchMelonBySongId(primary.providerId, primary);
 }