NLB Singapore Library MCP Server

nlb-mcp

NLB新加坡图书馆目录的非官方FastMCP服务器（可用性+标题搜索），用Python实现。

里面是什么

• 语言：Python 3.11+
• 框架：FastMCP（Python）、httpx（HTTP）、pydantic设置（env）、韧性（重试）
• 工具（MCP）：

- health_check –验证env+启动准备就绪。 - search_titles –关键字搜索BRN/ISBN/标题/作者/主题。 - search_titles_advanced –使用分页/排序进行字段搜索。 - availability_by_title –标题/ISBN/BID的分支级别可用性。

项目布局

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

设置

1. 创建一个virtualenv并安装deps：

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

1. 环境：

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

1. 在本地运行：

fastmcp run nlb_mcp/server.py:create_server

FastMCP云入口点

• 首选： nlb_mcp/server.py:create_server
• 直接对象导出： nlb_mcp/server.py:server （别名 mcp, app)

FastMCP Cloud可以指向 nlb_mcp/server.py:create_server；它将为用户处理OAuth2。此服务器仅使用NLB X-Api-Key/X-App-Code 从env。

身份验证模型

• 客户端/用户身份验证由FastMCP内置的OAuth2提供程序处理；此服务器确实 不 添加另一层用户身份验证。
• NLB API身份验证仅使用环境提供的密钥；永远不要从用户输入中接受它们或记录它们。
• 对于每用户配额/审核，请在可用时依赖FastMCP身份上下文。

笔记 / 全部

• 如果你想要更严格的模式，可以考虑工具输入/输出的pydantic模型。
• 如果上游限制很紧，则添加缓存/速率限制；httpx+韧性已重试瞬态错误。
• 日志记录使用stdlib logging （记录器名称 nlb_mcp)秘密编辑；根据需要扩展度量或结构化日志。