mcp-stashbox

mcp-stashbox

スタッシュボックスは共有メタデータカタログです。シーン、そこにクレジットされた出演者、公開したスタジオ、分類に使われるタグを、投稿とレビューによって管理します。カタログにはメディアは保存されません。レコードには何かが公開された場所が記録されるだけで、そのコンテンツ自体は含まれません。また、ファイルはそこから計算されたフィンガープリントによって識別されます。このようなカタログは5つあり、それぞれ独立して運営され、登録アカウントごとに独自のキーを発行します。

このサーバーは、チャットクライアントをこれらすべてのカタログに同時に接続します。キーを持つすべてのカタログのシーン、出演者、スタジオ、タグを検索したり、該当レコードを持つすべてのカタログの情報をまとめた1枚のカードとしてレコードを読んだり、フィンガープリントからファイルを識別したり、各カタログがどのような測定結果を回答したかを尋ねたりできます。カタログごとにキーが必要です。キーを持つカタログのみを読み込みます。

フランス語版

---

インストール

ワンクリックインストール

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 はプロトコルが通る stdin を開いたままにします。TTY はストリームを書き換えるため、-t は指定しません。コンテナには、キーを持つカタログへの HTTPS アウトバウンド接続と、環境変数で設定したキーが必要です。ボリュームもポートも必要ありません。

npm を使わずにバンドルを使用する

最新リリースから mcp-stashbox-2.0.1.mcpb をダウンロードして開きます。MCP バンドルに対応したクライアントなら、npm を実行せずに自動でインストールできます。キーは引き続きクライアントの設定で指定します。

できること

• 「実際にどのカタログを読み込んでいますか？」
• 「その名前でクレジットされている出演者を探してください。」
• 「そのスタジオのレコードを読んでください。」
• 「このファイルは何ですか？ MD5 はこれです。」
• 「その2人が一緒に出演したシーンはどれですか？」

通常の流れは検索からカードへ進みます。行には 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	1 件のシーンを単独のカードとして読み取ります。
get_performer	1 人のパフォーマーを単独のカードとして読み取ります。
get_studio	1 件のスタジオを単独のカードとして読み取ります。
get_tag	1 件のタグを単独のカードとして読み取ります。
find_by_fingerprint	保持されているハッシュからファイルを特定します。

各検索では、相互に排他的な 2 つの方法を使えます。 query は各カタログ独自のテキストインデックスを実行し、入力された語句をいずれか含む結果を読み取ります。型指定された引数では、すべてに一致するよう範囲を絞り込みます。両方を指定すると拒否されます。

get_sources

設定されている各カタログが何に対応すると測定されたかと、その対応範囲を確認した日を示します。カタログへのアクセスは行わず、引数も取りません。

返される内容： 各カタログの名前、識別子の接頭辞、このインストールでキーが設定されているかどうか、設定されていない場合に設定する環境変数、対応するルートを含む 1 件のエントリです。キーが設定されているかどうかはこのインストールに関する情報であり、カタログの機能には影響しません。

search_scenes

シーンを検索します。

引数	型	必須	内容
query	string	いいえ	各カタログ独自のテキストインデックスで検索する語句です。
title	string	いいえ	タイトルに含まれる語句です。
code	string	いいえ	リリースに付けられたスタジオ独自の参照コードです。
alias	string	いいえ	リリースが別名で知られている場合のタイトルです。
date	a calendar day	いいえ	比較対象となるリリース日です。
date_compare	on、before または after	いいえ	日付をどのように判定するかです。
performer_ids	識別子のリスト	いいえ	その作品にクレジットされている出演者です。
studio_ids	識別子のリスト	いいえ	その作品をリリースしたスタジオです。
parent_studio_id	識別子	いいえ	リリースしたスタジオの上位にあたるスタジオです。
tag_ids	識別子のリスト	いいえ	その作品に付けられているタグです。
match	all または any	いいえ	識別子のリストをどのように判定するかです。
sort	title、date、duration、trending、popularity、created_at または updated_at	いいえ	カタログが適用する並び順です。
direction	asc または desc	いいえ	並び順の方向です。
page	1～1000 の整数	いいえ	各カタログ独自の並び順におけるページ番号です。
limit	1～100 の整数	いいえ	1ページに表示する、そのカタログの行数です。
sources	カタログのリスト	いいえ	これらのカタログのみを検索します。

