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 실제 데이터베이스 연동, 연합 공동 목록 연동(계약 실제 측정 + 토큰 방식)

• 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의 이 단락을 업데이트하면 됩니다.

규정 준수 선언(중요)

• 제조사/타사 소스 코드 미포함 : 본 프로젝트는 폐쇄형 Huiwen/Libsys의 독립 상호운용 계층으로, Huiwen 또는 연합 측의 독점 코드를 포함하지 않습니다. OPAC/연합 계약은 공개 웹 페이지 프로토콜과 실제 사이트 응답 기록에만 기반합니다. 자세한 내용은 NOTICE를 참조하세요.

• 저장소에 배포 민감 데이터 미포함 : 실제 DSN, 계정 비밀번호, OPAC 로그인 인스턴스, 연합 JWT, 독자 PII, 제조사 SECRET_KEY 등은 저장소 내에 없습니다(SECURITY.md/CONTRIBUTING.md에 이미 레드라인이 설정되어 의심스러운 민감 데이터의 저장소 유입을 엄격히 금지합니다).

• 상표 : Huiwen, Libsys, OPAC은 각각 Jiangsu Huiwen Software 등의 권리자의 상표/제품명이며, 본 저장소는 상호운용 지칭 목적으로만 사용하며 보증이나 연관을 암시하지 않습니다.

• 본 소프트웨어를 사용하기 전에 Huiwen Software, 연합 서비스 제공자 및 귀관의 정보 센터와 권한 및 사용 범위를 확인하시기 바랍니다.

문제 해결