ndl-mcp

MCP-сервер для поиска по 国立国会図書館サーチ (NDL Search), управляемый National Diet Library of Japan, через интерфейс SRU searchRetrieve.

Третий в серии вместе с cinii-mcp и jstage-mcp, разделяющий их конверт ответа: введённый запрос и письменность, режим сопоставления, ступенчатый охват, matched_in для каждого элемента, типизированная диагностика, журналируемая квитанция, атрибуция.

Перед запуском

Никаких учётных данных не требуется. Поисковые API NDL открыты. Никакого API-ключа, никакого идентификатора приложения, никакого токена, ничего, что нужно вставлять в конфигурационный файл. Если вы ждёте, что что-то придёт, прежде чем вы сможете этим воспользоваться, вы ждёте того, что не придёт.

Обязательство всё же есть. Раздел 17 документа APIのご利用について просит постоянных пользователей API сообщить свои контактные данные и характер использования через форму заявки — 「事前の利用申請の要否にかかわらず」, то есть независимо от того, требуется ли предварительная заявка на использование. Формальная 利用申請 требуется только для использования, приносящего доход; уведомление запрашивается у всех, кто обращается к API на постоянной основе.

Поскольку доступ не зависит от подачи уведомления, ничто в мире не помешает вам его пропустить. Поэтому install.ps1 останавливает вас: он отказывается регистрировать сервер, пока уведомление не будет зафиксировано, и записывает дату в NDL-API-NOTIFICATION.txt.

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

Запустите его без флага — и он выведет URL формы, предложит открыть её и завершится.

Related MCP server: jp-lit-mcp

Чего сервер делать не будет

Перечисленные ниже обязательства были заявлены в NDL. Они реализованы, а не декларируются как намерения, и смоук-тест установщика проверяет первые три:

Измените любое из них — и вы измените то, что было заявлено национальной библиотеке. Сначала подайте дополнительное уведомление.

Провайдеры

Доступны только пять наборов, заявленных в приложении. Все они созданы NDL и распространяются по лицензии CC BY, и ни один не требует заявки на использование:

ndl-dl и ndl-dl-online — более широкая Digital Collections — отмечены △ в списке провайдеров и требуют заявки, которая не подавалась. Запрос, называющий их, отклоняется внутри процесса с диагностикой 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 — никакой термин не выбирался.

Две вещи, которые укусят

Прописные AND, OR или NOT внутри поискового термина заставляют NDL отклонить весь запрос. Не «ничего не возвращает» — отклоняет. Правило чувствительно к регистру, как указано в спецификации: War AND Peace перехватывается, War and Peace проходит. Сервер проверяет перед отправкой и возвращает диагностику RESERVED_WORD_IN_QUERY с указанием поля-нарушителя, а не позволяет библиотеке ответить ошибкой разбора.

NDL вводит ограничение частоты запросов, которое не раскрывает количественно, и отвечает HTTP 429. На странице помощи сказано только 「同時リクエスト数には制限を設けています」, и она отказывается публиковать цифру. При тестировании 19 августа 2026 года ответ 429 пришёл при частоте значительно ниже одного постоянного запроса в секунду — так что заявленный библиотеке минимум в одну секунду является нижней границей, а не гарантией. Ответ 429 даёт одну паузу с соблюдением Retry-After, после чего сервер останавливается, а не продолжает давить. Он сообщает RATE_LIMITED, намеренно отличая это от API_ERROR, потому что для читателя эти два случая значат разное: поиск, ограниченный по частоте, имеет неизвестный результат, а не пустой, и его нельзя оформлять как отсутствие результатов.

Романизированный термин даст неполные результаты. 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. Метаданные, полученные через этот сервер, распространяются по лицензии CC BY 4.0 от National Diet Library; строка атрибуции, которую выдаёт сервер, — это указание авторства, требуемое этой лицензией, и она должна сохраняться во всём, что вы публикуете на основе результатов.

Что проверено, а что нет

Проверено на живом API 19 августа 2026 года:

• Поиск на японской письменности по 蔵書 и 雑誌記事索引 — правильные итоги, правильные записи, правильные годы и идентификаторы.

• Разбор DC-NDL, включая фильтр заглушек проявлений. NDL возвращает два элемента BibResource на запись; приём обоих удваивал набор результатов с пустыми местами, пока не был добавлен фильтр.

• 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 придётся блокировать. Проверяйте эти пути в обычном использовании, по одному запросу за раз.