返される内容： get_scene が受け取る instance:uuid 形式の id と、レコードを示す名前を含む行です。どのリリースかを区別する情報ではないため、概要、リンクのリスト、編集日時はカードに委ねられます。 応答では、各カタログについて次の3つのいずれに該当するかが示されます： 失敗、要求されていないカタログ、または空であることが確認された結果です。カウントがカタログ間で合算されることはありません。 単語だけで検索すると、各テキストインデックスが返す先頭の行が表示されます。これらの検索方法ではページを指定できないためです。

search_performers

出演者を検索します。

引数	型	必須	説明
query	文字列	いいえ	各カタログ独自のテキストインデックスで検索する語句です。
name	文字列	いいえ	名前に含まれる語句です。
alias	文字列	いいえ	別名として知られている名前です。
disambiguation	文字列	いいえ	2つの対象を区別するためにカタログが付加する情報です。
gender	カタログに記録されている値のいずれか	いいえ	カタログに記録されている性別です。
country	2文字の国コード	いいえ	カタログに記録されている国です。
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	いいえ	1つのカタログの1ページに含める行数です。
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の整数	いいえ	1ページに含める、そのカタログの行数。
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の整数	いいえ	1ページに含める、そのカタログの行数。
sources	カタログのリスト	いいえ	指定したカタログのみを読み取ります。

返される内容： 行と、search_scenesが返すカタログごとの集計。

get_scene

1 つのシーンを 1 枚のカードとして読み込みます。

引数	型	必須	内容
id	instance:uuid 形式で記述された識別子	はい	読み込むレコードです。
sections	basic、fingerprints、images のいずれか	いいえ	カードとあわせて読み込むブロックです。
sources	カタログのリスト	いいえ	これらのカタログのみを読み込みます。
prefer	カタログのリスト	いいえ	食い違いがある場合に優先する順序です。

返される内容： レコードを保持しているすべてのカタログで読み込まれ、各カタログが同じレコードを別の場所で公開しているリンクからたどった 1 枚のカードです。**各値には、その値を示したカタログが付記されます。**食い違いがある場合は、優先されなかった読み取り結果も、採用された読み取り結果の横に表示されます。省略した場合はレジストリ独自の順序が適用され、各カードに適用された順序が記載されます。

get_performer

1 人の出演者を 1 枚のカードとして読み込みます。

引数	型	必須	内容
id	instance:uuid 形式で記述された識別子	はい	読み込むレコードです。
sections	basic、appearance、images、studios のいずれか	いいえ	カードとあわせて読み込むブロックです。
sources	カタログのリスト	いいえ	これらのカタログのみを読み込みます。
prefer	カタログのリスト	いいえ	食い違いがある場合に優先する順序です。

studios は、その出演者のクレジットが記載されたスタジオの全リストで、数百行に及びます。

返される内容： 出演者に対して get_scene が返すカードです。

get_studio

1 つのスタジオを 1 枚のカードとして読み込みます。

引数	型	必須	内容
id	instance:uuid 形式で記述された識別子	はい	読み込むレコードです。
sources	カタログのリスト	いいえ	これらのカタログのみを読み込みます。
prefer	カタログのリスト	いいえ	食い違いがある場合に優先する順序です。

返される内容： スタジオに対して get_scene が返すカードです。

get_tag

1 つのタグを 1 枚のカードとして読み込みます。

引数	型	必須	内容
id	instance:uuid 形式で記述された識別子	はい	読み込むレコードです。
sources	カタログのリスト	いいえ	これらのカタログのみを読み込みます。
prefer	カタログのリスト	いいえ	食い違いがある場合に優先する順序です。

返される内容： タグに対して get_scene が返すカードです。

find_by_fingerprint

ファイルに保持されているハッシュから、そのファイルを特定します。

引数	型	必須	説明
fingerprints	{ hash, algorithm } のリスト。アルゴリズムは MD5、OSHASH、PHASH	はい	検索するハッシュです。
sections	basic、fingerprints、images のいずれか	いいえ	各カードとともに読み取るブロックです。1 回の呼び出しで、取得したレコードごとにカード 1 枚を返します。そのため、ここで指定したブロックは一致するたびに 1 回読み取られます。
sources	カタログのリスト	いいえ	指定したカタログのみを読み取ります。
prefer	カタログのリスト	いいえ	カタログ間で結果が異なる場合に優先する順序です。

