mcp-lyricscom 1.2.0 → 1.4.0

package/README.md

@@ -4,6 +4,7 @@
 [![CI](https://github.com/smeet666/mcp-lyricscom/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-lyricscom/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/mcp-lyricscom.svg)](./LICENSE)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.smeet666/mcp-lyricscom)
+[![Glama](https://glama.ai/mcp/servers/smeet666/mcp-lyricscom/badges/score.svg)](https://glama.ai/mcp/servers/smeet666/mcp-lyricscom)
 
 An [MCP](https://modelcontextprotocol.io) server for [lyrics.com](https://www.lyrics.com).
 Search songs by a word in their lyrics, by title, and read the full text.
@@ -41,6 +42,14 @@ claude mcp add lyricscom -- npx -y mcp-lyricscom
 
 That is the whole setup. There is nothing to sign up for.
 
+**Bundle, without npm**
+
+Download `mcp-lyricscom-<version>.mcpb` from
+[the latest release](https://github.com/smeet666/mcp-lyricscom/releases/latest) and open
+it. A client that supports MCP bundles installs it on its own, with no npm and
+no configuration file to edit. The bundle carries its dependencies, so nothing
+is fetched at install time.
+
 ## Tools
 
 | Tool            | What it does                                                                                 | Key parameters                                        |
@@ -240,6 +249,14 @@ claude mcp add lyricscom -- npx -y mcp-lyricscom
 
 C'est toute l'installation. Il n'y a aucune inscription.
 
+**Bundle, sans npm**
+
+Téléchargez `mcp-lyricscom-<version>.mcpb` depuis
+[la dernière release](https://github.com/smeet666/mcp-lyricscom/releases/latest) et
+ouvrez-le. Un client compatible avec les bundles MCP l'installe seul, sans npm
+ni fichier de configuration à modifier. Le bundle embarque ses dépendances,
+donc rien n'est téléchargé à l'installation.
+
 ## Outils
 
 | Outil           | Rôle                                                                                                                | Paramètres principaux                                 |

package/dist/index.js

@@ -4,7 +4,7 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/version.ts
-var PKG_VERSION = "1.2.0";
+var PKG_VERSION = "1.4.0";
 var REPO_URL = "https://github.com/smeet666/mcp-lyricscom";
 
 // src/config.ts
@@ -108,7 +108,7 @@ function createLogger(level) {
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // src/lyricscom/cache.ts
 var TtlLruCache = class {
@@ -679,7 +679,7 @@ var LyricsComClient = class {
 };
 
 // src/tools/getLyrics.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/text/keywordIndex.ts
 var WORD_DELIMITERS = "[\\s,;:'\".!?()\\[\\]&\u2019`@-]";
@@ -734,17 +734,69 @@ function matchedLineExcerpt(text, keyword, options = {}) {
   return `${start > 0 ? "\u2026" : ""}${slice}${end < line.length ? "\u2026" : ""}`;
 }
 
-// src/tools/shared.ts
+// src/tools/arguments.ts
 import { z } from "zod";
+var INVALID_INPUT = "invalid_input";
+function strictInput(shape) {
+  const declared = Object.keys(shape);
+  const errorMap = (issue, ctx) => issue.code === z.ZodIssueCode.unrecognized_keys ? { message: unknownArgumentMessage(issue.keys, declared) } : { message: ctx.defaultError };
+  return z.strictObject(shape, { errorMap });
+}
+function unknownArgumentMessage(keys, declared) {
+  const named = keys.map((key) => {
+    const near = nearestArgument(key, declared);
+    return near ? `'${key}' (did you mean '${near}'?)` : `'${key}'`;
+  }).join(", ");
+  return `[${INVALID_INPUT}] Unknown ${keys.length > 1 ? "arguments" : "argument"} ${named}. This tool takes: ${declared.join(", ")}.`;
+}
+function nearestArgument(key, declared) {
+  const flatten = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const flat = flatten(key);
+  if (flat.length === 0) return void 0;
+  const sameName = declared.find((name) => flatten(name) === flat);
+  if (sameName) return sameName;
+  const overlapping = declared.find((name) => {
+    const other = flatten(name);
+    const [shorter, longer] = other.length < flat.length ? [other, flat] : [flat, other];
+    return shorter.length >= 3 && (longer.startsWith(shorter) || longer.endsWith(shorter));
+  });
+  if (overlapping) return overlapping;
+  let closest;
+  let shortest = Number.POSITIVE_INFINITY;
+  for (const name of declared) {
+    const distance = editDistance(flat, flatten(name));
+    if (distance < shortest) {
+      shortest = distance;
+      closest = name;
+    }
+  }
+  return shortest <= Math.max(1, Math.floor(flat.length / 3)) ? closest : void 0;
+}
+function editDistance(left, right) {
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let row = 1; row <= left.length; row += 1) {
+    const current = [row];
+    for (let column = 1; column <= right.length; column += 1) {
+      const substitution = previous[column - 1] + (left[row - 1] === right[column - 1] ? 0 : 1);
+      current[column] = Math.min(substitution, previous[column] + 1, current[column - 1] + 1);
+    }
+    previous = current;
+  }
+  return previous[right.length];
+}
+
+// src/tools/shared.ts
+import { z as z2 } from "zod";
 var MAX_TEXT_MIRROR_CHARS = 1500;
-var songResultSchema = z.object({
-  id: z.string().describe("lyrics.com song id. Pass this to get_lyrics."),
-  title: z.string(),
-  artist: z.string(),
-  album: z.string().nullable(),
-  year: z.number().int().nullable(),
-  source_url: z.string().describe("Canonical lyrics.com page for this song."),
-  excerpt: z.string().nullable().describe("Short lyric line showing where the query appears, when available.")
+var MAX_PAGE = 20;
+var songResultSchema = z2.object({
+  id: z2.string().describe("lyrics.com song id. Pass this to get_lyrics."),
+  title: z2.string(),
+  artist: z2.string(),
+  album: z2.string().nullable(),
+  year: z2.number().int().nullable(),
+  source_url: z2.string().describe("Canonical lyrics.com page for this song."),
+  excerpt: z2.string().nullable().describe("Short lyric line showing where the query appears, when available.")
 });
 function toSongResultOut(song, excerpt) {
   return {
@@ -757,9 +809,17 @@ function toSongResultOut(song, excerpt) {
     excerpt
   };
 }
-function ok(structured, text) {
+function indentMarkerLines(body) {
+  return body.replace(/^(Note:)/gm, " $1");
+}
+function ok(structured, text, notes = []) {
+  const trailer = notes.map((note) => `Note: ${note}`).join("\n");
+  const budget = MAX_TEXT_MIRROR_CHARS - (trailer ? trailer.length + 2 : 0);
+  const body = truncate(indentMarkerLines(text), Math.max(0, budget));
   return {
-    content: [{ type: "text", text: truncate(text, MAX_TEXT_MIRROR_CHARS) }],
+    content: [{ type: "text", text: trailer ? `${body}
+
+${trailer}` : body }],
     structuredContent: structured
   };
 }
@@ -793,38 +853,39 @@ var getLyricsDescription = [
   "lyrics field, which is a valid answer and not an error, so do not retry them.",
   "Always cite 'source_url' and the artist when showing lyrics to a user."
 ].join(" ");
-var getLyricsInputShape = {
-  id: z2.string().regex(/^\d+$/, "Song ids are digits only.").optional().describe("lyrics.com numeric song id, as returned by the search tools. Preferred over 'url'."),
-  url: z2.string().url().optional().describe(
+var getLyricsInput = strictInput({
+  id: z3.string().regex(/^\d+$/, "Song ids are digits only.").optional().describe("lyrics.com numeric song id, as returned by the search tools. Preferred over 'url'."),
+  url: z3.string().url().optional().describe(
     "Full lyrics.com song URL. Only www.lyrics.com URLs are accepted. Ignored when 'id' is given."
   ),
-  max_chars: z2.number().int().min(200).max(2e4).default(6e3).describe("Maximum characters of lyrics text to return in this call."),
-  offset: z2.number().int().min(0).default(0).describe("Character offset to resume from, for lyrics longer than max_chars."),
-  highlight: z2.string().max(120).optional().describe(
+  max_chars: z3.number().int().min(200).max(2e4).default(6e3).describe("Maximum characters of lyrics text to return in this call."),
+  offset: z3.number().int().min(0).default(0).describe("Character offset to resume from, for lyrics longer than max_chars."),
+  highlight: z3.string().max(120).optional().describe(
     "Optional word. When set, the response reports whether it appears in the lyrics and on which line."
   )
-};
+});
 var getLyricsOutputShape = {
-  status: z2.enum(["ok", "no_lyrics"]),
-  id: z2.string(),
-  title: z2.string().nullable(),
-  artist: z2.string().nullable(),
-  source_url: z2.string(),
-  lyrics: z2.string().describe("Slice of the lyrics text. Empty when status is 'no_lyrics'."),
-  total_chars: z2.number().int(),
-  returned_chars: z2.number().int(),
-  offset: z2.number().int(),
-  next_offset: z2.number().int().nullable(),
-  truncated: z2.boolean(),
-  line_count: z2.number().int(),
-  highlight: z2.object({
-    word: z2.string(),
-    found: z2.boolean(),
-    line_number: z2.number().int().nullable(),
-    line: z2.string().nullable()
+  status: z3.enum(["ok", "no_lyrics"]),
+  id: z3.string(),
+  title: z3.string().nullable(),
+  artist: z3.string().nullable(),
+  source_url: z3.string(),
+  lyrics: z3.string().describe("Slice of the lyrics text. Empty when status is 'no_lyrics'."),
+  total_chars: z3.number().int(),
+  returned_chars: z3.number().int(),
+  offset: z3.number().int(),
+  next_offset: z3.number().int().nullable(),
+  truncated: z3.boolean(),
+  line_count: z3.number().int(),
+  highlight: z3.object({
+    word: z3.string(),
+    found: z3.boolean(),
+    line_number: z3.number().int().nullable(),
+    line: z3.string().nullable()
   }).nullable(),
-  attribution: z2.string().describe("Ready-to-display credit line."),
-  source: z2.literal("lyrics.com")
+  attribution: z3.string().describe("Ready-to-display credit line."),
+  source: z3.literal("lyrics.com"),
+  notes: z3.array(z3.string())
 };
 function sliceAtLineBoundary(text, offset, maxChars) {
   if (offset >= text.length) return { slice: "", nextOffset: null };
@@ -840,7 +901,9 @@ async function runGetLyrics(client, args) {
     const ref = {};
     if (args.id) ref.id = args.id;
     else if (args.url) ref.url = args.url;
-    const { data } = await client.getSong(ref);
+    const { data, cached } = await client.getSong(ref);
+    const notes = [];
+    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
     const credit = [data.title, data.artist].filter(Boolean).join(" \u2014 ");
     const attribution = `${credit || "Lyrics"} via lyrics.com \u2014 ${data.url}`;
     if (!data.hasLyrics) {
@@ -856,6 +919,7 @@ async function runGetLyrics(client, args) {
         offset: 0,
         next_offset: null,
         truncated: false,
+        notes,
         line_count: 0,
         highlight: null,
         attribution,
@@ -889,24 +953,31 @@ ${attribution}`
         line: match?.line ?? null
       } : null,
       attribution,
-      source: "lyrics.com"
+      source: "lyrics.com",
+      notes
     };
+    const pastTheEnd = args.offset > 0 && slice === "" && data.lyrics.length > 0;
+    if (pastTheEnd) {
+      notes.push(
+        `offset=${args.offset} is past the end of a body of ${data.lyrics.length} characters. Call again with offset=0 to read it from the start.`
+      );
+    }
     const summary = [
       attribution,
       `${structured.line_count} lines, ${structured.total_chars} characters.`,
-      nextOffset !== null ? `Truncated: call again with offset=${nextOffset} to continue.` : "Complete.",
+      pastTheEnd ? `Nothing at offset=${args.offset}: that is past the end. Call again with offset=0.` : nextOffset !== null ? `Truncated: call again with offset=${nextOffset} to continue.` : "Complete.",
       structured.highlight ? structured.highlight.found ? `"${structured.highlight.word}" appears on line ${structured.highlight.line_number}.` : `"${structured.highlight.word}" does not appear in these lyrics.` : ""
     ].filter(Boolean).join("\n");
     return ok(structured, truncate(`${summary}
 
-${slice}`, 4e3));
+${slice}`, 4e3), notes);
   } catch (error) {
     return toToolError(error);
   }
 }
 
 // src/tools/searchLyrics.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/text/dedupe.ts
 function songKey(artist, title) {
@@ -938,25 +1009,25 @@ var searchLyricsDescription = [
   "lyrics.com also returns loose and title-only matches, so results are filtered locally to keep only songs",
   `where the word genuinely appears in the lyrics. Set 'verify' to "none" to see the raw, unfiltered list.`
 ].join(" ");
-var searchLyricsInputShape = {
-  query: z3.string().min(1).max(120).describe("Word or short phrase to look for inside the lyrics, for example 'autrefois'."),
-  limit: z3.number().int().min(1).max(50).default(10).describe("Maximum songs to return from this page."),
-  page: z3.number().int().min(1).max(20).default(1).describe("Result page on lyrics.com. Each page holds up to 24 raw results."),
-  verify: z3.enum(["snippet", "full", "none"]).default("snippet").describe(
+var searchLyricsInput = strictInput({
+  query: z4.string().min(1).max(120).describe("Word or short phrase to look for inside the lyrics, for example 'autrefois'."),
+  limit: z4.number().int().min(1).max(50).default(10).describe("Maximum songs to return from this page."),
+  page: z4.number().int().min(1).max(20).default(1).describe("Result page on lyrics.com. Each page holds up to 24 raw results."),
+  verify: z4.enum(["snippet", "full", "none"]).default("snippet").describe(
     "How to confirm the query really appears in the lyrics. 'snippet' checks the excerpt lyrics.com already returned and costs nothing. 'full' fetches up to 5 song pages and checks the complete lyrics, which is slow and can trigger rate limiting. 'none' disables filtering."
   ),
-  include_excerpt: z3.boolean().default(true).describe("Include the matching lyric line excerpt in each result.")
-};
+  include_excerpt: z4.boolean().default(true).describe("Include the matching lyric line excerpt in each result.")
+});
 var searchLyricsOutputShape = {
-  query: z3.string(),
-  page: z3.number().int(),
-  results: z3.array(songResultSchema),
-  raw_result_count: z3.number().int().describe("Rows lyrics.com returned before local filtering and deduplication."),
-  filtered_out: z3.number().int().describe("Rows dropped because the query was not found in their lyrics."),
-  has_more: z3.boolean(),
-  next_page: z3.number().int().nullable(),
-  source: z3.literal("lyrics.com"),
-  notes: z3.array(z3.string()).describe("Caveats worth knowing, such as a cache hit or partial verification.")
+  query: z4.string(),
+  page: z4.number().int(),
+  results: z4.array(songResultSchema),
+  raw_result_count: z4.number().int().describe("Rows lyrics.com returned before local filtering and deduplication."),
+  filtered_out: z4.number().int().describe("Rows dropped because the query was not found in their lyrics."),
+  has_more: z4.boolean(),
+  next_page: z4.number().int().nullable(),
+  source: z4.literal("lyrics.com"),
+  notes: z4.array(z4.string()).describe("Caveats worth knowing, such as a cache hit or partial verification.")
 };
 async function runSearchLyrics(client, args) {
   try {
@@ -1006,14 +1077,16 @@ async function runSearchLyrics(client, args) {
       raw_result_count: data.rawCount,
       filtered_out: filteredOut,
       has_more: data.hasMore,
-      next_page: data.hasMore ? args.page + 1 : null,
+      next_page: data.hasMore && args.page < MAX_PAGE ? args.page + 1 : null,
       source: "lyrics.com",
       notes
     };
     const header = results.length > 0 ? `${results.length} song(s) on page ${args.page} for "${args.query}":` : `No song on page ${args.page} matched "${args.query}".`;
-    const footer = data.hasMore ? `
+    const footer = data.hasMore && args.page < MAX_PAGE ? `
+
+More results available: call again with page=${args.page + 1}.` : data.hasMore ? `
 
-More results available: call again with page=${args.page + 1}.` : "";
+lyrics.com holds more, but page ${MAX_PAGE} is as far as this tool reads. Narrow the query instead.` : "";
     return ok(structured, `${header}
 ${renderResultList(results)}${footer}`);
   } catch (error) {
@@ -1022,7 +1095,7 @@ ${renderResultList(results)}${footer}`);
 }
 
 // src/tools/searchSongs.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var searchSongsDescription = [
   "Find songs on lyrics.com by their title.",
   "Returns candidate songs with artist, album, year, and the lyrics.com id and URL.",
@@ -1031,26 +1104,26 @@ var searchSongsDescription = [
   "lyrics.com searches titles and lyrics together, so results are ranked and filtered locally by title match;",
   'use match="strict" to keep only genuine title matches.'
 ].join(" ");
-var searchSongsInputShape = {
-  title: z4.string().min(1).max(120).describe("Song title, or part of it."),
-  artist: z4.string().max(120).optional().describe("Optional artist name, matched case-insensitively against each result."),
-  limit: z4.number().int().min(1).max(50).default(10),
-  page: z4.number().int().min(1).max(20).default(1),
-  match: z4.enum(["loose", "strict"]).default("loose").describe(
+var searchSongsInput = strictInput({
+  title: z5.string().min(1).max(120).describe("Song title, or part of it."),
+  artist: z5.string().max(120).optional().describe("Optional artist name, matched case-insensitively against each result."),
+  limit: z5.number().int().min(1).max(50).default(10),
+  page: z5.number().int().min(1).max(20).default(1),
+  match: z5.enum(["loose", "strict"]).default("loose").describe(
     "'strict' keeps only results whose title matches the query as a whole title, ignoring suffixes such as '(Remastered)'. 'loose' keeps anything lyrics.com returned, best match first."
   )
-};
+});
 var searchSongsOutputShape = {
-  title: z4.string(),
-  artist_filter: z4.string().nullable(),
-  page: z4.number().int(),
-  results: z4.array(songResultSchema),
-  raw_result_count: z4.number().int(),
-  filtered_out: z4.number().int(),
-  has_more: z4.boolean(),
-  next_page: z4.number().int().nullable(),
-  source: z4.literal("lyrics.com"),
-  notes: z4.array(z4.string())
+  title: z5.string(),
+  artist_filter: z5.string().nullable(),
+  page: z5.number().int(),
+  results: z5.array(songResultSchema),
+  raw_result_count: z5.number().int(),
+  filtered_out: z5.number().int(),
+  has_more: z5.boolean(),
+  next_page: z5.number().int().nullable(),
+  source: z5.literal("lyrics.com"),
+  notes: z5.array(z5.string())
 };
 function normalizeTitle(title) {
   return title.replace(/\s*[[(].*?[\])]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
@@ -1097,16 +1170,24 @@ async function runSearchSongs(client, args) {
       raw_result_count: data.rawCount,
       filtered_out: filteredOut,
       has_more: data.hasMore,
-      next_page: data.hasMore ? args.page + 1 : null,
+      next_page: data.hasMore && args.page < MAX_PAGE ? args.page + 1 : null,
       source: "lyrics.com",
       notes
     };
-    const header = results.length > 0 ? `${results.length} song(s) on page ${args.page} matching "${args.title}":` : `No song on page ${args.page} matched "${args.title}".`;
-    const footer = data.hasMore ? `
+    const loose = args.match !== "strict";
+    const header = results.length > 0 ? loose ? `${results.length} song(s) lyrics.com offers on page ${args.page} for "${args.title}":` : `${results.length} song(s) on page ${args.page} matching "${args.title}":` : `No song on page ${args.page} matched "${args.title}".`;
+    const footer = data.hasMore && args.page < MAX_PAGE ? `
+
+More results available: call again with page=${args.page + 1}.` : data.hasMore ? `
 
-More results available: call again with page=${args.page + 1}.` : "";
+lyrics.com holds more, but page ${MAX_PAGE} is as far as this tool reads. Narrow the query instead.` : "";
+    if (results.length > 0 && loose) {
+      notes.push(
+        `These are lyrics.com's own suggestions for "${args.title}", not rows whose title matches it. Check each title before quoting one, or ask again with match="strict".`
+      );
+    }
     return ok(structured, `${header}
-${renderResultList(results)}${footer}`);
+${renderResultList(results)}${footer}`, notes);
   } catch (error) {
     return toToolError(error);
   }
@@ -1138,8 +1219,8 @@ function createServer(options = {}) {
     {
       title: "Search lyrics by word",
       description: searchLyricsDescription,
-      inputSchema: z5.object(searchLyricsInputShape),
-      outputSchema: z5.object(searchLyricsOutputShape),
+      inputSchema: searchLyricsInput,
+      outputSchema: z6.object(searchLyricsOutputShape),
       annotations: READ_ONLY
     },
     async (args) => runSearchLyrics(client, args)
@@ -1149,8 +1230,8 @@ function createServer(options = {}) {
     {
       title: "Search songs by title",
       description: searchSongsDescription,
-      inputSchema: z5.object(searchSongsInputShape),
-      outputSchema: z5.object(searchSongsOutputShape),
+      inputSchema: searchSongsInput,
+      outputSchema: z6.object(searchSongsOutputShape),
       annotations: READ_ONLY
     },
     async (args) => runSearchSongs(client, args)
@@ -1160,8 +1241,8 @@ function createServer(options = {}) {
     {
       title: "Get full lyrics",
       description: getLyricsDescription,
-      inputSchema: z5.object(getLyricsInputShape),
-      outputSchema: z5.object(getLyricsOutputShape),
+      inputSchema: getLyricsInput,
+      outputSchema: z6.object(getLyricsOutputShape),
       annotations: READ_ONLY
     },
     async (args) => runGetLyrics(client, args)