도서관 책길잡이 MCP (Library Book Guide)

도서관 책길잡이 MCP는 Data4Library(도서관 정보나루) Open API의 실측 데이터를 가공해 "내 위치 주변에 어떤 도서관이 있는지", "읽고 싶은 책을 빌리러 도서관에 가도 되는지", "그 김에 같이 빌릴 다음 책은 무엇인지", "다 읽고 무엇을 읽으면 좋은지"를 MCP 도구로 제공하는 Node.js/TypeScript 서버입니다.

사용자는 도서관 코드를 몰라도 됩니다. 정독도서관, 마포중앙도서관처럼 도서관 이름으로 질문하면 서버가 내부적으로 도서관 코드를 찾아 기존 정보나루 데이터를 조회합니다.

단순 API 래핑이 아니라, 원본 데이터 위에 사용자가 바로 판단할 수 있는 계산 결과를 얹는 것을 목표로 했습니다.

Problem

도서관 데이터는 공개되어 있지만 일반 사용자가 바로 활용하기에는 몇 가지 장벽이 있습니다.

• 인기 도서, 소장 여부, 이용 분석 데이터가 서로 다른 API로 흩어져 있습니다.

• API 응답은 XML 중심이라 LLM 도구 응답으로 그대로 보여주기 어렵습니다.

• 일반 사용자는 정보나루 도서관 코드를 알기 어렵습니다.

• "내 주변에 어떤 도서관이 있나", "이 책을 빌리러 이 도서관에 가도 될까", "간 김에 무엇을 같이 빌릴까" 같은 질문은 원본 조회만으로는 답하기 어렵습니다.

이 프로젝트는 공개 도서관 데이터를 MCP 도구 형태로 연결하고, 결과를 Markdown으로 정리해 대화형 사용 경험에 맞게 제공합니다.

Related MCP server: Traffic MCP Server

Features

Design Highlights

• Data-grounded answers: 추천 도서와 소장 여부는 Data4Library API 응답을 사용하고, 방문 후보는 공식 운영시간을 파싱해 계산합니다.

• Bookstore-augmented recommendations: ALADIN_TTB_KEY가 설정되면 알라딘 OpenAPI의 책 소개, 표지, 베스트셀러 순위를 추천 후보의 보조 신호로만 사용합니다. 분야 태그와 관심사 매칭은 정보나루 도서 정보와 한국십진분류표(KDC)를 기준으로 계산합니다.

• Location-aware discovery: 카카오 Local API 장소명 검색 또는 위도/경도 좌표를 기준으로 주변 도서관을 거리순으로 정렬합니다.

• Reading-visit planning: 단일 책 검색에서 끝내지 않고, 목표 도서와 다음 독서 후보의 같은 도서관 소장 여부를 함께 확인합니다.

• Name-first UX: 도서관 이름을 입력받아 내부적으로 libSrch 검색 결과의 도서관 코드로 변환합니다.

• Stale fallback notice: 정보나루 실시간 호출이 제한되거나 실패해도 같은 서버 프로세스에 마지막 정상 응답이 남아 있으면 이를 사용하고, 응답 하단에 실시간 데이터가 아닌 마지막 정상 응답 기준임을 표시합니다.

• Bounded LRU cache: 신선 데이터 TTL과 stale 보존 기간을 분리하고, 최대 엔트리 수를 넘으면 최근 사용 순서에 따라 제거해 장기 실행 중 메모리 증가를 제한합니다.

• Structured observability: HTTP 요청 ID를 MCP 도구 실행까지 전달하고, 상태·지연시간·출력 크기를 API 키나 사용자 인자 없이 JSON 로그로 남깁니다.

• Upstream resilience: 일시적 네트워크·5xx 오류만 짧게 재시도하고, 공급자별 circuit breaker로 반복 장애를 차단해 정보나루 호출량과 응답 지연을 보호합니다.

• HTTP boundary protection: MCP 경로에 Host/Origin 검증, JSON 콘텐츠 타입, 보안 헤더, 프로세스 단위 요청 제한을 적용합니다.

