korea-scholarship-mcp

한국 인용 색인(KCI, 한국학술지인용색인, 한국연구재단)과 오픈액세스코리아(OAK, 오픈액세스코리아, 국립중앙도서관)라는 두 한국 서지 서비스를 Claude Desktop 및 기타 MCP 클라이언트용 8개 도구로 노출하는 FastMCP stdio 서버입니다.

cinii-mcp 및 jstage-mcp의 한국어 대응 서버이며, 동일한 응답 봉투를 반환하므로 3개를 3자 작업에서 나란히 읽을 수 있습니다.

도구

8개 중 4개는 자격 증명 없이 작동합니다 — 모든 OAI-PMH 및 상태.

Related MCP server: Literatür MCP

소스의 실제 성격

KCI는 한국 등재 학술지의 논문을 색인합니다. 단행본, 장, 학위논문은 색인하지 않습니다. REST 인터페이스는 진정한 질의 인터페이스이며, OAI-PMH 인터페이스는 그렇지 않습니다.

OAK는 한국 기관 리포지토리 — 연구 보고서, 학위논문, 단행본, 고서 소장, OA 논문 — 를 회원 기관이 불균등하게 기여한 형태로 통합합니다.

둘 다 2026년 8월 19일에 실시간으로 조사되었으며, 세 가지 속성이 도구 작성 방식을 결정합니다:

1. OAI 날짜 스탬프는 수집일이지 발행일이 아닙니다. 2019년 5월 수집 창은 2010년에서 2015년 사이에 발행된 논문을 반환합니다. KCI의 OAI 피드가 최근 자료만 노출한다는 자주 반복되는 주장은 이를 오독한 것입니다: 피드는 전체 컬렉션을 다루지만, 질의할 방법이 없을 뿐입니다. 따라서 kci_harvest는 클라이언트 측에서 필터링하며 매 호출마다 진단에서 이를 명시합니다.

1a. KCI의 oai_dc는 완전히 유형화되어 있으며, 이 서버는 유형을 읽습니다. 500개 실시간 레코드로 측정: identifier[type=artiId|uci|doi|citedCnt|regularity|journalInfo], 500/500에서 issn= 속성, 모든 제목과 설명에서 lang="original|english". 버전 0.2.0은 반대를 주장했습니다 — 패턴으로 일치시킬 "위치 기반, 유형 없는 묶음" — 따라서 모든 ISSN, 모든 초록, 500개 레코드당 371개의 실제 DOI를 버렸습니다. 패턴 일치는 유형 태그 없이 도착하는 식별자에 대한 대체 수단으로만 남아 있습니다. KCI는 또한 해석자 접두사만 포함하는 type="doi" 요소를 내보냅니다. 이는 식별자로 전달되지 않고 null로 정규화됩니다.

2. OAK는 resumptionToken을 보내지 않습니다. noSetHierarchy를 선언하고 from/until을 존중하며, 창을 약 99개 레코드로 제한하고 연속이 없습니다. 프로토콜을 신뢰하는 수집기는 잘린 창을 완전한 창으로 조용히 제시할 것입니다. oak_harvest는 한도에 도달하면 OAI_WINDOW_TRUNCATED를 발생시키고 창을 분할하라고 알려줍니다.

3. OAK는 표준 Dublin Core가 아닙니다. dc:title_h, dc:abstract_e, dc:publish_date, dc:location_org, dc:deep_link, dc:contents_url을 내보내고 자료 유형을 dc:keyword에 넣습니다. 필드 존재 여부는 기여 리포지토리에 따라 다릅니다. 인식되지 않은 필드는 버려지지 않고 extra.raw_fields 아래에 보존됩니다.

두 가지 추가 비대칭은 매끄럽게 처리되지 않고 보고됩니다:

• KCI의 articleSearch는 keyword를 검색 필드로 받아들이지만 응답에서 저자 키워드, ISSN 및 UCI를 생략합니다. 빈 키워드 목록은 엔드포인트의 산물입니다. kci_search는 매 호출마다 이를 명시합니다. kci_article은 이를 복구합니다.

• KCI는 실패 시 HTTP 200으로 응답하며 오류를 outputData/result/resultMsg에 넣습니다. 상태 코드를 확인하는 클라이언트는 등록되지 않은 키를 성공적인 빈 검색으로 보고합니다.

응답 봉투

모든 도구는 mediation.py(스키마 2.1.0)에 문서화된 봉투를 반환합니다 — 유형화된 query/script, matching_mode, 단계적 breadth, 항목별 matched_in, 유형화된 diagnostics, 로깅 가능한 receipt, attribution. 어떤 것도 요약되거나 점수화되지 않습니다.

