mcp-stashbox

mcp-stashbox

stash-box 是一个共享元数据目录：它记录场景、出演者、发行场景的制片公司以及归档场景的标签，并通过提交和审核来维护。目录不存储任何媒体——记录只标明内容发布的位置，不包含内容本身——并通过从文件计算出的指纹来识别文件。这样的目录共有五个，彼此独立，每个目录都会为注册账户发放自己的密钥。

此服务可将聊天客户端同时连接到所有目录。你可以搜索持有密钥的每个目录中的场景、出演者、制片公司和标签；将所有包含某条记录的目录中的信息汇总成一张卡片来查看记录；根据文件指纹识别文件；还可以询问各目录在回答时使用了哪些度量。每个目录都需要一个密钥，并且只读取有密钥的目录。

法语版本

---

安装

一键安装

Claude Code

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

Claude Desktop、Cursor 以及使用标准配置格式的客户端

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

需要 Node 24 或更高版本。为每个要读取的目录设置一个密钥；所有回答都会注明其他目录不可用。

使用 Docker

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

-i 用于保持标准输入处于打开状态，协议通过标准输入传输；不使用 -t，因为 TTY 会改写数据流。容器需要通过 HTTPS 访问你持有密钥的目录，并需要从环境变量读取密钥：无需挂载卷，也无需开放端口。

使用 Bundle，无需 npm

从最新版本下载 mcp-stashbox-2.0.1.mcpb 并打开。支持 MCP bundle 的客户端会自动安装，无需运行 npm。仍需在客户端配置中设置密钥。

你可以询问什么

• “我实际读取的是哪些目录？”
• “查找以该名称登记的出演者。”
• “给我看看那家制片公司的记录。”
• “这个文件是什么？这是它的 MD5。”
• “他们两人共同出演过哪些场景？”

常规操作流程从搜索开始，到查看卡片结束：搜索结果中的一行包含一个 id，格式为 instance:uuid；记录工具会在包含该记录的每个目录中读取它。

目录

目录	地址	密钥
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

它们覆盖的范围各不相同：StashDB 覆盖此服务支持的所有路由，其他目录覆盖的范围较小。get_sources 会说明每个目录经测量可回答哪些内容，以及测量日期。没有密钥的目录会在每个回答中标记为缺失，因此，包含部分目录数据行的回答绝不会被误认为是全部数据。

工具

工具	功能
get_sources	说明每个目录可回答哪些内容，以及已持有的密钥。
search_scenes	搜索所有已配置目录中的场景。
search_performers	搜索表演者。
search_studios	搜索制片公司。
search_tags	搜索标签。
get_scene	将一个场景作为单张卡片读取。
get_performer	将一位表演者作为单张卡片读取。
get_studio	将一家制片公司作为单张卡片读取。
get_tag	将一个标签作为单张卡片读取。
find_by_fingerprint	根据文件所持有的哈希值识别文件。

每次搜索都必须在两种互斥路径中选择一种。 query 会使用每个目录自己的文本索引，将词语作为并集读取。类型化参数则会缩小为交集。两者不能同时填写。

get_sources

说明每个已配置目录经测量可回答哪些内容，以及读取其覆盖范围的日期。它不会访问任何目录，也不接受参数。

返回内容： 每个目录各有一条记录，包含其名称、标识符前缀、此安装中是否持有其密钥、未持有密钥时应设置的变量，以及它可回答的路由。是否持有密钥是关于此安装的事实，不会改变目录的功能。

search_scenes

搜索场景。

Argument	Type	Required	What it does
query	string	no	用于各目录自身文本索引的词语。
title	string	no	标题包含的词语。
code	string	no	制片公司为该发行作品使用的内部编号。
alias	string	no	该发行作品的另一个已知标题。
date	a calendar day	no	用于比较的发行日期。
date_compare	on, before or after	no	如何解读该日期。
performer_ids	list of identifiers	no	该作品署名的表演者。
studio_ids	list of identifiers	no	发行该作品的制片公司。
parent_studio_id	an identifier	no	发行该作品的制片公司所属的上级制片公司。
tag_ids	list of identifiers	no	该作品归类的标签。
match	all or any	no	如何解读标识符列表。
sort	title, date, duration, trending, popularity, created_at or updated_at	no	目录采用的排序方式。
direction	asc or desc	no	排序方向。
page	integer, 1 to 1000	no	各目录自身排序中的页码。
limit	integer, 1 to 100	no	单个目录一页包含的行数。
sources	list of catalogues	no	仅查询这些目录。

