ndl-mcp

Ein MCP-Server für die Suche in 国立国会図書館サーチ (NDL Search), betrieben von der National Diet Library of Japan, über die SRU-searchRetrieve-Schnittstelle.

Dritter in einer Reihe mit cinii-mcp und jstage-mcp, und teilt deren Antwort-Hülle: typisierte Abfrage und Skript, Abgleichmodus, abgestufte Breite, pro Element matched_in, typisierte Diagnosen, eine protokollierbare Quittung, Attribution.

Bevor Sie dies ausführen

Es gibt keine Zugangsdaten. Die NDL-Such-APIs sind offen. Kein API-Schlüssel, keine Anwendungs-ID, kein Token, nichts, das in eine Konfigurationsdatei eingefügt werden müsste. Wenn Sie auf etwas warten, das eintreffen muss, bevor Sie dies nutzen können, warten Sie auf etwas, das nicht kommt.

Es gibt dennoch eine Verpflichtung. Abschnitt 17 von APIのご利用について bittet kontinuierliche API-Nutzer, ihre Kontaktdaten und die Art ihrer Nutzung über das Antragsformular zu melden — 「事前の利用申請の要否にかかわらず」, unabhängig davon, ob eine vorherige Nutzungsanmeldung erforderlich ist. Eine formelle 利用申請 ist nur für umsatzgenerierende Nutzung erforderlich; die Meldung wird von allen erbeten, die kontinuierlich zugreifen.

Da der Zugriff nicht an die Einreichung gekoppelt ist, wird nichts auf der Welt Sie davon abhalten, sie zu überspringen. Also stoppt install.ps1 Sie: Es weigert sich, den Server zu registrieren, bis die Meldung aufgezeichnet ist, und schreibt das Datum in NDL-API-NOTIFICATION.txt.

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

Führen Sie es ohne das Flag aus, und es gibt die Formular-URL aus, bietet an, sie zu öffnen, und beendet sich.

Related MCP server: jp-lit-mcp

Was der Server nicht tun wird

Die folgenden Zusagen wurden bei der NDL eingereicht. Sie sind umgesetzt, nicht nur angestrebt, und der Rauchtest des Installers prüft die ersten drei:

Ändern Sie eine davon, und Sie ändern, was einer nationalen Bibliothek erklärt wurde. Reichen Sie zuerst eine ergänzende Meldung ein.

Anbieter

Nur die fünf in der Anwendung deklarierten Sets sind erreichbar. Alle sind von der NDL erstellt und CC BY, und keines erfordert eine Nutzungsanmeldung:

ndl-dl und ndl-dl-online — die breiteren Digital Collections — sind auf der Anbieterliste mit △ markiert und erfordern eine Anmeldung, die nicht erfolgt ist. Eine Anfrage, die sie benennt, wird im Prozess abgelehnt, mit einer DPID_NOT_PERMITTED-Diagnose, anstatt gesendet zu werden.

Werkzeuge

Suchfelder: title, creator, publisher, subject, anywhere, ndc, isbn, issn, from_year, to_year. Sie werden mit UND kombiniert; Titel, Urheber, Verlag und Betreff stimmen teilweise überein, ndc per Präfix, Identifikatoren exakt.

ndl_get_record ist ein Abruf, daher lässt seine Hülle searched_for weg — es wurde kein Begriff gewählt.

Zwei Dinge, die beißen werden

Ein großgeschriebenes AND, OR oder NOT innerhalb eines Suchbegriffs führt dazu, dass NDL die gesamte Abfrage ablehnt. Nicht "liefert nichts" — lehnt ab. Die Regel ist, wie die Spezifikation sie angibt, groß-/kleinschreibungsempfindlich: War AND Peace wird abgefangen, War and Peace wird durchgelassen. Der Server prüft vor dem Senden und gibt eine RESERVED_WORD_IN_QUERY-Diagnose zurück, die das fehlerhafte Feld benennt, anstatt die Bibliothek mit einem Parse-Fehler antworten zu lassen.

NDL setzt ein Ratenlimit durch, das es nicht beziffert, und antwortet mit HTTP 429. Die Hilfeseite sagt nur 「同時リクエスト数には制限を設けています」 und weigert sich, eine Zahl zu veröffentlichen. In Tests am 19. August 2026 kam eine 429 bei deutlich unter einer anhaltenden Anfrage pro Sekunde — also ist die bei der Bibliothek eingereichte Ein-Sekunden-Untergrenze ein Minimum, keine Garantie. Eine 429 erkauft eine Backoff-Phase, die Retry-After respektiert, und dann stoppt der Server, anstatt weiterzudrücken. Er meldet RATE_LIMITED, bewusst unterschieden von API_ERROR, weil die beiden für einen Leser unterschiedliche Bedeutungen haben: Eine ratenbegrenzte Suche hat ein unbekanntes Ergebnis, kein leeres, und darf niemals als Abwesenheit dargestellt werden.

