mcp-stashbox

A stash-box is a shared metadata catalogue: it records scenes, the performers credited on them, the studios that released them, and the tags they are filed under, each curated by submission and review. A catalogue holds no media — a record names where something was published and carries nothing of it — and it identifies a file by the fingerprints computed from it. Five such catalogues run independently, each issuing its own key to a registered account.

This server connects a chat client to all of them at once. You can search the scenes, performers, studios and tags of every catalogue you hold a key for, read one record as a single card assembled from every catalogue that holds it, identify a file from its fingerprints, and ask what each catalogue was measured answering. It needs a key per catalogue, and reads only the catalogues it has one for.

Version française

Install

One-click install

Claude Code

claude mcp add stashbox --env STASHBOX_STASHDB_KEY=your-key -- npx -y mcp-stashbox

Claude Desktop, Cursor, and any client using the standard config format

{
  "mcpServers": {
    "stashbox": {
      "command": "npx",
      "args": ["-y", "mcp-stashbox"],
      "env": {
        "STASHBOX_STASHDB_KEY": "your-key"
      }
    }
  }
}

Node 24 or later is required. Set a key for each catalogue you want read; the others are named as absent from every answer.

With Docker

{
  "mcpServers": {
    "stashbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "STASHBOX_STASHDB_KEY",
        "ghcr.io/smeet666/mcp-stashbox:2.0.1"
      ]
    }
  }
}

-i keeps stdin open, which is where the protocol travels, and -t is left out because a TTY rewrites the stream. The container needs outbound HTTPS to the catalogues you hold keys for, and the keys from your environment: no volume, no port.

Bundle, without npm

Download mcp-stashbox-2.0.1.mcpb from the latest release and open it. A client that supports MCP bundles installs it on its own, with no npm to run. The keys are still set in the client's configuration.

What you can ask

• "Which catalogues am I actually reading?"
• "Find the performers credited under that name."
• "Read me that studio's record."
• "What is this file? Here is its MD5."
• "Which scenes did those two perform in together?"

The ordinary path runs from a search to a card: a row carries an id written instance:uuid, and the record tool reads it on every catalogue that holds it.

The catalogues

They answer different surfaces: StashDB answers every route this server knows, and the others answer fewer. get_sources states what each was measured answering and the day it was measured. A catalogue with no key is named as absent from every answer, so an answer holding rows from some of them is never read as the whole.

Tools

Every search takes two exclusive paths. query runs each catalogue's own text index, which reads the words as a union. The typed arguments narrow as an intersection. Writing both is refused.

get_sources

States what each configured catalogue was measured answering, and the day its surface was read. It reaches no catalogue and takes no argument.

In return: one entry per catalogue with its name, its identifier prefix, whether a key is held for it in this install, the variable to set when none is, and the routes it answers. Whether a key is held is a fact about this install and changes nothing about what the catalogue does.

search_scenes

Searches the scenes.

In return: rows carrying the id written instance:uuid, which get_scene takes, and what names the record. A row leaves the synopsis, the link lists and the editing stamps to the card, since none of those separates two releases. The answer says per catalogue which of three it met: a failure, a catalogue nobody asked, or an emptiness it established. Counts are never added across catalogues. A search written with words alone reads the first rows each text index answers with, since those routes take no page.

search_performers

Searches the performers.

alias is declared and never sent. No catalogue's faceted route applies it: a request carrying it answers as wide as one carrying none, so it is left out and the answer names it as a narrowing nobody received.

In return: the rows and the per-catalogue accounting search_scenes returns.

search_studios

Searches the studios.

In return: the rows and the per-catalogue accounting search_scenes returns.

search_tags

Searches the tags.

In return: the rows and the per-catalogue accounting search_scenes returns.

get_scene

Reads one scene as a single card.

In return: one card, read on every catalogue that holds the record and reached by the link each of them publishes to the same record elsewhere. Every value names the catalogues that said it, and where they disagree the reading nobody preferred is published beside the one that won. Left out, the registry's own order stands, and every card states the order applied.

get_performer

Reads one performer as a single card.

studios is the whole table of studios they are credited on, which runs to hundreds of rows.

In return: the card get_scene returns, for a performer.

get_studio

Reads one studio as a single card.