**返回内容：**包含 id 的行，格式为 instance:uuid，可传给 get_scene，以及记录的名称。行中不包含简介、链接列表和编辑时间戳，这些信息会留在详情卡片中，因为它们无法区分不同的发行作品。 **答案会按目录说明它属于以下三种情况中的哪一种：**查询失败、未请求该目录，或已确认结果为空。**不同目录的计数绝不会相加。**仅使用词语进行搜索时，会返回各文本索引首先匹配的行，因为这些查询方式不接受页码。

search_performers

搜索表演者。

参数	类型	必填	作用
query	字符串	否	用于搜索各目录自身文本索引的词语。
name	字符串	否	名称中包含的词语。
alias	字符串	否	他们为人所知的另一个名称。
disambiguation	字符串	否	目录用于区分两者的信息。
gender	目录记录的某个值	否	目录记录的性别。
country	两位字母的国家代码	否	目录记录的国家。
ethnicity	目录记录的某个值	否	目录记录的族裔。
birth_year	整数，1800 到 2200	否	出生年份。
career_start_year	整数，1800 到 2200	否	职业生涯开始的年份。
career_end_year	整数，1800 到 2200	否	职业生涯结束的年份。
performed_with	一个标识符	否	与其共同署名的人。
studio_id	一个标识符	否	其署名中包含的一家工作室。
sort	name、birthdate、deathdate、scene_count、career_start_year、debut、last_scene、popularity、created_at 或 updated_at	否	目录采用的排序方式。
direction	asc 或 desc	否	排序方向。
page	整数，1 到 1000	否	页码。
limit	整数，1 到 100	否	单个目录每页包含的行数。
sources	目录列表	否	仅查询这些目录。
声明了 alias，但从未发送。 没有任何目录的分面路由会应用它：
携带此参数的请求返回的结果范围，和不携带任何参数的请求一样广，因此会将其省略，
并在答复中将其称为一个无人接收的缩小范围条件。

返回内容： search_scenes 返回的行和各目录的统计信息。

search_studios

搜索工作室。

参数	类型	必填	作用
query	string	否	用于各目录自身文本索引的词语。
name	string	否	名称中包含的词语。
parent_id	标识符	否	此工作室所属的上级工作室。
has_parent	boolean	否	是否有上级工作室。
sort	name、created_at 或 updated_at	否	目录应用的排序方式。
direction	asc 或 desc	否	排序方向。
page	整数，1 到 1000	否	页码。
limit	整数，1 到 100	否	单个目录单页包含的行数。
sources	目录列表	否	仅从这些目录读取。

返回内容： search_scenes 返回的行和各目录的统计信息。

search_tags

搜索标签。

参数	类型	必填	作用
query	string	否	用于各目录自身文本索引的词语。
name	string	否	名称中包含的词语。
category_id	标识符	否	此标签所属的类别。
sort	name、created_at 或 updated_at	否	目录应用的排序方式。
direction	asc 或 desc	否	排序方向。
page	整数，1 到 1000	否	页码。
limit	整数，1 到 100	否	单个目录单页包含的行数。
sources	目录列表	否	仅从这些目录读取。

返回内容： search_scenes 返回的行和各目录的统计信息。

get_scene

将一个场景作为单张卡片读取。

Argument	Type	Required	What it does
id	an identifier written instance:uuid	yes	要读取的记录。
sections	any of basic, fingerprints, images	no	随卡片一并读取的区块。
sources	list of catalogues	no	仅从这些目录读取。
prefer	list of catalogues	no	目录信息不一致时的优先顺序。

**返回内容：**一张卡片，读取所有收录该记录的目录，并通过它们各自发布的、指向其他目录中同一记录的链接找到该记录。每个值都会标明提供该值的目录；如果目录间信息不一致，还会在胜出的值旁边显示未被优先采用的读数。不设置此项时，将采用注册表自身的顺序，并且每张卡片都会注明所采用的顺序。

