huiwen-mcp

Servidor Model Context Protocol (MCP) para el sistema de gestión de bibliotecas Huiwen (Libsys / OPAC) — Puerta de enlace de datos de solo lectura para bibliotecas orientada a la IA: permite que clientes de IA como Claude, Cherry Studio, DeepSeek recuperen de forma segura y auditable el catálogo de la biblioteca, ejemplares disponibles, estadísticas de circulación y el catálogo colectivo de la alianza.

Capa de adaptación oficial desarrollada por el equipo de la biblioteca universitaria, que cumple con la línea base de seguridad de solo lectura por defecto, privilegios mínimos y auditoría de extremo a extremo.

• Protocolo: Model Context Protocol (estándar abierto de Anthropic, misma ruta técnica que la integración del catálogo de la Biblioteca de Yale)

• Entorno de ejecución: Python ≥ 3.10 · FastMCP 3.x

• Fuentes de datos: demo (demostración sin dependencias) / opac (protocolo web público de OPAC Huiwen) / oracle (conexión directa de solo lectura a la base de datos Libsys Huiwen)

• Licencia: Apache-2.0 (esquema recomendado, ver Licencia y cumplimiento)

Índice

1. Características

2. Enfoque de diseño del sistema

3. Esquema técnico de implementación

4. Inicio rápido

5. Configuración (variables de entorno / .env)

6. Lista de herramientas

7. Ejemplos de integración de clientes

8. Casos de uso

9. Seguridad y cumplimiento

10. Pruebas

11. Estructura del proyecto

12. Hoja de ruta

13. Licencia y cumplimiento

14. Solución de problemas

Características

Compensaciones de diseño: Las operaciones de escritura (renovación, reserva, pedidos de préstamo interbibliotecario) no se implementan intencionadamente — este proyecto solo se dedica a “leer de forma segura y auditable”; las rutas de escritura se delegan completamente al sistema de negocio original y a los procesos manuales.

Enfoque de diseño del sistema

Posicionamiento: puerta de enlace de datos / capa de habilidades, no un proxy de base de datos

Los clientes de IA (modelos grandes) nunca se conectan directamente a la base de datos Huiwen. Todas las consultas pasan por una capa de herramientas controladas:

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

• Responsabilidad única por capa: el adaptador solo se encarga de obtener datos; _guard solo se encarga de la seguridad; la auditoría escribe JSONL de forma independiente; la IA de nivel superior solo interactúa con las firmas de las herramientas, sin percibir las diferencias del backend (tres backends con la misma firma).

• Seguridad por defecto: data_source=demo se ejecuta sin dependencias; opac/oracle requiere configuración explícita; las herramientas sensibles del lector requieren un token de administrador; las operaciones de escritura están deshabilitadas por defecto; los servicios de alianza externos están desactivados por defecto.

Por qué MCP

• MCP es un estándar abierto de IA para conectar “bases de datos/sistemas de negocio” (lanzado por Anthropic en noviembre de 2024, ecosistema que incluye GitHub/proveedores de nube/proveedores de bases de datos). Elegir un estándar abierto en lugar de una API privada garantiza: clientes reemplazables (Claude/Cherry Studio/DeepSeek/Agente propio), servicio reutilizable por múltiples sistemas, sin bloqueo a largo plazo por parte del proveedor — esta es la misma ruta que la Biblioteca de Yale utiliza para integrar su catálogo con MCP.

• FastMCP proporciona transporte dual stdio/HTTP para la implementación del servidor, un solo código base compatible con despliegue en proceso y como servicio.

Elección del modo de transporte: stdio vs HTTP

• stdio: en proceso, se inicia con el cliente, sin operaciones, menor latencia, adecuado para uso personal/individual con clientes de escritorio de IA.

• HTTP (Streamable HTTP): servicio independiente, adecuado para despliegue multiusuario/centralizado; se puede colocar un proxy inverso OAuth2/JWT delante con identidad unificada del campus, para auditoría centralizada.

Esquema técnico de implementación

Contratos clave (todos verificados con pruebas reales)

• OPAC: resultados de búsqueda <ol id="search_book_list"> → <li class="book_list_info">, título / signatura / ejemplares en fondo / ejemplares disponibles / número de resultados; tabla de ejemplares en página de detalle; ranking de populares.

