Stash-box catalogues

Busca escenas, artistas, estudios y etiquetas en los catálogos públicos de stash-box.

Documentación

mcp-stashbox

Un stash-box es un catálogo compartido de metadatos: registra escenas, los artistas acreditados en ellas, los estudios que las publicaron y las etiquetas bajo las que se archivan, cada uno curado mediante envíos y revisiones. Un catálogo no contiene medios — un registro indica dónde se publicó algo y no lleva nada de ello — e identifica un archivo mediante las huellas digitales calculadas a partir de él. Cinco catálogos de este tipo funcionan de forma independiente, cada uno emitiendo su propia clave para una cuenta registrada.

Este servidor conecta un cliente de chat con todos ellos a la vez. Puedes buscar escenas, artistas, estudios y etiquetas de cada catálogo para el que tengas una clave, leer un registro como una sola tarjeta ensamblada a partir de cada catálogo que lo contenga, identificar un archivo a partir de sus huellas digitales y preguntar qué se midió que respondiera cada catálogo. Necesita una clave por catálogo y solo lee los catálogos para los que tiene una.

Versión francesa

Instalación

Instalación en un clic

Claude Code

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

Claude Desktop, Cursor y cualquier cliente que use el formato de configuración estándar

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

Se requiere Node 24 o posterior. Establece una clave para cada catálogo que quieras leer; los demás se indican como ausentes en cada respuesta.

Con Docker

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

-i mantiene stdin abierto, que es por donde viaja el protocolo, y -t se omite porque una TTY reescribe el flujo. El contenedor necesita HTTPS saliente hacia los catálogos para los que tengas claves, y las claves desde tu entorno: sin volumen, sin puerto.

Paquete, sin npm

Descarga mcp-stashbox-2.0.1.mcpb desde la última versión y ábrelo. Un cliente que admita paquetes MCP lo instala por sí solo, sin npm que ejecutar. Las claves se siguen estableciendo en la configuración del cliente.

Lo que puedes preguntar

"¿Qué catálogos estoy leyendo realmente?"
"Encuentra los artistas acreditados bajo ese nombre."
"Léeme el registro de ese estudio."
"¿Qué es este archivo? Aquí está su MD5."
"¿En qué escenas actuaron esos dos juntos?"

La ruta habitual va de una búsqueda a una tarjeta: una fila lleva un id escrito instance:uuid, y la herramienta de registro lo lee en cada catálogo que lo contenga.

Los catálogos

