mr-magic-mcp-server 0.3.9 → 0.3.11

package/.env.example

@@ -5,25 +5,26 @@
 # ───────────────────────────────────────────────────────────────────────────────
 # There are three ways to supply the Genius token (tried in order):
 #
+#   Direct token (env var, see debug section below)) — static bearer token, no auto-refresh
+#     Set GENIUS_DIRECT_TOKEN. Works everywhere but the token must be
+#     manually updated on expiry (or redeploy with a new value).
+#     Use this only when client_credentials are unavailable.
+#
 #   Auto-refresh (recommended for all deployments, including Render/ephemeral)
 #     Set GENIUS_CLIENT_ID + GENIUS_CLIENT_SECRET. The server calls the Genius
 #     OAuth client_credentials endpoint at runtime and refreshes the token in
 #     memory automatically. No disk, no scripts, no manual token copying needed.
 #
-#   Direct token (env var) — static bearer token, no auto-refresh
-#     Set GENIUS_DIRECT_TOKEN. Works everywhere but the token must be
-#     manually updated on expiry (or redeploy with a new value).
-#     Use this only when client_credentials are unavailable.
-#
 #   Cache token (on-disk) — local instance or persistent servers only
 #     Run `npm run fetch:genius-token` to write a token to
 #     `.cache/genius-token.json`. The server reads it on startup when a
 #     persistent, writable filesystem is available. Not suitable for
 #     ephemeral hosts.
+#
 # ═══════════════════════════════════════════════════════════════════════════════
+
 GENIUS_CLIENT_ID=
 GENIUS_CLIENT_SECRET=
-GENIUS_DIRECT_TOKEN=
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # REQUIRED (feature-specific) — Musixmatch
@@ -32,7 +33,7 @@ GENIUS_DIRECT_TOKEN=
 # ───────────────────────────────────────────────────────────────────────────────
 # Token resolution priority (1 = highest):
 #
-#   1. MUSIXMATCH_DIRECT_TOKEN (env var)
+#   1. MUSIXMATCH_DIRECT_TOKEN (env var, see debug section below)
 #        Static bearer token. Works everywhere but must be manually updated on
 #        expiry. Use when no other option is available.
 #
@@ -47,34 +48,22 @@ GENIUS_DIRECT_TOKEN=
 #        Run `npm run fetch:musixmatch-token` — writes .cache/musixmatch-token.json.
 #        The server reads it on startup when a writable filesystem is available.
 # ═══════════════════════════════════════════════════════════════════════════════
-MUSIXMATCH_DIRECT_TOKEN=
-
-# KV store for Musixmatch token persistence (ephemeral deployments / npx installs)
-# Priority: Upstash Redis (priority 1) → Cloudflare KV (priority 2)
-# If both are set, Upstash Redis is used and Cloudflare KV is ignored.
 #
-# Upstash Redis: reuse the same creds as the export backend (see below) — no extra setup.
-# Cloudflare KV: set the three CF_* vars; create a namespace at dash.cloudflare.com.
-CF_API_TOKEN=              # Cloudflare API token with KV:Edit permission (CF KV only)
-CF_ACCOUNT_ID=             # Cloudflare account ID (CF KV only)
-CF_KV_NAMESPACE_ID=        # KV namespace ID to store the token in (CF KV only)
-# Optional overrides (defaults are sensible for most users)
-MUSIXMATCH_TOKEN_KV_KEY=           # KV key name (default: mr-magic:musixmatch-token)
-MUSIXMATCH_TOKEN_KV_TTL_SECONDS=   # Token TTL in seconds (default: 2592000 = 30 days)
-
 # Headless / Render deployment — push a pre-captured token without opening a browser.
 # run `npm run fetch:musixmatch-token` or sign into Musixmatch manually to get a token, then set it in the env to push it to the KV store without browser automation.
 # Set MUSIXMATCH_DIRECT_TOKEN to the full musixmatchUserToken JSON payload (from fetch:musixmatch-token output),
