# hyread-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![English](https://img.shields.io/badge/README-English-green.svg)](README.en.md)
[![AI Agent](https://img.shields.io/badge/AI-MCP%20Ready-blue)](https://github.com/lunkerchen/hyread-mcp)
[![Platform](https://img.shields.io/badge/Platform-macOS-lightgrey.svg)](https://github.com/lunkerchen/hyread-mcp)

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

## 為什麼有這個專案

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

## 功能

| 功能 | 說明 |
|------|------|
| 🏛️ **30 館一次查詢** | `hyread_search` 對 HyRead One 注入 29 公共圖書館 + 電子書店（伺服器上限 30），約 20 秒 |
| 🔭 **全台 41 館掃描** | `hyread_search_all_libraries` 串行拜訪每個圖書館子網域（避免限流），約 6-8 分鐘 |
| 📖 **書籍詳情** | `hyread_book_detail` 回傳各館可借狀態（可借閱/借出） |
| 🛡️ **Cloudflare 免疫** | 使用 [Camoufox](https://github.com/daijro/camoufox)（反偵測 Firefox）— headless、免權限、無視窗 |
| 🪶 **零基礎設施** | 本地 stdio 執行；無伺服器、無 API key、零成本 |

## 架構

```
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](https://hermes-agent.nousresearch.com)（或其他 MCP client）
- [uv](https://docs.astral.sh/uv/)（或 Python 3.12 + venv）

### 安裝

```bash
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）

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

## 使用範例

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

| 你問 | 背後呼叫 | 回傳 |
|------|---------|------|
| 「查《AI 2041》全台哪幾間圖書館有」 | `hyread_search("AI 2041")` | 書單（含館藏連結），~20 秒 |
| 「查《原子習慣》所有 41 館完整分布」 | `hyread_search_all_libraries("原子習慣")` | 逐館命中/未命中清單，~6-8 分鐘 |
| 「這本書台北市立圖書館可借嗎」 | `hyread_book_detail(<館內連結>)` | 可借閱/借出狀態 |

實測輸出範例（`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_search(keyword, max_results=20)` | 30 館一次查詢（29 公共 + 電子書店） | ~20 秒 |
| `hyread_search_all_libraries(keyword, max_results=3)` | 全台 41 館串行掃描 | ~6-8 分鐘 |
| `hyread_book_detail(url)` | 書目資料 + 各館可借狀態 | ~5 秒 |
| `hyread_session_status()` | Cloudflare 放行狀態檢查 | ~3 秒 |

## 疑難排解

| 症狀 | 原因 | 解法 |
|------|------|------|
| 結果 `cf_blocked: true` | Cloudflare 對該 IP 給了互動式驗證 | 稍等 5-10 分鐘再試（Camoufox 通常自動過）；持續發生表示 IP 被標記，換網路或等冷卻 |
| `hyread_search` 回 0 筆 | 30 館中真的沒有，或伺服器暫時拒絕 | 改跑 `hyread_search_all_libraries` 確認 |
| 全台掃描有 `error: ... Timeout` | 單館主機慢/離線 | 重試該館（錯誤訊息含館名） |
| `ModuleNotFoundError` | 用了系統 python 而非 venv | 確認 MCP config 的 command 指向 `.venv/bin/python` |
| 搜尋很慢 | Camoufox 首次啟動 + 30 館查詢本身要時間 | 首次約 30 秒，之後 profile 熱了會快一些 |

## 專案結構

```
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](https://github.com/daijro/camoufox) — 反偵測 Firefox
- [Michelle37101/Library-Hyread-Ebook-Searching](https://github.com/Michelle37101/Library-Hyread-Ebook-Searching) — 圖書館子網域清單與技術參考
- HyRead（凌網知識）— 被查詢的平台

## License

MIT — 見 [LICENSE](LICENSE)。