huiwen-mcp

Model Context Protocol (MCP)-Server für das Huiwen-Bibliotheksverwaltungssystem (Libsys / OPAC) — Schreibgeschütztes Daten-Gateway für Bibliotheken für KI: Ermöglicht KI-Clients wie Claude / Cherry Studio / DeepSeek eine sichere, prüfbare Abfrage von Bestand, Exemplaren, Ausleihstatistiken und Verbundkatalogen.

Offizielle Adapterschicht, entwickelt von einer Hochschulbibliothek, unter Einhaltung der Sicherheitsrichtlinie standardmäßig schreibgeschützt, minimale Berechtigungen, vollständige Audit-Transparenz.

• Protokoll: Model Context Protocol (offener Standard von Anthropic, gleicher technischer Ansatz wie der Katalogzugang der Yale Library)

• Laufzeit: Python ≥ 3.10 · FastMCP 3.x

• Datenquellen: demo (keine Abhängigkeiten, Demo) / opac (öffentliches Webprotokoll des Huiwen OPAC) / oracle (schreibgeschützte Direktverbindung zur Huiwen Libsys-Datenbank)

• Lizenz: Apache-2.0 (empfohlen, siehe Lizenz & Compliance)

Inhaltsverzeichnis

1. Funktionen

2. Systemdesign-Ansatz

3. Implementierungstechnisches Konzept

4. Schnellstart

5. Konfiguration (Umgebungsvariablen / .env)

6. Werkzeugliste

7. Beispiele für Client-Integration

8. Anwendungsszenarien

9. Sicherheit & Compliance

10. Tests

11. Projektstruktur

12. Roadmap

13. Lizenz & Compliance

14. Fehlerbehebung

Funktionen

Design-Entscheidungen: Schreiboperationen (Verlängerung, Vormerkung, Fernleihe) wurden bewusst nicht implementiert – dieses Projekt dient ausschließlich dem „sicheren, prüfbaren Lesen“; Schreibpfade bleiben den ursprünglichen Geschäftssystemen und manuellen Prozessen überlassen.

Systemdesign-Ansatz

Positionierung: Daten-Gateway / Fähigkeitsschicht, kein Datenbank-Proxy

KI-Clients (große Modelle) verbinden sich niemals direkt mit der Huiwen-Datenbank. Alle Abfragen werden durch eine kontrollierte Werkzeugschicht gekapselt:

┌─────────────── 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：内置样例数据                                 → 离线演示/测试            │
└───────────────────────────────────────────────────────────────────────────────────────┘

• Jede Schicht hat eine einzige Verantwortung: Der Adapter holt nur Daten; _guard kümmert sich nur um Sicherheit; Audit schreibt unabhängig JSONL; die obere KI interagiert nur mit den Werkzeugsignaturen, ohne die Backend-Unterschiede zu kennen (drei Backends, gleiche Signaturen).

• Standardmäßig sicher: data_source=demo benötigt keine Abhängigkeiten und läuft sofort; opac/oracle erfordert explizite Konfiguration; sensible Leser-Tools benötigen ein Admin-Token; Schreiboperationen sind standardmäßig deaktiviert; externe Verbunddienste sind standardmäßig ausgeschaltet.

Warum MCP?

• MCP ist ein offener Standard für KI-Verbindungen zu „Datenbanken/Geschäftssystemen“ (Anthropic, veröffentlicht Nov. 2024, Ökosystem umfasst GitHub/Cloud-Anbieter/Datenbankanbieter). Die Wahl eines offenen Standards statt einer proprietären API gewährleistet: austauschbare Clients (Claude/Cherry Studio/DeepSeek/eigene Agents), wiederverwendbare Dienste für mehrere Systeme, langfristige Vermeidung von Vendor-Lock-in – dies ist derselbe Weg, den die Yale Library mit MCP für den Katalogzugang gewählt hat.

• FastMCP bietet serverseitig sowohl stdio- als auch HTTP-Transport, sodass eine Codebasis sowohl prozessinterne als auch serviceorientierte Bereitstellung unterstützt.

Wahl des Transportmodus: stdio vs. HTTP

• stdio: Prozessintern, wird mit dem Client gestartet, kein Betriebsaufwand, geringste Latenz, geeignet für persönliche/einzelne Maschinen, die KI-Desktop-Clients verwenden.

• HTTP (Streamable HTTP): Eigenständiger Dienst, geeignet für Multi-User- / zentralisierte Bereitstellung; kann mit einem OAuth2/JWT-Reverse-Proxy und Campus-Identitätsmanagement vorgeschaltet werden, für zentrales Audit.

Implementierungstechnisches Konzept

Wichtige Verträge (alle durch echte Tests bestätigt)

• OPAC: Suchergebnisse <ol id="search_book_list"> → <li class="book_list_info">, Titel/Signatur/Bestandsexemplare/ausleihbare Exemplare/Trefferzahl; Exemplartabelle auf der Detailseite; Beliebtheitsrangliste.

