mcp-books について
mcp-booksは、Internet Archive、Library of Congress、data.bnf.frを横断検索し、目録やスキャン資料を調べる人向けのサーバーです。OCRテキストを検索でき、記録を共通形式で取得できます。APIキーやアカウントは不要です。
主な機能
- 013つのアーカイブを横断検索
- 02スキャン文書内のテキスト検索
- 03メタデータによる目録検索
- 04共通形式での記録取得
- 05アーカイブごとの状態報告
活用シーン
- 01複数のアーカイブからテーマ資料を探す
- 02スキャン文書内の語句を検索する
- 03記録の出典や所蔵情報を確認する
MCP 対応
このMCPサーバーは、スキャンテキスト検索、目録検索、共通形式での記録取得ツールをクライアントに提供し、アーカイブごとの状態を個別に報告します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。
ツール
3掲載時のツール一覧 · 今日に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| page | integer | いいえ | 取得する一致結果のページ番号です。1 から始まります。各アーカイブは個別にページ分けされます。 |
| limit | integer | いいえ | 各アーカイブから取得する一致数です。1 つのアーカイブが一覧全体を占めないようにします。テキストブロックには一致が約 6 件表示され、残りの返却内容は構造化出力に含まれます。 |
| query | string | はい | 単語、または '"call me ishmael"' のように二重引用符で囲んだ語句です。 |
| fan_out | boolean | いいえ | クエリから短い表現や綴りの異なる表現を導き、各アーカイブに検索させて結果をまとめるかどうかを指定します。指定したすべての語が必要な検索インデックスでは、文で書かれた質問は結果を返しません。一方、語句をスコアリングするインデックスでは、最も高いスコアの行が返されます。指定した語句で 'limit' 件に達しなかった場合に限り、派生した表現をアーカイブに問い合わせます。そのため、必要な結果が得られるクエリではリクエストは 1 回です。false にすると、指定された語句だけを送信します。'per_source' には送信の有無にかかわらずすべての表現が記載され、各一致にはそれを返した表現が示されます。 |
| sources | array | いいえ | 問い合わせるアーカイブを ID で指定します。省略すると、機械可読テキストを読み取るすべてのアーカイブに問い合わせます。それがこのツールの目的です。 |
| max_excerpt_chars | integer | いいえ | 1 つの抜粋に使う文字数の上限です。'max_excerpts_per_match' と合わせて確認してください。回答のサイズはこの 2 つの値、limit、アーカイブ数の積になります。 |
| max_excerpts_per_match | integer | いいえ | 各一致について保持する抜粋数です。長い作品では複数箇所が一致することがありますが、後の箇所に最初の箇所にない情報が含まれることはほとんどありません。 |
詳細
mcp-books
3つの優れたアーカイブには、出版物をスキャンした記録が収蔵されており、それぞれが独自の言葉で内容を記述しています。Internet Archiveには、誰もが寄託した書籍、映画、録音物、ソフトウェアが保存されており、そのうち数百万点に光学文字認識を実施しています。Library of Congressは、米国の国立コレクションを資料の種類ごとにカタログ化して公開しています。data.bnf.frは、書籍そのものではなく作品や執筆者を記述した、フランス国立図書館の典拠レコードを公開しています。
このサーバーでは、1つの質問で3つすべてを検索できます。スキャンされた文書内の語句を検索したり、カタログを検索したり、どのアーカイブに所蔵されているかにかかわらず、1つの形式でレコードを読んだりできます。API キーもアカウントも必要ありません。
インストール
ワンクリックでインストール
Claude Code
claude mcp add books -- npx -y mcp-books
Claude Desktop、Cursor、および標準の設定形式を使用するクライアント
{
"mcpServers": {
"books": {
"command": "npx",
"args": ["-y", "mcp-books"]
}
}
}
Node 24 以降が必要です。環境変数の設定は不要です。
Docker を使用する場合
{
"mcpServers": {
"books": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-books:2.0.1"]
}
}
}
-i はプロトコルが流れる標準入力を開いたままにします。また、TTY はストリームを書き換えるため、-t は指定しません。コンテナに必要なのは、archive.org、openlibrary.org、www.loc.gov、data.bnf.fr への HTTPS アウトバウンド通信のみです。ボリューム、ポート、認証情報は不要です。
npm を使わずにバンドルを利用する場合
最新リリースからmcp-books-2.0.1.mcpbをダウンロードして開いてください。MCP バンドルに対応したクライアントなら、npm も設定ファイルの編集も必要なく、自動でインストールします。このバンドルには依存関係が含まれているため、インストール時に何かを取得することはありません。
質問できること
- 「Beaumont 灯台について言及している書籍はありますか?」
- 「1906 年のサンフランシスコ地震に関するものを何でも探してください。」
- 「そのレコードを読んで、原本を所蔵しているところを教えてください。」
- 「その著者について、BnF には何がありますか?」
- 「書籍ではなく写真を検索してください。」
回答には数秒かかります。3つのアーカイブに問い合わせ、それぞれのペースで応答を待つためです。
3 つのソース
| ソース | アーカイブ | 説明 |
|---|---|---|
archive | インターネット・アーカイブ | あらゆる種類の寄託された資料のコピー |
loc | 米国議会図書館 | 国立コレクション。種類ごとに 1 つのカタログ |
bnf | フランス国立図書館 | 著作物と、それを書いた人々 |
行の id はアーカイブを示すため、ある回答から取得した識別子を適切なアーカイブに戻せます。アーカイブをまたいで件数を合算することはありません。また、応答に失敗したアーカイブは、何も見つからなかったのではなく、失敗したものとして報告されます。
ツール
| ツール | 機能 |
|---|---|
search_inside | スキャンされた文書の本文にある語句を検索します。 |
search_items | タイトル、作成者、主題、または一般的な語句でカタログを検索します。 |
get_item | どのアーカイブにあるかにかかわらず、1 件のレコードを統一形式で取得します。 |
search_inside
光学文字認識によってページから読み取られた、スキャン文書内のテキストを検索します。
| 引数 | 型 | 必須 | 機能 |
|---|---|---|---|
query | string、2~300 文字 | はい | 文書内で検索する語句です。 |
limit | integer、1~25、デフォルトは 3 | いいえ | 各アーカイブから保持する一致件数です。 |
page | integer、1~100、デフォルトは 1 | いいえ | 一致結果のページ番号です。 |
max_excerpt_chars | integer、80~1200、デフォルトは 300 | いいえ | 提供する抜粋の長さです。 |
max_excerpts_per_match | integer、1~10、デフォルトは 2 | いいえ | 一致した文書ごとに提供する抜粋の数です。 |
fan_out | boolean、デフォルトは true | いいえ | 最初に応答したアーカイブで停止せず、すべてのアーカイブに問い合わせます。 |
sources | ソース ID の配列 | いいえ | これらのアーカイブのみに問い合わせます。 |
返される内容: id を含む hits。id は get_item に渡すもので、アーカイブも示します。さらに、source と source_name、接頭辞のないアーカイブ独自の identifier、title、creator、year、アーカイブが示す場合は page_number、excerpts、excerpt_kind が含まれます。
excerpt_kind は、抜粋がどのようなものかを示します。 passage は、一致した語句の前後にあるテキストです。page_opening はページの冒頭部分で、アーカイブが返した機械読み取りテキストがその語句の出現箇所より前で終わっているために送られます。この抜粋には検索語句が含まれていないため、引用すると別の箇所を引用することになります。1 件の一致結果に含まれる抜粋は、すべて同じ種類です。
search_items
カタログを検索します。
| Argument | Type | Required | What it does |
|---|---|---|---|
query | string, 1 to 300 characters | yes | タイトル、作成者、主題、または一般的な語句です。 |
media_type | a kind one of the archives holds | no | 検索する資料の種類です。 |
year_from | integer, 1000 to 2100 | no | 最も古い年です。 |
year_to | integer, 1000 to 2100 | no | 最も新しい年です。 |
sort | relevance, newest, oldest or title, default relevance | no | 行の並び順です。 |
limit | integer, 1 to 25, default 5 | no | 各アーカイブから取得する行数です。 |
page | integer, 1 to 100, default 1 | no | 取得する行のページです。 |
fan_out | boolean, default true | no | すべてのアーカイブに問い合わせます。 |
sources | array of source ids | no | 指定したアーカイブのみに問い合わせます。 |
3つのアーカイブでは、資料の分類方法がそれぞれ異なります。Internet Archive
は種類を指定しない場合、すべての種類を一度に検索します。Library of Congress は種類ごとに
検索経路が分かれているため、種類を指定しない検索では、どの種類を検索したかが示されます。また、BnF
の検索では作品を検索します。あるアーカイブが扱わない media_type を指定した場合、そのアーカイブは
検索対象から除外され、その旨が結果に示されます。
返される内容: ヒットした項目の形式の行と、アーカイブごとに1つのレポートを格納する per_source です。レポートには、そのアーカイブの
status、提供した count、reported_total、およびその数が何を数えているかを示す reported_total_means が含まれます。
get_item
どのアーカイブに収録されている場合も、1つのレコードを統一された形式で読み取ります。
| Argument | Type | Required | What it does |
|---|---|---|---|
identifier | string, 1 to 500 characters | yes | 行に含まれる id です。 |
sections | array of description, subjects, copies, context, default ["description"] | no | 返す項目を指定します。 |
max_copies | integer, 1 to 50, default 10 | no | 表示する複製の数です。 |
text_offset | integer, 0 to 1000000, default 0 | no | テキストを再開する位置です。 |
max_text_chars | integer, 200 to 8000, default 1500 | no | 返すテキストの量です。 |
返される内容: レコードの id、source、source_name、アーカイブ独自の
identifier、title、creator、公開時の表記そのままの date、そして
year と year_means です。3つのアーカイブではレコードの日付の付け方が異なるため、year_means はその年が何の年かを示します。attribution はそのアーカイブがクレジット表記として求める内容で、identifier_provisional は識別子が読み取られたものではなく生成された場合にその旨を示します。これにより、呼び出し元はその識別子でレコードを解決できない可能性があるとわかります。
アーカイブについての回答で明示すること
各回答では、各アーカイブについて個別に説明します。失敗したアーカイブ、誰も問い合わせなかったアーカイブ、何も回答しなかったアーカイブは、それぞれ異なるものとして報告します。合計数は、その数を公表したアーカイブの横に、そのアーカイブが数える対象(文書や新聞の紙葉など)とともに記載します。
スキャンされたテキストの扱い
スキャンされた文書内の語句は、光学文字認識によってページから読み取られたものです。抜粋にはその処理による読み取り間違いが含まれているため、修正せず、読み取られたとおりに提供します。引用する際はスキャンされたテキストとして扱い、読者がページを確認できるよう、記録へのリンクを付けてください。
設定
すべての変数は任意です。クライアント設定の env ブロックに設定してください。
| 変数 | デフォルト | 説明 |
|---|---|---|
BOOKS_USER_AGENT | プロジェクトの識別情報 | 3 つのアーカイブに対してアプリケーション名を通知します。人が連絡を取れる連絡先も含めます。 |
BOOKS_MIN_INTERVAL_MS | 各アーカイブ固有の間隔 | 同じアーカイブへの 2 回のリクエストの間隔を 500 から 60000 までの値に広げます。未設定の場合は各アーカイブが公表している間隔を維持し、ここで指定した値は、より長い間隔となる場合にのみ適用されます。 |
BOOKS_TIMEOUT_MS | 45000 | 1 回のリクエストの制限時間です。1000 から 120000 までの値を指定できます。 |
BOOKS_MAX_RETRIES | 3 | 一時的な失敗後の再試行回数です。0 から 8 までの値を指定できます。 |
BOOKS_CACHE_TTL_MS | 900000 | 回答をメモリに保持する時間です。0 から 86400000 までの値を指定できます。 |
BOOKS_CACHE_MAX_ENTRIES | 200 | 一度にメモリに保持する回答数です。1 から 5000 までの値を指定できます。 |
BOOKS_LOG_LEVEL | error | silent、error、info、debug のいずれかです。stderr に出力されます。 |
範囲外の値はデフォルト値に戻され、その理由は stderr に出力されます。
エラー
すべての失敗には、6 種類のコードのいずれか、メッセージ、そして必要に応じて次の対応を示すヒントが付いています。
| コード | 発生したこと | 対応 |
|---|---|---|
not_found | アーカイブから応答がありましたが、該当する記録はありません。 | search_items で識別子を確認してください。 |
invalid_input | リクエストが送信される前に、引数が拒否されました。 | 引数を明示しているメッセージを確認してください。 |
rate_limited | アーカイブから、このクライアントに速度を落とすよう求められました。 | 待ってから、同じ引数で再度呼び出してください。記録はそのまま残っています。 |
parse_failure | このクライアントが読み取れない形式で応答が届きました。 | イシュートラッカーで報告してください。 |
network_error | リクエストが完了しませんでした。 | 少し待ってから再試行してください。 |
timeout | リクエストが期限を超過しました。 | BOOKS_TIMEOUT_MS を増やすか、取得する行数を減らしてください。 |
失敗したアーカイブは、回答全体を失敗させるのではなく、アーカイブごとに報告されます。そのため、応答しないアーカイブがほかの結果を隠すことはありません。
ライブラリとして使う
3 つのアーカイブを読み取るレイヤーは、ペース調整、キャッシュ、エラーを備え、プロトコルに依存しない形で単独で公開されています。
import { BooksClient } from "mcp-books/client";
const client = new BooksClient();
const read = await client.searchItems({ query: "beaumont light-house", limit: 3 });
console.log(read.data.rows.length);
各読み取りは { data, cached } を返し、6 種類のコードのいずれかを含むエラーをスローします。各アーカイブはそれぞれ独自にペース調整され、ここでも下限が適用されます。
ペース調整と出典表記
各アーカイブは個別に、同時に 1 件ずつリクエストを送るようペース調整されます。各アーカイブ固有の下限と設定された間隔のうち、長い方が適用されます。Library of Congress が最も遅い間隔を公開しているため、3 つすべてに同時に問い合わせても、それぞれにかかるリクエストは 3 件ではなく 1 件です。User-Agent は必ずプロジェクトの識別情報と、連絡可能な宛先で終わります。
すべての記録には、そのページのアドレスと、アーカイブが求める attribution が含まれます。Internet Archive のアイテムの権利は寄託者に帰属し、Library of Congress の記録には各記録の権利が記載されています。また、BnF はメタデータを表示する箇所すべてで、出典と取得日を明記するよう求めています。
この MCP サーバーは非公式プロジェクトであり、読み取り対象のいずれのアーカイブとも提携していません。
プライバシー
このサーバーはあなたに関する情報を収集せず、作者に何も送信しません。あなたのマシン上で動作し、archive.org、openlibrary.org、www.loc.gov、data.bnf.fr のみに接続します。動作中は応答をメモリ上に保持し、ディスクには何も書き込みません。PRIVACY.md では、リクエストに含まれる情報と、それらを変更する設定について説明しています。
開発
npm install
npm run build:fixtures
npm test
npm run check
テストでは生成されたフィクスチャを使用し、ネットワークリクエストは行いません。ライブテストスイートの npm run test:live はルートごとに 1 件のリクエストを送信し、アーカイブ自体に対して毎晩実行されます。
貢献
バグ、質問、アイデアはイシュートラッカーでお知らせください。プルリクエストも歓迎します。まずイシューを作成しておくと、変更内容について合意しやすくなります。CONTRIBUTING.mdをご覧ください。
ライセンス
MIT ライセンスです。LICENSEをご覧ください。記録の権利は、それらを公開したアーカイブおよび寄託者に帰属します。
mcp-books(フランス語)
3つの大規模なアーカイブが、出版されたもののデジタル記録を保存しており、 それぞれ独自の言葉で記述しています。Internet Archive は、人々が預けた書籍、映画、録音、ソフトウェアを保管し、そのうち数百万点に 光学文字認識を施しています。Library of Congress は、 文書の種類ごとのカタログとして、米国の国立コレクションを公開しています。 data.bnf.fr は、所蔵資料ではなく作品やその著者を記述する フランス国立図書館の典拠レコードを公開しています。
このサーバーでは、1つの質問で3つすべてを検索できます。デジタル化された文書に 含まれる語句を検索したり、カタログを検索したり、どのアーカイブが所蔵しているかに かかわらず、統一された形式でレコードを読んだりできます。API キーもアカウントも 必要ありません。
インストール
ワンクリックインストール
Claude Code
claude mcp add books -- npx -y mcp-books
Claude Desktop、Cursor、および標準設定形式に対応するすべてのクライアント
{
"mcpServers": {
"books": {
"command": "npx",
"args": ["-y", "mcp-books"]
}
}
}
Node 24 以降が必要です。設定が必要な環境変数はありません。
Docker を使う
{
"mcpServers": {
"books": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-books:2.0.1"]
}
}
}
-i はプロトコルの通信路である標準入力を開いたままにします。-t は TTY が
ストリームを書き換えてしまうため省略します。コンテナに必要なのは、
archive.org、openlibrary.org、www.loc.gov、data.bnf.fr への HTTPS
アウトバウンドアクセスだけです。ボリューム、ポート、認証情報は必要ありません。
バンドル(npm 不要)
最新リリースから
mcp-books-2.0.1.mcpb をダウンロードして開きます。MCP バンドルに対応する
クライアントなら、npm も編集が必要な設定ファイルも使わずにインストールできます。
バンドルには依存関係が含まれているため、インストール時に何もダウンロードされません。
質問できること
- 「Beaumont 灯台に言及している書籍はありますか?」
- 「1906年のサンフランシスコ地震について調べてください。」
- 「このレコードを読んで、原本を所蔵しているところを教えてください。」
- 「この著者について、BnF にはどのような情報がありますか?」
- 「書籍ではなく、写真を検索してください。」
3つのアーカイブに問い合わせ、それぞれの処理速度に合わせて応答するため、 回答には数秒かかります。
3つの情報源
| 情報源 | アーカイブ | 説明するもの |
|---|---|---|
archive | Internet Archive | あらゆる種類の寄託資料 |
loc | Library of Congress | 種類ごとのカタログにまとめられた国立コレクション |
bnf | フランス国立図書館 | 作品とその著者 |
各行の id はアーカイブを示すため、回答で得た識別子から正しいアーカイブに戻れます。
件数をアーカイブ間で合算することはありません。また、失敗したアーカイブは、
何も見つからなかったのではなく、失敗したと報告されます。
ツール
| ツール | 説明 |
|---|---|
search_inside | スキャンされたドキュメントに含まれる単語を検索します。 |
search_items | カタログをタイトル、著者、主題、または簡単なキーワードで検索します。 |
get_item | アーカイブにかかわらず、統一された形式で書誌レコードを読み取ります。 |
search_inside
スキャンされたドキュメントに含まれるテキストを検索します。このテキストは光学式文字認識によって得られたものです。
| 引数 | 型 | 必須 | 説明 |
|---|---|---|---|
query | 文字列、2~300文字 | はい | ドキュメント内で検索する語句です。 |
limit | 整数、1~25、デフォルトは3 | いいえ | 各アーカイブから保持する一致件数です。 |
page | 整数、1~100、デフォルトは1 | いいえ | 一致結果のページ番号です。 |
max_excerpt_chars | 整数、80~1200、デフォルトは300 | いいえ | 返す抜粋の長さです。 |
max_excerpts_per_match | 整数、1~10、デフォルトは2 | いいえ | 一致したドキュメントごとに返す抜粋の数です。 |
fan_out | ブール値、デフォルトはtrue | いいえ | 最初に応答したアーカイブで止めず、各アーカイブに問い合わせます。 |
sources | ソース識別子の配列 | いいえ | 指定したアーカイブだけに問い合わせます。 |
戻り値: hits。各項目には、get_item が使用するアーカイブを示す id、source と source_name、プレフィックスのないアーカイブ固有の identifier、title、creator、year、アーカイブが示す場合の page_number、excerpts、および excerpt_kind が含まれます。
excerpt_kind は抜粋の内容を示します。 passage は、見つかった単語の周辺のテキストです。page_opening はページの冒頭部分で、アーカイブが返した機械読み取りテキストが検索語の出現箇所より前で途切れているために返されます。該当箇所は含まれないため、これを引用すると別の内容を引用することになります。1つの一致結果に含まれる抜粋は、すべて同じ種類です。
search_items
カタログを検索します。
| Argument | Type | Requis | Ce qu'il fait |
|---|---|---|---|
query | 文字列、1~300文字 | はい | タイトル、著者、主題、または一般的なキーワードです。 |
media_type | いずれかのアーカイブが所蔵する種類 | いいえ | 検索する資料の種類です。 |
year_from | 整数、1000~2100 | いいえ | 最も古い年です。 |
year_to | 整数、1000~2100 | いいえ | 最も新しい年です。 |
sort | relevance、newest、oldest、titleのいずれか、既定値はrelevance | いいえ | 結果の並び順です。 |
limit | 整数、1~25、既定値は5 | いいえ | 各アーカイブから取得する件数です。 |
page | 整数、1~100、既定値は1 | いいえ | 取得するページです。 |
fan_out | ブール値、既定値はtrue | いいえ | 各アーカイブに問い合わせます。 |
sources | ソース ID の配列 | いいえ | 指定したアーカイブだけに問い合わせます。 |
3つのアーカイブでは、所蔵資料の分類方法がそれぞれ異なります。Internet Archiveでは、種類を指定しない場合、すべての種類をまとめて検索します。Library of Congressでは種類ごとに検索経路があるため、種類を指定しない検索では、どの種類が検索されたかが通知されます。BnFの検索では作品が検索されます。アーカイブが扱っていないmedia_typeを指定すると、そのアーカイブは応答から除外され、そのことが応答に示されます。
返される内容: hit形式の結果と、アーカイブごとのレポートを示すper_sourceです。レポートには、そのアーカイブのstatus、返されたcount、reported_total、およびその数が何を数えているかを示すreported_total_meansが含まれます。
get_item
どのアーカイブが所蔵しているかにかかわらず、統一された形式で書誌レコードを読み取ります。
| Argument | Type | Requis | Ce qu'il fait |
|---|---|---|---|
identifier | 文字列、1~500文字 | はい | 結果行が持つidです。 |
sections | description、subjects、copies、contextの配列、既定値は["description"] | いいえ | 返すセクションです。 |
max_copies | 整数、1~50、既定値は10 | いいえ | 一覧表示する所蔵資料の数です。 |
text_offset | 整数、0~1000000、既定値は0 | いいえ | テキストの続きを始める位置です。 |
max_text_chars | 整数、200~8000、既定値は1500 | いいえ | 返すテキストの長さです。 |
返される内容: id、source、source_name、アーカイブ固有のidentifier、title、creator、公開時の表記そのままのdateを含む書誌レコードです。また、yearと、その年が何の年を示すかを示すyear_meansも含まれます。3つのアーカイブでは書誌レコードの日付の付け方が異なるためです。attributionは、そのアーカイブが求めるクレジット表記です。identifier_provisionalは、識別子が取得されたものではなく生成されたことを示すため、呼び出し側は解決できない場合があると分かります。
回答からアーカイブについてわかること
各回答では、アーカイブごとに個別に報告します。失敗したアーカイブ、誰も問い合わせなかったアーカイブ、空の回答を返したアーカイブは、それぞれ異なるものとして、別々に報告されます。合計値は、それを公開したアーカイブの横に、そのアーカイブが何を数えた値なのかとともに表示されます。あるアーカイブは文書を数え、別のアーカイブはログのページを数えます。
デジタル化されたテキストの価値
デジタル化された文書に含まれる語句は、光学文字認識によって読み取られたものです。抜粋にはこの処理による読み取り誤りが含まれており、修正せず、読み取られたとおりに提供されます。デジタル化されたテキストとして引用し、読者がページを確認できるよう、書誌情報へのリンクを付けてください。
設定
各変数はすべて任意です。クライアント設定の env ブロックに設定します。
| 変数 | デフォルト | 機能 |
|---|---|---|
BOOKS_USER_AGENT | プロジェクトの識別情報 | 3つのアーカイブに対してアプリケーション名と、担当者に連絡できるアドレスを通知します。 |
BOOKS_MIN_INTERVAL_MS | アーカイブごとの既定の間隔 | 同じアーカイブへの2回のリクエスト間隔を、500から60000の範囲で広げます。設定しない場合、各アーカイブは公開している間隔を維持し、ここに設定した値は、その値のほうが長いアーカイブにのみ適用されます。 |
BOOKS_TIMEOUT_MS | 45000 | リクエストのタイムアウト時間です。1000から120000の範囲で設定します。 |
BOOKS_MAX_RETRIES | 3 | 一時的な失敗の後に再試行する回数です。0から8の範囲で設定します。 |
BOOKS_CACHE_TTL_MS | 900000 | 回答をメモリに保持する期間です。0から86400000の範囲で設定します。 |
BOOKS_CACHE_MAX_ENTRIES | 200 | 同時にメモリに保持する回答の数です。1から5000の範囲で設定します。 |
BOOKS_LOG_LEVEL | error | silent、error、info、debugのいずれかを指定します。エラー出力に書き込まれます。 |
範囲外の値はデフォルト値に戻り、その理由がエラー出力に書き込まれます。
エラー
各失敗には6つのコードのいずれかとメッセージが含まれ、必要に応じて次に取るべき手順も示されます。
| コード | 発生したこと | 対処方法 |
|---|---|---|
not_found | アーカイブから応答がありましたが、そのレコードはありません。 | search_items で識別子を確認してください。 |
invalid_input | リクエストを送信する前に引数が拒否されました。 | 引数を示すメッセージを読んでください。 |
rate_limited | アーカイブがこのクライアントにリクエストを控えるよう求めています。 | 待ってから、同じ引数で再度呼び出してください。レコードは引き続き存在します。 |
parse_failure | 応答は届きましたが、ここでは読み取れない形式でした。 | 課題トラッカーで報告してください。 |
network_error | リクエストが完了しませんでした。 | 少し待ってから再試行してください。 |
timeout | リクエストがタイムアウトしました。 | BOOKS_TIMEOUT_MS を増やすか、取得する行数を減らしてください。 |
失敗したアーカイブは、応答全体を失敗させるのではなく、アーカイブごとに報告されます。そのため、応答しないアーカイブがほかのアーカイブの結果を隠すことはありません。
ライブラリとして
3つのアーカイブを読み取るレイヤーは、独自のリズム、キャッシュ、エラーを備えた単体のライブラリとして公開されており、特定のプロトコルには依存しません。
import { BooksClient } from "mcp-books/client";
const client = new BooksClient();
const read = await client.searchItems({ query: "beaumont light-house", limit: 3 });
console.log(read.data.rows.length);
読み取りごとに { data, cached } が返され、6つのコードのいずれかを持つエラーがスローされます。各アーカイブにはそれぞれ独自のリクエスト間隔があり、ここでも最小間隔が適用されます。
リクエスト間隔とクレジット表記
各アーカイブへのリクエストは個別に、同時に1件ずつ送信されます。適用されるのは、そのアーカイブ独自の最小間隔と設定された間隔のうち、長いほうです。Library of Congress が公開している間隔が最も長いため、3つのアーカイブに同時に問い合わせても、それぞれに1件ずつ、合計3件のリクエストが送信されます。User-Agent の末尾には、必ずプロジェクトの識別情報と連絡先のメールアドレスが含まれます。
各レコードには、そのページのURLと、アーカイブが求める attribution が含まれます。Internet Archive の資料は登録者に帰属し、Library of Congress のレコードには独自の権利情報が記載されています。また、BnF は、メタデータを表示するすべての場所で、出典と取得日を明記するよう求めています。
この MCP は非公式のプロジェクトであり、参照するいずれのアーカイブとも提携していません。
プライバシー
このサーバーはユーザーに関する情報を収集せず、作者に送信することもありません。お使いのマシン上で動作し、archive.org、openlibrary.org、www.loc.gov、data.bnf.fr のみに接続します。応答は動作中のみメモリに保持され、ディスクには何も書き込みません。PRIVACY.md には、リクエストに含まれる情報と、これを変更する設定が記載されています。
開発
npm install
npm run build:fixtures
npm test
npm run check
テストは生成されたフィクスチャを使って実行され、リクエストは送信されません。ライブテスト npm run test:live はルートごとに1件のリクエストを送信し、毎晩、各アーカイブに対して実行されます。
貢献
問題、質問、アイデアは課題トラッカーにお寄せください。変更の提案も歓迎します。まずチケットを作成すると、変更内容について合意しやすくなります。CONTRIBUTING.mdをご覧ください。
ライセンス
MIT です。LICENSEをご覧ください。レコードは、公開したアーカイブと、そこに登録した人に帰属します。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。