ndl-mcp

国立国会図書館が運営する国立国会図書館サーチ（NDL Search）を、SRU searchRetrieve インターフェース経由で検索するためのMCPサーバー。

cinii-mcp および jstage-mcp に続くシリーズ第3弾であり、それらとレスポンスエンベロープを共有しています。型付きクエリとスクリプト、マッチングモード、段階的な広さ、アイテムごとの matched_in、型付き診断、記録可能なレシート、帰属表示。

実行前に

認証情報は不要です。 NDL検索APIは公開されています。APIキーもアプリケーションIDもトークンも、設定ファイルに貼り付けるものは何もありません。何かが届くのを待ってから使おうとしているなら、それは決して来ないものを待っています。

それでも義務はあります。 APIのご利用について の第17条は、継続的にAPIを利用する利用者に対し、申請フォーム を通じて連絡先と利用内容を届け出るよう求めています — 「事前の利用申請の要否にかかわらず」、つまり事前の利用申請が必須かどうかに関わらずです。正式な利用申請が必須なのは収益を生む利用だけであり、届出は継続的にアクセスするすべての人に求められています。

アクセスは届出によって制限されていないため、世界中の何ものもあなたがそれを省略するのを止めません。そこで install.ps1 があなたを止めます。通知が記録されるまでサーバーの登録を拒否し、日付を NDL-API-NOTIFICATION.txt に書き込みます。

.\install.ps1 -NotificationFiled 2026-08-19

フラグなしで実行すると、フォームのURLを表示し、開くことを提案して終了します。

Related MCP server: jp-lit-mcp

サーバーが行わないこと

以下の約束はNDLに提出されたものです。これは目標ではなく実装されており、インストーラーのスモークテストは最初の3つを検証します。

これらのいずれかを変更することは、国立図書館に申告した内容を変更することです。まず追加の通知を提出してください。

プロバイダー

アプリケーションで申告した5つのセットのみが利用可能です。すべてNDLが作成しCC BYであり、利用申請は不要です。

ndl-dl と ndl-dl-online — より広いデジタルコレクション — は プロバイダー一覧 で △ とされており、行われていない申請が必要です。これらを指定するリクエストは送信されず、プロセス内で DPID_NOT_PERMITTED 診断とともに拒否されます。

ツール

検索フィールド: title, creator, publisher, subject, anywhere, ndc, isbn, issn, from_year, to_year。これらは AND で結合されます。title、creator、publisher、subject は部分一致、ndc は前方一致、識別子は完全一致です。

ndl_get_record はフェッチであるため、そのエンベロープには searched_for が含まれません — 検索語が選択されていないからです。

注意すべき2つのこと

検索語内の大文字の AND、OR、NOT は、NDLがクエリ全体を拒否します。 「何も返さない」のではなく「拒否」です。この規則は仕様書に記載されているとおり大文字小文字を区別します。War AND Peace は検出され、War and Peace は通ります。サーバーは送信前にチェックし、図書館が構文解析エラーで応答するのではなく、問題のフィールドを指定した RESERVED_WORD_IN_QUERY 診断を返します。

NDLは数値を明示しないレート制限を実施しており、HTTP 429で応答します。 ヘルプページには「同時リクエスト数には制限を設けています」とだけ書かれ、数値の公表を拒否しています。2026年8月19日のテストでは、持続的な1秒あたり1リクエストを大幅に下回る時点で429が発生しました。つまり、図書館に申告した1秒の下限は最低限であり、保証ではありません。429が発生すると、Retry-After を尊重して1回だけバックオフし、その後サーバーは押し続けずに停止します。RATE_LIMITED を報告しますが、これは意図的に API_ERROR とは区別されています。なぜなら、この2つは読者にとって異なる意味を持つからです。レート制限された検索の結果は 不明 であり、空であるわけではなく、決して「該当なし」として記述してはなりません。