• Verbund PROCAT: POST (GET→405); Authentifizierung über Query-Parameter tk= (JWT, ausgestellt durch OPAC-Lesersitzung getReaderJwt); items[].logic="1"(AND)/"2"(OR); Feldzuordnung any/title/author/subject/isbn/clcNumber/publisher/series. Siehe docs/Verbundkatalogrecherche.md.

⚠️ OPAC / Verbund sind geschlossene Systeme des Herstellers oder Drittanbieter; Verträge können sich mit der Bereitstellungsversion ändern. Alle Integrationsdokumente basieren auf „echten Standorttests“ und werden mit tests/test_*_live.py validiert.

Schnellstart

1) Installation

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) Null-Konfiguration (demo-Datenquelle, offline)

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

demo enthält integrierte Beispiel-Bibliografien/Leserdaten, geeignet für Smoke-Tests, Tests und Einführungslernen.

2b) Docker-Bereitstellung mit einem Klick

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

Mehr (Oracle 11g thick / compose / Reverse-Proxy-Authentifizierung mit Campus-CAS) finden Sie unter docs/Bereitstellungsleitfaden.md.

3) Anbindung einer echten Datenquelle (opac / oracle)

Kopieren Sie .env.example nach .env und füllen Sie es aus (.env ist git-ignoriert):

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

Oder verwenden Sie config.local.json (sensible Konfiguration automatisch geladen, nicht eingecheckt).

Konfiguration (Umgebungsvariablen / .env)

Alle Konfigurationen können über Umgebungsvariablen (Präfix HUIWEN_) injiziert werden, auch über .env-Datei (automatisch geladen). Priorität: Umgebungsvariablen > explizite config.json / CONFIG_PATH > config.local.json automatische Zusammenführung > integrierte Standardwerte.

Allgemein

OPAC

Oracle

Sicherheit

Werkzeugliste

Die Funktionsbeschreibung und Integrationsbewertung der Huiwen ACS / SIP2-Schnittstellendienste finden Sie unter [docs/Huiwen ACS-SIP2-Schnittstellenbeschreibung und Integrationsbewertung.md](docs/Huiwen ACS-SIP2-Schnittstellenbeschreibung und Integrationsbewertung.md) (autoritative Feldzuordnung, Kandidaten für schreibgeschützte Untermenge, explizit ausgeschlossene Elemente).

Leser-Tools sind standardmäßig anonymisiert (include_pii=false gibt keine Ausweisnummern/Kontaktdaten zurück; true erfordert admin).

Beispiele für Client-Integration

Claude Desktop / MCP-fähige Desktop-Clients

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

Remote HTTP (eigenes Gateway mit Authentifizierung erforderlich)

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

Der Client verbindet sich mit ${MCP_SERVER_URL} an http://<host>:8765/mcp/ (Streamable HTTP). Wenn HUIWEN_AUTH_ENABLED=true aktiviert ist, wird der Token als Werkzeugparameter token mit dem Aufruf übergeben; der HTTP-Authorization-Header wird vom Server nicht verarbeitet (siehe Bereitstellungsleitfaden §3.2).

Anwendungsszenarien

Vollständige Vorschläge (inkl. Lokale LLM + RAG-Schichtenansatz und nationale/internationale Vergleiche) finden Sie unter [docs/Dienst- und Anwendungsvorschläge.md](docs/Dienst- und Anwendungsvorschläge.md).

Sicherheit & Compliance

1. Standardmäßig schreibgeschützt: Alle Werkzeuge sind schreibgeschützt; Schreiboperationen (Verlängerung/Vormerkung/Fernleihe) wurden bewusst nicht implementiert.

2. Whitelist-SQL: Das Oracle-Backend führt nur parametrisierte SQL-Abfragen aus db/queries.py aus, keine freien SQL-Statements.

3. Vollständige Gate-Kette: Authentifizierung → Ratenbegrenzung → Leser-/PII-Gate → Audit (JSONL). Leser-Personendaten erfordern Admin-Token und sind standardmäßig anonymisiert.

4. Authentifizierungsvertrag (durch echte Tests bestätigt): Token wird über Werkzeugparameter token übergeben (optionaler Parameter jedes Werkzeugs, _guard extrahiert ihn aus den Parametern und vergleicht mit HUIWEN_AUTH_BEARER_TOKEN), keine Weitergabe des HTTP-Authorization-Headers – die Transportebene TLS/Identitätsmanagement wird vom Reverse-Proxy-Gateway übernommen, die Authentifizierung von huiwen-mcp selbst ist die zweite Verteidigungslinie hinter dem Gateway. Token werden nicht in das Audit-Log geschrieben (_guard entfernt sie vor der Aufzeichnung).

5. Keine Geheimnisse im Repository: DSN/Passwort/JWT/Standort-URLs werden nur über Umgebungsvariablen oder config.local.json (git-ignoriert) übergeben. Das Repository enthält keine echten Bereitstellungsdaten (siehe NOTICE).

6. Externe Dienste mit Vorsicht: Der Verbund PROCAT ist ein Multi-Mandanten-System eines Drittanbieters, standardmäßig deaktiviert; vor Aktivierung mit dem Verbund/Dienstanbieter die Berechtigung klären. OPAC ist Closed Source, historisch gab es Sicherheitslücken, der Adapter verwendet nur Whitelist-Parameter.

