korea-scholarship-mcp

Un servidor FastMCP stdio que expone dos servicios bibliográficos coreanos — el Korea Citation Index (KCI, 한국학술지인용색인, National Research Foundation of Korea) y Open Access Korea (OAK, 오픈액세스코리아, National Library of Korea) — como ocho herramientas para Claude Desktop y otros clientes MCP.

Es la contraparte coreana de cinii-mcp y jstage-mcp y devuelve el mismo sobre de respuesta, de modo que los tres pueden leerse lado a lado en un trabajo trilateral.

Herramientas

Cuatro de las ocho funcionan sin credenciales — todo lo de OAI-PMH, más el estado.

Related MCP server: Literatür MCP

Qué son realmente las fuentes

KCI indexa artículos en revistas académicas registradas en Corea. No indexa monografías, capítulos ni disertaciones. Su interfaz REST es una interfaz de consulta genuina; su interfaz OAI-PMH no lo es.

OAK agrega repositorios institucionales coreanos — informes de investigación, tesis, monografías, fondos 고서, artículos de acceso abierto — contribuidos de manera desigual por las instituciones miembros.

Ambos fueron probados en vivo el 19 de agosto de 2026, y tres propiedades dan forma a cómo están escritas las herramientas:

1. Las marcas de fecha OAI son fechas de ingesta, no fechas de publicación. Una ventana de cosecha de mayo de 2019 devuelve artículos publicados entre 2010 y 2015. La afirmación repetida a menudo de que el feed OAI de KCI solo expone material reciente es una mala lectura de esto: el feed cubre el corpus, simplemente no tiene forma de que se le pregunte nada. kci_harvest por lo tanto filtra en el cliente y lo dice en un diagnóstico en cada llamada.

1a. El oai_dc de KCI está completamente tipado, y este servidor lee los tipos. Medido sobre 500 registros en vivo: identifier[type=artiId|uci|doi|citedCnt|regularity|journalInfo], un atributo issn= en 500/500, y lang="original|english" en cada título y descripción. La versión 0.2.0 afirmaba lo contrario — "una bolsa posicional sin tipos" para emparejar por patrón — y en consecuencia descartaba cada ISSN, cada resumen y 371 DOIs reales por cada 500 registros. El emparejamiento por patrón sobrevive solo como respaldo para identificadores que llegan sin etiquetar. Nótese que KCI también emite elementos type="doi" que contienen solo el prefijo del resolver; esos se normalizan a null en lugar de pasarse como identificadores.

2. OAK no envía resumptionToken. Declara noSetHierarchy, honra from/until, y limita una ventana a aproximadamente 99 registros sin continuación. Un cosechador que confíe en el protocolo presentará silenciosamente una ventana truncada como completa. oak_harvest lanza OAI_WINDOW_TRUNCATED cuando alcanza el límite y te dice que dividas la ventana.

3. OAK no es Dublin Core estándar. Emite dc:title_h, dc:abstract_e, dc:publish_date, dc:location_org, dc:deep_link, dc:contents_url, y pone el tipo de material en dc:keyword. La presencia de campos varía según el repositorio contribuyente. Los campos no reconocidos se conservan bajo extra.raw_fields en lugar de descartarse.

Dos asimetrías adicionales se informan en lugar de suavizarse:

• El articleSearch de KCI acepta keyword como campo de búsqueda pero omite las palabras clave del autor, ISSN y UCI de su respuesta. Una lista de palabras clave vacía es un artefacto del endpoint. kci_search lo dice en cada llamada; kci_article las recupera.

• KCI responde HTTP 200 en caso de error, poniendo el error en outputData/result/resultMsg. Un cliente que verifica los códigos de estado informa una clave no registrada como una búsqueda vacía exitosa.

El sobre de respuesta

Cada herramienta devuelve el sobre documentado en mediation.py (esquema 2.1.0) — query/script tipados, matching_mode, breadth graduado, matched_in por elemento, diagnostics tipados, un receipt registrable, y attribution. Nada se resume o puntúa por ti.

mediation.py 2.2.0 es la reconciliación de una bifurcación. Hasta el 19 de agosto de 2026, dos archivos diferentes se llamaban a sí mismos 2.1.0: la copia japonesa tenía emit() — persistencia de libro mayor — pero clasificaba el hangul como latin; la copia coreana conocía el hangul y las extensiones CJK pero no tenía emit(), por lo que las consultas coreanas nunca llegaban al depósito que toda consulta japonesa ingresaba. 2.2.0 lleva ambos, y está vendido byte-idéntico en cinii-mcp, jstage-mcp, ndl-mcp y este servidor. Todo en él es aditivo, por lo que los servidores japoneses lo adoptan sin migración.

• detect_script() reconoce hangul y las extensiones CJK B–G más el Suplemento de Compatibilidad.

• title y source llevan una ranura ko junto a ja.

• emit() deposita el sobre en el libro mayor de consultas encadenado por hash; ledger_available() informa si puede hacerlo, en lugar de dejar un no-op silencioso.

title.romanized permanece null a menos que la fuente proporcione una romanización. Ni KCI ni OAK lo hacen, y este servidor no generará una: la Romanización Revisada de un nombre coreano requiere conocer el nombre, y una cadena transliterada por máquina presentada como dato bibliográfico es una fabricación con la forma de un hecho.

Códigos de diagnóstico

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

Requisitos previos

• Python 3.10+ en PATH.

• Opcionalmente, una clave API de KCI — gratuita, auto-registrada, requerida solo para las cuatro herramientas REST.

Cómo obtener una clave KCI

1. Regístrate en open.kci.go.kr y solicita una clave de Open API.