• Alianza PROCAT: POST (GET→405); autenticación con parámetro de consulta tk= (JWT emitido por la sesión de lector de OPAC getReaderJwt); items[].logic="1"(AND)/"2"(OR); mapeo de campos any/title/author/subject/isbn/clcNumber/publisher/series. Ver detalles en docs/búsqueda-catálogo-colectivo-alianza.md.

⚠️ Tanto OPAC como la alianza son sistemas cerrados del proveedor o de terceros, los contratos pueden variar según la versión del despliegue. Toda la documentación de integración se basa en “verificación con sitio real” y se registra con tests/test_*_live.py.

Inicio rápido

1) Instalación

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) Ejecución sin configuración (fuente de datos demo, sin conexión)

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

demo incluye datos de muestra de libros/lectores, útil para pruebas de humo, pruebas e integración didáctica.

2b) Despliegue con Docker con un solo comando

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

Más información (Oracle 11g thick / compose / autenticación a nivel de proxy inverso con CAS del campus) en docs/guía-de-despliegue.md.

3) Integración con fuentes de datos reales (opac / oracle)

Copie .env.example como .env y complete (.env está en git-ignore):

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

O use config.local.json (configuración sensible cargada automáticamente, no en el repositorio).

Configuración (variables de entorno / .env)

Toda la configuración se puede inyectar mediante variables de entorno (prefijo HUIWEN_), también compatible con archivo .env (carga automática). Prioridad: Variables de entorno > config.json explícito / CONFIG_PATH > fusión automática de config.local.json > valores predeterminados incorporados.

General

OPAC

Oracle

Seguridad

Lista de herramientas

Para la descripción de funciones y evaluación de integración de la interfaz de servicio ACS/SIP2 de Huiwen, ver docs/descripción-interfaz-ACS-SIP2-Huiwen-y-evaluación-integración.md (mapeo autorizado de campos, subconjunto candidato de solo lectura, elementos explícitamente deshabilitados).

Las herramientas de lector están desensibilizadas por defecto (include_pii=false no devuelve número de identificación / contacto, etc.; true requiere admin).

Ejemplos de integración de clientes

Claude Desktop / Clientes de escritorio compatibles con MCP

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

HTTP remoto (requiere autenticación propia en la puerta de enlace)

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

El cliente se conecta a http://<host>:8765/mcp/ (Streamable HTTP) usando ${MCP_SERVER_URL}. Cuando HUIWEN_AUTH_ENABLED=true, el token se pasa como parámetro de herramienta token con cada llamada; la cabecera HTTP Authorization no es consumida por el servidor (ver guía de despliegue §3.2).

Casos de uso

Recomendaciones completas (incluyendo esquema jerárquico con LLM local + RAG y comparación nacional e internacional) en docs/recomendaciones-de-servicio-y-aplicación.md.

Seguridad y cumplimiento

1. Solo lectura por defecto: todas las herramientas son de solo lectura; las operaciones de escritura (renovación/reserva/pedido interbibliotecario) no se implementan intencionadamente.

2. SQL de lista blanca: el backend Oracle solo ejecuta el conjunto cerrado de SQL parametrizado en db/queries.py, sin SQL libre.

3. Control de extremo a extremo: autenticación → limitación de velocidad → control de lector/PII → auditoría (JSONL). Los datos personales del lector requieren token de administrador y están desensibilizados por defecto.

4. Contrato de autenticación (verificado con pruebas reales): el token se pasa a través del parámetro de herramienta token (parámetro opcional de cada herramienta, _guard lo extrae de los parámetros y lo compara con HUIWEN_AUTH_BEARER_TOKEN), no se implementa la transmisión de la cabecera HTTP Authorization — la capa de transporte TLS/identidad unificada es responsabilidad del proxy inverso de la puerta de enlace, la autenticación de huiwen-mcp es la segunda línea de defensa detrás de la puerta de enlace. El token no se escribe en el registro de auditoría (_guard lo extrae antes de registrar).

5. Las claves no entran en el repositorio: DSN/contraseñas/JWT/direcciones de sitio solo a través de variables de entorno o config.local.json (git-ignored). El repositorio no contiene ningún dato de despliegue real (ver NOTICE).

6. Cuidado con servicios externos: la alianza PROCAT es un sistema multiusuario de terceros, desactivado por defecto; antes de activarlo, confirmar la autorización con la alianza/proveedor de servicios. OPAC es cerrado, históricamente ha tenido vulnerabilidades públicas, el adaptador solo usa parámetros de lista blanca.

7. Reporte y manejo de vulnerabilidades en SECURITY.md.

Pruebas