In return: the card get_scene returns, for a studio.

get_tag

Reads one tag as a single card.

In return: the card get_scene returns, for a tag.

find_by_fingerprint

Identifies a file from the hashes held for it.

MD5 and OSHASH name the bytes of a file. PHASH states a likeness, which a re-encode, a crop or another scene from the same shoot can satisfy: read a PHASH match as a resemblance rather than as an identity.

In return: each record reached, answered as one card read on every catalogue that holds it.

What an answer states about the catalogues

Every answer accounts for each catalogue separately, because merging them would lose what a caller needs. A catalogue that failed, one nobody asked, and one that answered with nothing are three different things, and they are reported as three. Counts stay beside the catalogue that produced them and are never added up. On a card, each value names the catalogues that said it, and a disagreement is published rather than resolved silently.

Configuration

A key per catalogue, and everything else optional. All of it goes in the env block of your client config.

Each catalogue issues its key to a registered account, in that account's settings. This server ships no key of its own, and each user brings their own. A value outside its range falls back to the default, and the reason is written to stderr.

Errors

Every failure carries one of six codes, a message, and where it helps a hint naming the next move.

A catalogue that failed is reported per catalogue rather than failing the whole answer, so one silent catalogue never hides the others.

As a library

The layer reading the catalogues is published on its own, with its pacing, its cache and its errors, and with no protocol attached.

import { Catalogues } from "mcp-stashbox/client";

const client = new Catalogues();
const read = await client.searchPerformers({ name: "example", limit: 5 });
console.log(read.data.rows.length, read.cached);

Each read answers { data, cached }, and throws an error carrying one of the six codes. The one-second floor between two requests holds here as well.

Pacing and attribution

Requests go out one at a time with at least a second between them, and that floor holds however the server is configured. The User-Agent always ends with the project identity and an address where a person can be reached.

Every record carries the address of its page on the catalogue it came from, and a card carries the link each catalogue publishes to the same record elsewhere. The catalogues are built by the people who submit and review their records.

This MCP server is an unofficial project, with no affiliation to any of the catalogues it reads.

Privacy

This server collects nothing about you and sends nothing to its author. It runs on your machine, contacts only the catalogues you hold a key for, holds its answers in memory while it runs, and writes nothing to disk. Your keys are read from the environment and sent to their own catalogue alone. PRIVACY.md states what a request carries and which settings change any of it.

Development

npm install
npm run build:fixtures
npm test
npm run check

Tests run against generated fixtures and make no network request. The live suite, npm run test:live, makes one request per route and runs nightly against the catalogues themselves.

Contributing

Bugs, questions and ideas belong in the issue tracker. Pull requests are welcome; opening an issue first helps agree on the shape of the change. See CONTRIBUTING.md.

License

MIT, see LICENSE. The records belong to the catalogues and to the people who built them.

mcp-stashbox (français)

English version

Un stash-box est un catalogue de métadonnées partagé : il enregistre des scènes, les interprètes qui y sont crédités, les studios qui les ont publiées, et les étiquettes sous lesquelles elles sont rangées, le tout tenu par soumission et relecture. Un catalogue ne contient aucun média — une fiche nomme où quelque chose a été publié et n'en emporte rien — et il identifie un fichier par les empreintes calculées dessus. Cinq catalogues de ce type fonctionnent indépendamment, chacun délivrant sa propre clé à un compte enregistré.

Ce serveur relie un client de conversation à tous à la fois. On peut chercher les scènes, les interprètes, les studios et les étiquettes de chaque catalogue dont on détient une clé, lire une fiche sous forme d'une carte unique assemblée depuis tous les catalogues qui la détiennent, identifier un fichier par ses empreintes, et demander ce que chaque catalogue a été mesuré répondant. Il demande une clé par catalogue, et ne lit que ceux dont il en a une.

Installation

Installation en un clic

Claude Code

claude mcp add stashbox --env STASHBOX_STASHDB_KEY=votre-cle -- npx -y mcp-stashbox

Claude Desktop, Cursor, et tout client au format de configuration standard

{
  "mcpServers": {
    "stashbox": {
      "command": "npx",
      "args": ["-y", "mcp-stashbox"],
      "env": {
        "STASHBOX_STASHDB_KEY": "votre-cle"
      }
    }
  }
}

