KCI_openAPI CLAUDE.md

kci-openapi-mcp — 프로젝트 지침

한국연구재단(NRF) KCI(Korea Citation Index) 문헌·인용지수 검색·수집기. 공개 MCP 서버 + CLI. 자매 프로젝트 scienceON-mcp(../scienceon)와 동일 아키텍처. KCI는 두 가지 공개 인터페이스를 제공하며 본 프로젝트는 둘 다 다룬다:

• REST Open API(키워드 검색형, 인증키 필요) → docs/KCI_API_GUIDE.md
• OAI-PMH(대량 수확형, 인증키 불필요) → docs/KCI_OAI_PMH_GUIDE.md

1. 목표

연구 초반 자료수집 단계에서 반복 재사용하는 도구. KCI에서 논문 서지·초록·참고문헌·저널 인용지수를 검색·수집해 후속 텍스트마이닝/계량서지 입력 데이터를 안정적으로 생산한다. ScienceON(KISTI)과 상호보완: 수록 범위 교차검증, 국문 초록 백필, KCI 연구분야 분류·인용지수 확보.

2. 확정/계획 결정사항

항목	결정
언어/런타임	Python 3.10+
패키지 관리	uv (pyproject + uv.lock). venv는 클라우드 폴더 밖 C:/Users/user/.venvs/kci-openapi-mcp (UV_PROJECT_ENVIRONMENT)
의존성(계획)	mcp(FastMCP), requests, openpyxl, python-dotenv, pyyaml (pycryptodome 불필요 — KCI는 토큰/AES 없음)
인터페이스	공용 코어 + MCP 서버(server.py) + CLI(cli.py)
인터페이스(소스)	REST(openApiSearch.kci, 키 필요) + OAI-PMH(/oai/request, 무인증) — 둘 다 지원
수집 대상	논문(articleSearch/Detail) 우선 → 참고문헌(referenceSearch) → 저널 인용지수(citation/Detail) → OAI-PMH 대량수확
출력	xlsx · csv · json · sqlite
공개	MIT 예정. .env·reference/·output/는 gitignore

3. 구조 (scienceON-mcp 미러, 계획)

src/kci_mcp/
  config.py     # .env 로딩, Base URL/엔드포인트(REST + OAI)
  client.py     # REST GET / 페이징(page,displayCount≤100) / 재시도·throttle / 에러매핑
  oai_client.py # OAI-PMH GET(verb) / resumptionToken 루프 / 무인증
  parser.py     # XML 정규화 — REST(MetaData/outputData/record) + OAI(oai_dc/oai_kci), raw 보존
  models.py     # Article / Reference / JournalCitation 스키마(REST·OAI 공통)
  exporters.py  # xlsx/csv/json/sqlite (scienceON 재사용 가능)
  server.py     # MCP 도구 (아래 §5)
  cli.py        # status/search/detail/references/citation/harvest/collect
docs/
  KCI_API_GUIDE.md       # ★ REST API 명세 (PDF 복구본)
  KCI_OAI_PMH_GUIDE.md   # ★ OAI-PMH 명세 (PDF 복구본)
reference/
  KCI Open API Service 활용가이드.pdf   # 공식 원본 REST (gitignore, 비공개)
  KCI OAI-PMH 활용가이드.pdf            # 공식 원본 OAI-PMH (gitignore, 비공개)
config/         # 검색 설정 템플릿 (search.example.yaml)

※ 현재 폴더에는 docs/(가이드 2종) + reference/(PDF 2종)만 마이그레이션 완료. src/·config/·pyproject·mcpb는 개발 단계에서 생성.