korea-scholarship-mcp

一个FastMCP stdio服务器，将两项韩国文献服务——韩国引文索引（KCI，한국학술지인용색인，韩国研究财团）和开放获取韩国（OAK，오픈액세스코리아，韩国国立中央图书馆）——作为八个工具提供给Claude Desktop及其他MCP客户端。

它是cinii-mcp和jstage-mcp的韩国对应版本，返回相同的响应封装格式，因此三者可在三方工作中并排阅读。

工具

八个工具中有四个完全无需凭据即可使用——所有OAI-PMH相关工具，以及状态工具。

Related MCP server: Literatür MCP

这些来源的实际内容

KCI索引韩国注册学术期刊中的文章。它不索引专著、章节或学位论文。其REST接口是真正的查询接口；其OAI-PMH接口则不是。

OAK聚合韩国机构知识库——研究报告、学位论文、专著、고서馆藏、开放获取文章——由成员机构不均衡地贡献。

两者均于2026年8月19日进行了实时探测，三个特性决定了工具的编写方式：

1. OAI日期戳是入库日期，而非出版日期。 2019年5月的抓取窗口返回的是2010年至2015年间出版的文章。关于KCI的OAI feed仅暴露近期材料的常见说法是对此的误读：该feed覆盖整个语料库，只是无法被“询问”任何内容。因此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不是标准都柏林核心。 它发出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（schema 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携带ko槽位，与ja并列。

• 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密钥——免费、自行注册，仅四个REST工具需要。

获取KCI密钥

1. 在open.kci.go.kr注册并申请Open API密钥。

2. 同一密钥服务所有五个apiCode值（articleSearch、articleDetail、referenceSearch、citation、citationDetail）。

KCI还作为四个数据集在data.go.kr上以한국연구재단名义镜像；该途径发出不同的密钥，此处不使用。

安装

该包使用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

安装后会在PATH上放置korea-scholarship-mcp命令。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块即可运行四个无密钥工具。

关于MCP SDK的说明

mcp 2.0.0移除了mcp.server.fastmcp。本服务器在存在FastMCP时导入它，在不存在时回退到MCPServer，因此它可以在任一版本上运行。相同的垫片已于2026年8月19日应用于cinii-mcp和jstage-mcp；在此之前，两者都直接导入mcp.server.fastmcp，同时固定mcp[cli]>=1.2.0且无上限，因此任一者的全新安装都会解析到2.0.0并在导入时失败。

凭据处理

KCI密钥在查询字符串中传输，这使其在两种特定方式下容易泄漏，本服务器已关闭：

• httpx在INFO级别记录每个请求URL。_silence_http_logging()将其静音并剥离任何stdout处理器——无论如何都是必要的，因为stdout承载JSON-RPC。

• 传输和状态异常嵌入请求URL。每条发往客户端的消息都通过_redact()传递，收据由移除凭据的参数构建，而不是掩蔽。

测试

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不可达则大声失败，而不是在未执行的路径上通过。

已知限制

四个KCI REST工具从未见过实时响应——没有API密钥。它们的字段映射遵循已发布的文档，未针对线路进行验证；成功/失败测试刻意是结构性的（存在记录即成功），因此既不会将冗长的成功消息误读为拒绝，也不会将简短的拒绝误读为成功。在密钥存在之前，将REST输出视为临时性的。

本服务器未覆盖的内容

ScienceON（KISTI）——刻意排除在范围之外。其网关需要从注册的MAC地址构建的AES-256-CBC令牌，以及注册的公共IP。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（Nurimedia）——密钥开放且慷慨（每天2,500次调用），但使用条款将服务限制为非商业目的并且禁止复制、存储或传输搜索结果，这些结果应实时显示且不得更改。这与采集到参考管理器、语料库索引或注册表中不兼容。限制是许可证，而非API。

korea_sources_status在适当位置报告所有这三项，因此省略从工具内部可见，而不仅仅是在此文件中。

使用规则

• KCI和OAK是公共部门服务，没有已发布的速率限制。请谨慎采集；切片窗口而不是猛击宽范围。

• 此处检索的元数据是书目性的。全文位于持有仓库设定的任何条款之后——OAK的contents_url指向成员仓库，每个仓库都有自己的许可证。

• 每个封装中都返回归属字符串；将其携带到任何已发布的内容中。

引用

如果本软件支持您的研究，请引用它。请参阅CITATION.cff，或使用GitHub上的“引用此仓库”按钮。

许可证

MIT © 2026 Christopher Gerteis.

本许可证仅涵盖服务器代码。它不对 KCI 或 OAK 数据授予任何权利，这些数据仍分别受 National Research Foundation of Korea 和 National Library of Korea 的条款约束。

免责声明

这是一个研究工具，以尽力而为的方式维护，并按“原样”提供，不提供任何保证。与 National Research Foundation of Korea、National Library of Korea、KERIS、KISTI 或 Nurimedia 均无关联，也未获得其认可。

作者

Dr Christopher Gerteis，SOAS University of London。