Catálogo	Dirección	Clave
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`

Responden a diferentes superficies: StashDB responde a cada ruta que este servidor conoce, y los demás responden a menos. get_sources indica qué se midió que respondiera cada uno y el día en que se midió. Un catálogo sin clave se indica como ausente en cada respuesta, por lo que una respuesta con filas de algunos de ellos nunca se lee como el todo.

Herramientas

Herramienta	Qué hace
`get_sources`	Indica qué responde cada catálogo y qué claves se tienen.
`search_scenes`	Busca las escenas de cada catálogo configurado.
`search_performers`	Busca los artistas.
`search_studios`	Busca los estudios.
`search_tags`	Busca las etiquetas.
`get_scene`	Lee una escena como una sola tarjeta.
`get_performer`	Lee un artista como una sola tarjeta.
`get_studio`	Lee un estudio como una sola tarjeta.
`get_tag`	Lee una etiqueta como una sola tarjeta.
`find_by_fingerprint`	Identifica un archivo a partir de los hashes que se tienen de él.

Cada búsqueda toma dos rutas exclusivas. query ejecuta el índice de texto propio de cada catálogo, que lee las palabras como una unión. Los argumentos tipados se reducen como una intersección. Escribir ambos se rechaza.

`get_sources`

Indica qué se midió que respondiera cada catálogo configurado y el día en que se leyó su superficie. No alcanza ningún catálogo y no toma ningún argumento.

A cambio: una entrada por catálogo con su nombre, su prefijo de identificador, si se tiene una clave para él en esta instalación, la variable a establecer cuando no se tiene, y las rutas que responde. Si se tiene una clave es un hecho sobre esta instalación y no cambia nada sobre lo que hace el catálogo.

`search_scenes`

Busca las escenas.

Argumento	Tipo	Obligatorio	Qué hace
`query`	string	no	Palabras para el índice de texto propio de cada catálogo.
`title`	string	no	Palabras que lleva un título.
`code`	string	no	La referencia propia del estudio para la publicación.
`alias`	string	no	Otro título por el que se conoce la publicación.
`date`	un día de calendario	no	La fecha de publicación a comparar.
`date_compare`	`on`, `before` o `after`	no	Cómo se lee esa fecha.
`performer_ids`	lista de identificadores	no	Artistas acreditados en ella.
`studio_ids`	lista de identificadores	no	Estudios que la publicaron.
`parent_studio_id`	un identificador	no	Un estudio bajo el que se sitúa el estudio publicador.
`tag_ids`	lista de identificadores	no	Etiquetas bajo las que está archivada.
`match`	`all` o `any`	no	Cómo se lee una lista de identificadores.
`sort`	`title`, `date`, `duration`, `trending`, `popularity`, `created_at` o `updated_at`	no	El orden que aplica el catálogo.
`direction`	`asc` o `desc`	no	En qué dirección corre ese orden.
`page`	entero, 1 a 1000	no	Qué página del orden propio de cada catálogo.
`limit`	entero, 1 a 100	no	Filas que lleva una página de un catálogo.
`sources`	lista de catálogos	no	Leer solo estos catálogos.

A cambio: filas que llevan el id escrito instance:uuid, que get_scene toma, y qué nombres nombran el registro. Una fila deja la sinopsis, las listas de enlaces y los sellos de edición para la tarjeta, ya que ninguno de esos separa dos publicaciones. La respuesta indica por catálogo cuál de tres encontró: un fallo, un catálogo que nadie pidió o un vacío que estableció. Los recuentos nunca se suman entre catálogos. Una búsqueda escrita solo con palabras lee las primeras filas que cada índice de texto responde, ya que esas rutas no toman página.

`search_performers`

Busca los artistas.

Argumento	Tipo	Obligatorio	Qué hace
`query`	string	no	Palabras para el índice de texto propio de cada catálogo.
`name`	string	no	Palabras que lleva un nombre.
`alias`	string	no	Otro nombre por el que se les conoce.
`disambiguation`	string	no	Lo que añade el catálogo para distinguir dos.
`gender`	uno de los valores que registra el catálogo	no	El género que registra el catálogo.
`country`	un código de país de dos letras	no	El país que registra el catálogo.
`ethnicity`	uno de los valores que registra el catálogo	no	La etnia que registra el catálogo.
`birth_year`	entero, 1800 a 2200	no	El año de nacimiento.
`career_start_year`	entero, 1800 a 2200	no	El año en que comenzó una carrera.
`career_end_year`	entero, 1800 a 2200	no	El año en que terminó una carrera.
`performed_with`	un identificador	no	Alguien con quien se les acredita.
`studio_id`	un identificador	no	Un estudio en el que se les acredita.
`sort`	`name`, `birthdate`, `deathdate`, `scene_count`, `career_start_year`, `debut`, `last_scene`, `popularity`, `created_at` o `updated_at`	no	El orden que aplica el catálogo.
`direction`	`asc` o `desc`	no	En qué dirección corre ese orden.
`page`	entero, 1 a 1000	no	Qué página.
`limit`	entero, 1 a 100	no	Filas que lleva una página de un catálogo.
`sources`	lista de catálogos	no	Leer solo estos catálogos.

alias está declarado y nunca se envía. Ninguna ruta facetada de catálogo lo aplica: una solicitud que lo lleva responde tan ampliamente como una que no lleva ninguno, por lo que se omite y la respuesta lo nombra como un estrechamiento que nadie recibió.

A cambio: las filas y el recuento por catálogo que devuelve search_scenes.

`search_studios`

Busca en los estudios.

Argumento	Tipo	Obligatorio	Qué hace
`query`	string	no	Palabras para el índice de texto propio de cada catálogo.
`name`	string	no	Palabras que lleva un nombre.
`parent_id`	un identificador	no	Un estudio bajo el que se encuentra.
`has_parent`	booleano	no	Si se encuentra bajo otro en absoluto.
`sort`	`name`, `created_at` o `updated_at`	no	El orden que aplica el catálogo.
`direction`	`asc` o `desc`	no	En qué dirección corre ese orden.
`page`	entero, 1 a 1000	no	Qué página.
`limit`	entero, 1 a 100	no	Filas que lleva una página de un catálogo.
`sources`	lista de catálogos	no	Leer solo estos catálogos.

A cambio: las filas y el recuento por catálogo que devuelve search_scenes.

`search_tags`

Busca en las etiquetas.

Argumento	Tipo	Obligatorio	Qué hace
`query`	string	no	Palabras para el índice de texto propio de cada catálogo.
`name`	string	no	Palabras que lleva un nombre.
`category_id`	un identificador	no	Una categoría a la que pertenece la etiqueta.
`sort`	`name`, `created_at` o `updated_at`	no	El orden que aplica el catálogo.
`direction`	`asc` o `desc`	no	En qué dirección corre ese orden.
`page`	entero, 1 a 1000	no	Qué página.
`limit`	entero, 1 a 100	no	Filas que lleva una página de un catálogo.
`sources`	lista de catálogos	no	Leer solo estos catálogos.

A cambio: las filas y el recuento por catálogo que devuelve search_scenes.

`get_scene`

Lee una escena como una sola tarjeta.

Argumento	Tipo	Obligatorio	Qué hace
`id`	un identificador escrito `instance:uuid`	sí	El registro a leer.
`sections`	cualquiera de `basic`, `fingerprints`, `images`	no	Los bloques leídos junto a la tarjeta.
`sources`	lista de catálogos	no	Leer solo estos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde no coinciden.

A cambio: una tarjeta, leída en cada catálogo que tiene el registro y alcanzada por el enlace que cada uno publica al mismo registro en otro lugar. Cada valor nombra los catálogos que lo dijeron, y donde no coinciden, la lectura que nadie prefirió se publica junto a la que ganó. Si se omite, el orden propio del registro se mantiene, y cada tarjeta indica el orden aplicado.

`get_performer`

Lee un intérprete como una sola tarjeta.

Argumento	Tipo	Obligatorio	Qué hace
`id`	un identificador escrito `instance:uuid`	sí	El registro a leer.
`sections`	cualquiera de `basic`, `appearance`, `images`, `studios`	no	Los bloques leídos junto a la tarjeta.
`sources`	lista de catálogos	no	Leer solo estos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde no coinciden.

studios es la tabla completa de estudios en los que se les acredita, que llega a cientos de filas.

A cambio: la tarjeta que devuelve get_scene, para un intérprete.

`get_studio`

Lee un estudio como una sola tarjeta.

Argumento	Tipo	Obligatorio	Qué hace
`id`	un identificador escrito `instance:uuid`	sí	El registro a leer.
`sources`	lista de catálogos	no	Leer solo estos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde no coinciden.

A cambio: la tarjeta que devuelve get_scene, para un estudio.

`get_tag`

Lee una etiqueta como una sola tarjeta.

Argumento	Tipo	Obligatorio	Qué hace
`id`	un identificador escrito `instance:uuid`	sí	El registro a leer.
`sources`	lista de catálogos	no	Leer solo estos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde no coinciden.

A cambio: la tarjeta que devuelve get_scene, para una etiqueta.

`find_by_fingerprint`

Identifica un archivo a partir de los hashes que se tienen para él.

Argumento	Tipo	Obligatorio	Qué hace
`fingerprints`	una lista de `{ hash, algorithm }`, el algoritmo `MD5`, `OSHASH` o `PHASH`	sí	Los hashes que se deben buscar.
`sections`	cualquiera de `basic`, `fingerprints`, `images`	no	Los bloques que se leen junto a cada ficha. Una llamada responde una ficha por registro alcanzado, así que un bloque solicitado aquí llega a un lector una vez por coincidencia.
`sources`	lista de catálogos	no	Lee solo estos catálogos.
`prefer`	lista de catálogos	no	El orden preferido cuando no coinciden.

MD5 y OSHASH nombran los bytes de un archivo. PHASH expresa una semejanza, que una recodificación, un recorte u otra escena de la misma sesión puede satisfacer: lee una coincidencia de PHASH como una similitud, no como una identidad.

A cambio: cada registro alcanzado, respondido como una ficha leída en cada catálogo que lo contiene.

Qué expresa una respuesta sobre los catálogos

Cada respuesta da cuenta de cada catálogo por separado, porque fusionarlos perdería lo que quien llama necesita. Un catálogo que falló, uno que nadie solicitó y uno que respondió sin nada son tres cosas distintas, y se informan como tres. Los conteos permanecen junto al catálogo que los produjo y nunca se suman. En una ficha, cada valor nombra los catálogos que lo dijeron, y un desacuerdo se publica en lugar de resolverse en silencio.

Configuración

Una clave por catálogo, y todo lo demás opcional. Todo va en el bloque env de la configuración de tu cliente.

Variable	Predeterminado	Qué hace
`STASHBOX_STASHDB_KEY`	ninguno	La clave que StashDB emite para tu cuenta.
`STASHBOX_TPDB_KEY`	ninguno	La clave que TPDB emite para tu cuenta.
`STASHBOX_FANSDB_KEY`	ninguno	La clave que FansDB emite para tu cuenta.
`STASHBOX_PMV_KEY`	ninguno	La clave que PMV Stash emite para tu cuenta.
`STASHBOX_JAVSTASH_KEY`	ninguno	La clave que JAVStash emite para tu cuenta.
`SB_USER_AGENT`	la identidad del proyecto	Nombra tu aplicación ante los catálogos, con una dirección donde se pueda contactar a una persona.
`SB_MIN_INTERVAL_MS`	`1000`	Intervalo entre dos solicitudes, de 1000 a 60000.
`SB_TIMEOUT_MS`	`20000`	Plazo para una solicitud, de 1 a 600000.
`SB_MAX_RETRIES`	`3`	Intentos tras un fallo transitorio, de 0 a 10.
`SB_CACHE_TTL_MS`	`300000`	Cuánto tiempo permanece una respuesta en memoria, de 0 a 86400000.
`SB_CACHE_MAX_ENTRIES`	`500`	Respuestas retenidas en memoria a la vez, de 1 a 100000.
`SB_LOG_LEVEL`	`error`	`silent`, `error`, `info` o `debug`, escritos en stderr.

Cada catálogo emite su clave a una cuenta registrada, en la configuración de esa cuenta. Este servidor no incluye ninguna clave propia, y cada usuario aporta la suya. Un valor fuera de su rango vuelve al predeterminado, y el motivo se escribe en stderr.

Errores

Cada fallo lleva uno de seis códigos, un mensaje y, cuando ayuda, una pista que nombra el siguiente paso.

Código	Qué ocurrió	Qué hacer
`not_found`	Un catálogo respondió y no contiene ese registro.	Comprueba el identificador con una búsqueda.
`invalid_input`	Los argumentos se rechazaron antes de enviar cualquier solicitud.	Lee el mensaje, que nombra el argumento.
`rate_limited`	Un catálogo pidió a este cliente que se ralentizara.	Espera y vuelve a llamar con los mismos argumentos. El registro sigue ahí.
`parse_failure`	Una respuesta llegó en un formato que este cliente no puede leer.	Repórtalo en el rastreador de incidencias.
`network_error`	La solicitud no se completó.	Inténtalo de nuevo en breve.
`timeout`	La solicitud superó su plazo.	Aumenta `SB_TIMEOUT_MS`, o pide menos filas.

Un catálogo que falló se informa por catálogo en lugar de hacer fallar toda la respuesta, así que un catálogo silencioso nunca oculta a los demás.

Como biblioteca

La capa que lee los catálogos se publica por separado, con su ritmo, su caché y sus errores, y sin protocolo adjunto.

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

Cada lectura responde { data, cached } y lanza un error con uno de los seis códigos. El mínimo de un segundo entre dos solicitudes también se aplica aquí.

Ritmo y atribución

Las solicitudes salen de una en una con al menos un segundo entre ellas, y ese mínimo se mantiene sin importar cómo esté configurado el servidor. El User-Agent siempre termina con la identidad del proyecto y una dirección donde se pueda contactar a una persona.

Cada registro lleva la dirección de su página en el catálogo del que proviene, y una ficha lleva el enlace que cada catálogo publica al mismo registro en otro lugar. Los catálogos los construyen las personas que envían y revisan sus registros.

Este servidor MCP es un proyecto no oficial, sin afiliación con ninguno de los catálogos que lee.

Privacidad

Este servidor no recopila nada sobre ti y no envía nada a su autor. Se ejecuta en tu máquina, contacta solo los catálogos para los que tienes una clave, guarda sus respuestas en memoria mientras se ejecuta y no escribe nada en disco. Tus claves se leen del entorno y se envían únicamente a su propio catálogo. PRIVACY.md indica qué lleva una solicitud y qué ajustes cambian cualquier parte de ello.

Desarrollo

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

Las pruebas se ejecutan contra accesorios generados y no hacen ninguna solicitud de red. La suite en vivo, npm run test:live, hace una solicitud por ruta y se ejecuta cada noche contra los propios catálogos.

Contribuciones

Errores, preguntas e ideas pertenecen a el rastreador de incidencias. Las solicitudes de extracción son bienvenidas; abrir una incidencia primero ayuda a acordar la forma del cambio. Consulta CONTRIBUTING.md.

Licencia

MIT, consulta LICENSE. Los registros pertenecen a los catálogos y a las personas que los construyeron.

mcp-stashbox (français)

Versión en inglés

Un stash-box es un catálogo de metadatos compartido: registra escenas, los intérpretes acreditados en ellas, los estudios que las publicaron y las etiquetas bajo las que se clasifican, todo mantenido por envío y revisión. Un catálogo no contiene ningún medio — una ficha nombra dónde se publicó algo y no lleva nada de ello — e identifica un archivo por las huellas calculadas sobre él. Cinco catálogos de este tipo funcionan de forma independiente, cada uno entregando su propia clave a una cuenta registrada.

Este servidor conecta un cliente de conversación con todos a la vez. Se pueden buscar escenas, intérpretes, estudios y etiquetas de cada catálogo del que se tenga una clave, leer una ficha como una tarjeta única ensamblada desde todos los catálogos que la contienen, identificar un archivo por sus huellas y preguntar qué se ha medido que responde cada catálogo. Requiere una clave por catálogo y solo lee aquellos de los que tiene una.

Instalación

Instalación en un clic

Claude Code

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

Claude Desktop, Cursor y cualquier cliente con formato de configuración estándar

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

Se necesita Node 24 o más reciente. Coloca una clave por catálogo a leer; los demás se nombran como ausentes en cada respuesta.

Con Docker

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

-i mantiene abierta la entrada estándar, que es el canal del protocolo, y -t se omite porque un TTY reescribe el flujo. El contenedor necesita acceso HTTPS saliente a los catálogos de los que tienes las claves, y esas claves tomadas de tu entorno: sin volúmenes, sin puertos.

Bundle, sin npm

Descarga mcp-stashbox-2.0.1.mcpb desde la última publicación y ábrelo. Un cliente que gestiona bundles MCP lo instala solo, sin necesidad de ejecutar npm. Las claves siempre se colocan en la configuración del cliente.

Qué se puede pedir

«¿Qué catálogos estoy leyendo realmente?»
«Encuentra los intérpretes acreditados bajo este nombre.»
«Léeme la ficha de este estudio.»
«¿Qué es este archivo? Aquí está su MD5.»
«¿En qué escenas han actuado juntos estos dos?»

El camino habitual va de una búsqueda a una tarjeta: una línea lleva un id escrito instance:uuid, y la herramienta de ficha lo lee en cada catálogo que lo contiene.

Los catálogos

Catálogo	Dirección	Clave
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`

