huiwen-mcp

汇文图书管理系统（Libsys / OPAC）的 Model Context Protocol (MCP) 服务器 —— 面向 AI 的图书馆只读数据网关：让 Claude / Cherry Studio / DeepSeek 等 AI 客户端 安全、可审计地检索馆藏书目、复本在馆、流通统计与联盟联合目录。

由高校图书馆方开发的官方适配层，遵守默认只读、最小权限、全链路审计的安全基线。

• 协议：Model Context Protocol（Anthropic 开放标准，与 Yale Library 的目录接入同技术路线）

• 运行时：Python ≥ 3.10 · FastMCP 3.x

• 数据源：demo（零依赖演示）/ opac（汇文 OPAC 公开网页协议）/ oracle（汇文 Libsys 数据库只读直连）

• 开源协议：Apache-2.0（推荐方案，见协议与合规）

目录

1. 功能特性

2. 系统设计思路

3. 实现技术方案

4. 快速开始

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

6. 工具清单

7. 客户端接入示例

8. 使用场景

9. 安全与合规

10. 测试

11. 项目结构

12. Roadmap

13. 协议与合规

14. 故障排查

功能特性

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

系统设计思路

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

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 反向代理与校园统一身份，做中心审计。

实现技术方案

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

• 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) 安装

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 数据源，离线）

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

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

2b) Docker 一键部署

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。

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

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

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 自动合并 > 内置默认。

通用

OPAC

Oracle

安全

工具清单

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

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

客户端接入示例

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

{
  "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）。

使用场景

完整建议（含本地部署 LLM + RAG 的分层方案与国内外对标）见 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）。

6. 外部服务慎重：联盟 PROCAT 为第三方多租户系统，默认关闭；启用前与 联盟/服务方确认授权。OPAC 闭源，历史存在公开漏洞，适配器仅用白名单参数。

7. 漏洞报告与处理见 SECURITY.md。

测试

真库/真站测试默认关闭（需本地显式设置 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

• Phase 1：只读检索 MCP（demo + opac + oracle 三后端）

• Phase 2：OPAC / Oracle 真库联调、联盟联合目录联调（契约实测 + token 方案）

• Phase 2 余项：Docker 镜像（非 root、可重复构建）+ 部署指南（含反向代理级认证模板）

• 已发布：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）：

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。

• 不随仓库发布任何部署敏感数据：真实的 DSN、账号口令、OPAC 登录实例、 联盟 JWT、读者 PII、厂商 SECRET_KEY 均不在仓库内（SECURITY.md/CONTRIBUTING.md 已设红线，严禁任何疑似敏感数据入库）。

• 商标：汇文、Libsys、OPAC 分别为江苏汇文软件等权利人的商标/产品名， 本仓库仅作互操作指称，不暗示背书与关联。

• 你在使用本软件前，请与汇文软件、联盟服务方及贵馆信息中心确认授权与使用边界。

故障排查