mr-magic-mcp-server 0.1.21 → 0.1.25

package/.env.example

@@ -119,6 +119,7 @@ MR_MAGIC_TOOL_ARG_CHUNK_SIZE=400  # Chunk size in chars (only used when LOG_TOOL
 # Streamable HTTP MCP transport diagnostics
 MR_MAGIC_MCP_HTTP_DIAGNOSTICS=0  # Set to 1 to log enriched request diagnostics at transport ingress
 MR_MAGIC_ALLOWED_HOSTS=           # Optional. Comma-separated extra allowed hostnames for DNS rebinding protection when binding to 0.0.0.0 (e.g. custom domains). RENDER_EXTERNAL_HOSTNAME is auto-included on Render.
+MR_MAGIC_SESSIONLESS=0            # Set to 1 to force sessionless mode (each request handled by a fresh server/transport, no in-memory session). Auto-enabled on Render. Set manually on ECS, Fly.io, Railway, etc.
 
 # SDK repro harness verbose HTTP logging
 MR_MAGIC_SDK_REPRO_HTTP_DEBUG=0  # Set to 1 for verbose HTTP previews in the SDK repro harness script

package/README.md

@@ -94,15 +94,16 @@ grouped below by purpose.
 
 ### Server and runtime
 
-| Variable                   | Default          | Description                                                                                                                                                                                     |
-| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PORT`                     | `3444` / `3333`  | Override server port. On Render this is set automatically (default `10000`).                                                                                                                    |
-| `LOG_LEVEL`                | `info`           | Verbosity: `error` \| `warn` \| `info` \| `debug`.                                                                                                                                              |
-| `MR_MAGIC_QUIET_STDIO`     | `0`              | Set to `1` to suppress non-error stdout logs (forces `LOG_LEVEL=error`). Recommended under stdio MCP clients.                                                                                   |
-| `MR_MAGIC_HTTP_TIMEOUT_MS` | `10000`          | Global outbound HTTP timeout in milliseconds.                                                                                                                                                   |
-| `MR_MAGIC_ROOT`            | _(project root)_ | Override the project root used for `.env` and `.cache` path resolution.                                                                                                                         |
-| `MR_MAGIC_ENV_PATH`        | _(auto)_         | Point to a specific `.env` file instead of `<project root>/.env`.                                                                                                                               |
-| `MR_MAGIC_ALLOWED_HOSTS`   | _(empty)_        | Comma-separated extra hostnames allowed for DNS rebinding protection when binding to `0.0.0.0`. `RENDER_EXTERNAL_HOSTNAME` is included automatically on Render. Only needed for custom domains. |
+| Variable                   | Default          | Description                                                                                                                                                                                                      |
+| -------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                     | `3444` / `3333`  | Override server port. On Render this is set automatically (default `10000`).                                                                                                                                     |
+| `LOG_LEVEL`                | `info`           | Verbosity: `error` \| `warn` \| `info` \| `debug`.                                                                                                                                                               |
+| `MR_MAGIC_QUIET_STDIO`     | `0`              | Set to `1` to suppress non-error stdout logs (forces `LOG_LEVEL=error`). Recommended under stdio MCP clients.                                                                                                    |
+| `MR_MAGIC_HTTP_TIMEOUT_MS` | `10000`          | Global outbound HTTP timeout in milliseconds.                                                                                                                                                                    |
+| `MR_MAGIC_ROOT`            | _(project root)_ | Override the project root used for `.env` and `.cache` path resolution.                                                                                                                                          |
+| `MR_MAGIC_ENV_PATH`        | _(auto)_         | Point to a specific `.env` file instead of `<project root>/.env`.                                                                                                                                                |
+| `MR_MAGIC_ALLOWED_HOSTS`   | _(empty)_        | Comma-separated extra hostnames allowed for DNS rebinding protection when binding to `0.0.0.0`. `RENDER_EXTERNAL_HOSTNAME` is included automatically on Render. Only needed for custom domains.                  |
+| `MR_MAGIC_SESSIONLESS`     | `0`              | Set to `1` to force **sessionless mode** on the MCP Streamable HTTP server — each request is handled by a fresh, temporary server/transport with no in-memory session state. Auto-enabled on Render (see below). |
 
 ### Genius credentials
 
@@ -315,6 +316,25 @@ Recommended Render service settings:
 > your Render environment so the DNS rebinding protection accepts requests with
 > those `Host` headers.
 
+#### Sessionless mode on Render (automatic)
+
+When `RENDER=true` is detected, the MCP Streamable HTTP server automatically operates
+in **sessionless mode**. This is essential for multi-instance deployments where Render
+routes requests across several processes:
+
+- An `initialize` request served by **Instance A** would store the session in A's
+  in-memory `Map`. A follow-up `tools/list` call routed to **Instance B** cannot
+  find that session and returns `{"error": "Session not found. …"}`.
+- In sessionless mode, every request — `initialize`, `tools/list`, `tools/call`, etc.
+  — is handled by a fresh, short-lived `Server + StreamableHTTPServerTransport` pair.
+  No `Mcp-Session-Id` header is issued and no session state is stored. Each request
+  is fully self-contained and works correctly regardless of which instance handles it.
+
+You do **not** need to set `MR_MAGIC_SESSIONLESS=1` manually on Render — it is
+auto-enabled via the platform-injected `RENDER` env var. Set `MR_MAGIC_SESSIONLESS=1`
+explicitly on other multi-instance platforms (ECS, Fly.io, Railway, etc.) where
+a similar load-balanced, stateless deployment is used.
+
 ### Transport selection
 
 | Transport            | Command                   | Use case                            |
@@ -570,10 +590,10 @@ Recommended presets:
 
 Mr. Magic supports two connection modes depending on where the MCP client runs:
 
-| Mode | Transport | When to use |
-| ---- | --------- | ----------- |
-| **Local (stdio)** | `mcp-server` binary via stdin/stdout | Cline, Claude Desktop, and any client that runs locally on the same machine |
-| **Remote (Streamable HTTP)** | `POST https://your-server.com/mcp` | TypingMind, browser-based clients, and any client connecting to a deployed server |
+| Mode                         | Transport                            | When to use                                                                       |
+| ---------------------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
+| **Local (stdio)**            | `mcp-server` binary via stdin/stdout | Cline, Claude Desktop, and any client that runs locally on the same machine       |
+| **Remote (Streamable HTTP)** | `POST https://your-server.com/mcp`   | TypingMind, browser-based clients, and any client connecting to a deployed server |
 
 ---
 
