nikhil-grayscale/nlb-mcp

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

1. Create a virtualenv and install deps:

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

2. 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

3. 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.