get_performer

将一位表演者作为单张卡片读取。

Argument	Type	Required	What it does
id	an identifier written instance:uuid	yes	要读取的记录。
sections	any of basic, appearance, images, studios	no	随卡片一并读取的区块。
sources	list of catalogues	no	仅从这些目录读取。
prefer	list of catalogues	no	目录信息不一致时的优先顺序。

studios 是其署名参与的所有制片厂的完整表格，可能有数百行。

返回内容：get_scene 为场景返回的卡片，适用于表演者。

get_studio

将一家制片厂作为单张卡片读取。

Argument	Type	Required	What it does
id	an identifier written instance:uuid	yes	要读取的记录。
sources	list of catalogues	no	仅从这些目录读取。
prefer	list of catalogues	no	目录信息不一致时的优先顺序。

返回内容：get_scene 为场景返回的卡片，适用于制片厂。

get_tag

将一个标签作为单张卡片读取。

Argument	Type	Required	What it does
id	an identifier written instance:uuid	yes	要读取的记录。
sources	list of catalogues	no	仅从这些目录读取。
prefer	list of catalogues	no	目录信息不一致时的优先顺序。

返回内容：get_scene 为场景返回的卡片，适用于标签。

find_by_fingerprint

根据文件的哈希值识别文件。

Argument	Type	Required	What it does
fingerprints	a list of { hash, algorithm }, the algorithm MD5, OSHASH or PHASH	yes	要查找的哈希值。
sections	any of basic, fingerprints, images	no	每张卡片旁读取的信息块。一次调用会为找到的每条记录返回一张卡片，因此，此处请求的信息块会针对每个匹配项各读取一次。
sources	list of catalogues	no	仅从这些目录读取。
prefer	list of catalogues	no	目录之间存在差异时，优先采用的顺序。

MD5 和 OSHASH 标识文件的字节内容。PHASH 表示相似度；重新编码、裁剪，或同一次拍摄中的另一个场景都可能符合条件：应将 PHASH 匹配理解为相似，而非相同。

返回内容： 找到的每条记录都会作为一张卡片，从所有包含该记录的目录中读取。

答案如何说明目录情况

每个答案都会分别说明各个目录的情况，因为合并信息会丢失调用方所需的内容。目录读取失败、未被请求，以及读取成功但未找到内容，是三种不同的情况，报告时也会分别列出。计数会保留在产生它们的目录旁，绝不会相加。在卡片中，每个值都会列出提供该值的目录；如果存在差异，也会直接呈现，而不会悄然消解。

配置

每个目录各需要一个密钥，其他配置均为可选项。所有配置都放在客户端配置的 env 区块中。

变量	默认值	作用
STASHBOX_STASHDB_KEY	无	StashDB 为你的账户签发的密钥。
STASHBOX_TPDB_KEY	无	TPDB 为你的账户签发的密钥。
STASHBOX_FANSDB_KEY	无	FansDB 为你的账户签发的密钥。
STASHBOX_PMV_KEY	无	PMV Stash 为你的账户签发的密钥。
STASHBOX_JAVSTASH_KEY	无	JAVStash 为你的账户签发的密钥。
SB_USER_AGENT	项目标识	向各目录标识你的应用，并提供可联系到负责人的地址。
SB_MIN_INTERVAL_MS	1000	两次请求之间的间隔，范围为 1000 到 60000。
SB_TIMEOUT_MS	20000	单次请求的截止时间，范围为 1 到 600000。
SB_MAX_RETRIES	3	临时故障后的重试次数，范围为 0 到 10。
SB_CACHE_TTL_MS	300000	答案在内存中的保留时长，范围为 0 到 86400000。
SB_CACHE_MAX_ENTRIES	500	内存中同时保留的答案数量，范围为 1 到 100000。
SB_LOG_LEVEL	error	日志级别：silent、error、info 或 debug，写入 stderr。

每个目录都会在已注册账户的设置中为该账户签发密钥。本服务不提供自有密钥，每位用户都需自备密钥。超出范围的值会回退到默认值，原因会写入 stderr。