ローマ字表記の語は検索結果が少なくなります。 NDL Searchは日本語のレコードを日本語の文字で索引付けしています。日本語コーパスに対するラテン文字クエリはローマ字の罠であり、エンベロープはそれに対して SCRIPT_LATIN_QUERY を発生させます。searched_for の見出しは、アシスタントが実際に選んだ語がレスポンスの先頭に埋もれずに見えるようにするために存在します。それがこのフィールドの存在意義であり、開示が検索で使用された語を報告できる理由です。

レシート

mediation.emit() は各レスポンスエンベロープを、追記専用でハッシュチェーンされた台帳 MCP_RECEIPT_LOG に書き込みます。install.ps1 はこれを他のサーバーが使用するのと同じファイルに設定します。変数を未設定にすると、何も書き込まれず、何も失敗しません。

台帳が保持するものと保持しないものに注意してください。保持するのは、クエリ、正規化された語、送信されたパラメータ、タイムスタンプ、クエリとパラメータに対するSHA-256、そして返されたレコードの識別子です。書誌レコード自体は保持しません。クエリを記録することはデータベースを蓄積することではなく、レシートを保持しても蓄積しないという約束に違反しません。しかし、この区別は暗黙の前提にするのではなく明言する価値があります。なぜなら、外部から見ると両者は似ているからです。

SRUのみである理由

申請ではSRUとOpenSearchを宣言しています。このサーバーはSRUのみを実装しています。これは宣言した内容より少ないため安全です — 図書館に伝えた内容より少なく使うことは常に許されます。

その理由は証拠にあります。OpenSearchのレスポンス形式は第1.4版仕様書に文書化されていません。要素表もサンプルもなく、付録はSRUとOAI-PMHのみを扱っています。さらに悪いことに、仕様書は不正なパラメータがエラーではなく ゼロ件 のレスポンスを返すと述べています — 「引数（パラメータ）誤りの場合には検索結果ゼロ件となる」 — そのため、フィールド名のタイプミスは本当の該当なしと区別できません。歴史家に「何も見つからなかった」ことを信頼させることを目的としたツールにとって、これは失格です。SRUは型付き診断と文書化されたDC-NDLレコードスキーマを返します。後でOpenSearchを追加するのに新しい通知は不要です。必要なのは文書化されたレスポンス形式です。

出典

• 国立国会図書館サーチ 外部提供インタフェース仕様書 第1.4版 (2026-03-31)

• APIのご利用について — 利用条件、クレジット要件、同時実行性、通知

• API提供対象データプロバイダ一覧 — dpid値とライセンス条件

ライセンス

MIT。このサーバーを通じて取得したメタデータは、National Diet LibraryによるCC BY 4.0です。サーバーが出力するクレジット行は、そのライセンスが要求する帰属表示であり、結果から公開するあらゆるものに残すべきです。

テスト済みのものと未テストのもの

2026年8月19日に実APIに対して検証済み:

• 蔵書と雑誌記事索引にわたる日本語スクリプト検索 — 正しい総数、正しいレコード、正しい年と識別子。

• DC-NDLのパース。manifestation-stubフィルタを含む。NDLはレコードごとに2つの BibResource 要素を返します。フィルタが入るまで両方を取得すると、空白のまま結果セットが2倍になりました。

• searched_for は組み立てられたCQLではなく選択された語を報告するため、そのスクリプト検出は意味を持ちます。正確なCQLは query.params に含まれ、レシートのハッシュによって固定されます。

• DPID_NOT_PERMITTED ガード: ndl-dl を指定するリクエストはプロセス内で拒否されます。

• RESERVED_WORD_IN_QUERY: War AND Peace は検出され、War and Peace は通りました。

• レートリミッターは、意図せず検証されました — 上記のHTTP 429を参照。

実APIに対して未検証であり、実行ではなく読解による確認: 「Record does not exist」のパススルー、ndl_get_record、およびバックオフ経路。テストは429で継続をやめました。なぜなら、未公開のレート制限をプローブして特徴づけることは、まさに利用規約が警告する継続して大量のアクセスであり、このサーバーの目的はNational Diet Libraryがブロックせざるを得ない存在になることではないからです。通常の利用で、一度に1クエリずつこれらの経路を試してください。