Responden superficies diferentes: StashDB responde a todas las rutas que este servidor conoce, los demás a menos. get_sources dice qué se ha medido que responde cada uno y el día de la medición. Un catálogo sin clave se nombra como ausente en cada respuesta, así que una respuesta que lleva las líneas de algunos nunca se lee como el conjunto.

Las herramientas

Herramienta	Qué hace
`get_sources`	Dice qué responde cada catálogo y qué claves se plantean.
`search_scenes`	Busca las escenas de cada catálogo configurado.
`search_performers`	Busca los intérpretes.
`search_studios`	Busca los estudios.
`search_tags`	Busca las etiquetas.
`get_scene`	Lee una escena como una ficha única.
`get_performer`	Lee un intérprete como una ficha única.
`get_studio`	Lee un estudio como una ficha única.
`get_tag`	Lee una etiqueta como una ficha única.
`find_by_fingerprint`	Identifica un archivo por las huellas que se tienen de él.

Cada búsqueda toma dos caminos exclusivos. query consulta el índice textual de cada catálogo, que lee las palabras como una unión. Los argumentos tipados estrechan como una intersección. Escribir ambos está rechazado.

`get_sources`

Dice qué ha medido responder a cada catálogo configurado y el día en que se leyó su superficie. No une ningún catálogo y no toma ningún argumento.