错误

每种失败都包含六种错误代码之一、一条消息，以及在有帮助时指出下一步操作的提示。

代码	发生了什么	如何处理
not_found	目录已响应，但没有此记录。	使用搜索检查标识符。
invalid_input	请求发出前，参数已被拒绝。	阅读指出具体参数的消息。
rate_limited	目录要求此客户端降低请求频率。	等待后，使用相同参数再次调用。记录仍然存在。
parse_failure	收到的答案格式无法由此客户端读取。	在问题跟踪器中报告。
network_error	请求未能完成。	稍后重试。
timeout	请求超过了截止时间。	提高 SB_TIMEOUT_MS，或减少请求的行数。

目录失败时会按目录分别报告，而不会导致整个答案失败，因此某个目录无响应不会掩盖其他目录的结果。

作为库

读取目录的这一层独立发布，拥有自己的请求节奏、缓存和错误，且不绑定任何协议。

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

每次读取都会返回 { data, cached }，并抛出携带六种代码之一的错误。两次请求之间至少间隔一秒，这里也同样适用。

请求节奏与署名

请求依次发送，间隔至少一秒；无论服务如何配置，这一间隔都有效。User-Agent 始终以项目标识和可供联系的地址结尾。

每条记录都附有其所在目录中的页面地址，每张卡片都包含各目录发布的、指向同一条记录在其他目录中对应页面的链接。目录由提交和审核记录的人共同维护。

这个 MCP 服务是一个非官方项目，与它读取的任何目录均无关联。

隐私

此服务不会收集任何关于你的信息，也不会向其作者发送任何信息。它在你的计算机上运行，只联系你持有密钥的目录，在运行期间将响应保存在内存中，且不会写入磁盘。你的密钥从环境中读取，并且只发送到对应的目录。 PRIVACY.md 说明了请求会携带哪些内容，以及哪些设置会改变这些内容。

开发

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

测试使用生成的固定数据运行，不会发起网络请求。实时测试套件 npm run test:live 会对每个路由发起一次请求，并每晚直接针对各目录运行。

贡献

漏洞、问题和想法请提交到问题跟踪器。欢迎提交拉取请求；先提交问题有助于就变更方案达成一致。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。记录归各目录及其创建者所有。

---

mcp-stashbox（法语）

英文版

stash-box 是一个共享的元数据目录：它记录场景、场景中署名的表演者、发布场景的工作室，以及场景所属的标签；所有内容都通过提交和审核来维护。目录不包含任何媒体——一条记录只说明内容发布在哪里，不包含内容本身——文件则通过基于文件计算出的指纹进行识别。此类目录共有五个，彼此独立运行，每个目录都会向注册账户发放自己的密钥。

此服务将对话客户端连接到所有目录。你可以搜索自己持有密钥的每个目录中的场景、表演者、工作室和标签；读取一条记录，并将所有包含该记录的目录中的信息汇总为一张卡片；通过指纹识别文件；还可以查询各目录所报告的测量结果。每个目录都需要单独的密钥，服务只读取你持有密钥的目录。

安装

一键安装

Claude Code

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

Claude Desktop、Cursor，以及任何使用标准配置格式的客户端

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

需要 Node 24 或更高版本。为每个要读取的目录设置一个密钥；其他目录会在每条响应中标记为不可用。

使用 Docker

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

-i 会保持标准输入打开，它是协议通道；省略 -t，因为 TTY 会重写流。容器需要能够通过 HTTPS 访问出站请求，连接到你持有密钥的目录，并从环境变量中获取这些密钥：不需要挂载卷，也不需要开放端口。

Bundle，无需 npm

从最新发布版本 下载 mcp-stashbox-2.0.1.mcpb 并打开。支持 MCP bundle 的客户端会自行安装，无需运行 npm。密钥仍需放入客户端配置中。

可以询问什么

• “我实际读取了哪些目录？”
• “查找以这个名字署名的表演者。”
• “为我读取这家工作室的资料。”
• “这个文件是什么？这是它的 MD5。”
• “这两个人共同出演过哪些场景？”

常见流程是从搜索到资料卡：某一行包含一个写作 instance:uuid 的 id，资料工具会在持有该条目的每个目录中读取它。