MD5 と OSHASH はファイルのバイト列を示します。PHASH は類似性を示すため、再エンコードやトリミング、同じ撮影での別のシーンでも一致することがあります。PHASH の一致は、同一性ではなく類似性として解釈してください。

**戻り値：**取得した各レコードについて、そのレコードを保持するすべてのカタログからカードを 1 枚ずつ読み取った結果です。

カタログについて回答が示す内容

回答ではカタログごとに情報を示します。統合すると、呼び出し元に必要な情報が失われるためです。失敗したカタログ、誰も問い合わせていないカタログ、何も見つからなかったカタログは、それぞれ異なる状態であり、区別して報告されます。件数はその件数を返したカタログに紐づけたままにし、決して合算しません。カードでは、各値について、その値を返したカタログを示します。見解の相違があれば、暗黙に解消せず、そのまま公開します。

設定

カタログごとにキーが必要で、それ以外はすべて任意です。すべてクライアント設定の 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 件のリクエストのタイムアウト時間です。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 に出力されます。

エラー

すべての失敗には、6 種類のコードのいずれか、メッセージ、および必要に応じて次の対応を示すヒントが含まれます。

コード	発生したこと	対応
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 } を返し、6つのコードのいずれかを持つエラーをスローします。2つのリクエスト間に設ける1秒の最小間隔も、ここで適用されます。

ペース調整と帰属表示

リクエストは一度に1つずつ送信され、間隔は最低1秒です。この最小間隔は、サーバーの設定にかかわらず適用されます。User-Agent の末尾には必ずプロジェクトの識別情報と、担当者に連絡できる宛先が含まれます。

各レコードには、取得元カタログにあるそのページのアドレスが付与されます。また、カードには、各カタログが同じレコードについて公開している他の場所へのリンクが含まれます。カタログは、レコードを提出・審査する人々によって構築されています。

この MCP サーバーは非公式のプロジェクトであり、読み取り対象のいずれのカタログとも提携していません。

プライバシー

このサーバーはユーザーに関する情報を収集せず、作者に何も送信しません。お使いのマシン上で動作し、キーを持つカタログにのみ接続します。動作中は回答をメモリに保持し、ディスクには何も書き込みません。キーは環境変数から読み込まれ、それぞれのカタログにのみ送信されます。 PRIVACY.md では、リクエストに含まれる情報と、その内容を変更する設定について説明しています。

開発

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

テストは生成されたフィクスチャに対して実行され、ネットワークリクエストは行いません。ライブテストスイートの npm run test:live は、各ルートにつき1回リクエストを行い、カタログ自体に対して毎晩実行されます。

コントリビューション

バグ、質問、アイデアはイシュートラッカーにお寄せください。プルリクエストも歓迎します。まずイシューを作成すると、変更内容の方向性を合意しやすくなります。CONTRIBUTING.mdをご覧ください。

ライセンス

MITです。LICENSEをご覧ください。レコードはカタログと、それを構築した人々に帰属します。

---

mcp-stashbox（フランス語）

英語版

stash-box は、共有メタデータカタログです。シーン、そのシーンにクレジットされている出演者、公開したスタジオ、分類に使われるタグを記録し、提出と審査によって管理されています。カタログにはメディアは含まれません。レコードには何かが公開された場所が記されていますが、そのもの自体は含まれません。また、ファイルはそのファイルから計算されたフィンガープリントによって識別されます。このようなカタログは5つあり、それぞれ独立して運営され、登録済みのアカウントに独自のキーを発行しています。

このサーバーは、会話型クライアントをこれらすべてのカタログに接続します。キーを持つ各カタログのシーン、出演者、スタジオ、タグを検索したり、レコードを、それを保持するすべてのカタログから集めた1つのカードとして読んだり、フィンガープリントでファイルを識別したり、各カタログがどのような測定結果を返すかを確認したりできます。カタログごとにキーが必要です。キーを持つカタログのみを読み込みます。

インストール