Node 24 ou plus récent est nécessaire. Posez une clé par catalogue à lire ; les autres sont nommés comme absents de chaque réponse.

Avec Docker

{
  "mcpServers": {
    "stashbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "STASHBOX_STASHDB_KEY",
        "ghcr.io/smeet666/mcp-stashbox:2.0.1"
      ]
    }
  }
}

-i garde l'entrée standard ouverte, qui est le canal du protocole, et -t est omis parce qu'un TTY réécrit le flux. Le conteneur a besoin d'un accès HTTPS sortant vers les catalogues dont vous détenez les clés, et de ces clés prises dans votre environnement : aucun volume, aucun port.

Bundle, sans npm

Téléchargez mcp-stashbox-2.0.1.mcpb depuis la dernière publication et ouvrez-le. Un client qui gère les bundles MCP l'installe seul, sans npm à lancer. Les clés se posent toujours dans la configuration du client.

Ce qu'on peut demander

• « Quels catalogues est-ce que je lis réellement ? »
• « Trouve les interprètes crédités sous ce nom. »
• « Lis-moi la fiche de ce studio. »
• « Qu'est-ce que ce fichier ? Voici son MD5. »
• « Dans quelles scènes ces deux-là ont-ils joué ensemble ? »

Le chemin ordinaire va d'une recherche à une carte : une ligne porte un id écrit instance:uuid, et l'outil de fiche le lit sur chaque catalogue qui le détient.

Les catalogues

Ils répondent des surfaces différentes : StashDB répond à toutes les routes que ce serveur connaît, les autres à moins. get_sources dit ce que chacun a été mesuré répondant et le jour de la mesure. Un catalogue sans clé est nommé comme absent de chaque réponse, si bien qu'une réponse portant les lignes de certains ne se lit jamais comme l'ensemble.

Les outils

Chaque recherche prend deux chemins exclusifs. query interroge l'index textuel de chaque catalogue, qui lit les mots comme une union. Les arguments typés resserrent comme une intersection. Écrire les deux est refusé.

get_sources

Dit ce que chaque catalogue configuré a été mesuré répondant, et le jour où sa surface a été lue. Il ne joint aucun catalogue et ne prend aucun argument.

En retour : une entrée par catalogue avec son nom, son préfixe d'identifiant, la présence d'une clé dans cette installation, la variable à poser quand il n'y en a pas, et les routes auxquelles il répond. La présence d'une clé est un fait sur cette installation et ne change rien à ce que le catalogue fait.

search_scenes

Cherche les scènes.

En retour : des lignes portant l'id écrit instance:uuid, que get_scene reprend, et ce qui nomme la fiche. Une ligne laisse à la carte le synopsis, les listes de liens et les horodatages d'édition, dont aucun ne distingue deux publications. La réponse dit par catalogue laquelle des trois il a rencontrées : un échec, un catalogue que personne n'a interrogé, ou un vide qu'il a établi. Les comptes ne sont jamais additionnés entre catalogues. Une recherche écrite avec des mots seuls lit les premières lignes que rend chaque index textuel, ces routes ne prenant aucune page.

search_performers

Cherche les interprètes.

alias est déclaré et jamais envoyé. Aucune route à facettes ne l'applique : une requête qui le porte répond aussi large qu'une requête sans lui, donc il est laissé de côté et la réponse le nomme comme un resserrement que personne n'a reçu.

En retour : les lignes et la comptabilité par catalogue que rend search_scenes.

search_studios

Cherche les studios.

En retour : les lignes et la comptabilité par catalogue de search_scenes.

search_tags

Cherche les étiquettes.

En retour : les lignes et la comptabilité par catalogue de search_scenes.

get_scene

Lit une scène sous forme d'une carte unique.

En retour : une carte, lue sur chaque catalogue qui détient la fiche et atteinte par le lien que chacun publie vers la même fiche ailleurs. Chaque valeur nomme les catalogues qui l'ont dite, et là où ils divergent, la lecture que personne n'a préférée est publiée à côté de celle qui l'emporte. Omis, l'ordre propre du registre s'applique, et chaque carte énonce l'ordre appliqué.

get_performer