En retorno: una entrada por catálogo con su nombre, su prefijo de identificador, la presencia de una clave en esa instalación, la variable a plantear cuando no la hay, y las rutas a las que responde. La presencia de una clave es un hecho sobre esa instalación y no cambia nada de lo que hace el catálogo.

`search_scenes`

Busca las escenas.

Argumento	Tipo	Requerido	Qué hace
`query`	cadena	no	Palabras para el índice textual de cada catálogo.
`title`	cadena	no	Palabras que lleva un título.
`code`	cadena	no	La referencia propia del estudio para la publicación.
`alias`	cadena	no	Otro título bajo el cual se la conoce.
`date`	un día de calendario	no	La fecha de publicación a comparar.
`date_compare`	`on`, `before` o `after`	no	Cómo se lee esa fecha.
`performer_ids`	lista de identificadores	no	Los intérpretes que aparecen en los créditos.
`studio_ids`	lista de identificadores	no	Los estudios que la publicaron.
`parent_studio_id`	un identificador	no	Un estudio bajo el cual se clasifica el estudio editor.
`tag_ids`	lista de identificadores	no	Las etiquetas bajo las cuales se la clasifica.
`match`	`all` o `any`	no	Cómo se lee una lista de identificadores.
`sort`	`title`, `date`, `duration`, `trending`, `popularity`, `created_at` o `updated_at`	no	El orden que aplica el catálogo.
`direction`	`asc` o `desc`	no	El sentido de ese orden.
`page`	entero, 1 a 1000	no	Qué página del orden propio de cada catálogo.
`limit`	entero, 1 a 100	no	Líneas que lleva una página de un catálogo.
`sources`	lista de catálogos	no	Leer solo esos catálogos.