目录

目录	地址	密钥
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

它们提供的接口范围各不相同：StashDB 支持此服务了解的所有路由，其他目录支持的路由较少。get_sources 会说明每个目录经测量后有哪些响应，以及测量日期。每个响应都会将未配置密钥的目录标记为缺失，因此只包含部分目录条目的响应绝不代表全集。

工具

工具	功能
get_sources	说明每个目录是否响应，以及是否配置了密钥。
search_scenes	搜索每个已配置目录中的场景。
search_performers	搜索表演者。
search_studios	搜索工作室。
search_tags	搜索标签。
get_scene	以单个资料卡的形式读取场景。
get_performer	以单个资料卡的形式读取表演者。
get_studio	以单个资料卡的形式读取工作室。
get_tag	以单个资料卡的形式读取标签。
find_by_fingerprint	根据已知的指纹识别文件。

每次搜索只能使用两种互斥方式之一。 query 会查询每个目录的文本索引，将词语按并集匹配。类型化参数会按交集缩小范围。同时使用两者会被拒绝。

get_sources

说明每个已配置目录经测量后是否响应，以及读取其接口范围的日期。它不会连接任何目录，也不接受任何参数。

**返回内容：**每个目录各有一条记录，包含其名称、标识符前缀、本机是否配置了密钥、缺少密钥时需要设置的变量，以及该目录支持的路由。密钥是否存在是关于本机配置的信息，不会影响目录本身的行为。

search_scenes

搜索场景。

参数	类型	必填	作用
query	字符串	否	用于搜索每个目录文本索引的词语。
title	字符串	否	标题中包含的词语。
code	字符串	否	发行作品的工作室专属编号。
alias	字符串	否	作品的另一个已知标题。
date	一个日历日期	否	用于比较的发行日期。
date_compare	on、before 或 after	否	如何解读该日期。
performer_ids	ID 列表	否	获得该作品演出署名的表演者。
studio_ids	ID 列表	否	发行该作品的工作室。
parent_studio_id	一个 ID	否	发行工作室所属的上级工作室。
tag_ids	ID 列表	否	作品所属的标签。
match	all 或 any	否	如何解读 ID 列表。
sort	title、date、duration、trending、popularity、created_at 或 updated_at	否	目录采用的排序方式。
direction	asc 或 desc	否	排序方向。
page	整数，1 到 1000	否	每个目录自身排序中的页码。
limit	整数，1 到 100	否	每个目录页面包含的行数。
sources	目录列表	否	只读取这些目录。

返回： 包含 instance:uuid 格式 id 的行，可供 get_scene 调用，以及用于命名条目的信息。行会将简介、链接列表和编辑时间戳留给详情页，这些信息都无法区分两个发行作品。响应会按目录说明它遇到的三种情况之一： 查询失败、未曾查询的目录，或已确认为空的目录。各目录的计数绝不会相加。 仅使用词语进行搜索时，会读取每个目录文本索引返回的首批行；这些路由不接受页码。

search_performers

搜索表演者。

Argument	类型	必填	说明
query	字符串	否	用于文本索引的词语。
name	字符串	否	名称中包含的词语。
alias	字符串	否	他们为人所知的另一个名称。
disambiguation	目录记录的某个值	否	目录用于区分两个对象的补充信息。
gender	目录记录的某个值	否	目录记录的性别。
country	两个字母的国家代码	否	目录记录的国家。
ethnicity	目录记录的某个值	否	目录记录的族裔。
birth_year	整数，1800 至 2200	否	出生年份。
career_start_year	整数，1800 至 2200	否	职业生涯开始年份。
career_end_year	整数，1800 至 2200	否	职业生涯结束年份。
performed_with	一个标识符	否	与他们共同获得署名的人。
studio_id	一个标识符	否	为他们提供署名的工作室。
sort	name、birthdate、deathdate、scene_count、career_start_year、debut、last_scene、popularity、created_at 或 updated_at	否	目录采用的排序方式。
direction	asc 或 desc	否	排序方向。
page	整数，1 至 1000	否	页码。
limit	整数，1 至 100	否	目录每页包含的行数。
sources	目录列表	否	仅读取这些目录。
alias 已声明，但从未发送。 没有任何方面路由会应用它：
带有它的查询返回的结果与不带它的查询一样宽泛，因此它被忽略，而响应却把它称为一个无人接收的收窄条件。