+#
 # then run `npm run push:musixmatch-token` or prepend it to the start command:
 #   npm run push:musixmatch-token && npm run server:mcp:http
 # If unset, push:musixmatch-token exits silently (safe no-op in start commands).
 # MUSIXMATCH_DIRECT_TOKEN also serves as the runtime token override (highest env priority).
-
+#
 # ═══════════════════════════════════════════════════════════════════════════════
 # REQUIRED (feature-specific) — Airtable
 # Only needed if you use the push_catalog_to_airtable tool.
 # Get from https://airtable.com/create/tokens
 # ═══════════════════════════════════════════════════════════════════════════════
+
 AIRTABLE_PERSONAL_ACCESS_TOKEN=
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -86,25 +75,36 @@ AIRTABLE_PERSONAL_ACCESS_TOKEN=
 # inline — embeds payload directly in the MCP response (no storage needed)
 # redis  — stores in Upstash Redis KV store; best for production/ephemeral hosts
 # ═══════════════════════════════════════════════════════════════════════════════
+
 MR_MAGIC_EXPORT_BACKEND=    # local | inline | redis
 
-# Required when BACKEND=local
-MR_MAGIC_EXPORT_DIR=        # Absolute path to the directory to write export files into
+# KV store for Musixmatch token persistence (ephemeral deployments / npx installs)
+# Priority: Upstash Redis (priority 1) → Cloudflare KV (priority 2)
+# If both are set, Upstash Redis is used and Cloudflare KV is ignored.
 
-# Required when BACKEND=redis — get from https://console.upstash.com/redis/rest
+# Note: Upstash Redis is required when BACKEND=redis — get from https://console.upstash.com/redis/rest
 # These same credentials are also used by the Musixmatch KV token store, so
 # setting them once enables both features.
 UPSTASH_REDIS_REST_URL=
 UPSTASH_REDIS_REST_TOKEN=
 
+# Cloudflare KV: set the three CF_* vars; create a namespace at dash.cloudflare.com.
+CF_API_TOKEN=              # Cloudflare API token with KV:Edit permission (CF KV only)
+CF_ACCOUNT_ID=             # Cloudflare account ID (CF KV only)
+CF_KV_NAMESPACE_ID=        # KV namespace ID to store the token in (CF KV only)
+
+# Required when BACKEND=local
+MR_MAGIC_EXPORT_DIR=/Users/naji/Downloads/magic-export/        # Absolute path to the directory to write export files into
+
 # Base URL the server uses to build download links returned to the MCP client.
-# Examples: https://yourserver.com  |  http://localhost:3444
+# Examples: https://yourserver.com  |  http://localhost:3444 | http://localhost:3333
 # See README for details.
 MR_MAGIC_DOWNLOAD_BASE_URL=
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # Server & Runtime
 # ═══════════════════════════════════════════════════════════════════════════════
+
 PORT=                       # Override all server ports (default: 3444 MCP / 3333 HTTP automation)
 LOG_LEVEL=                  # error | warn | info | debug  (default: info)
 MR_MAGIC_QUIET_STDIO=0      # Set to 1 to suppress non-error stdout logs (recommended under stdio MCP clients)
@@ -113,6 +113,7 @@ MR_MAGIC_HTTP_TIMEOUT_MS=10000  # Global outbound HTTP timeout in ms (default: 1
 # ═══════════════════════════════════════════════════════════════════════════════
 # Optional — Melon provider
 # ═══════════════════════════════════════════════════════════════════════════════
+
 MELON_COOKIE=               # Pin a browser session cookie for consistent results; anonymous access usually works without it
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -130,10 +131,19 @@ MR_MAGIC_EXPORT_TTL_SECONDS=3600
 GENIUS_TOKEN_CACHE=.cache/genius-token.json
 MUSIXMATCH_TOKEN_CACHE=.cache/musixmatch-token.json
 