ワンクリックでインストール

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 はプロトコルのチャネルである標準入力を開いたままにし、TTY がストリームを書き換えるため、-t は省略します。コンテナには、キーをお持ちのカタログへの送信 HTTPS アクセスと、環境から取得したそれらのキーが必要です。ボリュームもポートも必要ありません。

npm を使わないバンドル

最新のリリース から mcp-stashbox-2.0.1.mcpb をダウンロードして開きます。MCP バンドルに対応したクライアントなら、npm を実行せずに単独でインストールできます。キーは引き続きクライアントの設定に配置します。

できること

• 「実際に参照できるカタログはどれですか？」
• 「この名前でクレジットされている出演者を探してください。」
• 「このスタジオのプロフィールを読んでください。」
• 「このファイルは何ですか？ MD5 はこれです。」
• 「この2人が共演したシーンはどれですか？」

通常は検索からカードへ進みます。行には 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	シーンを1枚のカードとして読み取ります。
get_performer	出演者を1枚のカードとして読み取ります。
get_studio	スタジオを1枚のカードとして読み取ります。
get_tag	タグを1枚のカードとして読み取ります。
find_by_fingerprint	保有する指紋情報を使ってファイルを特定します。

各検索では、排他的な2つの方法のいずれかを使います。 query は各カタログのテキストインデックスを検索します。各カタログは単語を OR 条件として解釈します。型付き引数を使うと、AND 条件で絞り込めます。両方を指定すると拒否されます。

get_sources

設定済みの各カタログについて、応答が確認されたかどうかと、その対象範囲を確認した日を示します。カタログには接続せず、引数も受け取りません。

戻り値： カタログごとに、名前、識別子のプレフィックス、このインストール環境にキーが設定されているかどうか、キーがない場合に設定すべき環境変数、および応答するルートを含むエントリーが返されます。キーの有無はこのインストール環境に関する情報であり、カタログの動作には影響しません。

search_scenes

シーンを検索します。

引数	型	必須	説明
query	文字列	いいえ	各カタログのテキストインデックスを検索する語句です。
title	文字列	いいえ	タイトルに含まれる語句です。
code	文字列	いいえ	公開作品に付けられたスタジオ独自の識別子です。
alias	文字列	いいえ	別名として知られているタイトルです。
date	暦日	いいえ	比較する公開日です。
date_compare	on、before または after	いいえ	日付の比較方法です。
performer_ids	識別子のリスト	いいえ	クレジットに記載された出演者です。
studio_ids	識別子のリスト	いいえ	公開したスタジオです。
parent_studio_id	識別子	いいえ	公開スタジオが所属する上位スタジオです。
tag_ids	識別子のリスト	いいえ	分類に使用されるタグです。
match	all または any	いいえ	識別子のリストの照合方法です。
sort	title、date、duration、trending、popularity、created_at または updated_at	いいえ	カタログで適用する並べ替え順です。
direction	asc または desc	いいえ	並べ替えの方向です。
page	1～1000 の整数	いいえ	各カタログ固有の並べ替え順でのページ番号です。
limit	1～100 の整数	いいえ	カタログの各ページに含める行数です。
sources	カタログのリスト	いいえ	指定したカタログのみを検索します。

返される内容： get_scene で使用する instance:uuid 形式の id と、作品を識別する情報を含む行です。各行では、あらすじ、リンクのリスト、編集日時は省略されます。これらはいずれも、2つの公開作品を区別する情報ではありません。**レスポンスには、各カタログが次の3つのどれに該当するかが示されます：**検索に失敗した、検索されていない、または検索した結果がなかった。**件数がカタログ間で合算されることはありません。**語句だけを指定した検索では、各テキストインデックスが返す先頭の行を取得します。これらのルートではページ指定を受け付けません。

search_performers

出演者を検索します。

引数	型	必須	説明
query	文字列	いいえ	テキストインデックスで検索する語句です。
name	文字列	いいえ	名前に含まれる語句です。
alias	文字列	いいえ	知られている別の名前です。
disambiguation	文字列	いいえ	2つを区別するためにカタログが付け加える情報です。
gender	カタログに記録されている値のいずれか	いいえ	カタログに記録されている性別です。
country	2文字の国コード	いいえ	カタログに記録されている国です。
ethnicity	カタログに記録されている値のいずれか	いいえ	カタログに記録されている民族です。
birth_year	整数、1800〜2200	いいえ	生年です。
career_start_year	整数、1800〜2200	いいえ	キャリアを開始した年です。
career_end_year	整数、1800〜2200	いいえ	キャリアを終えた年です。
performed_with	ID	いいえ	共同でクレジットされている人物です。
studio_id	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	いいえ	カタログの1ページに含める行数です。
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	いいえ	カタログの1ページに含める行数です。
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	いいえ	カタログの1ページに含める行数です。
sources	カタログのリスト	いいえ	これらのカタログのみを読み取ります。