En retorno: líneas que llevan el id escrito instance:uuid, que get_scene retoma, y lo que nombra la ficha. Una línea deja a la ficha el resumen, las listas de enlaces y las marcas de tiempo de edición, de las cuales ninguna distingue dos publicaciones. La respuesta dice por catálogo cuál de las tres ha encontrado: un fallo, un catálogo que nadie ha consultado, o un vacío que ha establecido. Los conteos nunca se suman entre catálogos. Una búsqueda escrita solo con palabras lee las primeras líneas que devuelve cada índice textual, ya que esas rutas no toman ninguna página.

`search_performers`

Busca los intérpretes.

Argumento	Tipo	Requerido	Qué hace
`query`	cadena	no	Palabras para el índice textual.
`name`	cadena	no	Palabras que lleva un nombre.
`alias`	cadena	no	Otro nombre bajo el cual se los conoce.
`disambiguation`	cadena	no	Lo que el catálogo añade para distinguir a dos.
`gender`	uno de los valores que registra el catálogo	no	El género que registra el catálogo.
`country`	un código de país de dos letras	no	El país que registra el catálogo.
`ethnicity`	uno de los valores que registra el catálogo	no	La etnia que registra el catálogo.
`birth_year`	entero, 1800 a 2200	no	El año de nacimiento.
`career_start_year`	entero, 1800 a 2200	no	El año en que se abrió una carrera.
`career_end_year`	entero, 1800 a 2200	no	El año en que se cerró una carrera.
`performed_with`	un identificador	no	Alguien junto a quien aparecen en los créditos.
`studio_id`	un identificador	no	Un estudio en el que aparecen en los créditos.
`sort`	`name`, `birthdate`, `deathdate`, `scene_count`, `career_start_year`, `debut`, `last_scene`, `popularity`, `created_at` o `updated_at`	no	El orden que aplica el catálogo.
`direction`	`asc` o `desc`	no	El sentido de ese orden.
`page`	entero, 1 a 1000	no	Qué página.
`limit`	entero, 1 a 100	no	Líneas que lleva una página de un catálogo.
`sources`	lista de catálogos	no	Leer solo esos catálogos.