返回： search_scenes 返回的行和按目录统计的信息。

search_studios

搜索工作室。

参数	类型	必填	功能
query	字符串	否	用于文本索引的词语。
name	字符串	否	名称中包含的词语。
parent_id	一个 ID	否	工作室所属的上级工作室。
has_parent	布尔值	否	是否隶属于另一个工作室。
sort	name、created_at 或 updated_at	否	目录采用的排序方式。
direction	asc 或 desc	否	排序方向。
page	整数，1 到 1000	否	页码。
limit	整数，1 到 100	否	目录每页包含的行数。
sources	目录列表	否	只读取这些目录。

返回： search_scenes 返回的行和按目录统计的信息。

search_tags

搜索标签。

参数	类型	必填	功能
query	字符串	否	用于文本索引的词语。
name	字符串	否	名称中包含的词语。
category_id	一个 ID	否	标签所属的类别。
sort	name、created_at 或 updated_at	否	目录采用的排序方式。
direction	asc 或 desc	否	排序方向。
page	整数，1 到 1000	否	页码。
limit	整数，1 到 100	否	目录每页包含的行数。
sources	目录列表	否	只读取这些目录。

返回： search_scenes 返回的行和按目录统计的信息。

get_scene

以单张卡片的形式读取一个场景。

参数	类型	必填	功能
id	采用 instance:uuid 格式书写的 ID	是	要读取的条目。
sections	从 basic、fingerprints、images 中选择	否	与卡片一同读取的区块。
sources	目录列表	否	只读取这些目录。
prefer	目录列表	否	目录内容不一致时的优先顺序。

返回： 一张卡片，从持有该条目的每个目录读取，并通过各目录发布的链接找到它在其他位置的同一条目。每个值都会注明提供该值的目录；如果目录之间存在差异，则会同时显示未被选为优先项的读数和胜出的读数。省略该参数时，将应用注册表自身的顺序，每张卡片都会说明所应用的顺序。

get_performer

以单张卡片的形式读取一位表演者。

参数	类型	必填	作用
id	格式为 instance:uuid 的标识符	是	要读取的档案。
sections	basic、appearance、images、studios 中的项	否	随卡片一并读取的区块。
sources	目录列表	否	仅读取这些目录。
prefer	目录列表	否	目录内容不一致时的优先顺序。

studios 是其获得署名的所有工作室的完整表格，可能有数百行。

返回： get_scene 返回的表演者卡片。

get_studio

以单张卡片的形式读取一家工作室。

参数	类型	必填	作用
id	格式为 instance:uuid 的标识符	是	要读取的档案。
sources	目录列表	否	仅读取这些目录。
prefer	目录列表	否	目录内容不一致时的优先顺序。

返回： get_scene 返回的工作室卡片。

get_tag

以单张卡片的形式读取一个标签。

参数	类型	必填	作用
id	格式为 instance:uuid 的标识符	是	要读取的档案。
sources	目录列表	否	仅读取这些目录。
prefer	目录列表	否	目录内容不一致时的优先顺序。

返回： get_scene 返回的标签卡片。

find_by_fingerprint

根据已知指纹识别文件。

参数	类型	必填	作用
fingerprints	{ hash, algorithm } 列表，算法为 MD5、OSHASH 或 PHASH	是	要查找的指纹。
sections	basic、fingerprints、images 中的若干项	否	每张卡片旁读取的区块。一次调用会为每条命中的记录返回一张卡片，因此这里请求的区块会对每个匹配项各返回一次。
sources	目录列表	否	仅读取这些目录。
prefer	目录列表	否	目录结果不一致时的首选顺序。

MD5 和 OSHASH 标识文件的字节。PHASH 表示相似性， 重新编码、裁剪或同一拍摄过程中的另一场景都可能满足这一条件：请将 PHASH 匹配视为相似，而非相同。

**返回内容：**每条命中的记录，作为从持有该记录的每个目录读取的卡片返回。

