ndl-mcp

Un servidor MCP para buscar en 国立国会図書館サーチ (NDL Search), operado por la Biblioteca Nacional de la Dieta de Japón, a través de la interfaz SRU searchRetrieve.

Tercero de una serie con cinii-mcp y jstage-mcp, y comparte su sobre de respuesta: consulta y script tipados, modo de coincidencia, amplitud gradual, matched_in por elemento, diagnósticos tipados, un recibo registrable, atribución.

Antes de ejecutar esto

No hay credencial. Las API de búsqueda de NDL son abiertas. Sin clave de API, sin ID de aplicación, sin token, nada que pegar en un archivo de configuración. Si estás esperando que llegue algo antes de poder usar esto, estás esperando algo que no va a llegar.

Sigue habiendo una obligación. La sección 17 de APIのご利用について pide a los usuarios continuos de la API que informen de sus datos de contacto y la naturaleza de su uso a través del formulario de solicitud — 「事前の利用申請の要否にかかわらず」, tanto si se requiere una solicitud de uso previa como si no. Una 利用申請 formal solo se requiere para uso generador de ingresos; la notificación se pide a todos los que acceden de forma continua.

Como el acceso no depende de la presentación, nada en el mundo te impedirá omitirla. Así que install.ps1 te lo impide: se niega a registrar el servidor hasta que se registre la notificación, y escribe la fecha en NDL-API-NOTIFICATION.txt.

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

Ejecútalo sin la bandera e imprime la URL del formulario, ofrece abrirlo y sale.

Related MCP server: jp-lit-mcp

Lo que el servidor no hará

Los compromisos siguientes se presentaron ante la NDL. Están implementados, no aspirados, y la prueba de humo del instalador afirma los tres primeros:

Cambia cualquiera de ellos y estarás cambiando lo que se declaró a una biblioteca nacional. Presenta primero una notificación complementaria.

Proveedores

Solo los cinco conjuntos declarados en la solicitud son accesibles. Todos son creados por NDL y CC BY, y ninguno requiere una solicitud de uso:

ndl-dl y ndl-dl-online — las Colecciones Digitales más amplias — están marcados con △ en la lista de proveedores y requieren una solicitud que no se ha realizado. Una solicitud que los nombre se rechaza en el proceso, con un diagnóstico DPID_NOT_PERMITTED, en lugar de enviarse.

Herramientas

Campos de búsqueda: title, creator, publisher, subject, anywhere, ndc, isbn, issn, from_year, to_year. Se combinan con AND; title, creator, publisher y subject coinciden parcialmente, ndc por prefijo, identificadores exactamente.

ndl_get_record es una recuperación, por lo que su sobre omite searched_for — no se eligió ningún término.

Dos cosas que morderán

Un AND, OR o NOT en mayúsculas dentro de un término de búsqueda hace que NDL rechace toda la consulta. No "no devuelve nada" — rechaza. La regla distingue mayúsculas y minúsculas tal como la especificación la establece: War AND Peace se detecta, War and Peace pasa. El servidor comprueba antes de enviar y devuelve un diagnóstico RESERVED_WORD_IN_QUERY nombrando el campo infractor, en lugar de dejar que la biblioteca responda con un error de análisis.

NDL impone un límite de velocidad que no cuantificará, y responde con HTTP 429. La página de ayuda solo dice 「同時リクエスト数には制限を設けています」 y se niega a publicar una cifra. En las pruebas del 19 de agosto de 2026, un 429 llegó muy por debajo de una solicitud sostenida por segundo — así que el mínimo de un segundo presentado ante la biblioteca es un mínimo, no una garantía. Un 429 compra una sola espera, respetando Retry-After, y luego el servidor se detiene en lugar de presionar. Informa RATE_LIMITED, deliberadamente distinto de API_ERROR, porque los dos significan cosas diferentes para un lector: una búsqueda limitada por velocidad tiene un resultado desconocido, no uno vacío, y nunca debe escribirse como una ausencia.