@@ -755,7 +775,7 @@ Automated checks:
 
 ```bash
 npm run test                  # full bundled test runner
-node tests/mcp-tools.test.js  # raw MCP integration harness
+node src/tests/mcp-tools.test.js  # raw MCP integration harness
 npm run repro:mcp:arg-boundary       # JSON-RPC argument boundary repro
 npm run repro:mcp:arg-boundary:sdk   # SDK client transport repro
 npm run lint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-magic-mcp-server",
-  "version": "0.1.21",
+  "version": "0.1.25",
   "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
   "type": "module",
   "main": "src/index.js",
@@ -29,12 +29,11 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "test": "node tests/run-tests.js",
-    "fetch:musixmatch-token": "node scripts/fetch_MUSIXMATCH_ALT_FALLBACK_TOKEN.mjs",
-    "fetch:genius-token": "node scripts/fetch_genius_token.mjs",
-    "repro:mcp:arg-boundary": "node scripts/mcp-arg-boundary-repro.mjs",
-    "repro:mcp:arg-boundary:sdk": "node scripts/mcp-arg-boundary-sdk-repro.mjs",
-    "prepack": "npm run test"
+    "test": "node src/tests/run-tests.js",
+    "fetch:musixmatch-token": "node src/scripts/fetch_MUSIXMATCH_ALT_FALLBACK_TOKEN.mjs",
+    "fetch:genius-token": "node src/scripts/fetch_genius_token.mjs",
+    "repro:mcp:arg-boundary": "node src/scripts/mcp-arg-boundary-repro.mjs",
+    "repro:mcp:arg-boundary:sdk": "node src/scripts/mcp-arg-boundary-sdk-repro.mjs"
   },
   "keywords": [
     "lyrics",
@@ -55,7 +54,7 @@
   },
   "homepage": "https://github.com/mrnajiboy/mr-magic-mcp-server#readme",
   "engines": {
-    "node": ">=18.17"
+    "node": ">=20"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

package/prompts/airtable-song-importer.md

@@ -1,3 +1,5 @@
+# Airtable Song Importer
+
 You are an Airtable Song Importing Assistant. You are helping the user add songs to an Airtable catalog.
 
 The user will provide:
@@ -15,6 +17,7 @@ Use Airtable tools to determine the correct:
 
 - base ID
 - table ID
+- view ID (needed for constructing final entry links)
 - target field IDs or field names
 
 Always verify field IDs against field names before inserting or updating records.
@@ -214,15 +217,32 @@ If the tool returns a URL, present that URL clearly.
 If the tool returns a file path, present that file path clearly.
 If the tool returns inline content because persistence was skipped or failed, provide the SRT content in the conversation and clearly explain that no downloadable file/link was available.
 
-## 9) Progress reporting rules
+## 9) Final output — Entry Summary
+
+When all processing is complete, output a concise **Entry Summary** — one line (or short block) per song. Do not explain phases or steps.
+
+Each entry should include:
+
+- The formatted `Song (Video)` title
+- Status: `created` or `updated`
+- A direct Airtable link to the record, constructed as:
+  `https://airtable.com/{baseId}/{tableId}/{viewId}/{recordId}`
+- Any per-entry notes (e.g. lyrics fallback used, SRT export path, or a failure)
 
-When reporting progress:
+### Example output
+
+```text
+✅ BLACKPINK, Doja Cat - Crazy (Lyrics) — created
+   https://airtable.com/appeBUkVEp3N4RT0C/tbl0y5XHFXpjUJXHu/viwXXXXXXXXXXXXX/recABCDEFG1234567
+
+✅ Joji - Glimpse of Us (Lyrics) — created
+   https://airtable.com/appeBUkVEp3N4RT0C/tbl0y5XHFXpjUJXHu/viwXXXXXXXXXXXXX/rec1234567ABCDEFG
+
+❌ Some Artist - Song Title (Lyrics) — lyrics write failed (splitLyricsUpdate retried)
+   https://airtable.com/appeBUkVEp3N4RT0C/tbl0y5XHFXpjUJXHu/viwXXXXXXXXXXXXX/recZZZZZZZZZZZZZZ
+```
 
