# huiwen-mcp

> 汇文图书管理系统（Libsys / OPAC）的 **Model Context Protocol (MCP) 服务器** ——
> 面向 AI 的**图书馆只读数据网关**：让 Claude / Cherry Studio / DeepSeek 等 AI 客户端
> 安全、可审计地检索馆藏书目、复本在馆、流通统计与联盟联合目录。
>
> 由高校图书馆方开发的官方适配层，遵守**默认只读、最小权限、全链路审计**的安全基线。

- **协议**：[Model Context Protocol](https://modelcontextprotocol.io/)（Anthropic 开放标准，与 Yale Library 的目录接入同技术路线）
- **运行时**：Python ≥ 3.10 · FastMCP 3.x
- **数据源**：`demo`（零依赖演示）/ `opac`（汇文 OPAC 公开网页协议）/ `oracle`（汇文 Libsys 数据库只读直连）
- **开源协议**：Apache-2.0（推荐方案，见[协议与合规](#协议与合规-open-source--compliance)）

---

## 目录

1. [功能特性](#功能特性)
2. [系统设计思路](#系统设计思路)
3. [实现技术方案](#实现技术方案)
4. [快速开始](#快速开始)
5. [配置（环境变量 / .env）](#配置环境变量--env)
6. [工具清单](#工具清单)
7. [客户端接入示例](#客户端接入示例)
8. [使用场景](#使用场景)
9. [安全与合规](#安全与合规)
10. [测试](#测试)
11. [项目结构](#项目结构)
12. [Roadmap](#roadmap)
13. [协议与合规](#协议与合规-open-source--compliance)
14. [故障排查](#故障排查)

---

## 功能特性

| 能力 | 说明 |
|---|---|
| 🔍 馆藏检索 | 多字段 / 中图法 / 馆藏地 / 在馆过滤 / 排序 / 分页 |
| 📚 书目详情 | 单册完整书目、全部馆藏复本状态与流通统计 |
| ✅ 复本在馆 | 按 ISBN / 条码 / 题名快查可借状态 |
| 🔥 热门&新书 | 热门借阅排行、近 N 天新书通报 |
| 🧭 分类浏览 | 中图法分类/前缀实时命中数 |
| 📊 统计 | 馆藏总数 / 按馆藏地 / 按分类 |
| 🤝 联盟联合目录 | **PROCAT** 跨馆联合检索（可选，默认关闭，JWT 鉴权） |
| 👤 读者数据（admin） | 在借 / 借阅历史 / 欠款（PII 默认脱敏） |
| 🛡️ 安全 | 认证→限流→PII/读者门控→JSONL 审计；默认只读 |
| 🔌 传输 | stdio（进程内） / Streamable HTTP（服务化） |
| 🐳 部署 | Docker 镜像（非 root、可重复构建）；生产/网关级认证方案见 `docs/部署指南.md` |
| 🧩 数据源可插拔 | `demo` / `opac` / `oracle` 一键切换，同签名工具 |

**设计取舍**：写操作（续借、预约、馆际互借下单）**刻意未实现**——本项目只做
“安全可审计地读”，写路径一律交给原业务系统与人工流程。

---

## 系统设计思路

### 定位：数据网关 / 技能层，而非数据库代理

AI 客户端（大模型）**绝不直连汇文数据库**。所有查询经由一层受控工具封装：

```
┌─────────────── AI 客户端（Claude / Cherry Studio / 自研 Agent / 本地 LLM） ───────────────┐
│                                      │                                                    │
│             stdio（子进程协议）        │        Streamable HTTP（服务化 / 网关 / SSO）        │
└──────────────────────────────────────┼────────────────────────────────────────────────────┘
                                       ▼
┌───────────────────────────────────────────────────────────────────────────────────────┐
│   huiwen-mcp（FastMCP 3.x）                                                            │
│   ┌─────────────── 安全链 _guard ───────────────┐                                        │
│   │ 认证(Auth) → 限流(TokenBucket) → 门控(PII/读者) │   ← 每个工具必经                     │
│   └──────────────────────────────────────────────┘                                        │
│   │ 工具层：search_books / get_book_detail / union_search / get_reader_* / … (12 个)     │
│   └──────────────────────────────────┬───────────────────────────────────────────────────┘
                                       ▼
┌───────────────────────────────────────────────────────────────────────────────────────┐
│   适配器（可插拔数据源，统一 CatalogBackend 接口）                                       │
│   ├─ OracleBackend：白名单参数化 SQL（db/queries.py 封闭集）   → 汇文 Libsys 只读账号    │
│   ├─ OpacBackend：白名单参数调汇文 OPAC 公开网页协议           → opac 站点                │
│   └─ DemoBackend：内置样例数据                                 → 离线演示/测试            │
└───────────────────────────────────────────────────────────────────────────────────────┘
```

- **每层职责单一**：适配器只负责取数；`_guard` 只负责安全；审计独立落盘 JSONL；
  上层 AI 只与工具签名交互，不感知后端差异（三后端同签名）。
- **默认安全**：`data_source=demo` 零依赖即可跑通；`opac/oracle` 需要显式配置；
  读者敏感工具需要 admin 令牌；
  写操作默认禁用；外部联盟服务默认关闭。

### 为什么选 MCP

- MCP 是 AI 连接“数据库/业务系统”的开放标准（Anthropic 2024-11 发布，生态包括
  GitHub/云厂商/数据库厂商）。**选择开放标准而非私有 API**，保证：客户端可替换
  （Claude/Cherry Studio/DeepSeek/自研 Agent）、服务可被多系统复用、长期不被厂商
  锁定——这也是 Yale Library 用 MCP 接入目录的同一路线。
- FastMCP 为服务端实现提供 stdio / HTTP 双传输，一个代码库同时支持进程内与
  服务化部署。

### 传输模式的选择：stdio vs HTTP

- **stdio**：进程内随客户端拉起，零运维、延迟最低，适合个人/单机接入 AI 桌面客户端。
- **HTTP（Streamable HTTP）**：独立服务，适合多用户/中心化部署；可在前面挂
  OAuth2/JWT 反向代理与校园统一身份，做中心审计。

---

## 实现技术方案

| 关注点 | 方案 |
|---|---|
| MCP 服务端 | `fastmcp>=2,<4`；`add_tool` 注册；`stdio`/`http` 双 `run()` |
| 工具签名硬约束 | FastMCP 3.x **拒绝带 `*args/**kwargs` 的工具函数** → 工具一律显式类型化参数；`_guard` 用 `functools.wraps` 包装并透传 kwargs（显式令牌模型，避免 `**kwargs` 触发框架拒绝） |
| 鉴权链路 | `AuthConfig`（Bearer）+ `RateLimit`（令牌桶）+ 读者层/PII 门控（admin 令牌）+ `AuditLogger`（JSONL） |
| Oracle 后端 | `python-oracledb`；**11g → thick 模式**（Instant Client），12c+ → thin；SQL 全部封闭在 `db/queries.py`（参数化、白名单、只读账号） |
| OPAC 后端 | 白名单参数构造汇文公开网页协议（`openlink.php` 检索 / `item.php` 详情 / `top_lend.php` 热门），解析公开 HTML 模板（选择器与厂商模板逐项核对） |
| 联盟联合目录 | `POST {base}/api/search/listByQuery` + `{current,pageSize,items:[{field,value,logic,type}]}` + `?tenantCode&tk=<JWT>`（契约经真站实测）；默认关闭 |
| 配置 | `HUIWEN_` 环境变量（.env 自动加载）+ `config.local.json`（敏感值，git-ignored，自动合并） |
| 模型 | `pydantic` 显式结果模型，类型安全、序列化稳定 |

### 关键契约（都已实测确认）

- **OPAC**：检索结果 `<ol id="search_book_list">` → `<li class="book_list_info">`，
  题名/索书号/馆藏复本/可借复本/命中数；详情页复本表；热门榜。
- **联盟 PROCAT**：`POST`（GET→405）；鉴权用查询参数 `tk=`（JWT 由 OPAC 读者会话
  `getReaderJwt` 签发）；`items[].logic`=`"1"`(AND)/`"2"`(OR)；字段映射
  `any/title/author/subject/isbn/clcNumber/publisher/series`。详见
  `docs/联盟联合目录检索.md`。

> ⚠️ OPAC / 联盟均为厂商闭源或第三方系统，契约可能随部署版本变化。所有对接
> 文档以“真站实测”为准，并用 `tests/test_*_live.py` 记录验证。

---

## 快速开始

### 1) 安装

```bash
git clone <your-repo-url> && cd huiwen-mcp
# 方式 A：uv（推荐）
uv sync
# 方式 B：pip
python -m venv .venv
. .venv/bin/activate
pip install -e .
```

### 2) 零配置跑通（demo 数据源，离线）

```bash
HUIWEN_DATA_SOURCE=demo uv run huiwen-mcp        # stdio 模式
HUIWEN_DATA_SOURCE=demo HUIWEN_TRANSPORT=http uv run huiwen-mcp   # HTTP 模式
```

demo 内置样例书目/读者数据，可用于冒烟、测试与接入教学。

### 2b) Docker 一键部署

```bash
docker build -t huiwen-mcp:latest .
docker run --rm -it -e HUIWEN_DATA_SOURCE=demo huiwen-mcp:latest   # stdio，离线可跑

# 服务化（HTTP + 认证 + 审计）
docker run -d --name huiwen -p 8765:8765 \
  -e HUIWEN_TRANSPORT=http -e HUIWEN_DATA_SOURCE=opac \
  -e HUIWEN_OPAC_BASE_URL=https://opac.example.edu.cn \
  -e HUIWEN_AUTH_ENABLED=true -e HUIWEN_AUTH_BEARER_TOKEN=<强随机> \
  -v huiwen-audit:/var/log/huiwen huiwen-mcp:latest
```

更多（Oracle 11g thick / compose / 反向代理级认证对接校园 CAS）见 **[docs/部署指南.md](docs/部署指南.md)**。

### 3) 接入真实数据源（opac / oracle）

复制 `.env.example` 为 `.env` 并填写（.env 已被 git-ignore）：

```bash
cp .env.example .env
# 编辑 .env：设置 HUIWEN_DATA_SOURCE 与对应凭据
HUIWEN_DATA_SOURCE=opac
HUIWEN_OPAC_BASE_URL=https://opac.example.edu.cn      # 你们学校 OPAC 地址
```

或使用 `config.local.json`（敏感配置自动加载、不入库）。

---

## 配置（环境变量 / .env）

所有配置均可用环境变量（前缀 `HUIWEN_`）注入，也支持 `.env` 文件（自动加载）。
优先级：**环境变量 > 显式 config.json / CONFIG_PATH > config.local.json 自动合并 > 内置默认**。

### 通用

| 变量 | 说明 | 默认 |
|---|---|---|
| `HUIWEN_DATA_SOURCE` | `demo` / `opac` / `oracle` | `demo` |
| `HUIWEN_TRANSPORT` | `stdio` / `http` | `stdio` |
| `HUIWEN_HOST` / `HUIWEN_PORT` | HTTP 监听 | `127.0.0.1` / `8765` |
| `HUIWEN_INCLUDE_PII` | 是否输出读者敏感字段（需 admin） | `false` |
| `HUIWEN_AUDIT_LOG` | JSONL 审计日志路径（留空关闭） | 空 |
| `HUIWEN_CONFIG_LOCAL_PATH` | 本地敏感配置文件名 | `config.local.json` |

### OPAC

| 变量 | 说明 |
|---|---|
| `HUIWEN_OPAC_BASE_URL` | 汇文 OPAC 根地址 |
| `HUIWEN_OPAC_TIMEOUT` | 检索超时（回收站 15-40s 慢，给足） | 25s |
| `HUIWEN_OPAC_ALLOW_READER_SESSION` | 是否允许读者登录后个人数据（默认关） |
| `HUIWEN_OPAC_UNION_ENABLED` | 联盟联合目录开关（默认关） |
| `HUIWEN_OPAC_UNION_BASE_URL` | 联盟服务地址 |
| `HUIWEN_OPAC_UNION_TENANT` | 租户代码 |
| `HUIWEN_OPAC_UNION_TOKEN` | 读者会话 JWT（`getReaderJwt` 整串） |

### Oracle

| 变量 | 说明 |
|---|---|
| `HUIWEN_ORACLE_DSN` | `host:port/service` 或 Easy Connect |
| `HUIWEN_ORACLE_USER` / `_PASSWORD` | 只读账号（强烈建议） |
| `HUIWEN_ORACLE_MODE` | `thin`（12c+） / `thick`（11g/10g 需 Instant Client） |
| `HUIWEN_ORACLE_CLIENT_LIB_DIR` | thick 模式的 Instant Client 目录 |
| `HUIWEN_ORACLE_READ_ONLY` | 语义上约束只读（默认 true） |
| `HUIWEN_ORACLE_POOL_MIN/MAX` | 连接池大小 |

### 安全

| 变量 | 说明 |
|---|---|
| `HUIWEN_AUTH_ENABLED` | 是否启用 Bearer 认证（生产必开） |
| `HUIWEN_AUTH_BEARER_TOKEN` | 静态 Bearer Token |
| `HUIWEN_AUTH_ADMIN_TOKENS` | 逗号分隔的 admin 令牌（读者/写类导出工具） |
| `HUIWEN_RATE_LIMIT_ENABLED` / `_RPS` / `_BURST` | 令牌桶限流 |

---

## 工具清单

| 工具 | 说明 | 需要令牌 |
|---|---|---|
| `search_books` | 馆藏书目检索（字段/中图法/馆藏地/在馆过滤/排序/分页） | — |
| `get_book_detail` | 单册书目完整信息（含全部馆藏复本与流通统计） | — |
| `get_availability` | 按 ISBN/条码/题名查复本在馆可借状态 | — |
| `get_hot_books` | 热门借阅排行（可按中图类目过滤） | — |
| `get_new_arrivals` | 近 N 天新书通报 | — |
| `browse_classification` | 中图法分类浏览/前缀实时命中数 | — |
| `union_search` | 跨馆联盟联合目录只读检索（默认关闭） | 配置 |
| `get_statistics` | 馆藏统计（总数/按馆藏地/按分类） | — |
| `get_reader_borrowing` | 读者当前在借 | admin |
| `get_reader_history` | 读者借阅历史 | admin |
| `get_reader_fines` | 读者欠款 | admin |
| `get_system_status` | 数据源与服务状态 | — |

> 汇文 ACS / SIP2 接口服务的功能说明与对接评估见 [docs/汇文ACS-SIP2接口说明与对接评估.md](docs/汇文ACS-SIP2接口说明与对接评估.md)（权威字段映射、只读子集候选、明确禁用项）。

读者工具默认脱敏（`include_pii=false` 时不返回证件号/联系方式等；`true` 需 admin）。

---

## 客户端接入示例

### Claude Desktop / 支持 MCP 的桌面客户端

```jsonc
{
  "mcpServers": {
    "huiwen": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/huiwen-mcp", "run", "huiwen-mcp"],
      "env": { "HUIWEN_DATA_SOURCE": "demo" }
    }
  }
}
```

### 远程 HTTP（需自行在网关挂认证）

```
HUIWEN_TRANSPORT=http HUIWEN_HOST=0.0.0.0 HUIWEN_PORT=8765 uv run huiwen-mcp
```

客户端用 `${MCP_SERVER_URL}` 接入 `http://<host>:8765/mcp/`（Streamable HTTP）。
启用 `HUIWEN_AUTH_ENABLED=true` 时，令牌以**工具参数 `token`** 随调用传入；
HTTP `Authorization` 头不会被服务端消费（见部署指南 §3.2）。

---

## 使用场景

| 对象 | 场景 |
|---|---|
| 读者 | “有没有《三体》、在哪层、几本可借、附近热门” —— 找书/备考/研学一条龙 |
| 参考咨询馆员 | 自动查馆藏/复本 → 生成答复草稿 → 人工核对（Copilot 模式） |
| 学科馆员 | 学科书目、文献支撑统计、院系荐购报告 |
| 采访/编目 | ISBN 查重、缺藏分析、新书通报、元数据校验 |
| 馆领导 | 馆藏/流通统计图表、数据周报 |
| AI 馆员门户 | 作为智能问答/智能荐书的内核数据层 |
| 联盟共建 | 跨馆联合检索（缺藏→联盟找书→走正式馆际互借） |

完整建议（含**本地部署 LLM + RAG** 的分层方案与国内外对标）见
[`docs/服务与应用建议.md`](docs/服务与应用建议.md)。

---

## 安全与合规

1. **默认只读**：全部工具只读；写操作（续借/预约/馆际下单）刻意未实现。
2. **白名单 SQL**：Oracle 后端仅执行 `db/queries.py` 内参数化 SQL 封闭集，
   无自由 SQL。
3. **全链路门控**：认证 → 限流 → 读者/PII 门控 → 审计（JSONL）。读者个人数据
   需 admin 令牌并默认脱敏。
4. **认证契约（实测确认）**：令牌经**工具参数 `token`** 传入（每个工具
   可选参数，`_guard` 从参数中取出并与 `HUIWEN_AUTH_BEARER_TOKEN` 比对），
   未实现 HTTP `Authorization` 头的透传——传输层 TLS/统一身份由反向代理网关
   负责，huiwen-mcp 自身认证是网关背后的第二道防线。令牌不写入审计日志
   （`_guard` 先 pop 再记录）。
5. **密钥不入库**：DSN/口令/JWT/站点地址只经环境变量或 `config.local.json`
   （git-ignored）。仓库不含任何真实部署数据（见 [NOTICE](NOTICE)）。
6. **外部服务慎重**：联盟 PROCAT 为第三方多租户系统，默认关闭；启用前与
   联盟/服务方确认授权。OPAC 闭源，历史存在公开漏洞，适配器仅用白名单参数。
7. 漏洞报告与处理见 [SECURITY.md](SECURITY.md)。

---

## 测试

| 文件 | 内容 | 运行 |
|---|---|---|
| `tests/smoke_demo.py` | demo 后端冒烟（离线） | `uv run python tests/smoke_demo.py` |
| `tests/test_stdio.py` | stdio 集成/鉴权回归（demo） | `uv run python tests/test_stdio.py` |
| `tests/test_oracle_live.py` | 真库集成（**默认关闭**） | `HUIWEN_LIVE_ORACLE=1 ...` |
| `tests/test_union_live.py` | 联盟 PROCAT 真站（**默认关闭**） | `HUIWEN_LIVE_UNION=1 ...` |

真库/真站测试默认关闭（需本地显式设置 `HUIWEN_LIVE_*` 才执行），避免触达任何真实系统。
**Docker 镜像默认不构建/发布**（发布策略为“只发布源码与文档”）：需要镜像时请本地自行
`docker build`（Oracle thick 模式加 `--build-arg WITH_INSTANT_CLIENT=true`）。

---

## 项目结构

```
huiwen-mcp/
├── src/huiwen_mcp/
│   ├── server.py            # FastMCP 装配、stdio/http 启动、main()
│   ├── config.py            # 配置：env/.env/config.local.json 分层合并
│   ├── audit.py             # JSONL 审计
│   ├── adapters/
│   │   ├── base.py          # CatalogBackend 抽象
│   │   ├── demo.py          # 内置演示数据
│   │   ├── opac.py          # 汇文 OPAC 网页协议（含 union_search）
│   │   └── oracle.py        # Libsys 数据库只读（thin/thick）
│   ├── db/queries.py        # 白名单参数化 SQL（Oracle 后端唯一 SQL 来源）
│   ├── models/schemas.py    # pydantic 结果模型
│   └── tools/catalog.py     # 12 个 MCP 工具 + _guard 安全链
├── docs/                    # 表结构 / 联盟契约 / 服务与应用建议 / 部署指南 / SIP2 评估
├── tests/                   # demo/stdio/oracle-live/union-live
├── Dockerfile / compose.yaml / .dockerignore
├── .env.example / config.example.json / config.local.json(忽略)
├── LICENSE / NOTICE / SECURITY.md / CONTRIBUTING.md / CODE_OF_CONDUCT.md
└── pyproject.toml
```

---

## Roadmap

- [x] Phase 1：只读检索 MCP（demo + opac + oracle 三后端）
- [x] Phase 2：OPAC / Oracle 真库联调、联盟联合目录联调（契约实测 + token 方案）
- [x] Phase 2 余项：Docker 镜像（非 root、可重复构建）+ 部署指南（含反向代理级认证模板）
- [x] 已发布：`v1.0.0` tag + GitHub Release（源码与文档；不设 CI/工作流，Docker 镜像不自动构建）
- [ ] OAuth2/JWT 网关落地对接校园 CAS / 一网通办（模板已就绪，需现场配置）
- [ ] Phase 2.5/3 候选：汇文 ACS/SIP2 只读子集（评估见 docs/汇文ACS-SIP2接口说明与对接评估.md）
- [ ] Phase 3：RAG 向量库 + 本地 LLM 智能荐书 / 参考咨询（见 docs/服务与应用建议.md）
- [ ] Phase 4：汇文新一代平台 OpenAPI 对接

---

## 协议与合规（Open Source & Compliance）

### 开源协议版本建议

本项目推荐采用 **Apache License 2.0**（仓库已附完整 [LICENSE](LICENSE)）：

1. **宽松（permissive）**：允许高校、厂商、云平台自由使用/修改/再发布（含商业
   使用），只需保留版权与许可声明——利于被 AI 工具链与第三方系统采纳。
2. **专利授权**：Apache-2.0 明确授予贡献者专利使用许可（第 3 条），多机构/多方
   （多所高校联合、技术厂商）共同贡献时更清晰、更“抗告”。
3. **贡献者条款规范**：隐式授予项目许可（第 5 条 Contribution Grant），免去每个
   贡献者单独签 CLA 的负担，符合 GitHub 公开项目惯例。
4. **区分度**：相比 MIT，Apache-2.0 更适用于以机构身份正式发布的、可能被多方
   长期维护的基础设施型项目。

> 若贵馆更偏好“极简风格”，可随时退回 MIT：仅需替换 `LICENSE` 全文、将
> `pyproject.toml` 中 `license` 改回 `{ text = "MIT" }`，并在 README 本段更新。

### 合规声明（重要）

- **不含厂商/第三方源码**：本工程是闭源汇文/Libsys 的**独立互操作层**，不包含
  汇文或联盟方的任何专有代码；OPAC/联盟契约仅依据公开网页协议与真站响应记录。
  详见 [NOTICE](NOTICE)。
- **不随仓库发布任何部署敏感数据**：真实的 DSN、账号口令、OPAC 登录实例、
  联盟 JWT、读者 PII、厂商 `SECRET_KEY` 均不在仓库内（SECURITY.md/CONTRIBUTING.md
  已设红线，严禁任何疑似敏感数据入库）。
- **商标**：`汇文`、`Libsys`、`OPAC` 分别为江苏汇文软件等权利人的商标/产品名，
  本仓库仅作互操作指称，不暗示背书与关联。
- 你在使用本软件前，请与汇文软件、联盟服务方及贵馆信息中心确认**授权与使用边界**。

---

## 故障排查

| 现象 | 处理 |
|---|---|
| “该后端不支持” | 确认 `HUIWEN_DATA_SOURCE`；`union_search` 仅 opac 后端、且需启用联盟配置 |
| Oracle `DPY-3010` / 连接失败 | 11g 用 `HUIWEN_ORACLE_MODE=thick` + `HUIWEN_ORACLE_CLIENT_LIB_DIR`（Instant Client） |
| OPAC 检索超时 | 站点侧慢（15-40s 常见），调大 `HUIWEN_OPAC_TIMEOUT` 或稍后重试 |
| `union_search` 返回 `enabled:false` | 未启用联盟或 token 缺失 → 启用配置并填 JWT |
| 联盟返回 `storage token not found` | JWT 过期 → 重新登录 OPAC 取 `getReaderJwt` 更新 token |
| 框架拒绝工具注册（`*args/**kwargs`） | 工具函数必须显式参数；不要使用 `*args/**kwargs` 签名 |
| 读者工具返回“需要管理员令牌” | 使用 `HUIWEN_AUTH_ADMIN_TOKENS` 中的令牌 |