README.md•2.31 kB
# 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.