Mcp Stashbox

io.github.smeet666由 GitHub 账号 smeet666 发布v2.1.0更新于 Nov 3, 2026

Search scenes, performers, studios and tags across the public stash-box catalogues.

已验证STDIO仅桌面网页搜索与抓取媒体与设计

服务详情

标识符: io.github.smeet666/mcp-stashbox
传输: STDIO
运行时: Desktop only
信任: Verified
发布于: Sep 16, 2026

安全提示

MCP 服务会接收对话中的工具调用请求，并可能执行外部操作。启用前请先了解该服务能做什么，并只授予它所需的权限。

注册中心已验证此条目所属的 GitHub 账号 smeet666。这并不表明该账号就是产品方。

SourceWeft 的检查只涵盖条目是否完整、端点是否响应；不审查服务器的代码，也不审查其工具的行为。

在 README 中添加徽章

向读者展示该 MCP 服务已收录于 SourceWeft，徽章链接到本页。

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.smeet666%2Fmcp-stashbox.svg)](https://sourceweft.com/mcp/io.github.smeet666%2Fmcp-stashbox?utm_source=readme&utm_medium=badge)

概览

AI 生成的概览

在已配置密钥的多个 stash-box 元数据目录中搜索和读取场景、演员、片商与标签，并可通过哈希识别文件。

可以做什么: 跨已配置目录搜索场景、演员、片商和标签，支持文本查询或结构化筛选
将单个场景、演员、片商或标签读取为合并各目录数据的卡片，并标注每个值的来源
通过 MD5、OSHASH 或 PHASH 指纹识别文件
查看已配置的目录、各目录实测可用的接口以及已持有的密钥
适用场景: 适合需要让助手同时查询多个 stash-box 成人影视元数据目录、比较各目录对同一记录的描述，或用哈希把本地文件对应到已知场景的场景。
运行要求: 以 stdio 本地运行，可通过 npx（需 Node 24 或更高版本）、Docker 镜像或 MCP 安装包部署。每个目录需要各自的 API 密钥，通过 STASHBOX_STASHDB_KEY、STASHBOX_TPDB_KEY、STASHBOX_FANSDB_KEY、STASHBOX_PMV_KEY 或 STASHBOX_JAVSTASH_KEY 设置；未配置密钥的目录会在结果中标为缺失。需要对这些目录的出站 HTTPS 访问。另有缓存、超时、重试、请求间隔、User-Agent 和日志级别等可选变量。

安装前请注意

各目录密钥是与注册账户绑定的凭据，从环境变量读取且只发送给对应目录。服务器为只读，不回写数据，但会访问第三方目录并发送查询内容和文件哈希。PHASH 匹配表示相似而非同一。该项目为非官方项目，与各目录无隶属关系。

安装

在 SourceWeft 中

打开控制台中的 Mcp Stashbox，将其添加到工作区。
为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照仓库中的启动说明。

README

mcp-stashbox

[npm] [CI] [license] [MCP Registry] [M8ven] [LobeHub] [Install in Cursor] [Install in VS Code]

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

[Install in Cursor] [Install in VS Code]

Claude Code

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

json

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

{  "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

json

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

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

-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.1.0.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

Catalogue	Address	Key
StashDB	`stashdb.org`	`STASHBOX_STASHDB_KEY`
TPDB	`theporndb.net`	`STASHBOX_TPDB_KEY`
FansDB	`fansdb.cc`	`STASHBOX_FANSDB_KEY`
PMV Stash	`pmvstash.org`	`STASHBOX_PMV_KEY`
JAVStash	`javstash.org`	`STASHBOX_JAVSTASH_KEY`

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

Tool	What it does
`get_sources`	States what each catalogue answers, and which keys are held.
`search_scenes`	Searches the scenes of every configured catalogue.
`search_performers`	Searches the performers.
`search_studios`	Searches the studios.
`search_tags`	Searches the tags.
`get_scene`	Reads one scene as a single card.
`get_performer`	Reads one performer as a single card.
`get_studio`	Reads one studio as a single card.
`get_tag`	Reads one tag as a single card.
`find_by_fingerprint`	Identifies a file from the hashes held for it.

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.

Argument	Type	Required	What it does
`query`	string	no	Words for each catalogue's own text index.
`title`	string	no	Words a title carries.
`code`	string	no	The studio's own reference for the release.
`alias`	string	no	Another title the release is known by.
`date`	a calendar day	no	The release date to compare against.
`date_compare`	`on`, `before` or `after`	no	How that date is read.
`performer_ids`	list of identifiers	no	Performers credited on it.
`studio_ids`	list of identifiers	no	Studios that released it.
`parent_studio_id`	an identifier	no	A studio the releasing studio sits under.
`tag_ids`	list of identifiers	no	Tags it is filed under.
`match`	`all` or `any`	no	How a list of identifiers is read.
`sort`	`title`, `date`, `duration`, `trending`, `popularity`, `created_at` or `updated_at`	no	The order the catalogue applies.
`direction`	`asc` or `desc`	no	Which way that order runs.
`page`	integer, 1 to 1000	no	Which page of each catalogue's own order.
`limit`	integer, 1 to 100	no	Rows one page of one catalogue carries.
`sources`	list of catalogues	no	Read these catalogues alone.

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.

Argument	Type	Required	What it does
`query`	string	no	Words for each catalogue's own text index.
`name`	string	no	Words a name carries.
`alias`	string	no	Another name they are known by.
`disambiguation`	string	no	What the catalogue adds to tell two apart.
`gender`	one of the values the catalogue records	no	The gender the catalogue records.
`country`	a two-letter country code	no	The country the catalogue records.
`ethnicity`	one of the values the catalogue records	no	The ethnicity the catalogue records.
`birth_year`	integer, 1800 to 2200	no	The year of birth.
`career_start_year`	integer, 1800 to 2200	no	The year a career opened.
`career_end_year`	integer, 1800 to 2200	no	The year a career closed.
`performed_with`	an identifier	no	Someone they are credited alongside.
`studio_id`	an identifier	no	A studio they are credited on.
`sort`	`name`, `birthdate`, `deathdate`, `scene_count`, `career_start_year`, `debut`, `last_scene`, `popularity`, `created_at` or `updated_at`	no	The order the catalogue applies.
`direction`	`asc` or `desc`	no	Which way that order runs.
`page`	integer, 1 to 1000	no	Which page.
`limit`	integer, 1 to 100	no	Rows one page of one catalogue carries.
`sources`	list of catalogues	no	Read these catalogues alone.

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.

Argument	Type	Required	What it does
`query`	string	no	Words for each catalogue's own text index.
`name`	string	no	Words a name carries.
`parent_id`	an identifier	no	A studio it sits under.
`has_parent`	boolean	no	Whether it sits under another at all.
`sort`	`name`, `created_at` or `updated_at`	no	The order the catalogue applies.
`direction`	`asc` or `desc`	no	Which way that order runs.
`page`	integer, 1 to 1000	no	Which page.
`limit`	integer, 1 to 100	no	Rows one page of one catalogue carries.
`sources`	list of catalogues	no	Read these catalogues alone.

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

`search_tags`

Searches the tags.

Argument	Type	Required	What it does
`query`	string	no	Words for each catalogue's own text index.
`name`	string	no	Words a name carries.
`category_id`	an identifier	no	A category the tag belongs to.
`sort`	`name`, `created_at` or `updated_at`	no	The order the catalogue applies.
`direction`	`asc` or `desc`	no	Which way that order runs.
`page`	integer, 1 to 1000	no	Which page.
`limit`	integer, 1 to 100	no	Rows one page of one catalogue carries.
`sources`	list of catalogues	no	Read these catalogues alone.

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

`get_scene`

Reads one scene as a single card.

Argument	Type	Required	What it does
`id`	an identifier written `instance:uuid`	yes	The record to read.
`sections`	any of `basic`, `fingerprints`, `images`	no	The blocks read beside the card.
`sources`	list of catalogues	no	Read these catalogues alone.
`prefer`	list of catalogues	no	The order preferred where they disagree.

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.

Argument	Type	Required	What it does
`id`	an identifier written `instance:uuid`	yes	The record to read.
`sections`	any of `basic`, `appearance`, `images`, `studios`	no	The blocks read beside the card.
`sources`	list of catalogues	no	Read these catalogues alone.
`prefer`	list of catalogues	no	The order preferred where they disagree.

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.

Argument	Type	Required	What it does
`id`	an identifier written `instance:uuid`	yes	The record to read.
`sources`	list of catalogues	no	Read these catalogues alone.
`prefer`	list of catalogues	no	The order preferred where they disagree.

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

`get_tag`

Reads one tag as a single card.

Argument	Type	Required	What it does
`id`	an identifier written `instance:uuid`	yes	The record to read.
`sources`	list of catalogues	no	Read these catalogues alone.
`prefer`	list of catalogues	no	The order preferred where they disagree.

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

`find_by_fingerprint`

Identifies a file from the hashes held for it.

Argument	Type	Required	What it does
`fingerprints`	a list of `{ hash, algorithm }`, the algorithm `MD5`, `OSHASH` or `PHASH`	yes	The hashes to look up.
`sections`	any of `basic`, `fingerprints`, `images`	no	The blocks read beside each card. One call answers a card per record reached, so a block asked for here reaches a reader once per match.
`sources`	list of catalogues	no	Read these catalogues alone.
`prefer`	list of catalogues	no	The order preferred where they disagree.

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.

Variable	Default	What it does
`STASHBOX_STASHDB_KEY`	none	The key StashDB issues to your account.
`STASHBOX_TPDB_KEY`	none	The key TPDB issues to your account.
`STASHBOX_FANSDB_KEY`	none	The key FansDB issues to your account.
`STASHBOX_PMV_KEY`	none	The key PMV Stash issues to your account.
`STASHBOX_JAVSTASH_KEY`	none	The key JAVStash issues to your account.
`SB_USER_AGENT`	the project identity	Names your application to the catalogues, with an address where a person can be reached.
`SB_MIN_INTERVAL_MS`	`1000`	Gap between two requests, from 1000 to 60000.
`SB_TIMEOUT_MS`	`20000`	Deadline for one request, from 1 to 600000.
`SB_MAX_RETRIES`	`3`	Attempts after a transient failure, from 0 to 10.
`SB_CACHE_TTL_MS`	`300000`	How long an answer stays in memory, from 0 to 86400000.
`SB_CACHE_MAX_ENTRIES`	`500`	Answers held in memory at once, from 1 to 100000.
`SB_LOG_LEVEL`	`error`	`silent`, `error`, `info` or `debug`, written to stderr.

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.

Code	What happened	What to do
`not_found`	A catalogue answered, and holds no such record.	Check the identifier with a search.
`invalid_input`	The arguments were refused before any request went out.	Read the message, which names the argument.
`rate_limited`	A catalogue asked this client to slow down.	Wait, then call again with the same arguments. The record is still there.
`parse_failure`	An answer arrived in a shape this client cannot read.	Report it at the issue tracker.
`network_error`	The request did not complete.	Try again shortly.
`timeout`	The request passed its deadline.	Raise `SB_TIMEOUT_MS`, or ask for fewer rows.

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);

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

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

[Install in Cursor] [Install in VS Code]

Claude Code

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

json

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

{  "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

json

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

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

-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.1.0.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

Catalogue	Adresse	Clé
StashDB	`stashdb.org`	`STASHBOX_STASHDB_KEY`
TPDB	`theporndb.net`	`STASHBOX_TPDB_KEY`
FansDB	`fansdb.cc`	`STASHBOX_FANSDB_KEY`
PMV Stash	`pmvstash.org`	`STASHBOX_PMV_KEY`
JAVStash	`javstash.org`	`STASHBOX_JAVSTASH_KEY`

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

Outil	Ce qu'il fait
`get_sources`	Dit ce que chaque catalogue répond, et quelles clés sont posées.
`search_scenes`	Cherche les scènes de chaque catalogue configuré.
`search_performers`	Cherche les interprètes.
`search_studios`	Cherche les studios.
`search_tags`	Cherche les étiquettes.
`get_scene`	Lit une scène sous forme d'une carte unique.
`get_performer`	Lit un interprète sous forme d'une carte unique.
`get_studio`	Lit un studio sous forme d'une carte unique.
`get_tag`	Lit une étiquette sous forme d'une carte unique.
`find_by_fingerprint`	Identifie un fichier par les empreintes qu'on en détient.

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.

Argument	Type	Requis	Ce qu'il fait
`query`	chaîne	non	Des mots pour l'index textuel de chaque catalogue.
`title`	chaîne	non	Des mots que porte un titre.
`code`	chaîne	non	La référence propre du studio pour la publication.
`alias`	chaîne	non	Un autre titre sous lequel elle est connue.
`date`	un jour de calendrier	non	La date de publication à comparer.
`date_compare`	`on`, `before` ou `after`	non	Comment cette date est lue.
`performer_ids`	liste d'identifiants	non	Les interprètes qui y sont crédités.
`studio_ids`	liste d'identifiants	non	Les studios qui l'ont publiée.
`parent_studio_id`	un identifiant	non	Un studio sous lequel le studio éditeur se range.
`tag_ids`	liste d'identifiants	non	Les étiquettes sous lesquelles elle est rangée.
`match`	`all` ou `any`	non	Comment une liste d'identifiants est lue.
`sort`	`title`, `date`, `duration`, `trending`, `popularity`, `created_at` ou `updated_at`	non	L'ordre qu'applique le catalogue.
`direction`	`asc` ou `desc`	non	Le sens de cet ordre.
`page`	entier, 1 à 1000	non	Quelle page de l'ordre propre à chaque catalogue.
`limit`	entier, 1 à 100	non	Lignes que porte une page d'un catalogue.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.

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.

Argument	Type	Requis	Ce qu'il fait
`query`	chaîne	non	Des mots pour l'index textuel.
`name`	chaîne	non	Des mots que porte un nom.
`alias`	chaîne	non	Un autre nom sous lequel ils sont connus.
`disambiguation`	chaîne	non	Ce que le catalogue ajoute pour en distinguer deux.
`gender`	une des valeurs que le catalogue enregistre	non	Le genre que le catalogue enregistre.
`country`	un code pays à deux lettres	non	Le pays que le catalogue enregistre.
`ethnicity`	une des valeurs que le catalogue enregistre	non	L'ethnicité que le catalogue enregistre.
`birth_year`	entier, 1800 à 2200	non	L'année de naissance.
`career_start_year`	entier, 1800 à 2200	non	L'année où une carrière s'est ouverte.
`career_end_year`	entier, 1800 à 2200	non	L'année où une carrière s'est close.
`performed_with`	un identifiant	non	Quelqu'un à côté de qui ils sont crédités.
`studio_id`	un identifiant	non	Un studio sur lequel ils sont crédités.
`sort`	`name`, `birthdate`, `deathdate`, `scene_count`, `career_start_year`, `debut`, `last_scene`, `popularity`, `created_at` ou `updated_at`	non	L'ordre qu'applique le catalogue.
`direction`	`asc` ou `desc`	non	Le sens de cet ordre.
`page`	entier, 1 à 1000	non	Quelle page.
`limit`	entier, 1 à 100	non	Lignes que porte une page d'un catalogue.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.

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.

Argument	Type	Requis	Ce qu'il fait
`query`	chaîne	non	Des mots pour l'index textuel.
`name`	chaîne	non	Des mots que porte un nom.
`parent_id`	un identifiant	non	Un studio sous lequel il se range.
`has_parent`	booléen	non	S'il se range sous un autre.
`sort`	`name`, `created_at` ou `updated_at`	non	L'ordre qu'applique le catalogue.
`direction`	`asc` ou `desc`	non	Le sens de cet ordre.
`page`	entier, 1 à 1000	non	Quelle page.
`limit`	entier, 1 à 100	non	Lignes que porte une page d'un catalogue.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.

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

`search_tags`

Cherche les étiquettes.

Argument	Type	Requis	Ce qu'il fait
`query`	chaîne	non	Des mots pour l'index textuel.
`name`	chaîne	non	Des mots que porte un nom.
`category_id`	un identifiant	non	Une catégorie dont l'étiquette relève.
`sort`	`name`, `created_at` ou `updated_at`	non	L'ordre qu'applique le catalogue.
`direction`	`asc` ou `desc`	non	Le sens de cet ordre.
`page`	entier, 1 à 1000	non	Quelle page.
`limit`	entier, 1 à 100	non	Lignes que porte une page d'un catalogue.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.

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

`get_scene`

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

Argument	Type	Requis	Ce qu'il fait
`id`	un identifiant écrit `instance:uuid`	oui	La fiche à lire.
`sections`	parmi `basic`, `fingerprints`, `images`	non	Les blocs lus à côté de la carte.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.
`prefer`	liste de catalogues	non	L'ordre préféré là où ils divergent.

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.

Argument	Type	Requis	Ce qu'il fait
`id`	un identifiant écrit `instance:uuid`	oui	La fiche à lire.
`sections`	parmi `basic`, `appearance`, `images`, `studios`	non	Les blocs lus à côté de la carte.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.
`prefer`	liste de catalogues	non	L'ordre préféré là où ils divergent.

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.

Argument	Type	Requis	Ce qu'il fait
`id`	un identifiant écrit `instance:uuid`	oui	La fiche à lire.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.
`prefer`	liste de catalogues	non	L'ordre préféré là où ils divergent.

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

`get_tag`

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

Argument	Type	Requis	Ce qu'il fait
`id`	un identifiant écrit `instance:uuid`	oui	La fiche à lire.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.
`prefer`	liste de catalogues	non	L'ordre préféré là où ils divergent.

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.

Argument	Type	Requis	Ce qu'il fait
`fingerprints`	une liste de `{ hash, algorithm }`, l'algorithme `MD5`, `OSHASH` ou `PHASH`	oui	Les empreintes à chercher.
`sections`	parmi `basic`, `fingerprints`, `images`	non	Les blocs lus à côté de chaque carte. Un appel rend une carte par fiche atteinte, donc un bloc demandé ici parvient au lecteur une fois par correspondance.
`sources`	liste de catalogues	non	Ne lire que ces catalogues.
`prefer`	liste de catalogues	non	L'ordre préféré là où ils divergent.

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.

Variable	Défaut	Ce qu'elle fait
`STASHBOX_STASHDB_KEY`	aucun	La clé que StashDB délivre à votre compte.
`STASHBOX_TPDB_KEY`	aucun	La clé que TPDB délivre à votre compte.
`STASHBOX_FANSDB_KEY`	aucun	La clé que FansDB délivre à votre compte.
`STASHBOX_PMV_KEY`	aucun	La clé que PMV Stash délivre à votre compte.
`STASHBOX_JAVSTASH_KEY`	aucun	La clé que JAVStash délivre à votre compte.
`SB_USER_AGENT`	l'identité du projet	Nomme votre application auprès des catalogues, avec une adresse où joindre une personne.
`SB_MIN_INTERVAL_MS`	`1000`	Écart entre deux requêtes, de 1000 à 60000.
`SB_TIMEOUT_MS`	`20000`	Délai d'une requête, de 1 à 600000.
`SB_MAX_RETRIES`	`3`	Tentatives après un échec passager, de 0 à 10.
`SB_CACHE_TTL_MS`	`300000`	Durée pendant laquelle une réponse reste en mémoire, de 0 à 86400000.
`SB_CACHE_MAX_ENTRIES`	`500`	Réponses gardées en mémoire à la fois, de 1 à 100000.
`SB_LOG_LEVEL`	`error`	`silent`, `error`, `info` ou `debug`, écrit sur la sortie d'erreur.

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.

Code	Ce qui s'est passé	Que faire
`not_found`	Un catalogue a répondu, et n'a pas cette fiche.	Vérifiez l'identifiant avec une recherche.
`invalid_input`	Les arguments ont été refusés avant toute requête.	Lisez le message, qui nomme l'argument.
`rate_limited`	Un catalogue demande à ce client de ralentir.	Attendez, puis rappelez avec les mêmes arguments. La fiche est toujours là.
`parse_failure`	Une réponse est arrivée dans une forme illisible ici.	Signalez-le sur le suivi d'incidents.
`network_error`	La requête n'a pas abouti.	Réessayez sous peu.
`timeout`	La requête a dépassé son délai.	Augmentez `SB_TIMEOUT_MS`, ou demandez moins de lignes.

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);

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

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.

来源：README.md，提交 83e8ac8

工具

get_sources

What each catalogue answers

What each configured stash-box catalogue was measured answering, and the day its surface was read from it. Whether a key is held for a catalogue is a fact about this install and changes nothing about what the catalogue does. Reaches no catalogue and takes no argument.

无需输入参数。

search_scenes

Search scenes

Search scenes across every configured stash-box catalogue. Two exclusive paths: 'query' runs each catalogue's own text index, which reads the words as a union, and the typed arguments narrow as an intersection. Writing both is refused. The answer says per catalogue which of three it met: a failure, a catalogue nobody asked, and an emptiness it established. Counts are never added across them.

输入参数codedatepagesortaliaslimitmatchquerytitlesourcestag_idsdirection另有 4 个

search_performers

Search performers

Search performers across every configured stash-box catalogue. Two exclusive paths: 'query' runs each catalogue's own text index, which reads the words as a union, and the typed arguments narrow as an intersection. Writing both is refused. The answer says per catalogue which of three it met: a failure, a catalogue nobody asked, and an emptiness it established. Counts are never added across them.

输入参数namepagesortaliaslimitquerygendercountrysourcesdirectionethnicitystudio_id另有 5 个

search_studios

Search studios

Search studios across every configured stash-box catalogue. Two exclusive paths: 'query' runs each catalogue's own text index, which reads the words as a union, and the typed arguments narrow as an intersection. Writing both is refused. The answer says per catalogue which of three it met: a failure, a catalogue nobody asked, and an emptiness it established. Counts are never added across them.

输入参数namepagesortlimitquerysourcesdirectionparent_idhas_parent

search_tags

Search tags

Search tags across every configured stash-box catalogue. Two exclusive paths: 'query' runs each catalogue's own text index, which reads the words as a union, and the typed arguments narrow as an intersection. Writing both is refused. The answer says per catalogue which of three it met: a failure, a catalogue nobody asked, and an emptiness it established. Counts are never added across them.

输入参数namepagesortlimitquerysourcesdirectioncategory_id

get_scene

Get one scene

Read one scene from the catalogue its identifier names, written instance:uuid. The answer is 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. Name 'sources' to read one catalogue alone.

输入参数id必填prefersourcessections

get_performer

Get one performer

Read one performer from the catalogue its identifier names, written instance:uuid. The answer is 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. Name 'sources' to read one catalogue alone.

输入参数id必填prefersourcessections

get_studio

Get one studio

Read one studio from the catalogue its identifier names, written instance:uuid. The answer is 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. Name 'sources' to read one catalogue alone.

输入参数id必填prefersources

get_tag

Get one tag

Read one tag from the catalogue its identifier names, written instance:uuid. The answer is 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. Name 'sources' to read one catalogue alone.

输入参数id必填prefersources

find_by_fingerprint

Find scenes by fingerprint

Identify a file from the hashes held for it, across every configured stash-box catalogue. MD5 and OSHASH name the bytes of a file; PHASH states a likeness a re-encode, a crop or another scene from one shoot can satisfy. Each record reached is answered as one card, read on every catalogue that holds it.

输入参数prefersourcessectionsfingerprints必填

版本历史

v2.1.0最新Oct 29, 2026
v2.0.1Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

近 30 天内可连通25 分
已声明认证方式10 分
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
已列出工具必需15 分
描述必需15 分
图标10 分
文档15 分
许可证10 分