-- show how many songs are being processed in the current batch
-- confirm each Airtable bulk create/update result (report record IDs created)
-- confirm each lyrics write separately (report `success`, `recordId`, `lyricsWritten` from `push_catalog_to_airtable`)
-- clearly separate Airtable insertion phases from SRT export
-- if a fallback or retry was required, state exactly which step failed and what workaround was used
+If the view ID could not be resolved, omit it from the URL rather than guessing.
 
 ## 10) Tool responsibility summary
 

package/src/scripts/fetch_genius_token.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import axios from 'axios';
+import '../src/utils/config.js';
+
+const TOKEN_ENDPOINT = 'https://api.genius.com/oauth/token';
+
+function printDeploymentBlock(accessToken) {
+  console.log('\n' + '─'.repeat(68));
+  console.log('Token captured successfully!\n');
+  console.log('RECOMMENDED: AUTO-REFRESH (no script needed on redeploy)');
+  console.log('  Set GENIUS_CLIENT_ID and GENIUS_CLIENT_SECRET in your platform');
+  console.log('  dashboard. The server calls the Genius OAuth endpoint at runtime');
+  console.log('  and auto-refreshes the token in memory — no filesystem, no scripts.\n');
+  console.log('LOCAL DEVELOPMENT (cache token)');
+  console.log('  Token written to the cache file above.');
+  console.log('  The server reads it on startup when a writable filesystem is available.\n');
+  console.log('RENDER / EPHEMERAL DEPLOYMENTS (fallback token)');
+  console.log('  If you cannot use client_credentials, set the token as an env var');
+  console.log('  in your platform dashboard. It acts as a static fallback token:\n');
+  console.log(`  GENIUS_ACCESS_TOKEN=${accessToken}\n`);
+  console.log("  Note: static tokens don't auto-refresh. Redeploy with a new token");
+  console.log('  if/when it expires. The client_credentials path avoids this entirely.');
+  console.log('─'.repeat(68) + '\n');
+}
+
+async function main() {
+  const clientId = process.env.GENIUS_CLIENT_ID;
+  const clientSecret = process.env.GENIUS_CLIENT_SECRET;
+  if (!clientId || !clientSecret) {
+    console.error('GENIUS_CLIENT_ID and GENIUS_CLIENT_SECRET must be set in the environment.');
+    process.exit(1);
+  }
+
+  try {
+    const params = new URLSearchParams({
+      client_id: clientId,
+      client_secret: clientSecret,
+      grant_type: 'client_credentials'
+    });
+    const response = await axios.post(TOKEN_ENDPOINT, params.toString(), {
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8'
+      }
+    });
+    const { access_token: accessToken, expires_in: expiresIn } = response.data ?? {};
+    if (!accessToken) {
+      console.error('Response did not include access_token:', response.data);
+      process.exit(1);
+    }
+    console.log('Genius access token refreshed successfully.');
+    console.log(`Expires in: ${expiresIn || 'unknown'} seconds`);
+
+    // Uses the same env var as the server runtime so both read/write the same path.
+    const cachePath = process.env.GENIUS_TOKEN_CACHE || path.resolve('.cache', 'genius-token.json');
+    await mkdir(path.dirname(cachePath), { recursive: true });
+    await writeFile(
+      cachePath,
+      JSON.stringify({
+        access_token: accessToken,
+        expires_at: Date.now() + (expiresIn || 3600) * 1000
+      })
+    );
+    console.log(`\nCache token written to: ${cachePath}`);
+    console.log('(The server reads this file on startup when a writable filesystem is available.)');
+
+    printDeploymentBlock(accessToken);
+  } catch (error) {
+    console.error('Failed to refresh Genius token:', error.response?.data || error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/src/scripts/fetch_musixmatch_token.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { chromium } from 'playwright-chromium';
+import '../src/utils/config.js';
+
+const AUTH_URL = 'https://auth.musixmatch.com/';
+
+async function saveToken(token, desktopCookie) {
+  // Uses the same env var as the server runtime so both read/write the same path.
+  const cachePath =
+    process.env.MUSIXMATCH_TOKEN_CACHE || path.resolve('.cache', 'musixmatch-token.json');
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  const payload = { token };
+  if (desktopCookie) {
+    payload.desktopCookie = desktopCookie;
+  }
+  await writeFile(cachePath, JSON.stringify(payload, null, 2), 'utf8');
+  console.log(`\nCache token written to: ${cachePath}`);
+  console.log('(The server reads this file on startup when a writable filesystem is available.)');
+}
+
+function printDeploymentBlock(tokenValue) {
+  const tokenString =
+    typeof tokenValue === 'string'
+      ? tokenValue
+      : (tokenValue?.message?.body?.usertoken ?? JSON.stringify(tokenValue));
+  console.log('\n' + '─'.repeat(68));
+  console.log('Token captured successfully!\n');
+  console.log('LOCAL DEVELOPMENT (cache token)');
+  console.log('  The token has been written to the cache file above.');
+  console.log('  The server loads it at startup — no further action needed.\n');
+  console.log('RENDER / EPHEMERAL DEPLOYMENTS (fallback token)');
+  console.log('  The filesystem is wiped on restart, so set the token as an');
+  console.log('  environment variable in your platform dashboard instead:\n');
+  console.log(`  MUSIXMATCH_FALLBACK_TOKEN=${tokenString}\n`);
+  console.log('  The server reads MUSIXMATCH_FALLBACK_TOKEN on startup (1st priority)');
+  console.log('  and never touches the cache file on ephemeral hosts.');
+  console.log('─'.repeat(68) + '\n');
+}
+
+async function main() {
+  console.log('Launching Playwright to acquire Musixmatch token...');
+  const browser = await chromium.launch({ headless: process.env.HEADLESS !== 'false' });
+  const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+  const page = await context.newPage();
+
+  console.log('Navigate to Musixmatch login and sign in.');
+  await page.goto(AUTH_URL, { waitUntil: 'domcontentloaded' });
+  console.log('Waiting to be redirected to https://www.musixmatch.com/discover ...');
+  await page.waitForURL('**/discover', { timeout: 0 });
+
+  const cookies = await context.cookies('https://www.musixmatch.com');
+  const userCookie = cookies.find((cookie) => cookie.name === 'musixmatchUserToken');
+  const desktopCookie = cookies.find((cookie) => cookie.name === 'web-desktop-app-v1.0');
+  if (!userCookie) {
+    console.error('musixmatchUserToken cookie not found; ensure you completed login.');
+    process.exit(1);
+  }
+  const decoded = decodeURIComponent(userCookie.value);
+  let parsed;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch (error) {
+    console.error('Unable to parse musixmatchUserToken JSON payload. Raw value:');
+    console.error(decoded);
+    process.exit(1);
+  }
+  console.log('\nMusixmatch token payload:');
+  console.log(JSON.stringify(parsed, null, 2));
+
+  await saveToken(parsed, desktopCookie ? decodeURIComponent(desktopCookie.value) : null);
+
+  // Extract the raw token string for the deployment hint.
+  // The parsed payload is the full musixmatchUserToken JSON object; the server
+  // stores and reads the entire parsed object as the `token` field.
+  printDeploymentBlock(parsed);
+
+  await browser.close();
+}
+
+main().catch((error) => {
+  console.error('Failed to fetch Musixmatch token:', error);
+  process.exit(1);
+});

package/src/scripts/mcp-arg-boundary-repro.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+const endpoint = process.env.MR_MAGIC_MCP_ENDPOINT || 'http://127.0.0.1:3444/mcp';
+let sessionId = null;
+
+async function postJsonRpc(body) {
+  const headers = {
+    'content-type': 'application/json',
+    accept: 'application/json, text/event-stream'
+  };
+  if (sessionId) {
+    headers['mcp-session-id'] = sessionId;
+  }
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body)
+  });
+
+  const responseSessionId = response.headers.get('mcp-session-id');
+  if (responseSessionId) {
+    sessionId = responseSessionId;
+  }
+
+  const text = await response.text();
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = { raw: text };
+  }
+
+  return {
+    status: response.status,
+    ok: response.ok,
+    body: parsed
+  };
+}
+
+async function initializeMcp() {
+  const initializeResponse = await postJsonRpc({
+    jsonrpc: '2.0',
+    id: 0,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: {
+        name: 'mcp-arg-boundary-repro',
+        version: '0.1.0'
+      }
+    }
+  });
+
+  await postJsonRpc({
+    jsonrpc: '2.0',
+    method: 'notifications/initialized',
+    params: {}
+  });
+
+  return initializeResponse;
+}
+
+async function callMcp(id, name, args) {
+  const body = {
+    jsonrpc: '2.0',
+    id,
+    method: 'tools/call',
+    params: {
+      name,
+      arguments: args
+    }
+  };
+
+  return postJsonRpc(body);
+}
+
+function summarize(result) {
+  const json = result.body || {};
+  const isRpcError = Boolean(json?.error);
+  const errorMessage = json?.error?.message || null;
+  return {
+    httpStatus: result.status,
+    ok: result.ok,
+    rpcError: isRpcError,
+    errorMessage
+  };
+}
+
+function printCase(name, payload, result) {
+  console.log(`\n=== ${name} ===`);
+  console.log('request.arguments.type:', Array.isArray(payload) ? 'array' : typeof payload);
+  if (typeof payload === 'string') {
+    console.log('request.arguments.length:', payload.length);
+  }
+  console.log('result:', JSON.stringify(summarize(result), null, 2));
+  console.log('rawBody:', JSON.stringify(result.body, null, 2));
+}
+
+async function run() {
+  console.log('MCP endpoint:', endpoint);
+  const init = await initializeMcp();
+  console.log('initialize:', JSON.stringify(summarize(init), null, 2));
+
+  const caseAArgs = {
+    track: { title: "I'LL SHOW YOU", artist: 'K/DA' },
+    options: { omitInlineLyrics: true, lyricsPayloadMode: 'payload', airtableSafePayload: true }
+  };
+  const caseA = await callMcp(1, 'build_catalog_payload', caseAArgs);
+  printCase('Case A - valid object args (recommended)', caseAArgs, caseA);
+
+  const caseBArgs = '{"track":{"title":"I\'LL SHOW YOU","artist":"K/DA"}';
+  const caseB = await callMcp(2, 'build_catalog_payload', caseBArgs);
+  printCase('Case B - malformed/truncated string args', caseBArgs, caseB);
+
+  const longLyrics = Array.from(
+    { length: 120 },
+    (_, i) => `Line ${String(i + 1).padStart(3, '0')}: I'll show you ✨`
+  ).join('\n');
+  const caseCObject = {
+    match: {
+      provider: 'debug',
+      result: {
+        provider: 'debug',
+        title: "I'LL SHOW YOU",
+        artist: 'K/DA',
+        plainLyrics: longLyrics
+      }
+    }
+  };
+  const caseCStringArgs = JSON.stringify(caseCObject);
+  const caseC = await callMcp(3, 'select_match', caseCStringArgs);
+  printCase('Case C - large multiline payload via string args', caseCStringArgs, caseC);
+
+  const caseD = await callMcp(4, 'select_match', caseCObject);
+  printCase('Case D - large multiline payload via object args (safest)', caseCObject, caseD);
+}
+
+run().catch((error) => {
+  console.error('Repro script failed:', error);
+  process.exit(1);
+});

