huiwen-mcp

Model Context Protocol (MCP) сервер для системы управления библиотекой Huiwen (Libsys / OPAC) — только для чтения шлюз данных библиотеки для ИИ: позволяет AI-клиентам (Claude / Cherry Studio / DeepSeek и др.) безопасно и с аудитом получать данные о фондах, наличии экземпляров, статистике выдачи и объединённом каталоге.

Официальный адаптационный слой, разработанный библиотекой университета, соблюдающий базовые принципы безопасности: только чтение, минимальные привилегии, полный аудит всей цепочки.

• Протокол: Model Context Protocol (открытый стандарт Anthropic, та же технологическая линия, что и подключение каталога Yale Library)

• Среда выполнения: Python ≥ 3.10 · FastMCP 3.x

• Источники данных: demo (нулевая зависимость, демонстрация) / opac (открытый веб-протокол Huiwen OPAC) / oracle (прямое подключение только для чтения к базе данных Huiwen Libsys)

• Лицензия: Apache-2.0 (рекомендуемый вариант, см. Лицензия и соответствие)

Содержание

1. Функциональные возможности

2. Концепция проектирования системы

3. Техническая реализация

4. Быстрый старт

5. Конфигурация (переменные окружения / .env)

6. Список инструментов

7. Примеры подключения клиентов

8. Сценарии использования

9. Безопасность и соответствие требованиям

10. Тестирование

11. Структура проекта

12. План развития

13. Лицензия и соответствие

14. Устранение неполадок

Функциональные возможности

Компромиссы в проектировании: операции записи (продление, бронирование, межбиблиотечный заказ) намеренно не реализованы — этот проект предназначен только для “безопасного и аудируемого чтения”, пути записи оставлены исходным бизнес-системам и ручным процессам.

Концепция проектирования системы

Позиционирование: шлюз данных / уровень навыков, а не прокси базы данных

AI-клиенты (большие языковые модели) никогда не подключаются напрямую к базе данных Huiwen. Все запросы инкапсулируются через контролируемый слой инструментов:

┌─────────────── 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, экосистема включает GitHub/облачные провайдеры/поставщиков баз данных). Выбор открытого стандарта, а не частного API, гарантирует: взаимозаменяемость клиентов (Claude/Cherry Studio/DeepSeek/собственные агенты), возможность повторного использования сервиса несколькими системами, отсутствие привязки к поставщику в долгосрочной перспективе — это тот же путь, который 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 встроены примеры библиографических записей/данных читателя, можно использовать для smoke-тестирования, тестирования и обучения подключению.

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 толстый режим / 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

Безопасность

Список инструментов

Описание функций и оценка интеграции сервисных интерфейсов Huiwen ACS / SIP2 см. в docs/описание-и-оценка-интерфейсов-Huiwen-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

Клиент подключается к http://<host>:8765/mcp/ (Streamable HTTP) с использованием ${MCP_SERVER_URL}. При включении HUIWEN_AUTH_ENABLED=true токен передаётся как параметр инструмента token вместе с вызовом; заголовок HTTP Authorization не потребляется сервером (см. руководство по развёртыванию §3.2).

Сценарии использования

Полные рекомендации (включая локально развёрнутую LLM + RAG с многоуровневой схемой и сравнением с аналогами внутри страны и за рубежом) см. в docs/рекомендации-по-сервису-и-применению.md.

Безопасность и соответствие требованиям

1. Только чтение по умолчанию: все инструменты только для чтения; операции записи (продление/бронирование/межбиблиотечный заказ) намеренно не реализованы.

2. Белый список SQL: бэкенд Oracle выполняет только параметризованные SQL-запросы из закрытого набора db/queries.py, свободный SQL отсутствует.

3. Шлюзы по всей цепочке: аутентификация → ограничение запросов → шлюз читателя/PII → аудит (JSONL). Персональные данные читателя требуют admin-токена и по умолчанию обезличиваются.

4. Контракт аутентификации (проверено на реальном стенде): токен передаётся через параметр инструмента token (каждый инструмент имеет опциональный параметр, _guard извлекает его из параметров и сравнивает с HUIWEN_AUTH_BEARER_TOKEN), передача через HTTP-заголовок Authorization не реализована — транспортный уровень TLS/единая аутентификация обеспечивается обратным прокси-шлюзом, аутентификация самого huiwen-mcp является второй линией защиты за шлюзом. Токен не записывается в журнал аудита (_guard сначала извлекает его, затем записывает).

5. Ключи не попадают в репозиторий: DSN/пароли/JWT/адреса сайтов передаются только через переменные окружения или config.local.json (в git-ignored). Репозиторий не содержит никаких реальных данных развёртывания (см. NOTICE).