mediation.py 2.2.0은 포크의 조정입니다. 2026년 8월 19일까지 두 개의 다른 파일이 모두 스스로를 2.1.0이라고 불렀습니다: 일본어 사본에는 emit() — 원장 지속성 — 이 있었지만 한글을 latin으로 분류했습니다. 한국어 사본은 한글과 CJK 확장을 알았지만 emit()이 없어 한국어 질의는 모든 일본어 질의가 들어간 예치에 도달하지 못했습니다. 2.2.0은 둘 다를 담고 있으며 cinii-mcp, jstage-mcp, ndl-mcp 및 이 서버에 바이트 단위로 동일하게 벤더링됩니다. 그 안의 모든 것은 추가적이므로 일본어 서버는 마이그레이션 없이 채택합니다.

• detect_script()는 한글과 CJK 확장 B–G 및 호환 보충을 인식합니다.

• title과 source는 ja 옆에 ko 슬롯을 담습니다.

• emit()은 봉투를 해시 체인 질의 원장에 예치합니다. ledger_available()은 조용한 no-op 대신 가능한지 보고합니다.

title.romanized는 소스가 로마자 표기를 제공하지 않는 한 null로 유지됩니다. KCI와 OAK 모두 제공하지 않으며, 이 서버는 생성하지 않습니다: 한국 이름의 개정 로마자 표기는 이름을 알아야 하며, 기계 번역된 문자열을 서지 데이터로 제시하는 것은 사실의 형태를 가진 조작입니다.

진단 코드

OK · NO_KEY · KCI_REJECTED · KCI_KEYWORDS_ABSENT · ZERO_CONJUNCTION · TRUNCATED · PAGE_PAST_END · REFERENCE_DEPOSIT_UNEVEN · BIBLIOMETRIC_SCOPE · SCRIPT_LATIN_QUERY · INGEST_DATE_NOT_PUBLICATION_DATE · CLIENT_SIDE_FILTER · OAI_MORE_AVAILABLE · OAI_INCOMPLETE · OAI_STALLED · OAI_PAGE_CAP · OAI_NO_RECORDS · OAI_ERROR · OAI_WINDOW_TRUNCATED · OAK_NONSTANDARD_DC · WINDOW_DOMINATED_BY_ONE_REPOSITORY · REDIRECTED · TRANSPORT_ERROR · API_ERROR · PARSE_ERROR

사전 요구 사항

• PATH에 Python 3.10+.

• 선택적으로 KCI API 키 — 무료, 자체 등록, 4개의 REST 도구에만 필요.

KCI 키 얻기

1. open.kci.go.kr에 등록하고 Open API 키를 신청합니다.

2. 동일한 키가 모든 5개 apiCode 값(articleSearch, articleDetail, referenceSearch, citation, citationDetail)에 사용됩니다.

KCI는 또한 data.go.kr에 한국연구재단 아래 4개 데이터셋으로 미러링됩니다. 해당 경로는 다른 키를 발급하며 여기서 사용되지 않습니다.

설치

패키지는 src/ 레이아웃을 사용하며 콘솔 스크립트를 설치합니다. 다음 중 아무거나 작동합니다:

# from a release archive
pip install korea-scholarship-mcp.zip

# from a built wheel
pip install korea_scholarship_mcp-0.4.0-py3-none-any.whl

# from a clone, for development
pip install -e ".[dev]"

# without installing anything, straight from the repository
uvx --from "git+https://github.com/ckgerteis/korea-scholarship-mcp" korea-scholarship-mcp

설치하면 korea-scholarship-mcp 명령이 PATH에 추가됩니다. python -m korea_scholarship_mcp도 동일합니다.

구성

cp .env.example .env

KCI_API_KEY=your_kci_api_key_here

Claude Desktop

패키지가 설치된 경우 콘솔 스크립트를 가리킵니다:

{
  "mcpServers": {
    "korea-scholarship": {
      "command": "C:\\path\\to\\.venv\\Scripts\\korea-scholarship-mcp.exe",
      "env": {
        "KCI_API_KEY": "your_kci_api_key_here"
      }
    }
  }
}

또는 설치 없이 클론에서 실행:

{
  "mcpServers": {
    "korea-scholarship": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["-m", "korea_scholarship_mcp"],
      "env": {
        "KCI_API_KEY": "your_kci_api_key_here"
      }
    }
  }
}

env 블록을 완전히 생략하면 4개의 키 없는 도구를 실행할 수 있습니다.

MCP SDK에 대한 참고

mcp 2.0.0은 mcp.server.fastmcp를 제거했습니다. 이 서버는 FastMCP가 존재하는 곳에서 가져오고, 존재하지 않는 곳에서 MCPServer로 대체하므로 둘 중 하나에서 실행됩니다. 동일한 shim이 2026년 8월 19일에 cinii-mcp와 jstage-mcp에 적용되었습니다. 그 전에는 둘 다 mcp.server.fastmcp를 직접 가져오면서 mcp[cli]>=1.2.0을 상한 없이 고정했으므로, 둘 중 하나를 새로 설치하면 2.0.0으로 해석되어 가져오기에서 실패했습니다.

자격 증명 처리

KCI 키는 쿼리 문자열로 전달되므로 이 서버가 차단하는 두 가지 특정 방식으로 누출되기 쉽습니다:

• httpx는 모든 요청 URL을 INFO로 기록합니다. _silence_http_logging()은 이를 음소거하고 stdout 핸들러를 제거합니다 — stdout이 JSON-RPC를 전달하므로 어차피 필요합니다.

• 전송 및 상태 예외는 요청 URL을 포함합니다. 클라이언트로 향하는 모든 메시지는 _redact()를 통과하며, receipt는 자격 증명이 마스킹되지 않고 제거된 매개변수로 구성됩니다.

테스트

python -m pytest tests -q                # offline, against fixtures captured 19 Aug 2026
RUN_LIVE=1 python -m pytest tests -q     # also exercises the live KCI endpoints
RUN_LIVE_OAK=1 python -m pytest tests -q # adds OAK; needs a network that reaches oak.go.kr

라이브 테스트는 이 README가 의존하는 주장을 보호합니다: KCI 수집 창이 오래된 출판물을 반환한다는 것, KCI의 식별자가 유형화되어 있다는 것, max_records가 힌트가 아닌 상한이라는 것, 재개 수집이 보내지 않은 날짜 창을 기록하지 않는다는 것. OAK 테스트는 별도로 게이트되며 OAK에 도달할 수 없으면 실행되지 않은 분기에서 통과하는 대신 크게 실패합니다.

알려진 한계

4개의 KCI REST 도구는 실시간 응답을 본 적이 없습니다 — API 키가 없습니다. 필드 매핑은 게시된 문서를 따르며 와이어에 대해 검증되지 않았습니다. 성공/실패 테스트는 의도적으로 구조적입니다(레코드 존재는 성공을 의미) — 수다스러운 성공 메시지나 간결한 거부를 오독하지 않도록. 키가 생길 때까지 REST 출력을 잠정적으로 취급하십시오.

이 서버가 다루지 않는 것

ScienceON (KISTI) — 의도적으로 범위 밖. 게이트웨이는 등록된 MAC 주소와 등록된 공용 IP로 구축된 AES-256-CBC 토큰을 요구합니다. rubato103/scienceon-mcp는 이미 실시간 자격 증명으로 구현되었으며 위에서 설명한 정확한 자격 증명 누출 경로에 대해 강화되었습니다. 테스트 불가능한 인증 코드를 복제하는 대신 함께 설치하십시오:

claude mcp add scienceon -- uvx --from "git+https://github.com/rubato103/scienceon-mcp" scienceon-mcp

RISS (KERIS) — 검색 API는 https://www.riss.kr/openApi에 존재하며 학위논문, 국내외 논문, 단행본, 연구 보고서, 연속 간행물을 다루지만 키는 한국 비영리 기관과 대학에만 발급되며 각 신청은 KERIS 직원이 승인합니다. 개인은 신청할 수 없습니다. 비한국 대학이 자격이 되는지는 테스트되지 않았습니다. 키를 얻으면 RISS는 이 서버에 속합니다.

DBpia (누리미디어) — 키는 개방적이고 넉넉하지만(하루 2,500회 호출), 이용 약관은 서비스를 비상업적 목적으로 제한하고 검색 결과를 복사, 저장 또는 전송하는 것을 금지하며, 실시간으로 변경 없이 표시해야 합니다. 이는 참고 관리자, 컬렉션 색인 또는 레지스터로 수집하는 것과 호환되지 않습니다. 제약은 API가 아니라 라이선스입니다.

korea_sources_status는 이 세 가지를 모두 현장에서 보고하므로 생략이 이 파일에서만이 아니라 도구 내부에서도 보입니다.

사용 규칙

• KCI와 OAK는 게시된 속도 제한이 없는 공공 부문 서비스입니다. 신중하게 수집하고 넓은 범위를 두드리기보다 창을 분할하십시오.

• 여기서 검색된 메타데이터는 서지적입니다. 전문은 보유 리포지토리가 설정한 조건에 따라 달라집니다 — OAK의 contents_url은 각각 자체 라이선스가 있는 회원 리포지토리를 가리킵니다.

• 귀속 문자열은 모든 봉투에 반환됩니다. 게시된 모든 것에 이를 포함하십시오.

인용

이 소프트웨어가 연구를 지원한다면 인용해 주십시오. CITATION.cff를 참조하거나 GitHub의 "Cite this repository" 버튼을 사용하십시오.

라이선스

MIT © 2026 Christopher Gerteis.

이 라이선스는 서버 코드에만 적용됩니다. KCI 또는 OAK 데이터에 대한 권한은 부여되지 않으며, 해당 데이터는 각각 한국연구재단과 국립중앙도서관의 약관에 따릅니다.

면책 조항

연구 도구로, 최선을 다해 유지관리되며 보증 없이 "있는 그대로" 제공됩니다. 한국연구재단, 국립중앙도서관, KERIS, KISTI 또는 누리미디어와 제휴하거나 보증하지 않습니다.

저자

Dr Christopher Gerteis, SOAS University of London.