Ein romanisierter Begriff wird zu wenig zurückliefern. NDL Search indexiert japanischsprachige Datensätze in japanischer Schrift. Eine Abfrage in lateinischer Schrift gegen einen japanischen Korpus ist die Romaji-Falle, und die Hülle erhebt dafür SCRIPT_LATIN_QUERY. Die searched_for-Überschrift existiert, damit der Begriff, den der Assistent tatsächlich gewählt hat, oben in der Antwort sichtbar ist und nicht vergraben — das ist der ganze Sinn des Feldes und der Grund, warum eine Offenlegung die Begriffe melden kann, die eine Suche verwendet hat.

Quittungen

mediation.emit() schreibt jede Antwort-Hülle in das append-only, hash-verkettete Ledger bei MCP_RECEIPT_LOG, das install.ps1 auf dieselbe Datei setzt, die die anderen Server verwenden. Wenn die Variable nicht gesetzt ist, wird nichts geschrieben und nichts schlägt fehl.

Beachten Sie, was das Ledger enthält und was nicht: die Abfrage, den normalisierten Begriff, die gesendeten Parameter, den Zeitstempel, einen SHA-256 über Abfrage und Parameter sowie die Identifikatoren der zurückgegebenen Datensätze. Es enthält nicht die bibliografischen Datensätze selbst. Das Protokollieren einer Abfrage ist kein Aufbau einer Datenbank, und die Zusage gegen Anhäufung wird durch das Aufbewahren der Quittung nicht verletzt — aber die Unterscheidung ist es wert, ausgesprochen zu werden, anstatt vorausgesetzt zu werden, weil die beiden von außen ähnlich aussehen.

Warum nur SRU

Die Anwendung deklariert SRU und OpenSearch. Dieser Server implementiert nur SRU, was weniger ist als deklariert und daher sicher — Sie dürfen immer weniger verwenden, als Sie der Bibliothek mitgeteilt haben.

Der Grund ist beweiskräftig. Das OpenSearch-Antwortformat ist in der 第1.4版-Spezifikation nicht dokumentiert: keine Elementtabelle, kein Beispiel, und die Anhänge decken nur SRU und OAI-PMH ab. Schlimmer noch, die Spezifikation besagt, dass ein fehlerhafter Parameter eine Null-Ergebnis-Antwort anstelle eines Fehlers zurückgibt — 「引数（パラメータ）誤りの場合には検索結果ゼロ件となる」 — sodass ein Tippfehler in einem Feldnamen von einem echten Fehlen nicht zu unterscheiden ist. Für ein Werkzeug, dessen Zweck es ist, einem Historiker zu ermöglichen, zu vertrauen, dass nichts gefunden wurde, ist das disqualifizierend. SRU gibt typisierte Diagnosen und ein dokumentiertes DC-NDL-Datensatzschema zurück. OpenSearch später hinzuzufügen erfordert keine neue Meldung; es erfordert ein dokumentiertes Antwortformat.

Quellen

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

• APIのご利用について — Bedingungen, Gutschrift-Anforderung, Nebenläufigkeit, Meldung

• API提供対象データプロバイダ一覧 — dpid-Werte und Lizenzbedingungen

Lizenz

MIT. Metadaten, die über diesen Server abgerufen werden, sind CC BY 4.0 von der National Diet Library; die Gutschriftszeile, die der Server ausgibt, ist die Attribution, die diese Lizenz verlangt, und sie sollte in alles überleben, was Sie aus den Ergebnissen veröffentlichen.

Was getestet wurde und was nicht

Verifiziert gegen die Live-API am 19. August 2026:

• Japanisch-schriftliche Suche über 蔵書 und 雑誌記事索引 — korrekte Gesamtzahlen, korrekte Datensätze, korrekte Jahre und Identifikatoren.

• DC-NDL-Parsing, einschließlich des Manifestations-Stub-Filters. NDL gibt zwei BibResource-Elemente pro Datensatz zurück; das Nehmen beider verdoppelte die Ergebnismenge mit Leerstellen, bis der Filter eingebaut wurde.

• searched_for meldet den gewählten Begriff, nicht das zusammengesetzte CQL, sodass seine Skripterkennung aussagekräftig ist; das genaue CQL wird in query.params getragen und durch den Quittungs-Hash fixiert.

• Die DPID_NOT_PERMITTED-Absicherung: Eine Anfrage, die ndl-dl benennt, wird im Prozess abgelehnt.

• RESERVED_WORD_IN_QUERY: War AND Peace abgefangen, War and Peace durchgelassen.

• Der Ratenbegrenzer, unfreiwillig — siehe HTTP 429 oben.

Nicht gegen die Live-API verifiziert und eher gelesen als ausgeführt: der Durchgriff "Datensatz existiert nicht", ndl_get_record und der Backoff-Pfad. Die Tests stoppten bei der 429, anstatt fortzufahren, weil das Charakterisieren einer nicht offengelegten Ratenbegrenzung durch Sondierung genau das 継続して大量のアクセス ist, vor dem die Bedingungen warnen, und der Zweck dieses Servers ist es nicht, das Ding zu sein, das die National Diet Library blockieren muss. Üben Sie diese Pfade im normalen Gebrauch, eine Abfrage nach der anderen.