7. Meldung und Behandlung von Schwachstellen siehe SECURITY.md.

Tests

Tests mit echten Datenbanken/echten Standorten sind standardmäßig deaktiviert (erfordern lokale explizite Setzung von HUIWEN_LIVE_*), um keine realen Systeme zu berühren. Das Docker-Image wird standardmäßig nicht erstellt/veröffentlicht (Veröffentlichungsstrategie: „nur Quellcode und Dokumentation veröffentlichen“): Wenn ein Image benötigt wird, bitte lokal docker build ausführen (für Oracle thick-Modus mit --build-arg WITH_INSTANT_CLIENT=true).

Projektstruktur

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: Schreibgeschützte MCP-Suche (drei Backends: demo + opac + oracle)

• Phase 2: Integration mit echtem OPAC / Oracle, Integration mit Verbundkatalog (Vertragstests + Token-Lösung)

• Phase 2 Rest: Docker-Image (nicht-root, reproduzierbar) + Bereitstellungsleitfaden (inkl. Reverse-Proxy-Authentifizierungsvorlage)

• Veröffentlicht: v1.0.0-Tag + GitHub Release (Quellcode und Dokumentation; kein CI/Workflow, Docker-Image nicht automatisch erstellt)

• OAuth2/JWT-Gateway-Integration mit Campus-CAS / One-Stop-Service (Vorlage bereit, erfordert Standortkonfiguration)

• Phase 2.5/3 Kandidat: Huiwen ACS/SIP2 schreibgeschützte Untermenge (Bewertung siehe docs/Huiwen ACS-SIP2-Schnittstellenbeschreibung und Integrationsbewertung.md)

• Phase 3: RAG-Vektor-Datenbank + lokales LLM für intelligente Buchempfehlung / Auskunft (siehe docs/Dienst- und Anwendungsvorschläge.md)

• Phase 4: Anbindung der Huiwen Next-Generation-Plattform-OpenAPI

Lizenz & Compliance (Open Source & Compliance)

Lizenzversionsempfehlung

Dieses Projekt empfiehlt die Verwendung der Apache License 2.0 (vollständige LICENSE im Repository beigefügt):

1. Permissiv: Ermöglicht Hochschulen, Herstellern und Cloud-Plattformen die freie Nutzung, Änderung und Weiterverbreitung (auch kommerziell), sofern die Urheberrechts- und Lizenzhinweise erhalten bleiben – vorteilhaft für die Integration in KI-Toolchains und Drittsysteme.

2. Patentlizenz: Apache-2.0 erteilt ausdrücklich eine Patentnutzungslizenz für Beitragende (Abschnitt 3), was bei gemeinsamen Beiträgen mehrerer Institutionen/Parteien (mehrere Hochschulen, Technologieanbieter) klarer und „klagefester“ ist.

3. Klare Beitragsbestimmungen: Stillschweigende Erteilung einer Projektlizenz (Abschnitt 5 Contribution Grant), wodurch die Notwendigkeit separater CLAs für jeden Beitragenden entfällt – entspricht der Praxis öffentlicher GitHub-Projekte.

4. Unterscheidbarkeit: Im Vergleich zu MIT eignet sich Apache-2.0 besser für Infrastrukturprojekte, die offiziell von Institutionen veröffentlicht werden und von mehreren Parteien langfristig gewartet werden können.

Falls Ihre Bibliothek den „minimalistischen Stil“ bevorzugt, können Sie jederzeit zu MIT zurückkehren: Ersetzen Sie den gesamten LICENSE-Text, ändern Sie in pyproject.toml das license-Feld zurück auf { text = "MIT" } und aktualisieren Sie diesen Abschnitt in der README.

Konformitätserklärung (wichtig)

• Kein Hersteller-/Drittanbieter-Quellcode: Dieses Projekt ist eine unabhängige Interoperabilitätsschicht für das Closed-Source-System Huiwen/Libsys und enthält keinen proprietären Code von Huiwen oder Partnerverbünden; OPAC-/Verbundverträge basieren ausschließlich auf öffentlichen Webprotokollen und Antwortaufzeichnungen echter Server. Siehe NOTICE.

• Keine sensiblen Bereitstellungsdaten im Repository: Echte DSN, Kontopasswörter, OPAC-Login-Instanzen, Verbund-JWTs, Leser-PII, Hersteller-SECRET_KEY sind nicht im Repository enthalten (SECURITY.md/CONTRIBUTING.md definieren rote Linien, die jegliche sensible Datenverbindungen verbieten).

• Marken: 汇文, Libsys, OPAC sind Marken-/Produktnamen von Jiangsu Huiwen Software usw. Dieses Repository dient nur der Interoperabilitätsbezeichnung, ohne Befürwortung oder Verbindung zu implizieren.

• Bitte klären Sie vor der Nutzung dieser Software mit Huiwen Software, dem Verbundsdienst und Ihrer Bibliotheks-IT die Autorisierung und Nutzungsgrenzen.

Fehlerbehebung