package/src/scripts/mcp-arg-boundary-sdk-repro.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import {
+  StreamableHTTPClientTransport,
+  StreamableHTTPError
+} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const endpoint = process.env.MR_MAGIC_MCP_ENDPOINT || 'http://127.0.0.1:3444/mcp';
+const debugHttp = process.env.MR_MAGIC_SDK_REPRO_HTTP_DEBUG === '1';
+
+async function loggingFetch(input, init) {
+  const response = await fetch(input, init);
+
+  if (debugHttp) {
+    const method = init?.method || 'GET';
+    const url = typeof input === 'string' ? input : input?.url;
+    const responseClone = response.clone();
+    let responseText = '';
+    try {
+      responseText = await responseClone.text();
+    } catch {
+      responseText = '<failed to read response body>';
+    }
+
+    console.log('\n--- HTTP Debug ---');
+    console.log('request:', JSON.stringify({ method, url }, null, 2));
+    console.log(
+      'response:',
+      JSON.stringify(
+        {
+          status: response.status,
+          ok: response.ok,
+          contentType: response.headers.get('content-type'),
+          mcpSessionId: response.headers.get('mcp-session-id')
+        },
+        null,
+        2
+      )
+    );
+    console.log('responseBodyPreview:', responseText.slice(0, 1200));
+  }
+
+  return response;
+}
+
+function summarizeSuccess(result) {
+  const content = Array.isArray(result?.content) ? result.content : [];
+  const textBlocks = content
+    .filter((block) => block?.type === 'text' && typeof block?.text === 'string')
+    .map((block) => block.text);
+  const firstText = textBlocks[0] || null;
+
+  return {
+    transportError: false,
+    toolReportedError: Boolean(result?.isError),
+    hasStructuredContent: Boolean(result?.structuredContent),
+    contentBlocks: content.length,
+    firstTextPreview: firstText ? firstText.slice(0, 200) : null
+  };
+}
+
+function summarizeFailure(error) {
+  const isStreamableHttpError = error instanceof StreamableHTTPError;
+  return {
+    transportError: true,
+    type: error?.name || 'Error',
+    message: error?.message || String(error),
+    httpCode: isStreamableHttpError ? error.code : null
+  };
+}
+
+function printCase(name, payload, response) {
+  console.log(`\n=== ${name} ===`);
+  console.log('request.arguments.type:', Array.isArray(payload) ? 'array' : typeof payload);
+  if (typeof payload === 'string') {
+    console.log('request.arguments.length:', payload.length);
+  }
+
+  if (response.ok) {
+    console.log('summary:', JSON.stringify(summarizeSuccess(response.result), null, 2));
+    console.log('rawResult:', JSON.stringify(response.result, null, 2));
+    return;
+  }
+
+  console.log('summary:', JSON.stringify(summarizeFailure(response.error), null, 2));
+  console.log(
+    'rawError:',
+    JSON.stringify(response.error, Object.getOwnPropertyNames(response.error || {}), 2)
+  );
+}
+
+async function runCase(client, id, title, toolName, args) {
+  try {
+    const result = await client.callTool({
+      name: toolName,
+      arguments: args
+    });
+    return { ok: true, id, title, result };
+  } catch (error) {
+    return { ok: false, id, title, error };
+  }
+}
+
+async function run() {
+  console.log('MCP endpoint:', endpoint);
+
+  const client = new Client(
+    { name: 'mcp-arg-boundary-sdk-repro', version: '0.1.0' },
+    { capabilities: {} }
+  );
+
+  const transport = new StreamableHTTPClientTransport(new URL(endpoint), {
+    fetch: loggingFetch
+  });
+  transport.onerror = (error) => {
+    console.error('[transport.onerror]', error);
+  };
+
+  await client.connect(transport);
+  console.log('connect: ok');
+
+  const tools = await client.listTools();
+  console.log(
+    'listTools:',
+    JSON.stringify(
+      {
+        toolCount: Array.isArray(tools?.tools) ? tools.tools.length : 0,
+        toolNames: Array.isArray(tools?.tools) ? tools.tools.map((tool) => tool.name) : []
+      },
+      null,
+      2
+    )
+  );
+
+  const caseAArgs = {
+    track: { title: "I'LL SHOW YOU", artist: 'K/DA' },
+    options: { omitInlineLyrics: true, lyricsPayloadMode: 'payload', airtableSafePayload: true }
+  };
+  const caseA = await runCase(
+    client,
+    1,
+    'Case A - valid object args (recommended)',
+    'build_catalog_payload',
+    caseAArgs
+  );
+  printCase(caseA.title, caseAArgs, caseA);
+
+  const caseBArgs = '{"track":{"title":"I\'LL SHOW YOU","artist":"K/DA"}';
+  const caseB = await runCase(
+    client,
+    2,
+    'Case B - malformed/truncated string args',
+    'build_catalog_payload',
+    caseBArgs
+  );
+  printCase(caseB.title, caseBArgs, caseB);
+
+  const longLyrics = Array.from(
+    { length: 120 },
+    (_, i) => `Line ${String(i + 1).padStart(3, '0')}: I'll show you ✨`
+  ).join('\n');
+  const caseCObject = {
+    match: {
+      provider: 'debug',
+      result: {
+        provider: 'debug',
+        title: "I'LL SHOW YOU",
+        artist: 'K/DA',
+        plainLyrics: longLyrics
+      }
+    }
+  };
+
+  const caseCStringArgs = JSON.stringify(caseCObject);
+  const caseC = await runCase(
+    client,
+    3,
+    'Case C - large multiline payload via string args',
+    'select_match',
+    caseCStringArgs
+  );
+  printCase(caseC.title, caseCStringArgs, caseC);
+
+  const caseD = await runCase(
+    client,
+    4,
+    'Case D - large multiline payload via object args (safest)',
+    'select_match',
+    caseCObject
+  );
+  printCase(caseD.title, caseCObject, caseD);
+
+  try {
+    await transport.terminateSession();
+  } catch {
+    // Session termination is optional and may be unsupported in sessionless mode.
+  }
+
+  await client.close();
+}
+
+run().catch((error) => {
+  console.error('SDK repro script failed:', error);
+  process.exit(1);
+});

