kci-openapi-mcp

한국연구재단(NRF) KCI(Korea Citation Index) 문헌·인용지수 검색·수집 MCP 서버 + CLI. REST Open API(키워드 검색)와 OAI-PMH(무인증 대량 수확)를 혼용한다. 자매 프로젝트 scienceon-mcp(KISTI ScienceON)와 동일 아키텍처.

무엇을 하나

논문 검색·상세 (서지 · 국문/영문 초록 · 키워드 · 저자/소속)
OAI-PMH 대량 수확 (인증키 불필요 — 세트+날짜범위)
참고문헌 원형 수집 · 저널 인용지수/등재이력 (REST 전용)
대량 수집 → xlsx / csv / json / sqlite

두 인터페이스

	REST Open API	OAI-PMH
엔드포인트	`…/po/openapi/openApiSearch.kci`	`…/oai/request`
인증	`KCI_API_KEY` 필요	불필요
질의	키워드 검색(title 필수)	세트+날짜 대량 수확
인용지수·참고문헌	✅	❌
규격: docs/KCI_API_GUIDE.md · docs/KCI_OAI_PMH_GUIDE.md · 설계: docs/ARCHITECTURE.md

현재 상태

✅ 구현·REST/OAI 라이브 검증 완료 · pytest 24 + MCP 프로토콜 스모크 · 도구 annotations
✅ 공식 MCP 레지스트리 발행됨: io.github.rubato103/kci-openapi-mcp (registry.modelcontextprotocol.io 검색 가능)
✅ Claude Desktop 자체완결 .mcpb(win/mac/linux, Python·uv 불필요) + Claude Code .mcp.json
⚠️ mcp SDK는 1.x 고정(mcp>=1.2.0,<2) — 2.0 에서 mcp.server.fastmcp 가 제거되어 상한 없이는 기동 실패

MCP 클라이언트에 등록

Claude Code

프로젝트 루트의 .mcp.json 이 자동 인식된다(키는 환경변수로 주입):

export KCI_API_KEY=<발급키>   # 선택 — 없으면 OAI 무인증 도구만 동작
# 또는 어디서나:
claude mcp add kci --env KCI_API_KEY=$KCI_API_KEY -- uvx --from git+https://github.com/rubato103/KCI_openAPI kci-mcp

Claude Desktop

(권장) 자체완결 .mcpb — Python·uv 불필요, 더블클릭 설치: 릴리스에서 OS에 맞는 파일 다운로드 → 더블클릭(또는 Settings → Extensions → Install) → KCI_API_KEY 입력(선택).

Windows: kci-openapi-mcp-win-x64.mcpb / macOS: …-macos-arm64.mcpb / Linux: …-linux-x64.mcpb

(경량) kci-openapi-mcp.mcpb — 크기 작지만 실행에 uv 필요(uvx --from git+…).

(수동 config) %APPDATA%/Claude/claude_desktop_config.json:

{ "mcpServers": { "kci": {
  "command": "uvx",
  "args": ["--from", "git+https://github.com/rubato103/KCI_openAPI", "kci-mcp"],
  "env": { "KCI_API_KEY": "<발급키 또는 비움>", "KCI_OS_TRUST": "1" }
} } }

uvx (저장소에서 직접 실행)

uvx --from git+https://github.com/rubato103/KCI_openAPI kci-mcp   # MCP 서버(stdio)

PyPI에는 게시하지 않음 — 레지스트리 배포는 .mcpb(GitHub Release) 방식.

CLI (로컬 개발)

uv sync                    # venv는 UV_PROJECT_ENVIRONMENT 로 클라우드 폴더 밖 권장
kci identify               # OAI 무인증 — 키 없이 즉시
kci harvest --set ARTI --from 2024-01-01 --until 2024-12-31 --contains 학부모 --max 500
kci search --title 경계선지능 --rows 20   # REST(인증키 필요)
kci collect --config config/borderline_slow.yaml

MCP 도구 (7종)

kci_status · kci_search · kci_detail · kci_references · kci_journal_citation · kci_harvest · kci_collect kci_collect 은 요청 성격·키 유무로 REST↔OAI 자동 선택.

상세 조회 인자는 arti_id(KCI Control Number, 예: ART003047608).

알아둘 두 가지 (실측 확인)

articleSearch 는 keyword= 로 검색은 되지만 응답에 키워드·ISSN·UCI 를 싣지 않는다. 검색 결과의 빈 keywords 는 '키워드 없는 논문'이 아니다 — 필요하면 kci_detail 로 건별 보강.

kci_collect 의 REST 경로는 각 검색어를 제목축·키워드축 두 번 조회해 합집합한다. 결과는 '제목검색 결과'가 아니라 제목∪키워드다. meta.axes 에 축별 total 이 담기고, max_records 상한에 걸리면 truncated: true 와 경고 문구가 함께 온다.

자격증명 / 네트워크

KCI_API_KEY (open.kci.go.kr 발급) → .env(gitignore) 또는 OS 환경변수. 커밋·로그 금지. OAI는 키 불필요.
KCI 방화벽은 User-Agent 필터를 건다(curl 기본 UA는 400 차단 안내페이지). 본 서버는 requests 로 호출하므로 정상.
교육망/사내망 SSL 인터셉션은 truststore로 OS 신뢰저장소를 사용해 통과(검증 유지). KCI_OS_TRUST=0로 비활성.

라이선스

MIT

KCI_openAPI

Install to Claude Code

README