回复如何说明目录情况

每条回复都会分别报告每个目录，因为将它们合并会丢失调用方需要的信息。目录读取失败、未被查询，以及返回空结果，是三种不同情况，回复会分别报告。计数始终与产生它们的目录对应，绝不会相加。卡片上的每个值都会标明提供该值的目录；若有分歧，会直接公布，而不是默默裁定。

配置

每个目录配置一个密钥，其余全部可选。所有内容都放在客户端配置的 env 块中。

变量	默认值	作用
STASHBOX_STASHDB_KEY	无	StashDB 发放给您账户的密钥。
STASHBOX_TPDB_KEY	无	TPDB 发放给您账户的密钥。
STASHBOX_FANSDB_KEY	无	FansDB 发放给您账户的密钥。
STASHBOX_PMV_KEY	无	PMV Stash 发放给您账户的密钥。
STASHBOX_JAVSTASH_KEY	无	JAVStash 发放给您账户的密钥。
SB_USER_AGENT	项目标识	向各目录标识您的应用，并提供可联系到负责人的地址。
SB_MIN_INTERVAL_MS	1000	两次请求之间的间隔，范围为 1000 到 60000。
SB_TIMEOUT_MS	20000	请求超时时间，范围为 1 到 600000。
SB_MAX_RETRIES	3	临时故障后的重试次数，范围为 0 到 10。
SB_CACHE_TTL_MS	300000	响应在内存中的保留时间，范围为 0 到 86400000。
SB_CACHE_MAX_ENTRIES	500	同时保存在内存中的响应数，范围为 1 到 100000。
SB_LOG_LEVEL	error	silent、error、info 或 debug，输出到标准错误。

每个目录都会在已注册账户的账户设置中提供密钥。此服务不内置任何密钥，每位用户都需提供自己的密钥。超出范围的值会恢复为默认值，原因会写入标准错误。

错误

每次失败都会包含六种代码之一、一条消息，以及在有帮助时提供的后续操作建议。

代码	发生的情况	处理方法
not_found	目录已响应，但没有这条记录。	通过搜索核对标识符。
invalid_input	请求发出前，参数已被拒绝。	阅读指出具体参数的消息。
rate_limited	目录要求此客户端降低请求频率。	等待后使用相同参数再次调用。记录仍然存在。
parse_failure	收到的响应格式无法在此处解析。	在问题跟踪页报告此问题。
network_error	请求未能完成。	稍后重试。
timeout	请求超时。	增大 SB_TIMEOUT_MS，或减少请求的行数。

某个目录出错时，会逐个报告目录的错误，而不会导致整个响应失败，因此一个无响应的目录绝不会掩盖其他目录的结果。

作为库

读取目录的层单独发布，拥有自己的节奏、缓存和错误处理，不绑定任何协议。

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

每次读取都会返回 { data, cached }，并抛出带有六种代码之一的错误。两次请求之间至少间隔一秒，这一限制在此同样适用。

请求节奏与归属信息

请求会逐个发出，彼此至少间隔一秒，无论配置如何，这一限制始终有效。User-Agent 始终以项目身份信息和联系地址结尾。

每个条目都带有其来源目录页面的地址；卡片则包含每个目录发布的链接，指向同一条目在其他目录中的页面。目录由提交和审核条目的人共同构建。

这个 MCP 是一个非官方项目，与它读取的任何目录都没有关联。

隐私

此服务不会收集您的任何信息，也不会向其作者发送任何信息。它在您的计算机上运行，只连接您持有密钥的目录，在运行期间将响应保存在内存中，并且不会向磁盘写入任何内容。您的密钥从环境变量中读取，并且只发送到对应的目录。 PRIVACY.md 说明了请求会携带哪些信息，以及哪些设置会改变这一点。

开发

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

测试使用生成的测试夹具运行，不会发出任何请求。实时测试套件 npm run test:live 会对每个路由发出一个请求，并且每晚直接针对目录运行。

贡献

问题、疑问和想法都可以提交到问题跟踪区。欢迎提交修改建议；先创建工单有助于就修改方案达成一致。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。条目归目录及其构建者所有。