+#   Direct tokens — Use these as temp overrides for testing or debugging, but for long-term use the auto-refresh or KV options are recommended to avoid manual token management.
+#   Set GENIUS_DIRECT_TOKEN and MUSIXMATCH_DIRECT_TOKEN to the full token payloads (from fetch-genius-token and fetch-musixmatch-token output), then restart the server.
+GENIUS_DIRECT_TOKEN=
+MUSIXMATCH_DIRECT_TOKEN=
+
 # Musixmatch: when 1, provider will attempt to re-run the fetch script
 # automatically (headless) if no token is available
 MUSIXMATCH_AUTO_FETCH=0
 
+# Optional overrides for Musixmatch KV token storage (only needed if using KV storage and want to customize beyond the defaults)
+MUSIXMATCH_TOKEN_KV_KEY=           # KV key name (default: mr-magic:musixmatch-token)
+MUSIXMATCH_TOKEN_KV_TTL_SECONDS=   # Token TTL in seconds (default: 2592000 = 30 days)
+
 # Playwright Headless mode toggle for fetch scripts that require browser automation (default: false)
 HEADLESS=
 

package/README.md

@@ -609,19 +609,141 @@ Responses:
 
 Both the stdio and Streamable HTTP & SSE transports expose the same tool registry:
 