alias está declarado y nunca se envía. Ninguna ruta de facetas lo aplica: una consulta que lo lleva responde tan amplia como una consulta sin él, por lo que se deja de lado y la respuesta lo nombra como un estrechamiento que nadie ha recibido.

En retorno: las líneas y la contabilidad por catálogo que devuelve search_scenes.

`search_studios`

Busca los estudios.

Argumento	Tipo	¿Requerido?	Qué hace
`query`	cadena	no	Palabras para el índice textual.
`name`	cadena	no	Palabras que lleva un nombre.
`parent_id`	un identificador	no	Un estudio bajo el cual se clasifica.
`has_parent`	booleano	no	Si se clasifica bajo otro.
`sort`	`name`, `created_at` o `updated_at`	no	El orden que aplica el catálogo.
`direction`	`asc` o `desc`	no	La dirección de ese orden.
`page`	entero, 1 a 1000	no	Qué página.
`limit`	entero, 1 a 100	no	Filas que lleva una página de un catálogo.
`sources`	lista de catálogos	no	Leer solo esos catálogos.

Devuelve: las filas y el recuento por catálogo de search_scenes.

`search_tags`

Busca las etiquetas.

Argumento	Tipo	¿Requerido?	Qué hace
`query`	cadena	no	Palabras para el índice textual.
`name`	cadena	no	Palabras que lleva un nombre.
`category_id`	un identificador	no	Una categoría a la que pertenece la etiqueta.
`sort`	`name`, `created_at` o `updated_at`	no	El orden que aplica el catálogo.
`direction`	`asc` o `desc`	no	La dirección de ese orden.
`page`	entero, 1 a 1000	no	Qué página.
`limit`	entero, 1 a 100	no	Filas que lleva una página de un catálogo.
`sources`	lista de catálogos	no	Leer solo esos catálogos.