• MCP-ready transport: Streamable HTTP 기반 MCP 서버로 구현했습니다.

• Stateless startup: 서버는 먼저 포트를 열고, 인증키나 외부 API 상태와 무관하게 tools/list가 동작하도록 구성했습니다.

• XML normalization: XML 파서가 0건, 1건, 다건을 다르게 반환하는 문제를 ensureArray와 빈 값 정규화로 방어합니다.

• Safe output: MCP 응답은 TextContent + Markdown만 반환하고, 20,000자 제한 가드로 과도한 응답을 차단합니다.

• Secret hygiene: API 키는 환경변수로만 주입하며 .env와 .env.*는 Git 추적에서 제외합니다.

자세한 설계 판단은 docs/design-decisions.md에 정리했습니다. 리뷰 지적부터 설계 선택, 장애 재현, 커밋별 검증 근거는 docs/engineering-hardening.md에 정리했습니다.

Architecture

Client / MCP Host
      |
      | POST /mcp
      v
Express + StreamableHTTPServerTransport
      |
      v
MCP tool handlers
      |
      +-- Child recommendation service
      +-- Library visit service
      +-- Library/book resolvers
      |
      v
Data4Library / Kakao Local / Aladin clients
      |
      +-- Bounded LRU + stale cache
      +-- XML/JSON normalization
      +-- Request-scoped fallback metadata

Example Prompts

초등학교 3학년 아이가 과학 좋아하는데 책 추천해줘

대전역 근처에서 초등학교 3학년 과학책 추천해줘. 만화책 말고

내 위치 주변 도서관 찾아줘

마포중앙도서관에 아몬드 빌리러 가도 될까?

정독도서관 한산한 시간 알려줘

마포중앙도서관에 요즘 인기책 있어?

아몬드 읽고 다음 책 추천해줘

Tech Stack

• Node.js 20+

• TypeScript

• Express

• @modelcontextprotocol/sdk

• fast-xml-parser

• Data4Library Open API

• Kakao Local API

• Aladin OpenAPI

Local Run

npm.cmd install
Copy-Item .env.example .env
# Fill DATA4LIBRARY_AUTH_KEY in .env
# Fill KAKAO_REST_API_KEY too if you want place-name search.
# Fill ALADIN_TTB_KEY too if you want bookstore metadata augmentation.
npm.cmd run build
npm.cmd start

Default endpoints:

• GET /health

• GET /ready

• POST /mcp

GET /mcp and DELETE /mcp return 405 because this server is designed for stateless Streamable HTTP.

Environment Variables

The server can start and expose tool metadata without an API key. Tool calls that need live Data4Library data return a clear setup message until DATA4LIBRARY_AUTH_KEY is configured. Place-name search, such as 홍대입구역 근처 도서관, additionally requires KAKAO_REST_API_KEY; coordinate-based nearby search still works without it. Aladin augmentation is optional; without ALADIN_TTB_KEY, child recommendations still use Data4Library age-group loan data.

Validation

npm.cmd run typecheck
npm.cmd test
npm.cmd run build
npm.cmd audit --omit=dev

All commands should pass before deployment. npm.cmd run test:failure runs only injected failure scenarios, while npm.cmd run test:integration runs deterministic upstream contract and HTTP tests without consuming real API quota.

After starting a local server, npm.cmd run test:load sends 40 bounded concurrent tools/list requests by default. Tune it with LOAD_TEST_URL, LOAD_TEST_REQUESTS, LOAD_TEST_CONCURRENCY, and LOAD_TEST_P95_LIMIT_MS.

Security Notes

• Do not commit .env or real API keys.

• .env.example intentionally contains only placeholder values.

• Cache keys exclude the API key to avoid retaining credentials in process memory longer than necessary.

• Tool output never returns raw upstream JSON/XML dumps.

• /mcp validates the configured Host and any supplied Origin before parsing JSON.

• Rate limiting is deliberately process-local; a multi-replica deployment should replace it with a shared gateway or distributed limiter.

• The runtime image executes as the unprivileged Alpine node user.

License

MIT