mcp-lyricscom 1.4.1 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+## 2.0.1
+
+- **Every tool is documented, with its arguments and what its answer carries.**
+  The README is written for a person deciding whether to install and for a
+  program installing on its own, and a test holds both halves to what the server
+  registers.
+- **The privacy policy travels in the package.** It states the hosts contacted,
+  what a request carries, what is held and for how long.
+- **The manifest names every tool the server registers**, which a host reads
+  before installing anything.
+
+## 2.0.0
+
+- **This server now needs node 24 or later.** Node 20 reached its end of
+  support on 2026-04-30 and node 22 is no longer what this code is built and
+  typed against. That is what makes this a major version: an install on an
+  older node is refused rather than left to fail somewhere later.
+- **Every refusal of an argument opens with `invalid_input`.** A value outside
+  its bounds, of the wrong type, or outside the set an argument reads used to
+  come back in the validator's own words, with no code to branch on.
+- **A container image is published for each version**, on ghcr, for amd64 and
+  arm64. The readme carries the configuration that runs it.
+- The published package carries its changelog, and the entry point it declares
+  for the package root now publishes its types.
+
+## 1.4.1
+
+- The README carries the same badge row as every server here: npm, CI, the
+  licence, the MCP registry entry, the Glama score, and one-click installs for
+  Cursor and VS Code. Each install link encodes this package. npm serves the
+  README frozen at publish time, so a release is what puts it there.
+
+## 1.4.0
+
+- Refuse an argument no tool declares, instead of reading it and dropping it.
+  Every tool's schema already announced `additionalProperties: false`, but the
+  server accepted an undeclared argument silently, computed the answer on the
+  default for it, and returned that answer as if it had honored what was
+  asked. Now the call is refused under the `invalid_input` code, the message
+  names the argument, and offers the declared name when one is close: passing
+  `limt` to `search_lyrics` gets "did you mean 'limit'?", and passing `art` to
+  `search_songs` gets "did you mean 'artist'?".
+
+## 1.3.0
+
+- Say that an offset landed past the end of the words. An empty body under the
+  word "Complete." reads as a song with nothing on file, which is a different
+  fact from the one that happened.
+- Stop calling the site's own suggestions matches. A loose title search returns
+  what lyrics.com guessed at, and a row whose title is not the one asked for sits
+  among them: announcing the list as songs "matching" the query is how one song's
+  words come to be quoted for another. The wording says who chose them, and a
+  note says how to ask for an exact title instead.
+- Never offer a page the schema refuses. A search that reached the last accepted
+  page advertised the next one, sending a caller into an argument that is turned
+  away.
+- Carry the notes into the text block, and keep published text from producing a
+  line shaped like one.
+
+## 1.2.0
+
+- Ship a `.mcpb` bundle on every release, so the server can be installed by
+  opening a file rather than by having npm and a client configuration. The
+  dependencies are compiled into a single file, which makes the bundle 164 kB
+  and five files instead of 3 MB and two thousand: a bundle is unpacked, not
+  resolved, so a copy of `node_modules` would only be dead weight. The npm build
+  still keeps its dependencies external, and the two builds are separate
+  configurations for that reason.
+- Declare the bundle in `server.json`, with the hash the registry requires
+  computed from the released file at publish time rather than committed as a
+  value that goes stale on every build.
+
+## 1.1.1
+
+Housekeeping, with no change to what any tool returns.
+
+- Declare the tool schemas as objects rather than as the raw shape the SDK now
+  deprecates. The emitted `tools/list` is byte for byte what it was.
+- Add an icon and a `websiteUrl` to `server.json`, so the registry has something
+  to show next to the entry.
+
+## 1.1.0
+
+- Cache a response only once it has been read successfully. The cache stored
+  the raw response before parsing, so a page lyrics.com served but this client could
+  not understand stayed pinned for the cache lifetime and was replayed on every
+  retry: the tool could not recover even after the site was healthy again. It
+  now holds the parsed result, which also keeps the raw payload out of memory.
+
+## 1.0.2
+
+- Claim a pacing slot per request instead of per task. A task runs a whole
+  retry chain, so stamping only its start let the next task follow the chain's
+  last request with no gap, below the interval the configuration promises.
+- Honour `Retry-After` when lyrics.com sends one, in both its seconds and its
+  HTTP-date form, instead of guessing a delay. The wait is spent between
+  attempts rather than after the last one, where nobody would use it.
+- Treat HTTP 403 as a refusal to back off from. It was reported as a plain
+  error, so the client kept its pace in the one situation where slowing down is
+  the remedy.
+- Bound the pacing wait by the interval. A clock stepped backwards, by NTP or a
+  resumed virtual machine, made the next request wait for the size of the step,
+  and the queue is serial so every pending call waited behind it.
+- Enforce the pacing floor and the identifying User-Agent in the client rather
+  than only when reading the environment. The client is published through the
+  `./client` export and accepts a caller-built config, so both promises were
+  previously optional for anyone importing the library.
+
+## 1.0.1
+
+- Refresh the packaged README, which now carries one-click install links for
+  Cursor and VS Code and a link to the entry in the official MCP registry.
+- Keep LICENSE to the plain MIT text. License detectors match the file against
+  the canonical template, so the trailing scope note made the package read as
+  unlicensed; that note lives in the README.
+
+## 1.0.0
+
+First stable release. The tool contracts are now considered settled: tool names,
+their parameters and the shape of their structured output will only change in a
+future major version.
+
+Every tool has been exercised end to end against the live site, including the
+paths that are easy to get wrong: pagination continuity in `get_lyrics`, pages
+that carry no lyrics, rejection of non-lyrics.com URLs, and rate limiting
+surfacing as an explicit error.
+
+## 0.1.1
+
+- Enforce a floor on the request interval. `LYRICSCOM_MIN_INTERVAL_MS` is now
+  refused below 500 ms; a lower value falls back to the default 1100 ms and warns
+  on stderr. The pacing that keeps this client polite towards lyrics.com no
+  longer depends on every installation configuring it correctly.
+
+## 0.1.0
+
+Initial release. Three tools over stdio, no API key: `search_lyrics` (word or
+phrase inside the lyrics), `search_songs` (by title), `get_lyrics` (full text by
+id or URL).

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 smeet666
+Copyright (c) 2026 Damien Bouissou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/PRIVACY.md