Devuelve: las filas y el recuento por catálogo de search_scenes.

`get_scene`

Lee una escena como una tarjeta única.

Argumento	Tipo	¿Requerido?	Qué hace
`id`	un identificador escrito `instance:uuid`	sí	La ficha a leer.
`sections`	entre `basic`, `fingerprints`, `images`	no	Los bloques leídos junto a la tarjeta.
`sources`	lista de catálogos	no	Leer solo esos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde divergen.

Devuelve: una tarjeta, leída en cada catálogo que posee la ficha y alcanzada por el enlace que cada uno publica hacia la misma ficha en otro lugar. Cada valor nombra los catálogos que lo dijeron, y donde divergen, la lectura que nadie prefirió se publica junto a la que prevalece. Si se omite, se aplica el orden propio del registro, y cada tarjeta indica el orden aplicado.

`get_performer`

Lee un intérprete como una tarjeta única.

Argumento	Tipo	¿Requerido?	Qué hace
`id`	un identificador escrito `instance:uuid`	sí	La ficha a leer.
`sections`	entre `basic`, `appearance`, `images`, `studios`	no	Los bloques leídos junto a la tarjeta.
`sources`	lista de catálogos	no	Leer solo esos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde divergen.

studios es la tabla completa de estudios en los que están acreditados, que tiene cientos de filas.

Devuelve: la tarjeta que produce get_scene, para un intérprete.

`get_studio`

Lee un estudio como una tarjeta única.

Argumento	Tipo	¿Requerido?	Qué hace
`id`	un identificador escrito `instance:uuid`	sí	La ficha a leer.
`sources`	lista de catálogos	no	Leer solo esos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde divergen.

Devuelve: la tarjeta que produce get_scene, para un estudio.

`get_tag`

Lee una etiqueta como una tarjeta única.

Argumento	Tipo	¿Requerido?	Qué hace
`id`	un identificador escrito `instance:uuid`	sí	La ficha a leer.
`sources`	lista de catálogos	no	Leer solo esos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde divergen.

Devuelve: la tarjeta que produce get_scene, para una etiqueta.

`find_by_fingerprint`

Identifica un archivo por las huellas que se tienen de él.

Argumento	Tipo	¿Requerido?	Qué hace
`fingerprints`	una lista de `{ hash, algorithm }`, el algoritmo `MD5`, `OSHASH` o `PHASH`	sí	Las huellas a buscar.
`sections`	entre `basic`, `fingerprints`, `images`	no	Los bloques leídos junto a cada tarjeta. Una llamada devuelve una tarjeta por ficha alcanzada, por lo que un bloque solicitado aquí llega al lector una vez por coincidencia.
`sources`	lista de catálogos	no	Leer solo esos catálogos.
`prefer`	lista de catálogos	no	El orden preferido donde divergen.

MD5 y OSHASH nombran los bytes de un archivo. PHASH indica una similitud, que un re-codificado, un recorte u otra escena del mismo rodaje pueden satisfacer: lea una coincidencia PHASH como una similitud en lugar de como una identidad.

Devuelve: cada ficha alcanzada, presentada como una tarjeta leída en cada catálogo que la posee.

Lo que una respuesta dice sobre los catálogos

Cada respuesta informa sobre cada catálogo por separado, porque fusionarlos perdería lo que un solicitante necesita. Un catálogo que falló, uno que nadie consultó y uno que respondió vacío son tres cosas diferentes, y se informan como tres. Los recuentos permanecen junto al catálogo que los produjo y nunca se suman. En una tarjeta, cada valor nombra los catálogos que lo dijeron, y un desacuerdo se publica en lugar de resolverse en silencio.

Configuración

Una clave por catálogo, y todo lo demás opcional. Todo se coloca en el bloque env de la configuración del cliente.