Las pruebas con base de datos real/sitio real están desactivadas por defecto (requieren establecer explícitamente HUIWEN_LIVE_* localmente) para evitar tocar cualquier sistema real. La imagen Docker no se construye/publica por defecto (la política de publicación es “solo publicar código fuente y documentación”): si se necesita la imagen, construirla localmente con docker build (para modo Oracle thick, añadir --build-arg WITH_INSTANT_CLIENT=true).

Estructura del proyecto

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

Hoja de ruta

• Fase 1: MCP de solo lectura (tres backends: demo + opac + oracle)

• Fase 2: Integración con bases de datos reales OPAC/Oracle, integración con catálogo colectivo de la alianza (contrato verificado + esquema de token)

• Resto de Fase 2: Imagen Docker (no root, reproducible) + guía de despliegue (incluyendo plantilla de autenticación a nivel de proxy inverso)

• Publicado: etiqueta v1.0.0 + GitHub Release (código fuente y documentación; sin CI/workflows, la imagen Docker no se construye automáticamente)

• Integración de puerta de enlace OAuth2/JWT con CAS del campus / ventanilla única (plantilla lista, requiere configuración in situ)

• Candidato Fase 2.5/3: Subconjunto de solo lectura de ACS/SIP2 de Huiwen (evaluación en docs/descripción-interfaz-ACS-SIP2-Huiwen-y-evaluación-integración.md)

• Fase 3: Base de datos vectorial RAG + LLM local para recomendación inteligente de libros / consulta de referencia (ver docs/recomendaciones-de-servicio-y-aplicación.md)

• Fase 4: Integración con OpenAPI de la nueva plataforma Huiwen

Licencia y cumplimiento (Open Source & Compliance)

Sugerencia de versión de licencia

Este proyecto recomienda adoptar Apache License 2.0 (el repositorio ya incluye el LICENSE completo):

1. Permisivo: permite que universidades, fabricantes y plataformas en la nube utilicen, modifiquen y redistribuyan libremente (incluido uso comercial), siempre que se conserve el aviso de derechos de autor y licencia, lo que favorece la adopción por parte de cadenas de herramientas de IA y sistemas de terceros.

2. Licencia de patentes: Apache-2.0 otorga explícitamente una licencia de uso de patentes a los contribuyentes (artículo 3), lo que resulta más claro y "resistente a demandas" cuando múltiples instituciones o partes (como universidades y fabricantes tecnológicos) contribuyen conjuntamente.

3. Cláusulas estandarizadas para contribuyentes: otorga implícitamente una licencia al proyecto (artículo 5, Concesión de contribuciones), eliminando la carga de que cada contribuyente firme un CLA individual, en línea con las prácticas de proyectos públicos en GitHub.

4. Diferenciación: en comparación con MIT, Apache-2.0 es más adecuado para proyectos de infraestructura publicados formalmente por instituciones y que pueden ser mantenidos a largo plazo por múltiples partes.

Si su institución prefiere un "estilo minimalista", puede volver a MIT en cualquier momento: solo necesita reemplazar el contenido completo de LICENSE, cambiar license en pyproject.toml a { text = "MIT" }, y actualizar esta sección en el README.

Declaración de cumplimiento (importante)

• No contiene código fuente de terceros/fabricantes: este proyecto es una capa de interoperabilidad independiente para el sistema cerrado Huiwen/Libsys, y no incluye ningún código propietario de Huiwen o de las entidades de la alianza; los contratos de OPAC/alianza se basan únicamente en los protocolos de páginas web públicas y los registros de respuesta del sitio real. Consulte NOTICE para más detalles.

• No se publican datos sensibles de despliegue junto con el repositorio: DSN reales, contraseñas de cuentas, instancias de inicio de sesión de OPAC, JWT de la alianza, PII de lectores, ni SECRET_KEY de fabricantes están presentes en el repositorio (SECURITY.md/CONTRIBUTING.md ya establecen líneas rojas, prohibiendo estrictamente la inclusión de cualquier dato sospechoso de ser sensible).

• Marcas registradas: Huiwen, Libsys y OPAC son marcas comerciales/nombres de productos de Jiangsu Huiwen Software y otros titulares de derechos; este repositorio solo los utiliza para referencias de interoperabilidad, sin implicar respaldo ni afiliación.

• Antes de utilizar este software, confirme los derechos de uso y límites con Huiwen Software, el proveedor de servicios de la alianza y el centro de información de su institución.

Solución de problemas