@@ -0,0 +1,152 @@
+# Privacy
+
+This server collects nothing about you, and sends nothing to its author.
+
+_[Version française](#confidentialité)_
+
+---
+
+## What this server is
+
+`mcp-lyricscom` is a read-only client for [lyrics.com](https://www.lyrics.com). It runs on your
+own machine, as a process your MCP host starts, and it speaks over stdio. It
+listens on no port.
+
+It needs no API key and no account, so there is no credential for it to hold and none for it to send.
+
+## What leaves your machine, and where it goes
+
+**One host is contacted: `www.lyrics.com`.** Nothing else.
+
+| Host             | What is read there |
+| ---------------- | ------------------ |
+| `www.lyrics.com` | the site's pages   |
+
+What a request carries:
+
+| What                   | Why it is there                                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| The question you asked | A search term or an identifier reaches the site as you wrote it.                                                                      |
+| A `User-Agent`         | `mcp-lyricscom/<version> (+https://github.com/smeet666/mcp-lyricscom)`, so the site can reach a person about the traffic it receives. |
+| Your IP address        | Sent by your network to any host you contact, as with any web request.                                                                |
+
+Your requests reach lyrics.com. What is done with them there is governed by that site's own privacy policy, which this project does not control.
+
+## What is kept, and for how long
+
+**Answers are held in memory only, and only while the server runs.** The cache is
+a table in the process: it holds what was read so that reading the same page
+twice costs one request instead of two. Closing the server empties it.
+
+**Nothing is written to disk.** The server creates no file, no database and no
+log file.
+
+## What is never collected
+
+- No analytics, no telemetry, no usage counter.
+- Nothing is sent to the author of this project or to any third party.
+- No account, no profile, no identifier is created for you.
+- Your questions are not stored, forwarded, or used to train anything.
+
+## Logs
+
+The server writes diagnostics to **stderr**, where your MCP host decides what
+becomes of them. `LYRICSCOM_LOG_LEVEL` governs how much is written and defaults to `error`. These lines stay on your machine.
+
+## The settings that change any of this
+
+| Variable                 | What it changes                                                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `LYRICSCOM_USER_AGENT`   | Adds your own identifier in front of this project's, which stays appended so the site can always reach a person. |
+| `LYRICSCOM_CACHE_TTL_MS` | How long an answer is held in memory. `0` turns the cache off.                                                   |
+| `LYRICSCOM_LOG_LEVEL`    | How much is written to stderr.                                                                                   |
+
+## Children
+
+This server is a tool for developers and it is not directed at children.
+
+## Changes
+
+A change to this policy travels in a release, and the changelog names it.
+
+## Contact
+
+Open an issue on [the repository](https://github.com/smeet666/mcp-lyricscom/issues). For something exploitable,
+follow [SECURITY.md](./SECURITY.md) instead.
+
+---
+
+# Confidentialité
+
+Ce serveur ne collecte rien sur vous et n'envoie rien à son auteur.
+
+## Ce qu'est ce serveur
+
+`mcp-lyricscom` est un client en lecture seule pour [lyrics.com](https://www.lyrics.com). Il
+tourne sur votre machine, comme un processus que votre hôte MCP démarre, et il
+parle en stdio. Il n'écoute sur aucun port.
+
+Il ne demande ni clé d'API ni compte, donc il ne détient aucun identifiant et n'en envoie aucun.
+
+## Ce qui quitte votre machine, et où cela va
+
+**Un seul hôte est joint : `www.lyrics.com`.** Rien d'autre.
+
+| Hôte             | Ce qui y est lu   |
+| ---------------- | ----------------- |
+| `www.lyrics.com` | les pages du site |
+
+Ce qu'une requête emporte :
+
+| Quoi              | Pourquoi                                                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| La question posée | Un terme de recherche ou un identifiant atteint le site tel que vous l'avez écrit.                                                                    |
+| Un `User-Agent`   | `mcp-lyricscom/<version> (+https://github.com/smeet666/mcp-lyricscom)`, pour que le site puisse joindre une personne au sujet du trafic qu'il reçoit. |
+| Votre adresse IP  | Transmise par votre réseau à tout hôte que vous joignez, comme pour n'importe quelle requête web.                                                     |
+
+Vos requêtes atteignent lyrics.com. Ce qui en est fait là-bas relève de la politique de confidentialité de ce site, que ce projet ne contrôle pas.
+
+## Ce qui est conservé, et combien de temps
+
+**Les réponses sont gardées en mémoire seulement, et seulement pendant que le
+serveur tourne.** Le cache est une table dans le processus : il retient ce qui a
+été lu pour que lire deux fois la même page coûte une requête plutôt que deux.
+Fermer le serveur le vide.
+
+**Rien n'est écrit sur le disque.** Le serveur ne crée aucun fichier, aucune base
+et aucun journal.
+
+## Ce qui n'est jamais collecté
+
+- Aucune analyse d'audience, aucune télémétrie, aucun compteur d'usage.
+- Rien n'est envoyé à l'auteur de ce projet ni à un tiers.
+- Aucun compte, aucun profil, aucun identifiant n'est créé pour vous.
+- Vos questions ne sont ni stockées, ni transmises, ni utilisées pour entraîner
+  quoi que ce soit.
+
+## Les journaux
+
+Le serveur écrit ses diagnostics sur **stderr**, où votre hôte MCP décide de ce
+qu'ils deviennent. `LYRICSCOM_LOG_LEVEL` règle leur quantité et vaut `error` par défaut. Ces lignes restent sur votre machine.
+
+## Les réglages qui changent tout cela
+
+| Variable                 | Ce qu'elle change                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `LYRICSCOM_USER_AGENT`   | Ajoute votre identifiant devant celui du projet, qui reste accolé pour que le site puisse toujours joindre une personne. |
+| `LYRICSCOM_CACHE_TTL_MS` | Combien de temps une réponse est gardée en mémoire. `0` éteint le cache.                                                 |
+| `LYRICSCOM_LOG_LEVEL`    | La quantité écrite sur stderr.                                                                                           |
+
+## Les enfants
+
+Ce serveur est un outil pour développeurs et ne s'adresse pas aux enfants.
+
+## Les évolutions
+
+Une modification de cette politique voyage dans une version, et le changelog la
+nomme.
+
+## Contact
+
+Ouvrez une issue sur [le dépôt](https://github.com/smeet666/mcp-lyricscom/issues). Pour quelque chose
+d'exploitable, suivez plutôt [SECURITY.md](./SECURITY.md).