Variable	Predeterminado	Qué hace
`STASHBOX_STASHDB_KEY`	ninguno	La clave que StashDB entrega a tu cuenta.
`STASHBOX_TPDB_KEY`	ninguno	La clave que TPDB entrega a tu cuenta.
`STASHBOX_FANSDB_KEY`	ninguno	La clave que FansDB entrega a tu cuenta.
`STASHBOX_PMV_KEY`	ninguno	La clave que PMV Stash entrega a tu cuenta.
`STASHBOX_JAVSTASH_KEY`	ninguno	La clave que JAVStash entrega a tu cuenta.
`SB_USER_AGENT`	la identidad del proyecto	Nombra tu aplicación ante los catálogos, con una dirección para contactar a una persona.
`SB_MIN_INTERVAL_MS`	`1000`	Intervalo entre dos solicitudes, de 1000 a 60000.
`SB_TIMEOUT_MS`	`20000`	Tiempo de espera de una solicitud, de 1 a 600000.
`SB_MAX_RETRIES`	`3`	Intentos después de un fallo temporal, de 0 a 10.
`SB_CACHE_TTL_MS`	`300000`	Duración durante la cual una respuesta permanece en memoria, de 0 a 86400000.
`SB_CACHE_MAX_ENTRIES`	`500`	Respuestas guardadas en memoria a la vez, de 1 a 100000.
`SB_LOG_LEVEL`	`error`	`silent`, `error`, `info` o `debug`, escrito en la salida de error.

Cada catálogo entrega su clave a una cuenta registrada, en los ajustes de esa cuenta. Este servidor no incluye ninguna clave, y cada uno aporta las suyas. Un valor fuera de su rango cae en el predeterminado, y la razón se escribe en la salida de error.

Errores

Cada fallo lleva uno de los seis códigos, un mensaje, y cuando ayuda una indicación del siguiente paso.

Código	Qué ocurrió	Qué hacer
`not_found`	Un catálogo respondió y no tiene esta ficha.	Verifique el identificador con una búsqueda.
`invalid_input`	Los argumentos fueron rechazados antes de cualquier solicitud.	Lea el mensaje, que nombra el argumento.
`rate_limited`	Un catálogo pide a este cliente que reduzca la velocidad.	Espere y vuelva a llamar con los mismos argumentos. La ficha sigue ahí.
`parse_failure`	Una respuesta llegó en una forma ilegible aquí.	Repórtelo en el seguimiento de incidentes.
`network_error`	La solicitud no se completó.	Reintente en breve.
`timeout`	La solicitud superó su tiempo límite.	Aumente `SB_TIMEOUT_MS`, o solicite menos líneas.

Un catálogo que falla se reporta catálogo por catálogo en lugar de hacer fallar toda la respuesta, por lo que un catálogo silencioso nunca oculta a otros.

Como biblioteca

La capa que lee los catálogos se publica sola, con su ritmo, su caché y sus errores, sin protocolo adjunto.

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

Cada lectura responde { data, cached }, y lanza un error con uno de los seis códigos. El mínimo de un segundo entre dos solicitudes también se aplica aquí.

Ritmo y atribución

Las solicitudes salen una a una con al menos un segundo entre ellas, y este mínimo se mantiene sin importar la configuración. El User-Agent termina siempre con la identidad del proyecto y una dirección para contactar a una persona.

Cada ficha lleva la dirección de su página en el catálogo de donde proviene, y una tarjeta lleva el enlace que cada catálogo publica hacia la misma ficha en otros lugares. Los catálogos son construidos por quienes envían y revisan sus fichas.

Este MCP es un proyecto no oficial, sin afiliación con ninguno de los catálogos que lee.

Privacidad

Este servidor no recopila nada sobre usted y no envía nada a su autor. Se ejecuta en su máquina, solo se conecta a los catálogos de los cuales usted tiene una clave, guarda sus respuestas en memoria mientras se ejecuta y no escribe nada en el disco. Sus claves se leen del entorno y se envían únicamente a su catálogo correspondiente. PRIVACY.md indica qué lleva una solicitud y qué ajustes cambian eso.

Desarrollo

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

Las pruebas se ejecutan sobre fixtures generados y no emiten ninguna solicitud. La suite en vivo, npm run test:live, emite una solicitud por ruta y se ejecuta cada noche contra los propios catálogos.

Contribuir

Las anomalías, las preguntas y las ideas tienen su lugar en el seguimiento de incidentes. Las propuestas de modificación son bienvenidas; abrir un ticket primero ayuda a ponerse de acuerdo sobre la forma del cambio. Ver CONTRIBUTING.md.

Licencia

MIT, ver LICENSE. Las fichas pertenecen a los catálogos y a quienes las construyeron.