-| Tool                       | Purpose                                                                                                                             |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `find_lyrics`              | Fetch best lyrics (prefers synced) plus metadata and payload.                                                                       |
-| `find_synced_lyrics`       | Like `find_lyrics` but rejects plain-only results.                                                                                  |
-| `search_lyrics`            | List candidate matches across all providers without downloading lyrics.                                                             |
-| `search_provider`          | Query a single named provider.                                                                                                      |
-| `get_provider_status`      | Report readiness and notes for each provider.                                                                                       |
-| `format_lyrics`            | Format lyrics in memory (optional romanization) for display.                                                                        |
-| `export_lyrics`            | Write plain / LRC / SRT / romanized files to the export backend.                                                                    |
-| `select_match`             | Pick a prior result by provider, index, or synced flag.                                                                             |
-| `build_catalog_payload`    | Return a compact record (title / link / lyrics) for Airtable-style inserts.                                                         |
-| `push_catalog_to_airtable` | Write catalog records to Airtable server-side — lyrics never pass through LLM arguments. Requires `AIRTABLE_PERSONAL_ACCESS_TOKEN`. |
-| `runtime_status`           | Snapshot provider readiness plus relevant env vars.                                                                                 |
+| Tool                       | Purpose                                                                                                                                           |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `find_lyrics`              | Fetch best lyrics (prefers synced) plus metadata and payload from direct track metadata, or resolve a prior provider reference / selected match.  |
+| `find_synced_lyrics`       | Like `find_lyrics` but rejects plain-only results; also accepts direct track metadata, a provider reference, or a selected match.                 |
+| `search_lyrics`            | Return grouped, preview-only candidate matches across all providers, including reusable provider references.                                      |
+| `search_provider`          | Query a single named provider and return flat, preview-only matches plus reusable provider references.                                            |
+| `get_provider_status`      | Report readiness and notes for each provider.                                                                                                     |
+| `format_lyrics`            | Format lyrics in memory (optional romanization) for display from direct track metadata, a provider reference, or a selected match.                |
+| `export_lyrics`            | Write plain / LRC / SRT / romanized files to the export backend from direct track metadata, a provider reference, or a selected match.            |
+| `select_match`             | Pick a single prior search result from grouped `items`, flat `matches`, or a direct `match`, using provider/index/synced filters.                 |
+| `build_catalog_payload`    | Return a compact record (title / link / lyrics) for Airtable-style inserts from direct track metadata, a provider reference, or a selected match. |
+| `push_catalog_to_airtable` | Write catalog records to Airtable server-side — lyrics never pass through LLM arguments. Requires `AIRTABLE_PERSONAL_ACCESS_TOKEN`.               |
+| `runtime_status`           | Snapshot provider readiness plus relevant env vars.                                                                                               |
+
+### MCP search result behavior
+
+`search_lyrics` and `search_provider` now return **preview-only** search results. They are intentionally compact and do **not** include full lyrics or raw provider payloads.
+
+Each returned result is designed for follow-up tool calls and includes:
+
+- core metadata such as provider, title, artist, album, duration, source URL, confidence, and synced/plain-only flags
+- preview snippets (`plainPreview` / `syncedPreview`) when available
+- a reusable `reference` object that can be passed back into downstream tools for exact result recall
+
+The `reference` object is the durable handoff between search and resolution. Instead of copying large provider payloads around, clients can reuse the compact reference to resolve the exact provider result later.
+
+### MCP provider-reference workflow
+
+After a search step, the following tools can resolve lyrics from **either**:
+
+- direct `track` metadata
+- a provider `reference` returned by `search_lyrics` or `search_provider`
+- a selected `match` object from prior search output
+
+This applies to:
+
+- `find_lyrics`
+- `find_synced_lyrics`
+- `build_catalog_payload`
+- `format_lyrics`
+- `export_lyrics`
+
+### `select_match` in the workflow
+
+`select_match` is the bridge between preview-only search results and the tools that resolve full lyrics.
+
+It accepts any of these input shapes:
+
+- `items` — grouped provider results returned by `search_lyrics`
+- `matches` — flat results returned by `search_provider` (or other flattened match arrays)
+- `match` — a single previously returned result passed through directly
+
+Use `criteria` to narrow the choice by provider, require synced lyrics, and/or choose a zero-based index. The returned selected match can then be passed directly into `find_lyrics`, `find_synced_lyrics`, `build_catalog_payload`, `format_lyrics`, or `export_lyrics`. If you already know which result you want, you can skip `select_match` and pass that result's `reference` directly.
+
+### Example workflow: search → select → build/export
+
+1. Call `search_lyrics` to get grouped, preview-only results plus provider `reference` objects.
+2. Call `select_match` with the returned `items` to choose one result.
+3. Pass the returned `match` into `build_catalog_payload`, `find_lyrics`, `format_lyrics`, or `export_lyrics`.
+4. Optionally reuse the nested `match.result.reference` later to resolve the exact same provider result again without repeating the original broad search.
+
+Example sequence:
+
+```json
+{
+  "track": { "artist": "Coldplay", "title": "Yellow" }
+}
+```
+
+→ `search_lyrics`
+
+```json
+{
+  "items": [
+    {
+      "provider": "lrclib",
+      "results": [
+        {
+          "title": "Yellow",
+          "artist": "Coldplay",
+          "synced": true,
+          "reference": {
+            "provider": "lrclib",
+            "providerId": "...",
+            "fingerprint": "..."
+          }
+        }
+      ]
+    }
+  ],
+  "criteria": { "requireSynced": true, "index": 0 }
+}
+```
+
+→ `select_match`
+
+```json
+{
+  "match": {
+    "provider": "lrclib",
+    "result": {
+      "title": "Yellow",
+      "artist": "Coldplay",
+      "reference": {
+        "provider": "lrclib",
+        "providerId": "...",
+        "fingerprint": "..."
+      }
+    }
+  },
+  "options": {
+    "omitInlineLyrics": true,
+    "lyricsPayloadMode": "payload"
+  }
+}
+```
+
+→ `build_catalog_payload`
+
+Or export the same exact result later with:
+
+```json
+{
+  "reference": {
+    "provider": "lrclib",
+    "providerId": "...",
+    "fingerprint": "..."
+  },
+  "options": {
+    "formats": ["plain", "lrc", "srt"]
+  }
+}
+```
+
+→ `export_lyrics`
 
 ## Airtable Integration
 
@@ -1199,6 +1321,8 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 #### `find_lyrics`
 