2. La misma clave sirve para los cinco valores de apiCode (articleSearch, articleDetail, referenceSearch, citation, citationDetail).

KCI también está reflejado como cuatro conjuntos de datos en data.go.kr bajo 한국연구재단; esa ruta emite una clave diferente y no se usa aquí.

Instalación

El paquete usa una estructura src/ e instala un script de consola. Cualquiera de estas opciones funciona:

# 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

Instalar pone un comando korea-scholarship-mcp en PATH. python -m korea_scholarship_mcp es equivalente.

Configuración

cp .env.example .env

KCI_API_KEY=your_kci_api_key_here

Claude Desktop

Si el paquete está instalado, apunta al script de consola:

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

O ejecútalo desde un clon sin instalar:

{
  "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"
      }
    }
  }
}

Omite el bloque env por completo para ejecutar las cuatro herramientas sin clave.

Una nota sobre el SDK de MCP

mcp 2.0.0 eliminó mcp.server.fastmcp. Este servidor importa FastMCP donde existe y recurre a MCPServer donde no, por lo que funciona en ambos. El mismo shim se aplicó a cinii-mcp y jstage-mcp el 19 de agosto de 2026; antes de eso, ambos importaban mcp.server.fastmcp directamente mientras fijaban mcp[cli]>=1.2.0 sin límite superior, por lo que una instalación nueva de cualquiera de ellos resolvía a 2.0.0 y fallaba en la importación.

Manejo de credenciales

La clave KCI viaja en la cadena de consulta, lo que la hace propensa a fugas de dos maneras específicas que este servidor cierra:

• httpx registra cada URL de solicitud en INFO. _silence_http_logging() lo silencia y elimina cualquier manejador de stdout — necesario de todos modos, ya que stdout lleva JSON-RPC.

• Las excepciones de transporte y estado incrustan la URL de la solicitud. Cada mensaje destinado al cliente pasa por _redact(), y el recibo se construye a partir de parámetros con las credenciales eliminadas en lugar de enmascaradas.

Pruebas

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

Las pruebas en vivo protegen las afirmaciones en las que se basa este README: que una ventana de ingesta de KCI devuelve publicaciones más antiguas, que los identificadores de KCI están tipados, que max_records es un límite en lugar de una sugerencia, y que una cosecha con reanudación no registra una ventana de fechas que nunca envió. La prueba de OAK está separada y falla ruidosamente si OAK es inalcanzable en lugar de pasar en una rama no ejercitada.

Límites conocidos

Las cuatro herramientas REST de KCI nunca han visto una respuesta en vivo — no hay clave API. Su mapeo de campos sigue la documentación publicada y no está verificado contra el cable; la prueba de éxito/fracaso es deliberadamente estructural (registros presentes significa éxito) para que ni un mensaje de éxito locuaz ni un rechazo breve se lean mal. Trata la salida REST como provisional hasta que exista una clave.

Lo que este servidor no cubre

ScienceON (KISTI) — deliberadamente fuera de alcance. Su puerta de enlace requiere un token AES-256-CBC construido a partir de una dirección MAC registrada, más una IP pública registrada. rubato103/scienceon-mcp ya lo implementa contra credenciales en vivo y está endurecido contra la ruta exacta de fuga de credenciales descrita anteriormente; instálalo junto a este en lugar de duplicar código de autenticación no comprobable:

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

RISS (KERIS) — la API de búsqueda existe en https://www.riss.kr/openApi y cubre tesis, artículos nacionales y extranjeros, monografías, informes de investigación y publicaciones periódicas, pero las claves se emiten solo a instituciones sin fines de lucro y universidades coreanas, cada solicitud aprobada por el personal de KERIS; los individuos no pueden solicitarlas. Si una universidad no coreana califica no está probado. Si alguna vez se obtiene una clave, RISS pertenece a este servidor.

DBpia (Nurimedia) — las claves son abiertas y generosas (2,500 llamadas al día), pero los términos de uso restringen el servicio a fines no comerciales y prohíben copiar, almacenar o transmitir los resultados de búsqueda, que deben mostrarse en tiempo real y sin alteraciones. Eso es incompatible con la cosecha en un gestor de referencias, un índice de corpus o un registro. La restricción es la licencia, no la API.

korea_sources_status informa los tres en el lugar, por lo que la omisión es visible desde dentro de la herramienta en lugar de solo en este archivo.

Reglas de uso

• KCI y OAK son servicios del sector público sin límite de tasa publicado. Cosecha con consideración; divide las ventanas en lugar de golpear rangos amplios.

• Los metadatos recuperados aquí son bibliográficos. El texto completo está detrás de los términos que establezca el repositorio que lo aloja — la contents_url de OAK apunta a repositorios miembros, cada uno con su propia licencia.

• Las cadenas de atribución se devuelven en cada sobre; llévalas a cualquier cosa que publiques.

Cita

Si este software apoya tu investigación, por favor cítalo. Consulta CITATION.cff, o usa el botón "Cite this repository" en GitHub.

Licencia

MIT © 2026 Christopher Gerteis.

Esta licencia cubre únicamente el código del servidor. No otorga ningún derecho sobre los datos de KCI o OAK, que siguen rigiéndose por los términos de la National Research Foundation of Korea y la National Library of Korea, respectivamente.

Descargo de responsabilidad

Una herramienta de investigación, mantenida sobre la base del mejor esfuerzo y proporcionada "tal cual", sin garantía. No está afiliada ni respaldada por la National Research Foundation of Korea, la National Library of Korea, KERIS, KISTI ni Nurimedia.

Autor

Dr Christopher Gerteis, SOAS University of London.