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. ロードマップ

13. ライセンスとコンプライアンス

14. トラブルシューティング

機能特性

設計のトレードオフ：書き込み操作（延長、予約、ILL 発注）は意図的に未実装——本プロジェクトは 「安全に監査可能な読み取り」のみを行い、書き込み経路はすべて元の業務システムと手動作業に委ねます。

システム設計の考え方

位置づけ：データゲートウェイ / スキル層、データベースプロキシではない

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 はツールシグネチャとのみ対話し、バックエンドの違いを認識しません（3 バックエンドで同一シグネチャ）。

• デフォルトで安全：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 が必要）。 n *** n

クライアント連携例

Claude Desktop / MCP をサポートするデスクトップクライアント

GXP6 n

リモート HTTP（ゲートウェイでの認証は別途必要） n

GXP7 n クライアントは ${MCP_SERVER_URL} を使って http://<host>:8765/mcp/（Streamable HTTP）に接続します。 HUIWEN_AUTH_ENABLED=true のとき、トークンはツールパラメータ token として呼び出し時に渡され； HTTP Authorization ヘッダーはサーバー側で消費されません（デプロイガイド §3.2 参照）。 n

使用シナリオ

完全な提案（ローカル LLM + RAG の階層的アプローチと国内外のベンチマークを含む）は docs/サービスとアプリケーション提案.md を参照。 n

セキューリティとコンプライアンス

1. デフォルト読み取り専用：すべてのツールは読み取り専用；書き込み操作（延長/予約/ILL 発注）は意図的に未実装。

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 を参照。 n

テスト

実データベース/実サイトのテストはデフォルトでオフ（ローカルで明示的に 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

ロードマップ

• Phase 1：読み取り専用検索 MCP（demo + opac + oracle 三バックエンド）

• Phase 2：OPAC / Oracle 実データベース連携テスト、連合共同目録連携テスト（契約実測 + トークン方式）

• 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 参照） n* [ ] Phase 4：汇文新世代プラットフォーム OpenAPI 連携 n *** n

ライセンスとコンプライアンス（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/連盟契約は、公開Webページのプロトコルと実際のサイトの応答記録にのみ基づいています。詳細はNOTICEを参照してください。

• リポジトリ内にデプロイに敏感なデータは公開されていません：実際のDSN、アカウントパスワード、OPACログインインスタンス、連盟JWT、読者PII、ベンダーのSECRET_KEYはリポジトリ内にありません（SECURITY.md/CONTRIBUTING.mdでレッドラインが設定されており、疑わしい機密データのコミットは厳禁）。

• 商標：汇文、Libsys、OPACはそれぞれ江蘇汇文ソフトウェアなどの権利者の商標/製品名であり、本リポジトリは相互運用のための参照に過ぎず、推薦や関連性を示すものではありません。

• 本ソフトウェアを使用する前に、汇文ソフトウェア、連盟サービス提供者、および貴館の情報センターと許諾および使用範囲を確認してください。

トラブルシューティング