package/src/tests/mcp-tools.test.js

@@ -0,0 +1,251 @@
+import assert from 'node:assert/strict';
+
+import { mcpToolDefinitions, handleMcpTool } from '../src/transport/mcp-tools.js';
+import { buildMcpResponse } from '../src/transport/mcp-response.js';
+
+const sampleTrack = {
+  title: 'Kill This Love',
+  artist: 'BLACKPINK'
+};
+
+async function testToolRegistry() {
+  const toolNames = mcpToolDefinitions.map((tool) => tool.name);
+  const expected = [
+    'find_lyrics',
+    'build_catalog_payload',
+    'find_synced_lyrics',
+    'search_lyrics',
+    'search_provider',
+    'get_provider_status',
+    'export_lyrics',
+    'format_lyrics',
+    'select_match',
+    'runtime_status'
+  ];
+  expected.forEach((tool) => {
+    assert.ok(toolNames.includes(tool), `expected tool ${tool}`);
+  });
+}
+
+async function testFindLyricsTool() {
+  const payload = await handleMcpTool('find_lyrics', { track: sampleTrack });
+  assert.ok(payload?.best, 'find_lyrics should return best match');
+}
+
+async function testFindLyricsAllowsPartialTrack() {
+  const payload = await handleMcpTool('find_lyrics', { track: { title: sampleTrack.title } });
+  assert.ok(payload?.matches?.length > 0, 'find_lyrics should tolerate partial track metadata');
+  const firstResult = payload.matches[0]?.result;
+  assert.ok(
+    firstResult && Object.prototype.hasOwnProperty.call(firstResult, 'providerId'),
+    'normalized match results should expose providerId'
+  );
+}
+
+async function testFindSyncedLyricsTool() {
+  const payload = await handleMcpTool('find_synced_lyrics', { track: sampleTrack });
+  assert.ok(payload);
+}
+
+async function testSearchProviderRequiresProvider() {
+  await assert.rejects(
+    () => handleMcpTool('search_provider', { track: sampleTrack }),
+    /provider is required/
+  );
+}
+
+async function testSearchProviderReturnsArray() {
+  const results = await handleMcpTool('search_provider', {
+    provider: 'lrclib',
+    track: sampleTrack
+  });
+  assert.ok(Array.isArray(results));
+}
+
+async function testFormatLyricsShape() {
+  const response = await handleMcpTool('format_lyrics', {
+    track: sampleTrack,
+    options: { includeSynced: false }
+  });
+  assert.ok(response?.formatted || response?.error, 'format_lyrics should format or report error');
+}
+
+async function testBuildCatalogPayload() {
+  const response = await handleMcpTool('build_catalog_payload', {
+    track: sampleTrack,
+    options: { preferRomanized: false }
+  });
+  assert.ok(response?.songVideoTitle, 'catalog payload should include songVideoTitle');
+  assert.ok(response?.lyrics, 'catalog payload should include lyrics');
+  assert.ok(response?.provider, 'catalog payload should include provider info');
+}
+
+async function testBuildCatalogPayloadWithLyricsPayload() {
+  const response = await handleMcpTool('build_catalog_payload', {
+    track: sampleTrack,
+    options: {
+      preferRomanized: false,
+      omitInlineLyrics: true,
+      lyricsPayloadMode: 'payload'
+    }
+  });
+
+  assert.ok(!response?.lyrics, 'inline lyrics should be omitted');
+  assert.ok(response?.lyricsPayload, 'lyricsPayload bundle should exist');
+  assert.equal(response.lyricsPayload.contentType, 'text/plain');
+
+  if (response.lyricsPayload.transport === 'inline') {
+    assert.ok(response.lyricsPayload.preview?.length > 0, 'preview should be populated');
+    assert.ok(response.lyricsPayload.content?.length > 0, 'inline payload should include content');
+  } else {
+    assert.equal(
+      response.lyricsPayload.transport,
+      'reference',
+      'payload mode should only resolve to inline or reference transport'
+    );
+    assert.ok(
+      response.lyricsPayload.reference,
+      'reference transport should include reference metadata'
+    );
+  }
+}
+
+async function testBuildCatalogPayloadWithAirtableSafePayload() {
+  const response = await handleMcpTool('build_catalog_payload', {
+    track: sampleTrack,
+    options: {
+      preferRomanized: false,
+      omitInlineLyrics: true,
+      lyricsPayloadMode: 'payload',
+      airtableSafePayload: true
+    }
+  });
+
+  assert.ok(
+    response?.lyricsPayload?.airtableEscapedContent,
+    'Airtable escaped content should exist'
+  );
+  assert.equal(response.lyricsPayload.transportRequested, 'inline');
+  assert.equal(response.lyricsPayload.compact, true);
+  assert.ok(!response.lyrics, 'inline lyrics should stay omitted');
+  assert.ok(
+    response.lyricsPayload.airtableEscapedContent.includes('\\n'),
+    'escaped content should include literal \\n'
+  );
+}
+
+async function testSelectMatchErrors() {
+  const response = await handleMcpTool('select_match', { matches: [] });
+  assert.equal(response.error, 'No matches provided');
+}
+
+async function testRuntimeStatusIncludesEnvOverview() {
+  const response = await handleMcpTool('runtime_status');
+  assert.ok(Array.isArray(response?.providers));
+  assert.ok(Array.isArray(response?.env));
+}
+
+async function testMcpResponseHandlesMultilineLyrics() {
+  const lyricBlob = `This line has quotes "like this" and commas,
+and spans multiple lines,
+ending with unicode ♥`;
+  const result = {
+    provider: 'test-provider',
+    track: { title: 'Sample', artist: 'Tester' },
+    lyrics: lyricBlob,
+    extras: { airtableEscapedContent: 'Line 1\nLine 2\nLine 3' }
+  };
+  const response = buildMcpResponse(result);
+  assert.equal(
+    response.structuredContent,
+    result,
+    'structuredContent should pass through original object'
+  );
+  const primaryText = response.content?.[0]?.text;
+  assert.ok(
+    primaryText?.includes('This line has quotes "like this"'),
+    'lyric payload responses should expose full JSON as first content item'
+  );
+  assert.equal(
+    response.content?.length,
+    1,
+    'lyric payload responses should omit secondary summary preview text'
+  );
+}
+
+async function testMcpResponseHandlesStringResults() {
+  const lyricString = 'Line 1\nLine 2\nLine 3 "quoted"';
+  const response = buildMcpResponse(lyricString);
+  assert.deepEqual(
+    response.structuredContent,
+    { value: lyricString },
+    'structuredContent should wrap string payloads'
+  );
+  const summary = response.content?.[0]?.text;
+  assert.ok(
+    typeof summary === 'string' && summary.length > 0,
+    'summary text should exist for strings'
+  );
+  assert.ok(summary.includes('Line 1'), 'summary should include first line of lyrics');
+}
+
+async function testMcpResponsePreservesArrayResults() {
+  const items = [{ provider: 'lrclib', result: { title: 'Song' } }];
+  const response = buildMcpResponse(items);
+  assert.deepEqual(
+    response.structuredContent,
+    { items },
+    'structuredContent should wrap array payloads for MCP tools'
+  );
+  assert.ok(
+    response.content?.[1]?.text.includes('lrclib'),
+    'raw JSON content should include serialized array data'
+  );
+}
+
+async function testExportLyricsReturnsFileUrl() {
+  const response = await handleMcpTool('export_lyrics', {
+    track: sampleTrack,
+    options: { formats: ['plain'] }
+  });
+
+  const plainExport = response?.exports?.plain;
+  if (plainExport && !plainExport.skipped) {
+    assert.ok(
+      plainExport.filePath || plainExport.url,
+      'plain export should include either filePath or url depending on storage backend'
+    );
+    if (plainExport.filePath) {
+      assert.ok(plainExport.url?.startsWith('file://'), 'local exports should include file URL');
+    } else {
+      assert.ok(
+        typeof plainExport.url === 'string' && plainExport.url.length > 0,
+        'remote exports should include url'
+      );
+    }
+  }
+}
+
+async function run() {
+  await testToolRegistry();
+  await testFindLyricsTool();
+  await testFindLyricsAllowsPartialTrack();
+  await testFindSyncedLyricsTool();
+  await testSearchProviderRequiresProvider();
+  await testSearchProviderReturnsArray();
+  await testFormatLyricsShape();
+  await testBuildCatalogPayload();
+  await testBuildCatalogPayloadWithLyricsPayload();
+  await testBuildCatalogPayloadWithAirtableSafePayload();
+  await testSelectMatchErrors();
+  await testRuntimeStatusIncludesEnvOverview();
+  await testMcpResponseHandlesMultilineLyrics();
+  await testMcpResponseHandlesStringResults();
+  await testMcpResponsePreservesArrayResults();
+  await testExportLyricsReturnsFileUrl();
+}
+
+run().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/tests/run-tests.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+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 { mcpToolDefinitions, handleMcpTool } from '../transport/mcp-tools.js';
+
+const divider = () => console.log('\n---');
+
+function mockRecord({
+  provider,
+  synced = false,
+  confidence = 0.5,
+  title = 'Song',
+  artist = 'Artist',
+  plainLyrics = synced ? null : 'plain',
+  syncedLyrics = synced ? '[00:00.00] synced line\n[00:01.00] next' : null
+}) {
+  return {
+    provider,
+    result: {
+      provider,
+      synced,
+      confidence,
+      title,
+      artist,
+      plainLyrics,
+      syncedLyrics
+    }
+  };
+}
+
+function testAutoPickPrefersSynced() {
+  const matches = [
+    mockRecord({ provider: 'plain', synced: false }),
+    mockRecord({ provider: 'synced', synced: true })
+  ];
+  const chooser = buildChooserEntries(matches);
+  const picked = autoPick(chooser, true);
+  assert.equal(picked.provider, 'synced');
+  divider();
+  console.log('autoPick prefers synced: ok');
+}
+
+function testAutoPickFallbackWhenNoSynced() {
+  const matches = [
+    mockRecord({ provider: 'plainA', synced: false }),
+    mockRecord({ provider: 'plainB', synced: false })
+  ];
+  const chooser = buildChooserEntries(matches);
+  const picked = autoPick(chooser, true);
+  assert.equal(picked.provider, 'plainA');
+  divider();
+  console.log('autoPick fallback first result: ok');
+}
+
+function testSelectMatchRespectsProviderAndSynced() {
+  const matches = [
+    { provider: 'lrclib', result: { synced: true } },
+    { provider: 'genius', result: { synced: false } }
+  ];
+  const syncedOnly = selectMatch(matches, { requireSynced: true });
+  assert.equal(syncedOnly.provider, 'lrclib');
+  const filtered = selectMatch(matches, { providerName: 'genius' });
+  assert.equal(filtered.provider, 'genius');
+  divider();
+  console.log('selectMatch provider/synced filtering: ok');
+}
+
+function testNormalizationDetectsSyncedState() {
+  const raw = {
+    provider: 'test',
+    id: '1',
+    trackName: 'Song',
+    artistName: 'Artist',
+    syncedLyrics: '[00:00.00] hi\n[00:02.00] bye',
+    plainLyrics: 'hi\nbye',
+    confidence: 0.5
+  };
+  const normalized = normalizeLyricRecord(raw);
+  assert.equal(normalized.synced, true);
+  assert.equal(normalized.plainOnly, false);
+  const { hasSynced, timestampCount } = detectSyncedState('[00:00.00] hi');
+  assert.equal(hasSynced, false);
+  assert.equal(timestampCount, 1);
+  divider();
+  console.log('normalize/detect synced state: ok');
+}
+
+async function run() {
+  testAutoPickPrefersSynced();
+  testAutoPickFallbackWhenNoSynced();
+  testSelectMatchRespectsProviderAndSynced();
+  testNormalizationDetectsSyncedState();
+  const toolNames = mcpToolDefinitions.map((tool) => tool.name);
+  console.log('MCP tooling available:', toolNames.join(', '));
+  console.log('All sanity checks passed');
+}
+
+run().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

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