Lit un interprète sous forme d'une carte unique.

studios est la table entière des studios sur lesquels ils sont crédités, qui fait des centaines de lignes.

En retour : la carte que rend get_scene, pour un interprète.

get_studio

Lit un studio sous forme d'une carte unique.

En retour : la carte que rend get_scene, pour un studio.

get_tag

Lit une étiquette sous forme d'une carte unique.

En retour : la carte que rend get_scene, pour une étiquette.

find_by_fingerprint

Identifie un fichier par les empreintes qu'on en détient.

MD5 et OSHASH nomment les octets d'un fichier. PHASH énonce une ressemblance, qu'un ré-encodage, un recadrage ou une autre scène du même tournage peuvent satisfaire : lisez une correspondance PHASH comme une ressemblance plutôt que comme une identité.

En retour : chaque fiche atteinte, rendue comme une carte lue sur chaque catalogue qui la détient.

Ce qu'une réponse dit des catalogues

Chaque réponse rend compte de chaque catalogue séparément, parce que les fondre perdrait ce dont un appelant a besoin. Un catalogue qui a échoué, un que personne n'a interrogé et un qui a répondu vide sont trois choses différentes, et elles sont rapportées comme trois. Les comptes restent à côté du catalogue qui les a produits et ne sont jamais additionnés. Sur une carte, chaque valeur nomme les catalogues qui l'ont dite, et un désaccord est publié plutôt que tranché en silence.

Configuration

Une clé par catalogue, et tout le reste facultatif. Tout se pose dans le bloc env de la configuration du client.

Chaque catalogue délivre sa clé à un compte enregistré, dans les réglages de ce compte. Ce serveur n'embarque aucune clé, et chacun apporte les siennes. Une valeur hors de sa plage retombe sur le défaut, et la raison est écrite sur la sortie d'erreur.

Erreurs

Chaque échec porte un des six codes, un message, et quand cela aide une indication du geste suivant.

Un catalogue qui échoue est rapporté catalogue par catalogue plutôt que de faire échouer toute la réponse, donc un catalogue silencieux n'en cache jamais d'autres.

Comme bibliothèque

La couche qui lit les catalogues est publiée seule, avec son rythme, son cache et ses erreurs, sans protocole attaché.

import { Catalogues } from "mcp-stashbox/client";

const client = new Catalogues();
const read = await client.searchPerformers({ name: "example", limit: 5 });
console.log(read.data.rows.length, read.cached);

Chaque lecture répond { data, cached }, et lève une erreur portant un des six codes. Le plancher d'une seconde entre deux requêtes tient également ici.

Rythme et attribution

Les requêtes partent une à une avec au moins une seconde entre elles, et ce plancher tient quelle que soit la configuration. Le User-Agent se termine toujours par l'identité du projet et une adresse où joindre une personne.

Chaque fiche porte l'adresse de sa page sur le catalogue d'où elle vient, et une carte porte le lien que chaque catalogue publie vers la même fiche ailleurs. Les catalogues sont bâtis par ceux qui soumettent et relisent leurs fiches.

Ce MCP est un projet non officiel, sans affiliation à aucun des catalogues qu'il lit.

Confidentialité

Ce serveur ne collecte rien sur vous et n'envoie rien à son auteur. Il tourne sur votre machine, ne joint que les catalogues dont vous détenez une clé, garde ses réponses en mémoire le temps qu'il tourne, et n'écrit rien sur le disque. Vos clés sont lues dans l'environnement et envoyées à leur seul catalogue. PRIVACY.md dit ce qu'une requête emporte et quels réglages changent cela.

Développement

npm install
npm run build:fixtures
npm test
npm run check

Les tests s'exécutent sur des fixtures engendrées et n'émettent aucune requête. La suite en direct, npm run test:live, émet une requête par route et tourne chaque nuit contre les catalogues eux-mêmes.

Contribuer

Les anomalies, les questions et les idées ont leur place dans le suivi d'incidents. Les propositions de modification sont bienvenues ; ouvrir un ticket d'abord aide à s'accorder sur la forme du changement. Voir CONTRIBUTING.md.

Licence

MIT, voir LICENSE. Les fiches appartiennent aux catalogues et à ceux qui les ont bâties.