6. Внешние сервисы с осторожностью: консорциум PROCAT — сторонняя мультиарендная система, по умолчанию выключена; перед включением получите разрешение от консорциума/провайдера сервиса. OPAC является закрытым, исторически имел открытые уязвимости, адаптер использует только параметры из белого списка.

7. Сообщение и обработка уязвимостей см. в SECURITY.md.

Тестирование

Тесты на реальной БД/реальном стенде по умолчанию выключены (требуется явная локальная установка HUIWEN_LIVE_* для выполнения), чтобы не затрагивать никакие реальные системы. Docker-образ по умолчанию не собирается/не публикуется (стратегия публикации: "публикуются только исходный код и документация"): если нужен образ, соберите локально docker build (для толстого режима Oracle добавьте --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

План развития

• Фаза 1: MCP только для чтения (три бэкенда: demo + opac + oracle)

• Фаза 2: Интеграция с реальными БД OPAC/Oracle, интеграция с объединённым каталогом консорциума (проверка контрактов + схема токенов)

• Остатки Фазы 2: Docker-образ (не root, воспроизводимая сборка) + руководство по развёртыванию (включая шаблон аутентификации на уровне обратного прокси)

• Опубликовано: тег v1.0.0 + GitHub Release (исходный код и документация; без CI/рабочих процессов, Docker-образ не собирается автоматически)

• Развёртывание шлюза OAuth2/JWT для интеграции с кампусным CAS / единым порталом (шаблон готов, требуется настройка на месте)

• Кандидаты на Фазу 2.5/3: подмножество только для чтения Huiwen ACS/SIP2 (оценка см. в docs/описание-и-оценка-интерфейсов-Huiwen-ACS-SIP2.md)

• Фаза 3: Векторная база данных RAG + локальная LLM для интеллектуальных рекомендаций книг / справочной службы (см. docs/рекомендации-по-сервису-и-применению.md)

• Фаза 4: Интеграция с OpenAPI новой платформы Huiwen

Лицензия и соответствие (Open Source & Compliance)

Рекомендация по версии лицензии с открытым исходным кодом

Для данного проекта рекомендуется использовать Apache License 2.0 (репозиторий уже содержит полный LICENSE):

1. Пермиссивная (разрешительная): позволяет университетам, производителям и облачным платформам свободно использовать, модифицировать и распространять (включая коммерческое использование), требуется только сохранение уведомления об авторских правах и лицензионного заявления — способствует принятию AI-инструментами и сторонними системами.

2. Патентная лицензия: Apache-2.0 явно предоставляет участникам патентную лицензию (статья 3), при совместном вкладе нескольких оргнизаций/сторон (консорциум университетов, технологических компаний) более ясна и устойчива к судебным искам.

3. Стандартные условия для участников: неявное предоставление лицензии проекту (статья 5, Contribution Grant), избавляет от необхдимости каждому участнику подписыват отдельное CLA, соответствует практике публичных проектов на GitHub.

4. Отличие: по сравению с MIT, Apache-2.0 больше подходит для официально выпущенных от имени организации инфраструктурных проектов, которые могут долгосрочно поддерживаться несколькими сторонами.

Если ваша организация предпочитает «минималистичный стиль», можно в любой момент вернуться к MIT: достаточно заменить полный текст LICENSE, изменить license в pyproject.toml обратно на { text = "MIT" } и обновить этот разел в README.

Соответствие требованиям (важно)

• Не сдержит исходного кода проиводителей/третьих сторон: данный проект является независимым уровнем взаимодействия для закрытого Huiwen/Libsys, не включает никакого проприетарного кода Huiwen или консорциума; соглашения OPAC/консорциума основаны только на публичных протоколах веб-страниц и записях ответов реальных станций. Подробнее см. NOTICE.

• Не публикует в репозитории никаких конфиденциальных данных для развертывания: реальные DSN, учетные данные, экземпляры для вхоа в OPAC, JWT консорциума, PII читателей, SECRET_KEY проиводителя не нахотятся в репозитории (SECURITY.md/CONTRUBTING.md установлены красные линии, строго зарещено внесение любых поозрительных конфиденциальных данных).

• Товарные знаки: 汇文, Libsys, OPAC являются товарными знаками/названиями продуктов Jiangsu Huiwen Software и других правообладателей; данный репозиторий использует их толко для обозначения совместимости, не подразмевая одобрения или аффилировванности.

• Перед использованием данного программного обеспечения, пожалуйста, уточните границы лицензирования и использования с Huiwen Software, обслуживающим консорциум и информационным центром вашего учреждения.

Устранение неполадок