返される内容： search_scenes の行とカタログ別の集計です。

get_scene

シーンを1件のカードとして読み取ります。

引数	型	必須	説明
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 のいずれか	いいえ	各カードとあわせて読み込むブロックです。1 回の呼び出しで該当する各レコードにつき 1 枚のカードが返されるため、ここで指定したブロックは一致ごとに 1 回、読み手に返されます。
sources	カタログのリスト	いいえ	これらのカタログのみを読み込みます。
prefer	カタログのリスト	いいえ	カタログ間で内容が異なる場合の優先順です。

MD5 と OSHASH はファイルのバイト列を識別します。PHASH が示すのは類似性です。 再エンコードやトリミング、同じ撮影の別の場面でも一致する場合があります。PHASH の一致は同一性ではなく、類似性としてお読みください。

**返り値：**該当する各レコードを、そのレコードを保有する各カタログから読み込んだカードとして返します。

カタログについて回答からわかること

各回答ではカタログごとに個別に報告します。まとめてしまうと、呼び出し元に必要な情報が失われるためです。失敗したカタログ、照会されなかったカタログ、空の結果を返したカタログはそれぞれ異なる状態であり、個別に報告されます。件数はそれを返したカタログの横に記載され、決して合算されません。カードでは、各値についてそれを返したカタログを示します。意見が分かれた場合も、黙って一方に決めるのではなく、そのまま公開します。

設定

カタログごとにキーが1つ必要で、それ以外はすべて任意です。すべてクライアント設定の 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 のいずれかを指定します。標準エラー出力に書き込みます。

各カタログは、登録済みアカウントの設定画面で、そのアカウントにキーを発行します。このサーバーにはキーが組み込まれていないため、各自でキーを用意してください。範囲外の値はデフォルト値に戻され、その理由が標準エラー出力に書き込まれます。

エラー

各エラーには6つのコードのいずれかとメッセージが含まれ、役立つ場合は次に行う操作も示されます。

コード	発生したこと	対処方法
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 } が返され、6種類のコードのいずれかを持つエラーが発生します。リクエスト間に1秒以上空ける制限も、ここで適用されます。

レート制限と帰属表示

リクエストは1件ずつ送信され、間隔は最低1秒空けられます。この制限は設定にかかわらず適用されます。User-Agent の末尾には、必ずプロジェクトの識別情報と担当者への連絡先が含まれます。

各エントリーには、取得元カタログ上のページのアドレスが記載されます。また、各カタログが同じエントリーの別の場所にあるページへのリンクを公開している場合、そのリンクもカードに記載されます。カタログは、エントリーを投稿・審査する人々によって構築されています。

この MCP は非公式プロジェクトであり、読み取り対象のいずれのカタログとも提携していません。

プライバシー

このサーバーは、お客様に関する情報を収集せず、開発者にも何も送信しません。お客様のマシン上で動作し、お客様がキーを持つカタログにのみ接続します。動作中はレスポンスをメモリに保持し、ディスクには何も書き込みません。キーは環境から読み取られ、該当するカタログにのみ送信されます。 PRIVACY.md には、リクエストに含まれる情報と、それを変更する設定について記載されています。

開発

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

テストは生成されたフィクスチャを使って実行され、リクエストは一切送信しません。ライブテストスイート npm run test:live はルートごとに1件のリクエストを送信し、毎晩カタログ自体に対して実行されます。

貢献

不具合、質問、アイデアはイシュートラッカーにお寄せください。変更の提案も歓迎します。まずチケットを作成すると、変更内容について合意しやすくなります。CONTRIBUTING.mdをご覧ください。

ライセンス

MIT ライセンスです。LICENSEをご覧ください。エントリーはカタログおよび、それを構築した人々に帰属します。