korea-scholarship-mcp

Сервер FastMCP stdio, предоставляющий две корейские библиографические службы — Korea Citation Index (KCI, 한국학술지인용색인, Национальный исследовательский фонд Кореи) и Open Access Korea (OAK, 오픈액세스코리아, Национальная библиотека Кореи) — в виде восьми инструментов для Claude Desktop и других MCP-клиентов.

Это корейский аналог cinii-mcp и jstage-mcp, возвращающий ту же обёртку ответа, так что все три можно читать бок о бок в трёхсторонней работе.

Инструменты

Четыре из восьми работают вообще без учётных данных — всё OAI-PMH, а также статус.

Related MCP server: Literatür MCP

Что представляют собой источники на самом деле

KCI индексирует статьи в корейских рецензируемых журналах. Он не индексирует монографии, главы или диссертации. Его REST-интерфейс — это настоящий интерфейс запросов; его интерфейс OAI-PMH — нет.

OAK агрегирует корейские институциональные репозитории — отчёты об исследованиях, диссертации, монографии, фонды 고서, статьи открытого доступа — неравномерно пополняемые учреждениями-участниками.

Обе службы были протестированы вживую 19 августа 2026 года, и три свойства определяют, как написаны инструменты:

1. Метки времени OAI — это даты поступления, а не публикации. Окно сбора за май 2019 года возвращает статьи, опубликованные в период с 2010 по 2015 год. Часто повторяемое утверждение, что канал OAI KCI раскрывает только недавние материалы, является неверным прочтением этого: канал охватывает весь корпус, просто его невозможно ни о чём спросить. Поэтому kci_harvest фильтрует на стороне клиента и сообщает об этом в диагностике при каждом вызове.

1a. oai_dc у KCI полностью типизирован, и этот сервер читает типы. По результатам измерений на 500 живых записях: identifier[type=artiId|uci|doi|citedCnt|regularity|journalInfo], атрибут issn= в 500/500 и lang="original|english" в каждом заголовке и описании. Версия 0.2.0 утверждала обратное — «позиционный нетипизированный мешок», который нужно сопоставлять по шаблону, — и, следовательно, отбрасывала все ISSN, все аннотации и 371 реальный DOI на 500 записей. Сопоставление по шаблону остаётся только как запасной вариант для идентификаторов, поступающих без тегов. Обратите внимание, что 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, а не отбрасываются.

Ещё две асимметрии сообщаются, а не сглаживаются:

• articleSearch в KCI принимает 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 — это примирение форка. До 19 августа 2026 года два разных файла называли себя 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() сообщает, может ли он это сделать, а не оставляет молчаливую заглушку.

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

Предварительные требования

• Python 3.10+ в PATH.

• Необязательно ключ API KCI — бесплатный, регистрируется самостоятельно, требуется только для четырёх инструментов 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

Установка помещает команду 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, чтобы запустить четыре инструмента без ключа.

Примечание об MCP SDK

mcp 2.0.0 удалил mcp.server.fastmcp. Этот сервер импортирует FastMCP, где он есть, и возвращается к MCPServer, где его нет, поэтому он работает в любом случае. Тот же самый шим был применён к cinii-mcp и jstage-mcp 19 августа 2026 года; до этого оба импортировали mcp.server.fastmcp напрямую, закрепляя mcp[cli]>=1.2.0 без верхней границы, поэтому свежая установка любого из них разрешалась в 2.0.0 и падала при импорте.

Обработка учётных данных

Ключ KCI передаётся в строке запроса, что делает его уязвимым для утечки двумя конкретными способами, которые этот сервер закрывает:

• httpx регистрирует каждый URL запроса на уровне INFO. _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) — намеренно вне области охвата. Его шлюз требует токен AES-256-CBC, созданный из зарегистрированного MAC-адреса, а также зарегистрированный публичный 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) — ключи открыты и щедры (2500 вызовов в день), но условия использования ограничивают сервис некоммерческими целями и запрещают копирование, хранение или передачу результатов поиска, которые должны отображаться в реальном времени и без изменений. Это несовместимо со сбором в менеджер ссылок, индекс корпуса или реестр. Ограничение — это лицензия, а не API.

korea_sources_status сообщает обо всех трёх на месте, так что упущение видно изнутри инструмента, а не только в этом файле.

Правила использования

• KCI и OAK — государственные сервисы без опубликованного лимита запросов. Собирайте данные благоразумно; нарезайте окна, а не долбите по широким диапазонам.

• Метаданные, полученные здесь, являются библиографическими. Полный текст находится на условиях, установленных репозиторием-держателем — contents_url OAK указывает на репозитории-участники, каждый со своей лицензией.

• Строки атрибуции возвращаются в каждой обёртке; переносите их в любые публикации.

Цитирование

Если это программное обеспечение поддерживает ваше исследование, пожалуйста, процитируйте его. См. CITATION.cff или используйте кнопку «Cite this repository» на 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.