hyread-mcp

直接在你的 AI Agent 裡查詢台灣公共圖書館 HyRead 電子書館藏 — 一次呼叫搜尋全台 41 間公共圖書館。

為什麼有這個專案

HyRead（凌網）是台灣公共圖書館電子書平台的事實標準，但沒有公開 API，且所有端點都在 Cloudflare Turnstile 後面。這個專案把網站包成一個正式的 MCP server — 任何支援 MCP 的 agent（Hermes、Claude、Cursor...）都能原生查詢館藏。

Related MCP server: mcp-tw-lvr

功能

架構

Agent（Hermes 或任何 MCP client）
        │  stdio (JSON-RPC)
        ▼
server.py (FastMCP)
        │  Camoufox headless（持久 profile）
        │  JS 注入 30 館 libid → searchFormSubmit()
        ▼
HyRead（one.ebook.hyread.com.tw + 41 個 *.ebook.hyread.com.tw）
        ▲
        └── Cloudflare Turnstile → Camoufox 指紋通過

關鍵機制：網站把「已選查詢館」只存在頁面狀態（伺服器端不持久化），且伺服器拒絕超過 30 間（searchLib invalid）。因此 hyread_search 每次提交前先重建 29 個優先公共館 + HyRead 電子書店的 DOM 清單，再讀結果頁。

快速開始

前置需求

• macOS（Apple Silicon 或 Intel）

• Hermes Agent（或其他 MCP client）

• uv（或 Python 3.12 + venv）

安裝

git clone https://github.com/lunkerchen/hyread-mcp.git
cd hyread-mcp
./install.sh

腳本會（自動偵測 arm64 / x86_64）：建 venv → 安裝依賴 → 下載 Camoufox 瀏覽器（約 300MB）→ 註冊 hyread MCP server 到 Hermes。

重啟 Hermes session，然後直接說：

查《原子習慣》HyRead 哪幾間圖書館有

手動註冊（其他 MCP client）

{
  "mcpServers": {
    "hyread": {
      "command": "/path/to/hyread-mcp/.venv/bin/python",
      "args": ["/path/to/hyread-mcp/server.py"],
      "timeout": 900
    }
  }
}

使用範例

以 Hermes Agent 為例（其他 agent 語法類似）：

實測輸出範例（hyread_search_all_libraries("AI 2041")）：

have: 4
HAVE: 臺中市立圖書館 -> ['AI 2041:預見10個未來新世界']
HAVE: 桃園市立圖書館 -> ['AI 2041:預見10個未來新世界']
HAVE: 苗栗縣立圖書館 -> ['AI 2041:預見10個未來新世界']
HAVE: 臺北市立圖書館 -> ['AI 2041:預見10個未來新世界']

工具

疑難排解

專案結構

hyread-mcp/
├── server.py          # MCP server（FastMCP + Camoufox）
├── libids.json        # 41 館名稱 → libid 對照（從官方 modal dump）
├── install.sh         # 一鍵安裝（venv + Camoufox + MCP 註冊，自動偵測架構）
├── requirements.txt
├── README.md          # 本檔（繁體中文）
└── README.en.md       # English

注意事項與使用倫理

• 伺服器上限：HyRead 每次查詢最多 30 館；其餘 11 間鄉鎮圖書館只能透過 hyread_search_all_libraries 查。

• 選館是 session 級：腳本每次搜尋前重新注入 30 館清單。

• 借閱/預約仍需要在各館網站用借書證登入（MCP 暴露館藏，不碰帳號）。

• 請合理使用：本工具僅供個人查詢館藏。請勿用於大量抓取、批次掃描全館藏、或任何可能影響 HyRead 服務的行為；HyRead 平台有 Cloudflare 保護自有其理由，保持低頻、禮貌的使用頻率。

• Camoufox 瀏覽器快取在 ~/Library/Caches/camoufox。

致謝

• Camoufox — 反偵測 Firefox

• Michelle37101/Library-Hyread-Ebook-Searching — 圖書館子網域清單與技術參考

• HyRead（凌網知識）— 被查詢的平台

License

MIT — 見 LICENSE。