mcp-lyricscom 0.1.0

package/dist/lyricscom/client.js

@@ -0,0 +1,624 @@
+// src/version.ts
+var PKG_VERSION = "0.1.0";
+var REPO_URL = "https://github.com/smeet666/mcp-lyricscom";
+
+// src/config.ts
+var DEFAULT_USER_AGENT = `mcp-lyricscom/${PKG_VERSION} (+${REPO_URL})`;
+var DEFAULTS = {
+  minIntervalMs: 1100,
+  timeoutMs: 15e3,
+  maxRetries: 3,
+  cacheTtlMs: 15 * 60 * 1e3,
+  cacheMaxEntries: 200,
+  logLevel: "error"
+};
+var LOG_LEVELS = ["silent", "error", "info", "debug"];
+function readNumber(name, env, range) {
+  const raw = env[name];
+  if (raw === void 0 || raw.trim() === "") return range.fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    warn(`${name}="${raw}" is not a number, using ${range.fallback}`);
+    return range.fallback;
+  }
+  const clamped = Math.min(range.max, Math.max(range.min, Math.round(parsed)));
+  if (clamped !== Math.round(parsed)) {
+    warn(`${name}=${raw} is out of range, clamped to ${clamped}`);
+  }
+  return clamped;
+}
+function warn(message) {
+  process.stderr.write(`[mcp-lyricscom] ${message}
+`);
+}
+function loadConfig(env = process.env) {
+  const rawUserAgent = env.LYRICSCOM_USER_AGENT?.trim();
+  const rawLogLevel = env.LYRICSCOM_LOG_LEVEL?.trim().toLowerCase();
+  let logLevel = DEFAULTS.logLevel;
+  if (rawLogLevel) {
+    if (LOG_LEVELS.includes(rawLogLevel)) {
+      logLevel = rawLogLevel;
+    } else {
+      warn(`LYRICSCOM_LOG_LEVEL="${rawLogLevel}" is unknown, using "${DEFAULTS.logLevel}"`);
+    }
+  }
+  return {
+    userAgent: rawUserAgent || DEFAULT_USER_AGENT,
+    // 0 is allowed so the throttling behaviour can be exercised deliberately.
+    minIntervalMs: readNumber("LYRICSCOM_MIN_INTERVAL_MS", env, {
+      min: 0,
+      max: 6e4,
+      fallback: DEFAULTS.minIntervalMs
+    }),
+    timeoutMs: readNumber("LYRICSCOM_TIMEOUT_MS", env, {
+      min: 1e3,
+      max: 12e4,
+      fallback: DEFAULTS.timeoutMs
+    }),
+    maxRetries: readNumber("LYRICSCOM_MAX_RETRIES", env, {
+      min: 0,
+      max: 10,
+      fallback: DEFAULTS.maxRetries
+    }),
+    cacheTtlMs: readNumber("LYRICSCOM_CACHE_TTL_MS", env, {
+      min: 0,
+      max: 24 * 60 * 60 * 1e3,
+      fallback: DEFAULTS.cacheTtlMs
+    }),
+    cacheMaxEntries: readNumber("LYRICSCOM_CACHE_MAX_ENTRIES", env, {
+      min: 0,
+      max: 1e4,
+      fallback: DEFAULTS.cacheMaxEntries
+    }),
+    logLevel
+  };
+}
+var LEVEL_RANK = { silent: 0, error: 1, info: 2, debug: 3 };
+function createLogger(level) {
+  const emit = (at, message) => {
+    if (LEVEL_RANK[level] >= LEVEL_RANK[at]) {
+      process.stderr.write(`[mcp-lyricscom] ${message}
+`);
+    }
+  };
+  return {
+    error: (message) => emit("error", message),
+    info: (message) => emit("info", message),
+    debug: (message) => emit("debug", message)
+  };
+}
+
+// src/lyricscom/cache.ts
+var TtlLruCache = class {
+  constructor(maxEntries, ttlMs) {
+    this.maxEntries = maxEntries;
+    this.ttlMs = ttlMs;
+  }
+  maxEntries;
+  ttlMs;
+  store = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() >= entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    if (this.maxEntries <= 0 || this.ttlMs <= 0) return;
+    this.store.delete(key);
+    this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    while (this.store.size > this.maxEntries) {
+      const oldest = this.store.keys().next();
+      if (oldest.done) break;
+      this.store.delete(oldest.value);
+    }
+  }
+  get size() {
+    return this.store.size;
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+// src/errors.ts
+var LyricsComError = class extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "LyricsComError";
+  }
+  code;
+  details;
+};
+var ISSUES_URL = "https://github.com/smeet666/mcp-lyricscom/issues";
+function throttled(url, retryAfterMs) {
+  return new LyricsComError(
+    "throttled",
+    "lyrics.com is rate limiting this client. It answered with an empty response instead of a page. This does NOT mean there are no results for this query.",
+    {
+      url,
+      retryAfterMs,
+      hint: "Wait at least a minute before calling the same tool again with the same arguments. Once lyrics.com starts throttling, the window commonly lasts several minutes, so retrying immediately will fail again. If it keeps happening, raise LYRICSCOM_MIN_INTERVAL_MS in your MCP client configuration."
+    }
+  );
+}
+function blockedUserAgent(url) {
+  return new LyricsComError(
+    "blocked_user_agent",
+    "lyrics.com refused the request because of the User-Agent this server sends (HTTP 403).",
+    {
+      url,
+      status: 403,
+      hint: "Set the LYRICSCOM_USER_AGENT environment variable in your MCP client configuration to a different value. See the Configuration section of the project README."
+    }
+  );
+}
+function notFound(url) {
+  return new LyricsComError("not_found", "lyrics.com has no page at this address.", {
+    url,
+    status: 404,
+    hint: "Check the song id. Ids come from the search tools; they are not stable to guess by hand."
+  });
+}
+function parseFailure(url, what) {
+  return new LyricsComError(
+    "parse_failure",
+    `The page loaded but the expected lyrics.com markup was not found (${what}). The site layout may have changed.`,
+    { url, hint: `Please report this, with the query you used, at ${ISSUES_URL}` }
+  );
+}
+function invalidInput(message, hint) {
+  return new LyricsComError("invalid_input", message, hint ? { hint } : {});
+}
+
+// src/lyricscom/parsers/detectThrottle.ts
+var MIN_PLAUSIBLE_HTML = 2e3;
+function classifyResponse(status, body) {
+  if (status === 202) return { kind: "throttled", reason: "status-202" };
+  if (status === 429) return { kind: "throttled", reason: "status-429" };
+  if (status === 503) return { kind: "throttled", reason: "status-503" };
+  if (status === 403) return { kind: "blocked", status };
+  if (status === 404) return { kind: "not-found" };
+  if (status >= 500) return { kind: "server-error", status };
+  const trimmed = body.trim();
+  if (trimmed.length === 0) return { kind: "throttled", reason: "empty-body" };
+  if (trimmed.length < MIN_PLAUSIBLE_HTML && !/<\/html>/i.test(trimmed)) {
+    return { kind: "throttled", reason: "short-body" };
+  }
+  return { kind: "ok", html: body };
+}
+
+// src/lyricscom/rateLimiter.ts
+var DEFAULT_MAX_INTERVAL_MS = 1e4;
+var RateLimiter = class {
+  baseIntervalMs;
+  maxIntervalMs;
+  intervalMs;
+  /** Tail of the queue: each task chains onto the previous one. */
+  tail = Promise.resolve();
+  lastStart = 0;
+  constructor(options) {
+    this.baseIntervalMs = Math.max(0, options.minIntervalMs);
+    this.maxIntervalMs = Math.max(
+      this.baseIntervalMs,
+      options.maxIntervalMs ?? DEFAULT_MAX_INTERVAL_MS
+    );
+    this.intervalMs = this.baseIntervalMs;
+  }
+  get currentIntervalMs() {
+    return this.intervalMs;
+  }
+  /** Queue a task. Tasks run in call order, one at a time. */
+  schedule(task) {
+    const run = this.tail.then(async () => {
+      await this.waitForSlot();
+      this.lastStart = Date.now();
+      return task();
+    });
+    this.tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  /** Called after the site signals it is under load. */
+  penalize() {
+    const next = this.intervalMs === 0 ? 250 : this.intervalMs * 2;
+    this.intervalMs = Math.min(this.maxIntervalMs, next);
+  }
+  /** Called after a success, so a single hiccup does not slow things down forever. */
+  relax() {
+    this.intervalMs = Math.max(this.baseIntervalMs, Math.floor(this.intervalMs * 0.75));
+  }
+  async waitForSlot() {
+    if (this.intervalMs === 0 || this.lastStart === 0) return;
+    const elapsed = Date.now() - this.lastStart;
+    const remaining = this.intervalMs - elapsed;
+    if (remaining > 0) await sleep(remaining);
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/lyricscom/http.ts
+var BACKOFF_BASE_MS = 2e3;
+var BACKOFF_FACTOR = 2;
+var BACKOFF_MAX_MS = 2e4;
+function backoffDelay(attempt, random = Math.random) {
+  const uncapped = BACKOFF_BASE_MS * BACKOFF_FACTOR ** attempt;
+  const capped = Math.min(BACKOFF_MAX_MS, uncapped);
+  return Math.round(capped * (0.5 + random() * 0.5));
+}
+async function fetchHtml(url, deps) {
+  const { config, limiter, logger } = deps;
+  const doFetch = deps.fetchImpl ?? fetch;
+  return limiter.schedule(async () => {
+    let lastError;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
+      if (attempt > 0) {
+        const delay = backoffDelay(attempt - 1);
+        logger.info(`retry ${attempt}/${config.maxRetries} in ${delay}ms for ${url}`);
+        await sleep(delay);
+      }
+      let status;
+      let body;
+      try {
+        const response = await doFetch(url, {
+          headers: {
+            "User-Agent": config.userAgent,
+            Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+            "Accept-Language": "en-US,en;q=0.9,fr;q=0.8"
+          },
+          redirect: "follow",
+          signal: AbortSignal.timeout(config.timeoutMs)
+        });
+        status = response.status;
+        body = await response.text();
+      } catch (error) {
+        lastError = asTransportError(error, url);
+        logger.debug(`${lastError.code} for ${url}: ${lastError.message}`);
+        continue;
+      }
+      const verdict = classifyResponse(status, body);
+      switch (verdict.kind) {
+        case "ok":
+          limiter.relax();
+          return verdict.html;
+        case "throttled":
+          limiter.penalize();
+          logger.info(
+            `throttled (${verdict.reason}) on ${url}, interval now ${limiter.currentIntervalMs}ms`
+          );
+          lastError = throttled(url, backoffDelay(attempt));
+          continue;
+        case "server-error":
+          lastError = new LyricsComError(
+            "network_error",
+            `lyrics.com returned HTTP ${verdict.status}.`,
+            {
+              url,
+              status: verdict.status
+            }
+          );
+          continue;
+        // Retrying these would only repeat the same answer.
+        case "blocked":
+          throw blockedUserAgent(url);
+        case "not-found":
+          throw notFound(url);
+      }
+    }
+    throw lastError ?? new LyricsComError("network_error", `Could not fetch ${url}.`, { url });
+  });
+}
+function asTransportError(error, url) {
+  if (error instanceof LyricsComError) return error;
+  const name = error instanceof Error ? error.name : "";
+  if (name === "TimeoutError" || name === "AbortError") {
+    return new LyricsComError("timeout", "lyrics.com did not answer in time.", {
+      url,
+      hint: "Raise LYRICSCOM_TIMEOUT_MS if this happens often on a slow connection."
+    });
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new LyricsComError("network_error", `Could not reach lyrics.com: ${message}`, { url });
+}
+
+// src/lyricscom/parsers/searchResults.ts
+import * as cheerio from "cheerio";
+
+// src/text/normalize.ts
+var HTML_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: "\xA0",
+  hellip: "\u2026",
+  mdash: "\u2014",
+  ndash: "\u2013",
+  rsquo: "\u2019",
+  lsquo: "\u2018",
+  ldquo: "\u201C",
+  rdquo: "\u201D"
+};
+function unescapeHtml(text) {
+  if (!text) return text;
+  return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (match, entity) => {
+    if (entity.startsWith("#")) {
+      const isHex = entity[1] === "x" || entity[1] === "X";
+      const codePoint = Number.parseInt(isHex ? entity.slice(2) : entity.slice(1), isHex ? 16 : 10);
+      if (Number.isNaN(codePoint) || codePoint < 0 || codePoint > 1114111) return match;
+      try {
+        return String.fromCodePoint(codePoint);
+      } catch {
+        return match;
+      }
+    }
+    return HTML_ENTITIES[entity.toLowerCase()] ?? match;
+  });
+}
+function fixEncodingIssues(text) {
+  if (!text || !/[ÃÂ]/.test(text)) return text;
+  try {
+    const repaired = Buffer.from(text, "latin1").toString("utf8");
+    if (repaired.includes("\uFFFD")) return text;
+    return repaired;
+  } catch {
+    return text;
+  }
+}
+function collapseWhitespace(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function cleanInlineText(text) {
+  if (!text) return "";
+  return collapseWhitespace(fixEncodingIssues(unescapeHtml(text)));
+}
+function cleanLyricsText(text) {
+  if (!text) return "";
+  const normalized = fixEncodingIssues(unescapeHtml(text)).replace(/\r\n?/g, "\n");
+  const lines = normalized.split("\n").map((line) => line.trim());
+  const out = [];
+  for (const line of lines) {
+    if (line === "" && (out.length === 0 || out[out.length - 1] === "")) continue;
+    out.push(line);
+  }
+  while (out.length > 0 && out[out.length - 1] === "") out.pop();
+  return out.join("\n");
+}
+
+// src/lyricscom/urls.ts
+var BASE_URL = "https://www.lyrics.com";
+var RESULTS_PER_PAGE = 24;
+var SONG_HREF_RE = /^\/lyric(?:-lf)?\/(\d+)\//;
+var ALLOWED_HOSTS = /* @__PURE__ */ new Set(["lyrics.com", "www.lyrics.com"]);
+function encodeTerm(term) {
+  return encodeURIComponent(term).replace(/%20/g, "+");
+}
+function buildSearchUrl(term, page) {
+  const encoded = encodeTerm(term);
+  if (page <= 1) return `${BASE_URL}/lyrics/${encoded}`;
+  return `${BASE_URL}/serp.php?st=${encoded}&p=${page}`;
+}
+function buildSongUrl(id) {
+  return `${BASE_URL}/lyric-lf/${id}/`;
+}
+function isLyricsComHost(rawUrl) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return false;
+  return ALLOWED_HOSTS.has(parsed.hostname.toLowerCase());
+}
+function extractSongId(hrefOrUrl) {
+  let path = hrefOrUrl;
+  if (/^https?:\/\//i.test(hrefOrUrl)) {
+    if (!isLyricsComHost(hrefOrUrl)) return null;
+    path = new URL(hrefOrUrl).pathname;
+  }
+  if (!path.startsWith("/")) path = `/${path}`;
+  const match = SONG_HREF_RE.exec(path);
+  return match?.[1] ?? null;
+}
+function resolveSongRef(input) {
+  if (input.id) {
+    if (!/^\d+$/.test(input.id)) {
+      throw invalidInput(
+        `"${input.id}" is not a lyrics.com song id.`,
+        "Ids are digits only, as returned by the search tools."
+      );
+    }
+    return { id: input.id, url: buildSongUrl(input.id) };
+  }
+  if (input.url) {
+    if (!isLyricsComHost(input.url)) {
+      throw invalidInput(
+        "Only www.lyrics.com URLs are accepted.",
+        "Pass the source_url returned by search_lyrics or search_songs, or use the numeric id instead."
+      );
+    }
+    const id = extractSongId(input.url);
+    if (!id) {
+      throw invalidInput(
+        "That lyrics.com URL is not a song page.",
+        "Song pages look like https://www.lyrics.com/lyric-lf/1234567/Artist/Title"
+      );
+    }
+    return { id, url: input.url };
+  }
+  throw invalidInput("Either 'id' or 'url' must be provided.");
+}
+function toAbsoluteUrl(href) {
+  return new URL(href, BASE_URL).toString();
+}
+
+// src/lyricscom/parsers/selectors.ts
+var SEL = {
+  /** One search result row. */
+  serpItem: "div.sec-lyric",
+  /**
+   * Page chrome that is present whether or not there are results. Used to tell
+   * "zero results" apart from "the markup changed", which must not look alike.
+   */
+  serpShell: "#lyric-search, .lyric-search, .pagination, #main-content, form[action*='serp']",
+  resultTitle: "p.lyric-meta-title a",
+  /**
+   * Rows tied to an album expose the artist under `lyric-meta-album-artist`,
+   * rows without one under `lyric-meta-artists`. Both shapes appear on the same
+   * page, so missing the second silently drops results.
+   */
+  resultArtist: "p.lyric-meta-album-artist a, p.lyric-meta-artists a",
+  resultAlbum: "p.lyric-meta-album",
+  resultYear: "p.lyric-meta-album-year",
+  resultSnippet: "pre.lyric-body",
+  /** Full lyrics on a song page, with the historical fallback. */
+  songBody: "pre#lyric-body-text, pre.lyric-body",
+  /** Marker for a valid song page that simply has no lyrics on file. */
+  songNoData: "div.lyric-no-data",
+  songTitle: "#lyric-title-text, .lyric-title",
+  songArtist: ".lyric-artist a, .lyric-artist"
+};
+
+// src/lyricscom/parsers/searchResults.ts
+function parseSearchResults(html, options) {
+  const $ = cheerio.load(html);
+  const rows = $(SEL.serpItem);
+  if (rows.length === 0) {
+    if ($(SEL.serpShell).length === 0) {
+      throw parseFailure(options.url, "no result rows and no recognizable search page structure");
+    }
+    return { results: [], page: options.page, rawCount: 0, hasMore: false };
+  }
+  const results = [];
+  let skipped = 0;
+  rows.each((_, element) => {
+    const row = $(element);
+    const titleLink = row.find(SEL.resultTitle).first();
+    const href = titleLink.attr("href");
+    const title = cleanInlineText(titleLink.text());
+    const artist = cleanInlineText(row.find(SEL.resultArtist).first().text());
+    const id = href ? extractSongId(href) : null;
+    if (!id || !title || !artist) {
+      skipped += 1;
+      return;
+    }
+    const album = cleanInlineText(row.find(SEL.resultAlbum).first().text()) || null;
+    const year = parseYear(row.find(SEL.resultYear).first().text());
+    const snippetRaw = row.find(SEL.resultSnippet).first().text();
+    const snippet = snippetRaw ? cleanLyricsText(snippetRaw) || null : null;
+    results.push({
+      id,
+      url: toAbsoluteUrl(href),
+      title,
+      artist,
+      album,
+      year,
+      snippet
+    });
+  });
+  if (results.length === 0) {
+    throw parseFailure(options.url, `${rows.length} result rows matched but none could be read`);
+  }
+  if (skipped > 0) {
+    process.stderr.write(
+      `[mcp-lyricscom] skipped ${skipped} unreadable result rows on ${options.url}
+`
+    );
+  }
+  return {
+    results,
+    page: options.page,
+    rawCount: rows.length,
+    hasMore: rows.length >= RESULTS_PER_PAGE
+  };
+}
+function parseYear(raw) {
+  const match = /\b(1[89]\d{2}|20\d{2})\b/.exec(raw);
+  if (!match?.[1]) return null;
+  return Number.parseInt(match[1], 10);
+}
+
+// src/lyricscom/parsers/songPage.ts
+import * as cheerio2 from "cheerio";
+function parseSongPage(html, options) {
+  const $ = cheerio2.load(html);
+  const title = cleanInlineText($(SEL.songTitle).first().text()) || null;
+  const artist = cleanInlineText($(SEL.songArtist).first().text()) || null;
+  const body = $(SEL.songBody).first();
+  if (body.length === 0) {
+    const declaresNoLyrics = $(SEL.songNoData).length > 0 || /no lyrics found/i.test($("title").text());
+    if (!declaresNoLyrics) {
+      throw parseFailure(options.url, "no lyrics container and no 'no lyrics' marker");
+    }
+    return { id: options.id, url: options.url, title, artist, lyrics: "", hasLyrics: false };
+  }
+  const lyrics = cleanLyricsText(extractBodyText($, body));
+  if (!lyrics) {
+    return { id: options.id, url: options.url, title, artist, lyrics: "", hasLyrics: false };
+  }
+  return { id: options.id, url: options.url, title, artist, lyrics, hasLyrics: true };
+}
+function extractBodyText($, body) {
+  const rawHtml = $.html(body);
+  const withoutAnchors = rawHtml.replace(/<a[^>]*>([\s\S]*?)<\/a>/gi, "$1");
+  const withNewlines = withoutAnchors.replace(/<br\s*\/?>/gi, "\n");
+  return cheerio2.load(withNewlines).root().text();
+}
+
+// src/lyricscom/client.ts
+var LyricsComClient = class {
+  config;
+  logger;
+  limiter;
+  cache;
+  fetchImpl;
+  constructor(options = {}) {
+    this.config = options.config ?? loadConfig();
+    this.logger = options.logger ?? createLogger(this.config.logLevel);
+    this.limiter = new RateLimiter({ minIntervalMs: this.config.minIntervalMs });
+    this.cache = new TtlLruCache(this.config.cacheMaxEntries, this.config.cacheTtlMs);
+    this.fetchImpl = options.fetchImpl;
+  }
+  async search(term, page) {
+    const url = buildSearchUrl(term, page);
+    const { html, cached } = await this.fetchPage(url);
+    return { data: parseSearchResults(html, { page, url }), cached };
+  }
+  async getSong(ref) {
+    const { id, url } = resolveSongRef(ref);
+    const { html, cached } = await this.fetchPage(url);
+    return { data: parseSongPage(html, { id, url }), cached };
+  }
+  async fetchPage(url) {
+    const hit = this.cache.get(url);
+    if (hit !== void 0) {
+      this.logger.debug(`cache hit ${url}`);
+      return { html: hit, cached: true };
+    }
+    const html = await fetchHtml(url, {
+      config: this.config,
+      limiter: this.limiter,
+      logger: this.logger,
+      ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
+    });
+    this.cache.set(url, html);
+    return { html, cached: false };
+  }
+};
+export {
+  LyricsComClient
+};
+//# sourceMappingURL=client.js.map