ndl-mcp

일본 국립국회도서관이 운영하는 国立国会図書館サーチ(NDL Search)를 SRU searchRetrieve 인터페이스로 검색하기 위한 MCP 서버입니다.

cinii-mcp 및 jstage-mcp에 이은 세 번째 시리즈로, 이들과 응답 형식을 공유합니다: 타입이 지정된 쿼리와 스크립트, 일치 모드, 점진적 범위, 항목별 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에 제출된 것입니다. 단순한 목표가 아니라 구현된 사항이며, 설치 프로그램의 스모크 테스트는 처음 세 가지를 검증합니다:

이 중 하나라도 변경하면 국가 도서관에 신고한 내용을 변경하는 것입니다. 먼저 추가 신고를 제출하세요.

제공자(Providers)

신청서에 명시된 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는 조회(fetch)이므로 응답에 searched_for가 포함되지 않습니다 — 선택된 검색어가 없기 때문입니다.

주의해야 할 두 가지

검색어 안의 대문자 AND, OR 또는 NOT은 NDL이 전체 쿼리를 거부하게 만듭니다. "결과 없음"이 아니라 거부입니다. 이 규칙은 사양에 명시된 대로 대소문자를 구분합니다: War AND Peace는 걸리고, War and Peace는 통과합니다. 서버는 전송 전에 확인하여, 도서관이 구문 분석 실패로 응답하게 두는 대신 해당 필드를 지목하는 RESERVED_WORD_IN_QUERY 진단을 반환합니다.

NDL은 수치를 공개하지 않는 속도 제한을 적용하며, HTTP 429로 응답합니다. 도움말 페이지는 「同時リクエスト数には制限を設けています」라고만 말하고 수치 공개를 거부합니다. 2026년 8월 19일 테스트에서 초당 1회 미만의 지속 요청에서도 429가 도착했습니다 — 따라서 도서관에 제출한 1초 최소 간격은 보장이 아니라 최소 기준입니다. 429가 오면 Retry-After를 존중하여 한 번 백오프하고, 그 후에는 계속 시도하지 않고 서버가 멈춥니다. API_ERROR와 의도적으로 구분되는 RATE_LIMITED를 보고하는데, 이는 독자에게 서로 다른 의미를 갖기 때문입니다: 속도 제한에 걸린 검색은 알 수 없는 결과를 가지며, 빈 결과가 아닙니다. 결코 부재로 기록되어서는 안 됩니다.

로마자 표기 검색어는 결과가 부족합니다. 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만 다룹니다. 더 나쁜 것은, 사양이 잘못된 매개변수는 오류가 아닌 결과 0건 응답을 반환한다고 명시한다는 점입니다 — 「引数（パラメータ）誤りの場合には検索結果ゼロ件となる」 — 따라서 필드 이름의 오타는 진정한 부재와 구별할 수 없습니다. 역사가가 아무것도 발견되지 않았다고 신뢰할 수 있게 하는 것이 목적인 도구에게 이것은 실격입니다. SRU는 타입이 지정된 진단과 문서화된 DC-NDL 레코드 스키마를 반환합니다. 나중에 OpenSearch를 추가하는 것은 새로운 신고가 필요하지 않습니다; 문서화된 응답 형식이 필요할 뿐입니다.

출처

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

• APIのご利用について — 이용 약관, 출처 표시 요건, 동시성, 통지

• API提供対象データプロバイダ一覧 — dpid 값 및 라이선스 조건

라이선스

MIT. 이 서버를 통해 검색된 메타데이터는 국립국회도서관의 CC BY 4.0입니다; 서버가 출력하는 출처 표시는 해당 라이선스가 요구하는 귀속 표시이며, 결과에서 게시하는 모든 것에 유지되어야 합니다.

테스트된 것과 테스트되지 않은 것

2026년 8월 19일 라이브 API에 대해 검증됨:

• 蔵書 및 雑誌記事索引에 대한 일본어 문자 검색 — 정확한 총계, 정확한 레코드, 정확한 연도와 식별자.

• 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에서 계속하지 않고 중단되었습니다, 공개되지 않은 속도 제한을 프로빙하여 특성화하는 것이 정확히 약관이 경고하는 継続して大量のアクセス이며, 이 서버의 목적은 국립국회도서관이 차단해야 하는 대상이 되는 것이 아니기 때문입니다. 일상적인 사용에서 한 번에 하나의 쿼리로 해당 경로를 실행하세요.