@@ -87,7 +87,15 @@ function createMcpServer() {
 export async function startMcpHttpServer(options = {}) {
   const logger = createLogger('mcp-http-server');
   const httpDiagnostics = process.env.MR_MAGIC_MCP_HTTP_DIAGNOSTICS === '1';
-  const configuredSessionless = Boolean(options.sessionless);
+  // Sessionless mode: skip persistent in-memory session tracking so every
+  // request is handled independently.  This is required on platforms like
+  // Render.com that run multiple instances (a session created on instance A is
+  // invisible to instance B).  Auto-enable when the RENDER env var is present,
+  // or when MR_MAGIC_SESSIONLESS=1 is set explicitly.
+  const configuredSessionless =
+    Boolean(options.sessionless) ||
+    Boolean(process.env.MR_MAGIC_SESSIONLESS) ||
+    Boolean(process.env.RENDER);
   const host = options.remote
     ? '0.0.0.0'
     : options.host || process.env.HOST || (process.env.RENDER ? '0.0.0.0' : '127.0.0.1');

package/src/utils/tokens/genius-token-manager.js

@@ -23,7 +23,7 @@ const logger = createLogger('genius-token-manager');
 //                      (i.e. local development). Ephemeral hosts (Render free tier, etc.)
 //                      should use the auto-refresh or fallback token paths instead.
 
-// Token cache path — must match the path used by scripts/fetch_genius_token.mjs.
+// Token cache path — must match the path used by src/scripts/fetch_genius_token.mjs.
 const TOKEN_CACHE_PATH =
   process.env.GENIUS_TOKEN_CACHE || path.join(getProjectRoot(), '.cache', 'genius-token.json');