Un término romanizado devolverá menos resultados. NDL Search indexa registros en japonés con escritura japonesa. Una consulta en escritura latina contra un corpus japonés es la trampa del romaji, y el sobre eleva SCRIPT_LATIN_QUERY para ello. El titular searched_for existe para que el término que el asistente realmente eligió sea visible en la parte superior de la respuesta en lugar de enterrado — ese es el propósito del campo, y la razón por la que una divulgación puede informar los términos que usó una búsqueda.

Recibos

mediation.emit() escribe cada sobre de respuesta en el libro mayor de solo añadir y encadenado por hash en MCP_RECEIPT_LOG, que install.ps1 establece al mismo archivo que usan los otros servidores. Si no se establece la variable, no se escribe nada y no falla nada.

Observa lo que contiene el libro mayor y lo que no: la consulta, el término normalizado, los parámetros enviados, la marca de tiempo, un SHA-256 sobre la consulta y los parámetros, y los identificadores de los registros devueltos. No contiene los registros bibliográficos en sí. Registrar una consulta no es acumular una base de datos, y el compromiso contra la acumulación no se viola al mantener el recibo — pero la distinción vale la pena declararla en lugar de asumirla, porque los dos se ven similares desde fuera.

Por qué solo SRU

La solicitud declara SRU y OpenSearch. Este servidor implementa solo SRU, que es menos de lo declarado y por lo tanto seguro — siempre puedes usar menos de lo que le dijiste a la biblioteca que usarías.

La razón es probatoria. El formato de respuesta de OpenSearch no está documentado en la especificación 第1.4版: sin tabla de elementos, sin muestra, y los apéndices cubren solo SRU y OAI-PMH. Peor aún, la especificación establece que un parámetro malformado devuelve una respuesta de cero resultados en lugar de un error — 「引数（パラメータ）誤りの場合には検索結果ゼロ件となる」 — así que un error tipográfico en un nombre de campo es indistinguible de una ausencia genuina. Para una herramienta cuyo propósito es permitir que un historiador confíe en que no se encontró nada, eso es descalificante. SRU devuelve diagnósticos tipados y un esquema de registro DC-NDL documentado. Añadir OpenSearch más tarde no necesita una nueva notificación; necesita un formato de respuesta documentado.

Fuentes

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

• APIのご利用について — términos, requisito de crédito, concurrencia, notificación

• API提供対象データプロバイダ一覧 — valores de dpid y condiciones de licencia

Licencia

MIT. Los metadatos recuperados a través de este servidor son CC BY 4.0 de la Biblioteca Nacional de la Dieta; la línea de crédito que emite el servidor es la atribución que esa licencia requiere, y debería sobrevivir en cualquier cosa que publiques a partir de los resultados.

Qué se ha probado y qué no

Verificado contra la API en vivo el 19 de agosto de 2026:

• Búsqueda en escritura japonesa en 蔵書 y 雑誌記事索引 — totales correctos, registros correctos, años e identificadores correctos.

• Análisis de DC-NDL, incluido el filtro de stub de manifestación. NDL devuelve dos elementos BibResource por registro; tomar ambos duplicaba el conjunto de resultados con espacios en blanco hasta que se añadió el filtro.

• searched_for informa el término elegido, no el CQL ensamblado, por lo que su detección de escritura es significativa; el CQL exacto se lleva en query.params y está fijado por el hash del recibo.

• La protección DPID_NOT_PERMITTED: una solicitud que nombre ndl-dl se rechaza en el proceso.

• RESERVED_WORD_IN_QUERY: War AND Peace detectado, War and Peace pasó.

• El limitador de velocidad, involuntariamente — ver HTTP 429 arriba.

No verificado contra la API en vivo, y leído en lugar de ejecutado: el paso directo de "El registro no existe", ndl_get_record y la ruta de espera. Las pruebas se detuvieron en el 429 en lugar de continuar, porque caracterizar un límite de velocidad no divulgado sondeándolo es precisamente el 継続して大量のアクセス que los términos advierten, y el punto de este servidor no es ser la cosa que la Biblioteca Nacional de la Dieta tenga que bloquear. Ejercita esas rutas en uso ordinario, una consulta a la vez.