nlb-mcp

Unofficial FastMCP server for NLB Singapore Library Catalogue (availability + title search), implemented in Python.

What’s inside

Language: Python 3.11+
Framework: FastMCP (Python), httpx (HTTP), pydantic-settings (env), tenacity (retry)
Tools (MCP):
- health_check – validate env + startup readiness.
- search_titles – keyword search over BRN/ISBN/Title/Author/Subject.
- search_titles_advanced – fielded search with pagination/sorting.
- availability_by_title – branch-level availability for a title/ISBN/BID.

Project layout

nlb_mcp/ config.py # env validation (API keys, base URL, timeout) http_client.py # httpx helper with retry/timeout nlb_client.py # thin NLB REST client wrappers models.py # lightweight normalized response shapes server.py # FastMCP server + tool registration (with basic logging) help/ nlb-swagger.json # upstream API spec for reference

Setup

Create a virtualenv and install deps:

python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

Environment:

NLB_API_KEY=your_api_key NLB_APP_CODE=your_app_code # optional NLB_API_BASE=https://openweb.nlb.gov.sg/api/v2/Catalogue REQUEST_TIMEOUT_MS=10000

Run locally:

fastmcp run nlb_mcp/server.py:create_server

FastMCP Cloud entrypoint

Preferred: nlb_mcp/server.py:create_server
Direct object exports: nlb_mcp/server.py:server (aliases mcp, app) FastMCP Cloud can point at nlb_mcp/server.py:create_server; it will handle OAuth2 for users. This server only uses NLB X-Api-Key/X-App-Code from env.

Auth model

Client/user auth is handled by FastMCP’s built-in OAuth2 provider; this server does not add another layer of user auth.
NLB API authentication uses env-provided keys only; never accept them from user input or log them.
For per-user quotas/auditing, rely on FastMCP identity context when available.

Notes / TODO

If you want stricter schemas, consider pydantic models for tool inputs/outputs.
Add caching/rate limits if upstream limits are tight; httpx + tenacity already retry transient errors.
Logging uses stdlib logging (logger name nlb_mcp) with secret redaction; extend as needed for metrics or structured logs.