+Accepts either direct `track` metadata, a provider `reference` from prior search output, or a selected `match`.
+
 ```bash
 curl -sS -X POST http://127.0.0.1:3444/mcp \
   -H 'Content-Type: application/json' \
@@ -1208,6 +1332,8 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 #### `find_synced_lyrics`
 
+Same lookup inputs as `find_lyrics`, but only returns timestamped results.
+
 ```bash
 curl -sS -X POST http://127.0.0.1:3444/mcp \
   -H 'Content-Type: application/json' \
@@ -1217,6 +1343,8 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 #### `build_catalog_payload` — inline lyrics
 
+Accepts direct `track` metadata, a reusable `reference`, or a selected `match` from prior search output.
+
 ```bash
 curl -sS -X POST http://127.0.0.1:3444/mcp \
   -H 'Content-Type: application/json' \
@@ -1241,6 +1369,8 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 #### `search_lyrics`
 
+Returns grouped, preview-only results under `items`. Each result includes a reusable `reference`, plus compact metadata and previews when available. Full lyrics and raw provider payloads are intentionally omitted.
+
 ```bash
 curl -sS -X POST http://127.0.0.1:3444/mcp \
   -H 'Content-Type: application/json' \
@@ -1250,6 +1380,8 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 #### `search_provider`
 
+Returns a flat `matches` array with the same preview-only result shape used by the grouped `search_lyrics` output.
+
 ```bash
 curl -sS -X POST http://127.0.0.1:3444/mcp \
   -H 'Content-Type: application/json' \
@@ -1259,6 +1391,8 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 #### `format_lyrics`
 
+Accepts direct `track` metadata, a reusable `reference`, or a selected `match`.
+
 ```bash
 curl -sS -X POST http://127.0.0.1:3444/mcp \
   -H 'Content-Type: application/json' \
@@ -1268,6 +1402,8 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 #### `export_lyrics`
 
+Accepts direct `track` metadata, a reusable `reference`, or a selected `match`.
+
 ```bash
 curl -sS -X POST http://127.0.0.1:3444/mcp \
   -H 'Content-Type: application/json' \
@@ -1321,6 +1457,8 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 #### `select_match`
 
+Use `items` for grouped `search_lyrics` output, `matches` for flat `search_provider` output, or `match` to pass through a single result directly.
+
 ```bash
 curl -sS -X POST http://127.0.0.1:3444/mcp \
   -H 'Content-Type: application/json' \
@@ -1334,6 +1472,21 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
   }' | jq
 ```
 
+Example using grouped `items` from `search_lyrics`:
+
+```bash
+curl -sS -X POST http://127.0.0.1:3444/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{
+    "jsonrpc":"2.0","id":14,"method":"tools/call",
+    "params":{"name":"select_match","arguments":{
+      "items":[{"provider":"lrclib","results":[{"title":"Yellow","artist":"Coldplay","synced":true,"reference":{"provider":"lrclib","providerId":"123","fingerprint":"abc"}}]}],
+      "criteria":{"requireSynced":true,"index":0}
+    }}
+  }' | jq
+```
+
 > **MCP tool response shape:**
 >
 > - `result.structuredContent` — machine-friendly object (all fields, full values)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-magic-mcp-server",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
   "type": "module",
   "main": "src/index.js",
@@ -21,6 +21,8 @@
     ".env.example"
   ],
   "scripts": {
+    "check-for-updates": "npx npm-check-updates",
+    "update-deps": "npx npm-check-updates -u && npm install",
     "cleanup": "eslint . --fix && prettier --write .",
     "cli": "node src/bin/cli.js",
     "server:http": "node src/bin/http-server.js",
@@ -59,17 +61,17 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.55.1",
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "axios": "^1.13.6",
+    "@dotenvx/dotenvx": "^1.59.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.14.0",
     "cheerio": "^1.2.0",
     "commander": "^14.0.3"
   },
   "devDependencies": {
-    "eslint": "^10.0.3",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import-x": "^4.15.1",
-    "playwright": "^1.58.2",
+    "eslint-plugin-import-x": "^4.16.2",
+    "playwright": "^1.59.0",
     "prettier": "^3.8.1"
   },
   "overrides": {