{
  "markdown": "# mcp-tvsubtitles\n\n[![npm](https://img.shields.io/npm/v/mcp-tvsubtitles.svg)](https://www.npmjs.com/package/mcp-tvsubtitles)\n[![CI](https://github.com/smeet666/mcp-tvsubtitles/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-tvsubtitles/actions/workflows/ci.yml)\n[![license](https://img.shields.io/npm/l/mcp-tvsubtitles.svg)](./LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.smeet666/mcp-tvsubtitles)\n[![Glama](https://glama.ai/mcp/servers/smeet666/mcp-tvsubtitles/badges/score.svg)](https://glama.ai/mcp/servers/smeet666/mcp-tvsubtitles)\n[![LobeHub](https://lobehub.com/badge/mcp/smeet666-mcp-tvsubtitles)](https://lobehub.com/mcp/smeet666-mcp-tvsubtitles)\n[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=tvsubtitles&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC10dnN1YnRpdGxlcyJdfQ==)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=tvsubtitles&config=%7B%22name%22%3A%22tvsubtitles%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-tvsubtitles%22%5D%7D)\n\n[TVsubtitles.net](https://www.tvsubtitles.net) catalogues subtitles for\ntelevision series. Its readers upload a file for one episode, timed to one video\nrelease, and the site records the language, the release it was cut for, who\nuploaded it and when, how large the file is and how often it has been taken. It\nholds around three hundred thousand of them, across some eighty-six thousand\nepisodes in twenty-four languages.\n\nThis server connects a chat client to that catalogue. You can search for a\nseries, read a season and see which languages hold something for each episode,\nread the records of one episode, and open one record with the release it was cut\nfor and who uploaded it. Every record carries the address of its page on the\nsite. No API key and no account are needed.\n\n_[Version française](#mcp-tvsubtitles-français)_\n\n---\n\n## Install\n\n**One-click install**\n\n[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=tvsubtitles&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC10dnN1YnRpdGxlcyJdfQ==)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=tvsubtitles&config=%7B%22name%22%3A%22tvsubtitles%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-tvsubtitles%22%5D%7D)\n\n**Claude Code**\n\n```bash\nclaude mcp add tvsubtitles -- npx -y mcp-tvsubtitles\n```\n\n**Any client reading `mcpServers`**\n\n```json\n{\n  \"mcpServers\": {\n    \"tvsubtitles\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-tvsubtitles\"]\n    }\n  }\n}\n```\n\n### With Docker\n\n```json\n{\n  \"mcpServers\": {\n    \"tvsubtitles\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"ghcr.io/smeet666/mcp-tvsubtitles:1.0.1\"]\n    }\n  }\n}\n```\n\nThe container reaches `https://www.tvsubtitles.net` and nothing else.\n\n### Bundle, without npm\n\nDownload `mcp-tvsubtitles.mcpb` from the\n[latest release](https://github.com/smeet666/mcp-tvsubtitles/releases/latest) and\nopen it with a host that installs MCP bundles. It carries its dependencies, so\nNode 24 or later is all it needs.\n\n## What you can ask\n\n- \"Does tvsubtitles have French subtitles for Smallville?\"\n- \"Which languages cover season 3 of Harbour Lights?\"\n- \"List the English subtitles for episode 7 of that season.\"\n- \"Which release is that subtitle timed to, and who uploaded it?\"\n- \"Find me the page to download the Polish subtitle for the finale.\"\n\n## Tools\n\n| Tool             | What it does                                                            |\n| ---------------- | ----------------------------------------------------------------------- |\n| `search_titles`  | Finds a television series by name, and returns the id the others take.  |\n| `list_subtitles` | Reads a season's coverage, or one episode's subtitle records.           |\n| `get_subtitle`   | Reads one record, with its release, its uploader and its download page. |\n| `list_languages` | Lists the languages the catalogue holds, or the ones one show holds.    |\n\n### `search_titles`\n\nSearches the catalogue by name. The site catalogues television only, so a search\nfor a film is refused rather than answered.\n\n| Argument      | Type                       | Required | What it does                                                                                                       |\n| ------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |\n| `query`       | string, 1–120 characters   | yes      | The name of a series, or part of one.                                                                              |\n| `media_type`  | `movie` \\| `tv` \\| `any`   | no       | `tv` and `any` search the catalogue. `movie` is refused.                                                           |\n| `year`        | integer, 1900–2100         | no       | Keeps rows whose published years cover this one.                                                                   |\n| `limit`       | integer, 1–100, default 20 | no       | Rows to render.                                                                                                    |\n| `with_counts` | boolean, default false     | no       | Reads each row's subtitle, episode and season counts from the catalogue index, at the cost of one further request. |\n\n**In return:** the matching series, each with the `id` the other tools take, the\nyears the site publishes, and the languages it draws a flag for. `imdb_id` and\n`tmdb_id` are null, because the site's search publishes none. `subtitle_count`,\n`episode_count` and `season_count` are null unless `with_counts` asks for them,\nsince the site publishes those three on its catalogue index rather than on the\npage a search answers with; each counts every season of the show together, which\n`counts_scope` names, each is read on its own, and a show the index carries no\nrow for keeps three nulls. `total_available` counts the rows this one search came\nback with, which `total_counts` names. A year that leaves nothing is set aside\nand named in `filters_dropped`.\n\n### `list_subtitles`\n\nReads what a series holds, in one of two shapes that `kind` names.\n\n| Argument   | Type                       | Required | What it does                                                        |\n| ---------- | -------------------------- | -------- | ------------------------------------------------------------------- |\n| `id`       | string, 1–12 characters    | yes      | A show id from `search_titles`.                                     |\n| `season`   | integer, 1–200             | no       | Left out, the newest season the site holds is read.                 |\n| `episode`  | integer, 1–500             | no       | Named, the answer is that episode's records.                        |\n| `language` | string, 1–40 characters    | no       | A language from `list_languages`, by name, site code or BCP 47 tag. |\n| `limit`    | integer, 1–200, default 40 | no       | Rows to render.                                                     |\n\n**In return:** with a season alone, `kind` reads `coverage` and each row is one\nepisode, carrying `episode_id`, the number of subtitles the site counts and the\nlanguages holding something. With an episode named, `kind` reads `subtitles` and\neach row is a record carrying the `id` that `get_subtitle` takes. `season` is the\nseason the site served and `season_requested` the one that was asked for, which\ndiffer when the newest was read. `seasons_available` lists the seasons the show\nholds. A language holding nothing is set aside, the answer comes back\nunnarrowed, and `filters_dropped` names it.\n\n### `get_subtitle`\n\nReads one record from an id `list_subtitles` returned.\n\n| Argument | Type                    | Required | What it does                         |\n| -------- | ----------------------- | -------- | ------------------------------------ |\n| `id`     | string, 1–12 characters | yes      | A subtitle id from `list_subtitles`. |\n\n**In return:** the record, with `page_url` for the page a reader opens to\ndownload the file. `read_from` reads `record` here and `listing` on a row\n`list_subtitles` produced, which is what tells an unread field from one the site\ndoes not publish: a listing carries no `file_name`, no `size_text` and no\n`comment`, because the site prints those on a record's own page alone. `releases` holds the video releases the site published and\n`release_match` says whether it published any: `stated` where it did, `none`\nwhere it did not, so a record marked `none` says nothing about which video it is\ntimed to. `uploader` is null on roughly two records out of three. `published_at`\nis the site's stamp read into ISO 8601 and carries no timezone, and\n`published_text` keeps the site's own wording. `rating` holds two counters the\nsite publishes, where a zero is a figure it printed.\n\n### `list_languages`\n\nLists the languages the site catalogues, or the ones one show holds.\n\n| Argument | Type                    | Required | What it does                                               |\n| -------- | ----------------------- | -------- | ---------------------------------------------------------- |\n| `id`     | string, 1–12 characters | no       | A show id, to read what that show holds.                   |\n| `season` | integer, 1–200          | no       | Which season to measure a show over. Ignored without `id`. |\n\n**In return:** each language with the name the site prints, the two-letter\n`site_code` it addresses the language by, the BCP 47 `code` where that mapping is\ncertain, and `differs_from_iso`. `scope` says what was measured: `catalogue` for\nthe whole site, or `season` when a show id was passed, and `count` is then the\nepisodes of that season holding the language.\n\n## Languages, and the codes the site uses\n\nThe site draws twenty-four flags and addresses each language by two letters of\nits own choosing. Six of them differ from ISO 639-1, and one collides: the site\nwrites `br` for Brazilian Portuguese, which ISO assigns to Breton.\n\n| Site code | Language             | BCP 47  |\n| --------- | -------------------- | ------- |\n| `br`      | Brazilian Portuguese | `pt-BR` |\n| `gr`      | Greek                | `el`    |\n| `cz`      | Czech                | `cs`    |\n| `jp`      | Japanese             | `ja`    |\n| `cn`      | Chinese              | `zh`    |\n| `ua`      | Ukrainian            | `uk`    |\n\n`language` keeps the site's own name and `language_code` carries the tag, so\nnothing has to be derived from the two letters. `list_subtitles` accepts a\nlanguage written any of the three ways.\n\n## Configuration\n\nNothing has to be set. Every variable below is optional.\n\n| Variable                | Default | Range                              | What it does                                                |\n| ----------------------- | ------- | ---------------------------------- | ----------------------------------------------------------- |\n| `TVS_USER_AGENT`        | unset   |                                    | Prepended to this server's own agent, which stays attached. |\n| `TVS_MIN_INTERVAL_MS`   | 2000    | 1500–60000                         | Milliseconds between two requests. 1500 is a floor.         |\n| `TVS_TIMEOUT_MS`        | 20000   | 1000–120000                        | Deadline for one attempt.                                   |\n| `TVS_BUDGET_MS`         | 60000   | 5000–600000                        | Deadline for one read, its retries included.                |\n| `TVS_MAX_RETRIES`       | 3       | 0–8                                | Attempts after the first.                                   |\n| `TVS_CACHE_TTL_MS`      | 900000  | 0–86400000                         | How long a page is held in memory. 0 turns the store off.   |\n| `TVS_CACHE_MAX_ENTRIES` | 200     | 1–5000                             | Pages held before the least recently used is dropped.       |\n| `TVS_MAX_BODY_BYTES`    | 8000000 | 100000–64000000                    | The largest answer read for one page.                       |\n| `TVS_LOG_LEVEL`         | `error` | `silent`, `error`, `info`, `debug` | What reaches stderr.                                        |\n\nA value outside its range is refused on stderr and the default stands.\n\n## Errors\n\n| Code            | What it means                                  | What to do                                            |\n| --------------- | ---------------------------------------------- | ----------------------------------------------------- |\n| `not_found`     | The site answered, and holds no such thing.    | Check the id came from a listing rather than by hand. |\n| `invalid_input` | The arguments could not produce a request.     | Read the message, which names the argument.           |\n| `rate_limited`  | The site asked this client to slow down.       | Wait and ask again. The thing asked for still exists. |\n| `parse_failure` | An answer arrived in a shape this cannot read. | Report it with the arguments used.                    |\n| `network_error` | The request did not complete.                  | Try again.                                            |\n| `timeout`       | No answer arrived inside the deadline.         | Try again, or raise `TVS_BUDGET_MS`.                  |\n\n## As a library\n\nThe layer that reads the site is published on its own, with the pacing, the\nstore and the error codes, and no protocol attached.\n\n```ts\nimport { TvSubtitlesClient } from \"mcp-tvsubtitles/client\";\n\nconst client = new TvSubtitlesClient();\nconst found = await client.searchShows(\"Smallville\");\nconst season = await client.getSeason(found.data.rows[0].id, 0);\nconsole.log(season.data.showName, season.data.season, season.data.episodes.length);\n```\n\nEvery read returns `{ data, cached }`, with `skipped` when rows were left out.\nThe constructor takes `{ config, logger, fetchImpl }`, and the interval floor\nholds whatever is passed.\n\n## Pacing and attribution\n\nOne request at a time, two seconds apart, widening when the site pushes back and\nnarrowing again on a run of clean answers. The floor of 1.5 seconds cannot be\nlowered. The agent string carries the project name, its version and the address\nof this repository, so the site can reach a person.\n\nSubtitles are the work of the people who wrote and timed them. This server reads\nthe catalogue and downloads no subtitle file: every record carries `page_url`,\nwhich is the page a reader opens to download it. Credit tvsubtitles.net and link\nthat page when you show a result.\n\nThis MCP server is not affiliated with tvsubtitles.net.\n\n## Privacy\n\nNo account, no key, no telemetry. The only host reached is\n`https://www.tvsubtitles.net`. Pages are held in memory for fifteen minutes and\nnothing is written to disk. Diagnostics go to stderr. See [PRIVACY.md](./PRIVACY.md).\n\n## Development\n\n```bash\nnpm install\nnpm run build:fixtures\nnpm test\nnpm run coverage\nnpm run check\n```\n\n`npm run test:live` makes one request per route against the site, and runs\nnightly.\n\n## Contributing\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md)\nand [SECURITY.md](./SECURITY.md).\n\n## License\n\nMIT, see [LICENSE](./LICENSE).\n\n---\n\n<a name=\"mcp-tvsubtitles-français\"></a>\n\n# mcp-tvsubtitles (français)\n\n_[English version](#mcp-tvsubtitles)_\n\n[TVsubtitles.net](https://www.tvsubtitles.net) catalogue les sous-titres de\nséries télévisées. Ses lecteurs y déposent un fichier pour un épisode, calé sur\nune version vidéo, et le site enregistre la langue, la version pour laquelle il a\nété taillé, qui l'a déposé et quand, la taille du fichier et le nombre de fois\nqu'il a été pris. Il en tient environ trois cent mille, sur quelque quatre-vingt-six\nmille épisodes, dans vingt-quatre langues.\n\nCe serveur relie un client de conversation à ce catalogue. On peut chercher une\nsérie, lire une saison en voyant quelles langues tiennent quelque chose pour\nchaque épisode, lire les fiches d'un épisode, et ouvrir une fiche avec la version\npour laquelle elle a été taillée et qui l'a déposée. Chaque fiche porte l'adresse\nde sa page sur le site. Aucune clé d'API ni aucun compte ne sont nécessaires.\n\n## Installation\n\n**Installation en un clic**\n\n[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=tvsubtitles&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC10dnN1YnRpdGxlcyJdfQ==)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=tvsubtitles&config=%7B%22name%22%3A%22tvsubtitles%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-tvsubtitles%22%5D%7D)\n\n**Claude Code**\n\n```bash\nclaude mcp add tvsubtitles -- npx -y mcp-tvsubtitles\n```\n\n**Tout client lisant `mcpServers`**\n\n```json\n{\n  \"mcpServers\": {\n    \"tvsubtitles\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-tvsubtitles\"]\n    }\n  }\n}\n```\n\n### Avec Docker\n\n```json\n{\n  \"mcpServers\": {\n    \"tvsubtitles\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"ghcr.io/smeet666/mcp-tvsubtitles:1.0.1\"]\n    }\n  }\n}\n```\n\nLe conteneur joint `https://www.tvsubtitles.net` et rien d'autre.\n\n### Bundle, sans npm\n\nTélécharger `mcp-tvsubtitles.mcpb` depuis la\n[dernière publication](https://github.com/smeet666/mcp-tvsubtitles/releases/latest)\net l'ouvrir avec un hôte qui installe les bundles MCP. Il emporte ses\ndépendances, donc Node 24 ou plus récent suffit.\n\n## Ce qu'on peut demander\n\n- « Est-ce que tvsubtitles a des sous-titres français pour Smallville ? »\n- « Quelles langues couvrent la saison 3 de Harbour Lights ? »\n- « Liste les sous-titres anglais de l'épisode 7 de cette saison. »\n- « Sur quelle version ce sous-titre est-il calé, et qui l'a déposé ? »\n- « Trouve-moi la page pour télécharger le sous-titre polonais du dernier épisode. »\n\n## Les outils\n\n| Outil            | Ce qu'il fait                                                              |\n| ---------------- | -------------------------------------------------------------------------- |\n| `search_titles`  | Trouve une série par son nom et rend l'id que les autres prennent.         |\n| `list_subtitles` | Lit la couverture d'une saison, ou les fiches d'un épisode.                |\n| `get_subtitle`   | Lit une fiche, avec sa version, son déposant et sa page de téléchargement. |\n| `list_languages` | Liste les langues du catalogue, ou celles que tient une série.             |\n\n### `search_titles`\n\nCherche dans le catalogue par le nom. Le site ne catalogue que la télévision,\ndonc une recherche de film est refusée au lieu d'être répondue.\n\n| Argument      | Type                       | Requis | Ce qu'il fait                                                                                                                      |\n| ------------- | -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |\n| `query`       | chaîne, 1 à 120 caractères | oui    | Le nom d'une série, ou une partie.                                                                                                 |\n| `media_type`  | `movie` \\| `tv` \\| `any`   | non    | `tv` et `any` cherchent dans le catalogue. `movie` est refusé.                                                                     |\n| `year`        | entier, 1900 à 2100        | non    | Garde les lignes dont les années publiées couvrent celle-ci.                                                                       |\n| `limit`       | entier, 1 à 100, défaut 20 | non    | Lignes à rendre.                                                                                                                   |\n| `with_counts` | booléen, défaut faux       | non    | Lit les comptes de sous-titres, d'épisodes et de saisons de chaque ligne dans l'index du catalogue, au prix d'une requête de plus. |\n\n**En retour :** les séries trouvées, chacune avec l'`id` que prennent les autres\noutils, les années publiées par le site et les langues pour lesquelles il dessine\nun drapeau. `imdb_id` et `tmdb_id` valent null, puisque la recherche du site n'en\npublie aucun. `subtitle_count`, `episode_count` et `season_count` valent null\ntant que `with_counts` ne les demande pas, car le site publie ces trois chiffres\nsur l'index de son catalogue et non sur la page qui répond à une recherche ;\nchacun compte toutes les saisons de la série ensemble, ce que `counts_scope`\nnomme, chacun se lit à part, et une série dont l'index ne porte aucune ligne\ngarde trois null. `total_available` compte les lignes que cette recherche a\nramenées, ce que `total_counts` nomme. Une année qui ne laisse rien est mise de\ncôté et nommée dans `filters_dropped`.\n\n### `list_subtitles`\n\nLit ce qu'une série tient, sous l'une de deux formes que `kind` nomme.\n\n| Argument   | Type                       | Requis | Ce qu'il fait                                                            |\n| ---------- | -------------------------- | ------ | ------------------------------------------------------------------------ |\n| `id`       | chaîne, 1 à 12 caractères  | oui    | Un id de série venu de `search_titles`.                                  |\n| `season`   | entier, 1 à 200            | non    | Omis, la saison la plus récente est lue.                                 |\n| `episode`  | entier, 1 à 500            | non    | Nommé, la réponse porte les fiches de cet épisode.                       |\n| `language` | chaîne, 1 à 40 caractères  | non    | Une langue de `list_languages`, par son nom, son code ou son tag BCP 47. |\n| `limit`    | entier, 1 à 200, défaut 40 | non    | Lignes à rendre.                                                         |\n\n**En retour :** avec une saison seule, `kind` vaut `coverage` et chaque ligne est\nun épisode, portant `episode_id`, le nombre de sous-titres que le site compte et\nles langues qui tiennent quelque chose. Avec un épisode nommé, `kind` vaut\n`subtitles` et chaque ligne est une fiche portant l'`id` que prend\n`get_subtitle`. `season` est la saison servie par le site et `season_requested`\ncelle demandée, les deux différant quand la plus récente a été lue.\n`seasons_available` liste les saisons que la série tient. Une langue qui ne tient\nrien est mise de côté, la réponse revient sans la restriction, et\n`filters_dropped` la nomme.\n\n### `get_subtitle`\n\nLit une fiche depuis un id rendu par `list_subtitles`.\n\n| Argument | Type                      | Requis | Ce qu'il fait                                 |\n| -------- | ------------------------- | ------ | --------------------------------------------- |\n| `id`     | chaîne, 1 à 12 caractères | oui    | Un id de sous-titre venu de `list_subtitles`. |\n\n**En retour :** la fiche, avec `page_url` pour la page qu'un lecteur ouvre afin\nde télécharger le fichier. `read_from` vaut ici `record`, et `listing` sur une\nligne venue de `list_subtitles` : c'est ce qui distingue un champ non lu d'un\nchamp que le site ne publie pas, car une liste ne porte ni `file_name`, ni\n`size_text`, ni `comment`, que le site n'imprime que sur la page d'une fiche. `releases` porte les versions vidéo publiées par le\nsite et `release_match` dit s'il en a publié une : `stated` quand oui, `none`\nquand non, donc une fiche marquée `none` ne dit rien de la vidéo sur laquelle\nelle est calée. `uploader` vaut null sur environ deux fiches sur trois.\n`published_at` est l'horodatage du site lu en ISO 8601 et ne porte aucun fuseau,\net `published_text` garde la formulation du site. `rating` porte deux compteurs\nque le site publie, où un zéro est un chiffre qu'il a imprimé.\n\n### `list_languages`\n\nListe les langues que le site catalogue, ou celles que tient une série.\n\n| Argument | Type                      | Requis | Ce qu'il fait                                       |\n| -------- | ------------------------- | ------ | --------------------------------------------------- |\n| `id`     | chaîne, 1 à 12 caractères | non    | Un id de série, pour lire ce que cette série tient. |\n| `season` | entier, 1 à 200           | non    | Sur quelle saison mesurer. Ignoré sans `id`.        |\n\n**En retour :** chaque langue avec le nom que le site imprime, le `site_code` de\ndeux lettres par lequel il l'adresse, le `code` BCP 47 quand la correspondance\nest certaine, et `differs_from_iso`. `scope` dit ce qui a été mesuré :\n`catalogue` pour le site entier, ou `season` quand un id de série a été passé, et\n`count` vaut alors les épisodes de cette saison qui tiennent la langue.\n\n## Les langues, et les codes du site\n\nLe site dessine vingt-quatre drapeaux et adresse chaque langue par deux lettres\nde son choix. Six diffèrent de l'ISO 639-1, et l'une entre en collision : le site\nécrit `br` pour le portugais brésilien, que l'ISO attribue au breton.\n\n| Code du site | Langue              | BCP 47  |\n| ------------ | ------------------- | ------- |\n| `br`         | Portugais brésilien | `pt-BR` |\n| `gr`         | Grec                | `el`    |\n| `cz`         | Tchèque             | `cs`    |\n| `jp`         | Japonais            | `ja`    |\n| `cn`         | Chinois             | `zh`    |\n| `ua`         | Ukrainien           | `uk`    |\n\n`language` garde le nom du site et `language_code` porte le tag, donc rien n'est\nà déduire des deux lettres. `list_subtitles` accepte une langue écrite de l'une\ndes trois façons.\n\n## Configuration\n\nRien n'est à régler. Toutes les variables ci-dessous sont optionnelles.\n\n| Variable                | Défaut  | Bornes                             | Ce qu'elle fait                                                 |\n| ----------------------- | ------- | ---------------------------------- | --------------------------------------------------------------- |\n| `TVS_USER_AGENT`        | absent  |                                    | Placé devant l'agent du serveur, qui reste attaché.             |\n| `TVS_MIN_INTERVAL_MS`   | 2000    | 1500 à 60000                       | Millisecondes entre deux requêtes. 1500 est un plancher.        |\n| `TVS_TIMEOUT_MS`        | 20000   | 1000 à 120000                      | Délai d'une tentative.                                          |\n| `TVS_BUDGET_MS`         | 60000   | 5000 à 600000                      | Délai d'une lecture, reprises comprises.                        |\n| `TVS_MAX_RETRIES`       | 3       | 0 à 8                              | Tentatives après la première.                                   |\n| `TVS_CACHE_TTL_MS`      | 900000  | 0 à 86400000                       | Durée de conservation d'une page en mémoire. 0 éteint le cache. |\n| `TVS_CACHE_MAX_ENTRIES` | 200     | 1 à 5000                           | Pages gardées avant que la plus ancienne parte.                 |\n| `TVS_MAX_BODY_BYTES`    | 8000000 | 100000 à 64000000                  | Plus grande réponse lue pour une page.                          |\n| `TVS_LOG_LEVEL`         | `error` | `silent`, `error`, `info`, `debug` | Ce qui atteint stderr.                                          |\n\nUne valeur hors bornes est refusée sur stderr et le défaut s'applique.\n\n## Erreurs\n\n| Code            | Ce que ça veut dire                               | Quoi faire                                                     |\n| --------------- | ------------------------------------------------- | -------------------------------------------------------------- |\n| `not_found`     | Le site a répondu et ne tient pas cette chose.    | Vérifier que l'id vient d'une liste et non d'une construction. |\n| `invalid_input` | Les arguments ne peuvent pas produire de requête. | Lire le message, qui nomme l'argument.                         |\n| `rate_limited`  | Le site demande à ce client de ralentir.          | Attendre et redemander. La chose demandée existe toujours.     |\n| `parse_failure` | Une réponse est arrivée dans une forme illisible. | Le signaler avec les arguments employés.                       |\n| `network_error` | La requête ne s'est pas achevée.                  | Réessayer.                                                     |\n| `timeout`       | Aucune réponse dans le délai.                     | Réessayer, ou élargir `TVS_BUDGET_MS`.                         |\n\n## Comme bibliothèque\n\nLa couche qui lit le site est publiée seule, avec son rythme, son cache et ses\ncodes d'erreur, sans protocole attaché.\n\n```ts\nimport { TvSubtitlesClient } from \"mcp-tvsubtitles/client\";\n\nconst client = new TvSubtitlesClient();\nconst found = await client.searchShows(\"Smallville\");\nconst season = await client.getSeason(found.data.rows[0].id, 0);\nconsole.log(season.data.showName, season.data.season, season.data.episodes.length);\n```\n\nToute lecture rend `{ data, cached }`, avec `skipped` quand des lignes ont été\nécartées. Le constructeur prend `{ config, logger, fetchImpl }`, et le plancher\nd'intervalle tient quoi qu'on lui passe.\n\n## Rythme et attribution\n\nUne requête à la fois, deux secondes d'écart, élargi quand le site repousse et\nresserré après une série de réponses propres. Le plancher d'une seconde et demie\nne peut pas être abaissé. La chaîne d'agent porte le nom du projet, sa version et\nl'adresse de ce dépôt, pour que le site puisse joindre une personne.\n\nLes sous-titres sont l'œuvre de ceux qui les ont écrits et calés. Ce serveur lit\nle catalogue et ne télécharge aucun fichier de sous-titres : chaque fiche porte\n`page_url`, la page qu'un lecteur ouvre pour le télécharger. Créditer\ntvsubtitles.net et lier cette page en montrant un résultat.\n\nCe serveur MCP n'est pas affilié à tvsubtitles.net.\n\n## Confidentialité\n\nAucun compte, aucune clé, aucune télémétrie. Le seul hôte joint est\n`https://www.tvsubtitles.net`. Les pages sont gardées quinze minutes en mémoire\net rien n'est écrit sur le disque. Les diagnostics vont sur stderr. Voir\n[PRIVACY.md](./PRIVACY.md).\n\n## Développement\n\n```bash\nnpm install\nnpm run build:fixtures\nnpm test\nnpm run coverage\nnpm run check\n```\n\n`npm run test:live` fait une requête par route contre le site, et tourne chaque\nnuit.\n\n## Contribuer\n\nLes issues et les pull requests sont bienvenues. Voir\n[CONTRIBUTING.md](./CONTRIBUTING.md) et [SECURITY.md](./SECURITY.md).\n\n## Licence\n\nMIT, voir [LICENSE](./LICENSE).\n",
  "bytes": 30653,
  "sha": "a8a87ac6838321e3e848ed911d6df1a5835838b5916f68858aa34e06aa7f76a0",
  "repo_slug": "smeet666/mcp-tvsubtitles",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_smeet666_mcp_tvsubtitles_105696bf/readme"
}