This server lets you search, retrieve, and harvest Korean scholarly metadata from KCI and OAK through eight MCP tools.
Search KCI articles by title, author, journal, keyword, abstract, DOI, affiliation, institution, and date range (kci_search).
Fetch full KCI records with abstracts, author keywords, ISSN, UCI, and affiliations (kci_article).
Retrieve works cited by a KCI article (kci_references) and journal-level citation metrics (kci_journal_metrics).
Harvest KCI records by ingest-date window with client-side filtering and resumption tokens — no API key required (kci_harvest).
Harvest Open Access Korea institutional repository records by ingest-date window (oak_harvest) and fetch a single OAK record by identifier (oak_record).
Check which Korean sources are configured, reachable, and what the server does not cover (korea_sources_status).
Four tools work without credentials; the KCI REST tools need a free KCI API key. All responses use a shared typed envelope with diagnostics and attribution.
Provides tools for searching and harvesting scholarly articles from Open Access Korea (OAK), a service aggregating Korean institutional repositories.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@korea-scholarship-mcp Search KCI for articles on Korean linguistics"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A FastMCP stdio server exposing two Korean bibliographic services — the Korea Citation Index (KCI, 한국학술지인용색인, National Research Foundation of Korea) and Open Access Korea (OAK, 오픈액세스코리아, National Library of Korea) — as eight tools for Claude Desktop and other MCP clients.
It is the Korean counterpart to cinii-mcp and jstage-mcp and returns the same response envelope, so the three can be read side by side in trilateral work.
Korean-language scholarship, through the Korea Citation Index and Open Access Korea.
Search KCI for articles in Korean-registered journals; pull a full record with its abstract, author keywords, ISSN and UCI; follow the works a given article cites; read journal-level citation metrics. OAK reaches the institutional repositories — theses, monographs, research reports, 고서 holdings and open-access articles contributed by member institutions. Half the tools need no credentials at all, so Korean material is reachable the moment the server is installed.
Records come back in the same response envelope the Japanese servers use, which is what makes genuinely trilateral work practical: Japanese, Korean and Anglophone scholarship on one question, read side by side in one format.
Related MCP server: Literatür MCP
A search you cannot re-run is a claim you cannot check. When a footnote rests on a database query, say that no article in this index uses a term before a certain year, the reader is asked to take the search on trust: which term, in which script, on what date, against which index and which version of it, and how far down the results the author went. Ordinary searching leaves none of that behind. This server leaves all of it. Every query-answering tool returns its envelope through the ledger, which appends one line to an append-only file: the term actually sent and its script, how the source matched it, how many records existed and how many came back, the diagnostics, the tool and its parameters, the server version, a timestamp, and the hash of the previous line. The hash makes the file a chain: a line cannot be altered, removed or reordered afterwards without the verifier saying so.
What that gives a researcher:
A citable search. Name the receipt in the footnote (session slug, server, date, line hash) and a reader can see exactly what was asked and run it again against the same version.
Negative findings that carry weight. "Not found" is evidence only if the search that produced it is on record, with its term, its script and its breadth.
A method section that writes itself. korea-scholarship-mcp-ledger manifest <folder> summarises every
query a project made, by server, script and session: the disclosure a journal, a
data-availability statement or a research-integrity review asks for.
A record of AI-mediated research. When a model chose the term, the receipt shows the term it chose and what came back, which is the thing to disclose about work done with an assistant.
Nothing interpreted. The receipt is the source's own answer with credentials removed. The server does not summarise, rank or paraphrase, so the record is of the source, not of the tool.
Receipts are off until you name a folder (MCP_RECEIPT_DIR); each server then writes its own
<server>.jsonl inside it, and MCP_RECEIPT_SESSION stamps a project or article slug on every
line so one folder can serve several projects. korea-scholarship-mcp-ledger verify-dir <folder> checks the chains.
The mechanics, the variables and what the envelope says when nothing is deposited are in the
receipts section below.
Tool | Source | Key required | Purpose |
| KCI REST | yes | Article search across title, author, journal, institution, affiliation, keyword, abstract, DOI, date range |
| KCI REST | yes | Full record by control number — the only endpoint carrying keywords, ISSN, UCI and abstracts |
| KCI REST | yes | Works cited by one article |
| KCI REST | yes | Journal citation indices (impact, immediacy, self-citation share) |
| KCI OAI-PMH | no | Harvest by ingest-date window, filter client-side, follow resumption tokens |
| OAK OAI-PMH | no | Harvest Korean institutional repositories by ingest-date window |
| OAK OAI-PMH | no | One OAK record by OAI identifier |
| — | — | What is configured, what is reachable, and what this server does not cover |
Four of the eight work with no credentials at all — everything OAI-PMH, plus status.
KCI indexes articles in Korean-registered scholarly journals. It does not index monographs, chapters, or dissertations. Its REST interface is a genuine query interface; its OAI-PMH interface is not.
OAK aggregates Korean institutional repositories — research reports, theses, monographs, 고서 holdings, OA articles — contributed unevenly by member institutions.
Both were probed live on 19 August 2026, and three properties shape how the tools are written:
OAI datestamps are ingest dates, not publication dates. A May 2019 harvest window returns articles published between 2010 and 2015. The often-repeated claim that KCI's OAI feed only exposes recent material is a misreading of this: the feed covers the corpus, it simply has no way to be asked anything. kci_harvest therefore filters client-side and says so in a diagnostic on every call.
1a. KCI's oai_dc is fully typed, and this server reads the types. Measured over 500 live records: identifier[type=artiId|uci|doi|citedCnt|regularity|journalInfo], an issn= attribute on 500/500, and lang="original|english" on every title and description. Version 0.2.0 asserted the opposite — "a positional, untyped bag" to be matched by pattern — and consequently discarded every ISSN, every abstract, and 371 real DOIs per 500 records. Pattern matching survives only as a fallback for identifiers that arrive untagged. Note that KCI also emits type="doi" elements containing nothing but the resolver prefix; those are normalised to null rather than passed through as identifiers.
OAK sends no resumptionToken. It declares noSetHierarchy, honours from/until, and caps a window at roughly 99 records with no continuation. A harvester that trusts the protocol will silently present a truncated window as a complete one. oak_harvest raises OAI_WINDOW_TRUNCATED when it hits the cap and tells you to slice the window.
OAK is not standard Dublin Core. It emits dc:title_h, dc:abstract_e, dc:publish_date, dc:location_org, dc:deep_link, dc:contents_url, and puts the material type in dc:keyword. Field presence varies by contributing repository. Unrecognised fields are preserved under extra.raw_fields rather than dropped.
Two further asymmetries are reported rather than smoothed over:
KCI's articleSearch accepts keyword as a search field but omits author keywords, ISSN and UCI from its response. An empty keywords list is an artefact of the endpoint. kci_search says so on every call; kci_article recovers them.
KCI answers HTTP 200 on failure, putting the error in outputData/result/resultMsg. A client that checks status codes reports an unregistered key as a successful empty search.
Every tool returns the envelope built by mediation.py and defined in response-schema.json, schema version 2.3.0 — typed query/script, matching_mode, graduated breadth, per-item matched_in, typed diagnostics, a loggable receipt, and attribution. Nothing is summarised or scored for you. kci_search also carries searched_for, the term actually sent with its detected script; the fetches and the harvests omit it, having chosen no term.
mediation.py 2.3.0 adds deposit reporting to 2.2.0, which was itself the reconciliation of a fork. Until 19 Aug 2026 two different files both called themselves 2.1.0: the Japanese copy had emit() — ledger persistence — but classified Hangul as latin; the Korean copy knew Hangul and the CJK extensions but had no emit(), so Korean queries never reached the deposit every Japanese query entered. 2.2.0 carries both, and is vendored byte-identical across cinii-mcp, jstage-mcp, ndl-mcp and this server. Everything in it is additive, so the Japanese servers adopt it without migration.
detect_script() recognises Hangul and CJK Extensions B–G plus the Compatibility Supplement.
title and source carry a ko slot alongside ja.
emit() deposits the envelope to the hash-chained query ledger; ledger_available() reports whether it can, rather than leaving a silent no-op. As of v0.4.1 every query-answering tool in this server returns through emit(), rejections included — a query issued and refused was still issued — so Korean queries now enter the same deposit every Japanese query enters. korea_sources_status is the one exception: it chooses no term and answers no corpus, so it serialises with dumps() and instead reports the deposit state. Note the second gate: the ledger writes nothing unless MCP_RECEIPT_DIR (a receipts folder, one hash-chained file per server) or the legacy MCP_RECEIPT_LOG is set, and korea_sources_status now says which of the two gates is closed when nothing is being written.
title.romanized stays null unless the source supplies a romanisation. Neither KCI nor OAK does, and this server will not generate one: Revised Romanisation of a Korean name requires knowing the name, and a machine-transliterated string presented as bibliographic data is a fabrication with the shape of a fact.
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 · RECEIPT_NOT_DEPOSITED · RECEIPT_WRITE_FAILED
Python 3.10+ on PATH.
Optionally, a KCI API key — free, self-registered, required only for the four REST tools.
Register at open.kci.go.kr and apply for an Open API key.
The same key serves all five apiCode values (articleSearch, articleDetail, referenceSearch, citation, citationDetail).
KCI is also mirrored as four datasets on data.go.kr under 한국연구재단; that route issues a different key and is not used here.
Three routes. All three give you the same server; pick by how much you want to see of it.
Python. The pip and source routes need Python 3.10 or later; 3.10, 3.12, 3.13 and 3.14 are tested in CI on Windows, macOS and Linux. The Claude Desktop bundle uses whichever of these is already installed, and has uv download one only if none is.
Every route needs Python 3.10 to 3.14. The Claude Desktop bundle uses one already on the machine
and has uv download one only if none is; the other routes also need the venv module, which the
official installers include.
Windows. Download the 64-bit installer from python.org/downloads
and run it; tick "Add python.exe to PATH" on the first screen. Afterwards py --version (the
launcher the installer adds) or python --version in a new terminal should print 3.1x. If typing
python opens the Microsoft Store instead, Windows has no Python yet: that Store page is a stub,
and it is also what "'python' is not recognized" usually means.
macOS. The python.org installer, or
brew install python@3.13 with Homebrew. The /usr/bin/python3 that Xcode's
command-line tools provide may be older than 3.10; python3 --version says.
Linux. Your distribution's package: sudo apt install python3 python3-venv on Debian and
Ubuntu, sudo dnf install python3 on Fedora. Or let uv provide one (next line).
Any platform, with uv. uv
installs Python itself: uv python install 3.13, then uv venv or the uvx route below.
Download korea-scholarship-mcp-0.6.1.mcpb from the latest release and open it; Claude Desktop installs it. One bundle serves Windows, macOS (Apple Silicon and Intel) and Linux. Claude Desktop asks for KCI API key and a receipts folder at install time; the key is stored in the OS keychain.
The bundle carries the server's source and a lock file, nothing compiled, and needs no Python of its own: Claude Desktop runs it with uv, using a uv already on your PATH if there is one and otherwise the copy the app ships. On first launch uv uses a Python 3.10 or later already on the machine, downloading one only if there is none, and installs the locked libraries: roughly 40 MB, or 60 MB with an interpreter, which took 26 to 46 seconds on the author's connection; later launches take under a second. If the first launch is slow enough that Claude Desktop reports the server disconnected, restart the app: what uv already fetched is cached, and the second launch completes. Bundles before 0.6.0 vendored libraries compiled for CPython 3.12 only and failed on every other interpreter; see Troubleshooting.
pip install "git+https://github.com/ckgerteis/korea-scholarship-mcp@v0.6.1"
# or, without an environment of your own:
uvx --from "git+https://github.com/ckgerteis/korea-scholarship-mcp@v0.6.1" korea-scholarship-mcpinstalls the korea-scholarship-mcp console script and korea-scholarship-mcp-ledger. The tag is the thing to cite; @main gets whatever is current. Then register it in Claude Desktop (below), or let install.py do that.
pip install "git+https://github.com/ckgerteis/bibliograph-mcp@v1.0.3" && bibliograph installinstalls all six servers and registers them together — one receipts folder, credentials asked for once. See bibliograph-mcp. From a checkout of this repository, python install.py does the same for this server alone, python install.py --all for the six, on Windows, macOS and Linux; install.ps1 remains for Windows.
# from a clone
pip install .
# from a built wheel, whatever its version
pip install dist/korea_scholarship_mcp-*.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-mcpInstalling puts a korea-scholarship-mcp command on PATH. python -m korea_scholarship_mcp is equivalent.
The package is namespaced, so it shares an environment with cinii-mcp,
jstage-mcp, ndl-mcp, openalex-mcp and semantic-scholar-mcp without
colliding. Verify the install with:
python -c "import korea_scholarship_mcp as k; print(k.__version__)"Do not use korea-scholarship-mcp --help as the check: unknown arguments are
ignored, the server starts, reads end-of-input and exits 0, so it reports
success whatever the state of the code.
Six independent packages. None imports another, none depends on another, and
each installs and answers on its own — pip install . in this directory is a
complete install of this server and nothing else.
They do share three things: a response envelope, a query ledger, and — if you
run more than one — a receipts folder. install.ps1 is vendored byte-identical
into all six and handles that on Windows; install.py is its cross-platform port. Both install this server by default, because
cloning one repository is not a request for five more.
.\install.ps1 # this server
.\install.ps1 -All # all six
.\install.ps1 -Servers korea_scholarship,cinii# a chosen subsetNothing about where things go is decided for you. The script asks where to
install (the virtual environment Claude Desktop will be pointed at), which
folder receives the receipts, and which session slug to stamp on them,
offering a neutral suggestion for each that Enter accepts; run without a
terminal it does not guess, and stops unless --venv and --receipts-dir
(or --no-receipts; -VenvDir and -ReceiptsDir for install.ps1) say
so. Whatever subset you name is registered against one receipts folder, asked for
once. The script prefers a sibling checkout to the network, carries across
credentials already registered rather than asking again, leaves servers it was
not asked about alone, and stops rather than guessing where the servers already
registered disagree about the folder or the session slug. It also asserts that
ledger.py and mediation.py are byte-identical across everything it
installed, so two envelope versions cannot end up in one environment unnoticed.
Nothing here is specific to Claude. The server speaks the Model Context Protocol over stdio and nothing else: any client that can start a process and talk JSON-RPC to it (Claude Code, Cursor, VS Code and Continue, Zed, LibreChat, a script of your own using an MCP SDK) can use it. The Claude Desktop bundle and the installers are conveniences for one client; the server underneath is the same console script. Register it anywhere by giving the client the absolute path of the console script and, optionally, the environment:
{
"mcpServers": {
"korea_scholarship": {
"command": "/absolute/path/to/.venv/bin/korea-scholarship-mcp",
"env": {
"KCI_API_KEY": "your key (optional; four tools need none)",
"MCP_RECEIPT_DIR": "/absolute/path/to/receipts",
"MCP_RECEIPT_SESSION": "project-or-article-slug"
}
}
}
}Claude Code takes the same thing on the command line:
claude mcp add korea_scholarship -- /absolute/path/to/.venv/bin/korea-scholarship-mcpOn Windows the path ends in \.venv\Scripts\korea-scholarship-mcp.exe. MCP_RECEIPT_DIR and MCP_RECEIPT_SESSION
are optional; without them the server runs and every envelope says RECEIPT_NOT_DEPOSITED. The
stdio transport is the only one: there is no HTTP endpoint to expose, and nothing to host.
"Server disconnected" is all Claude Desktop says when the server process exited before or during the handshake, whatever the reason. The reason is in the log:
Windows: %APPDATA%\Claude\logs\mcp-server-<name>.log (the extension's display name, or the key under mcpServers), with mcp.log beside it for the app's side of the conversation.
macOS: ~/Library/Logs/Claude/mcp-server-<name>.log and mcp.log.
Linux: ~/.config/Claude/logs/.
Read the last launch from the bottom up. Three shapes account for nearly every report:
A Python traceback ending in ImportError or ModuleNotFoundError (for example No module named 'pydantic_core._pydantic_core'). The interpreter started, the code was found, and a compiled library did not match that interpreter. This is what every bundle before 0.6.0 did on any Python other than 3.12. Install the current bundle, or use the pip route, which resolves wheels for the interpreter you install into.
'python' is not recognized, spawn python ENOENT, or a line from the Microsoft Store: no interpreter was found on the PATH Claude Desktop constructs. Nothing of this server ran. The current bundle does not launch python at all; for the pip route, register the console script by absolute path as shown above.
A line from uv (error: ..., or a download that never finished): the current bundle's runtime could not build its environment, usually because the first launch had no network or ran past Claude Desktop's sixty-second limit. Restart the app; uv keeps what it fetched. A uv older than 0.5 cannot read the lock file; upgrade it or remove it so the app uses its own.
The bundle's own entry point writes one line naming the interpreter, its path and the supported range before re-raising an import failure, so a log from 0.6.0 onwards says which of these it is.
cp .env.example .envKCI_API_KEY=your_kci_api_key_hereIf the package is installed, point at the console script:
{
"mcpServers": {
"korea-scholarship": {
"command": "C:\\path\\to\\.venv\\Scripts\\korea-scholarship-mcp.exe",
"env": {
"KCI_API_KEY": "your_kci_api_key_here"
}
}
}
}Or run it from a clone without installing:
{
"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"
}
}
}
}Omit the env block entirely to run the four keyless tools.
mcp 2.0.0 removed mcp.server.fastmcp. This server imports FastMCP where it exists and falls back to MCPServer where it does not, so it runs on either. The same shim was applied to cinii-mcp and jstage-mcp on 19 August 2026; before that, both imported mcp.server.fastmcp directly while pinning mcp[cli]>=1.2.0 with no upper bound, so a fresh install of either resolved to 2.0.0 and failed at import.
The KCI key travels in the query string, which makes it leak-prone in two specific ways this server closes:
httpx logs every request URL at INFO. _silence_http_logging() mutes it and strips any stdout handler — necessary anyway, since stdout carries JSON-RPC.
Transport and status exceptions embed the request URL. Every message bound for the client passes through _redact(), and the receipt is built from parameters with credentials removed rather than masked.
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.krThe live tests guard the claims this README rests on: that a KCI ingest window returns older publications, that KCI's identifiers are typed, that max_records is a cap rather than a hint, and that a resumption harvest does not record a date window it never sent. The OAK test is gated separately and fails loudly if OAK is unreachable rather than passing on an unexercised branch.
tests/smoke_stdio.py starts the installed console script over stdio, performs the MCP handshake, and checks tools/list against the tool table above; RUN_LIVE=1 … <tool> '<json params>' adds one live call.
The four KCI REST tools have never seen a live response — there is no API key. Their field mapping follows the published documentation and is unverified against the wire; the success/failure test is deliberately structural (records present means success) so that neither a chatty success message nor a terse rejection is misread. Treat REST output as provisional until a key exists.
ScienceON (KISTI) — deliberately out of scope. Its gateway requires an AES-256-CBC token built from a registered MAC address, plus a registered public IP. rubato103/scienceon-mcp already implements it against live credentials and is hardened against the exact credential-leak path described above; install it alongside rather than duplicating untestable auth code:
claude mcp add scienceon -- uvx --from "git+https://github.com/rubato103/scienceon-mcp" scienceon-mcpRISS (KERIS) — the search API exists at https://www.riss.kr/openApi and covers theses, domestic and foreign articles, monographs, research reports and serials, but keys are issued only to Korean non-profit institutions and universities, each application approved by KERIS staff; individuals cannot apply. Whether a non-Korean university qualifies is untested. If a key is ever obtained, RISS belongs in this server.
DBpia (Nurimedia) — keys are open and generous (2,500 calls a day), but the terms of use restrict the service to non-commercial purposes and forbid copying, storing or transmitting search results, which are to be displayed in real time and unaltered. That is incompatible with harvesting into a reference manager, a corpus index, or a register. The constraint is the licence, not the API.
korea_sources_status reports all three of these in situ, so the omission is visible from inside the tool rather than only in this file.
KCI and OAK are public-sector services with no published rate limit. Harvest considerately; slice windows rather than hammering wide ranges.
Metadata retrieved here is bibliographic. Full text sits behind whatever terms the holding repository sets — OAK's contents_url points into member repositories, each with its own licence.
Attribution strings are returned in every envelope; carry them into anything published.
If this software supports your research, please cite it. See CITATION.cff, or use the "Cite this repository" button on GitHub.
MIT © 2026 Christopher Gerteis.
This license covers the server code only. It grants no rights over KCI or OAK data, which remain governed by the terms of the National Research Foundation of Korea and the National Library of Korea respectively.
A research tool, maintained on a best-effort basis and provided "as is", without warranty. Not affiliated with or endorsed by the National Research Foundation of Korea, the National Library of Korea, KERIS, KISTI, or Nurimedia.
Dr Christopher Gerteis, SOAS University of London.
Full KCI record for one control number (e.g. ART001995054).
This is the only endpoint that carries author keywords, ISSN, author affiliations and the abstracts. Use it to repair records returned by kci_search.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description faithfully conveys the core behavior: a read-only retrieval of a full record, with no mutation implied. It adds meaningful context about scope and exclusivity, though it does not discuss error behavior or access prerequisites. The output schema covers return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences lead with the core definition and immediately add differentiating value. Every phrase contributes — no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup with an output schema, the description is nearly complete: it states what the tool returns, why it is unique, and when to use it. Minor omissions like invalid-ID behavior are acceptable given the simple shape and existing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description compensates by explaining article_id as a control number and giving a realistic example (ART001995054). That gives an agent enough to construct a valid call despite the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies a specific resource — the full KCI record for one control number — with a concrete example. It also distinguishes itself from sibling kci_search by naming the unique fields it carries (author keywords, ISSN, affiliations, abstracts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use this endpoint: to repair incomplete records returned by kci_search. The phrase 'the only endpoint that carries...' also communicates why it is the correct choice over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Harvest KCI by OAI-PMH — no API key required.
date_from/date_to are YYYY-MM-DD and select on KCI ingest datestamp,
not publication date: a July 2026 window returns articles published in
2015. There is no query interface, so contains is applied client-side to
whatever the window yielded. Sets: ARTI (article), ARTI_CONF (conference),
JOUR (journal).
This is a harvesting tool wearing a search tool's clothes. Treat a result as a slice of the accession stream, and say so in anything built on it.
| Name | Required | Description | Default |
|---|---|---|---|
| date_to | Yes | ||
| contains | No | ||
| set_spec | No | ARTI | |
| date_from | Yes | ||
| max_records | No | ||
| resumption_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals non-obvious behavior: the date window refers to KCI ingest datestamp rather than publication date, 'contains' is not a server-side query, and results are slices of the accession stream. This is genuinely transparent about how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the core identity comes first, then parameter semantics, then a useful mental-model warning. No sentence is wasted, and formatting highlights the most important caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers protocol, authentication, date semantics, filtering behavior, sets, and the right mental model for results. It does not explain resumption_token or max_records behavior, and it could be more explicit about when to prefer kci_search. Still, for an OAI-PMH harvesting tool, this is a strong and unusually complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains date_from/date_to format and semantics, clarifies 'contains' behavior, and enumerates the set_spec values. However, max_records and resumption_token are not explained beyond their names/defaults, leaving a small but real semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Harvest KCI by OAI-PMH'. It also explicitly reframes the tool as a harvesting tool rather than a search tool, which distinguishes it from sibling tools like kci_search. The first sentence makes the tool's identity unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: date selection is on ingest datestamp, there is no query interface, and 'contains' is applied client-side. This implies that users needing true search should use another tool, but it does not explicitly name kci_search or say when not to use this tool. Still, the guidance is strong and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
KCI journal citation indices (impact factor, immediacy, self-citation share).
Supply journal for the list view or journal_id for one journal's
history. years must be 2–5.
These are bibliometric artefacts of a national index with a small, largely domestic citing population. They measure position within KCI, not standing in a field, and should not be used to rank scholarship.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| years | No | ||
| journal | No | ||
| journal_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so this description carries the disclosure burden, and it does so well: it explains the parameter-driven behavior (list vs. history), the `years` constraint, and the important interpretive limitation that these indices measure rank within KCI, not scholarly standing. It does not discuss data freshness or rate limits, but those are less critical for a read-only metrics query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs with no fluff: definition, usage pattern, and a caveat that prevents misuse. Important information is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and the safety profile simple, the description covers the key call contract: purpose, parameter modes, validation, and interpretation limits. The only real gaps are the unexplained `year` parameter and the lack of explicit sibling-tool routing, but those are minor for this query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must document the parameters itself. It explains `journal` (list view), `journal_id` (one journal's history), and `years` (2–5 range). However, it never explains the `year` parameter or how it relates to `years`, `journal`, and `journal_id`, leaving one parameter semantically unresolved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line identifies the resource (KCI journal citation indices) and the exact metric set (impact factor, immediacy, self-citation share). The second paragraph's 'Supply ... for the list view or ... for history' clarifies the action and distinguishes the two primary call modes. It does not name a sibling tool, but the tool's scope is clear enough to separate it from kci_search, kci_article, and kci_references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage guidance: use `journal` for a list view, `journal_id` for a single journal's history, and keep `years` in the 2–5 range. It does not, however, state when to choose this tool over the sibling KCI/korea tools or mention any exclusions, so the routing guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Works cited by one KCI article (referenceSearch).
KCI's reference data is contributed by publishers and is uneven: an empty list is as likely to mean the publisher deposited no reference block as that the article cites nothing. Read it as a floor, never a count.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure and does so well by warning that an empty list may mean missing publisher data rather than zero citations. The 'floor, never a count' caveat is a meaningful behavioral trait beyond what the schema or output schema would reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and every sentence earns its place. The caveat about data quality is essential and presented without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter lookup with an output schema available, the description adequately covers what the tool does and the critical data-quality caveat. It is slightly incomplete only in not addressing tool-selection context relative to its siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one required parameter, article_id, and zero percent schema description coverage. The description implies that this parameter identifies a single KCI article, but it does not add explicit details about the expected format, provenance, or examples beyond what the parameter name and title convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as the works cited by one KCI article, and the parenthetical 'referenceSearch' reinforces the operation. It is distinguishable from sibling tools such as kci_search and kci_article, though it lacks an explicit imperative verb like 'retrieve' or 'list.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives important interpretive guidance about KCI's reference data being uneven and empty lists being ambiguous, which helps an agent use results correctly. However, it does not explicitly state when to choose this tool over siblings or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search KCI articles (REST, requires KCI_API_KEY).
title is mandatory — the KCI API rejects a query without it, so a
subject-led search must be run as a title query and again as a keyword
query, and the two sets unioned by hand. date_from/date_to are YYYYMM.
rows is capped at 100 by the API.
Two asymmetries this tool reports rather than hides: articleSearch accepts
keyword as a search field but omits author keywords, ISSN and UCI from
its response, so an empty keywords list here means the endpoint did not
return them, not that the article has none — use kci_article to recover
them per record.
| Name | Required | Description | Default |
|---|---|---|---|
| doi | No | ||
| page | No | ||
| rows | No | ||
| title | Yes | ||
| author | No | ||
| date_to | No | ||
| journal | No | ||
| keyword | No | ||
| abstract | No | ||
| date_from | No | ||
| affiliation | No | ||
| institution | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers richly: API key requirement, rejection of queries missing title, the 100-row cap, and the response asymmetry where omitted author keywords/ISSN/UCI produce an empty list that must not be interpreted as 'no keywords'. This is exactly the failure-mode disclosure that prevents an agent from confidently misinferring on empty data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three paragraphs follow a logical progression (purpose → constraints/workflow → caveats), with every sentence carrying operational information and the purpose front-loaded in the first clause. It is dense rather than padded, though the subject-led workflow explanation could arguably be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with 0% schema coverage and no annotations, the description covers the critical constraints and the key response quirk well. It is incomplete mainly because seven filter parameters get no semantics anywhere, and the response asymmetry is disclosed narratively rather than per-field. The presence of an output schema mitigates the return-value gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds real semantics for title (mandatory), date_from/date_to (YYYYMM format), rows (API cap 100), and keyword (accepted as a search field but absent from the response). However, 7 of the 12 parameters — doi, page, author, journal, abstract, affiliation, institution — remain undocumented in both the schema and the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'Search KCI articles (REST, requires KCI_API_KEY)' names a specific verb, resource, and transport/auth context in one line. It also differentiates from the kci_article sibling by explicitly assigning per-record field recovery (keywords, ISSN, UCI) to that tool rather than this one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit operational guidance: title is mandatory and the API rejects queries without it, so a subject-led search must be run as both a title query and a keyword query with the results unioned by hand. It also states an explicit alternative — use kci_article to recover keywords/ISSN/UCI — telling the agent exactly when this tool's output is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which Korean sources are configured and reachable right now.
Checks the KCI REST key, the two keyless OAI endpoints, and states plainly what this server does not cover (ScienceON, RISS, DBpia) and why.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does well by stating exactly what it checks (KCI REST key, two keyless OAI endpoints) and what it deliberately does not cover (ScienceON, RISS, DBpia) with reasons implied. It could add a note about being read-only, but the zero-parameter status-report nature makes side effects unlikely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight paragraphs: the first states the core purpose with a time qualifier ('right now'), and the second names the exact endpoints checked and the notable exclusions. Every sentence adds useful information, and the most important action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter status tool with an output schema present, the description is complete. It covers what is checked, how authentication is handled (REST key vs keyless endpoints), what is not covered, and the fact that the report is a current runtime view. Nothing needed for an agent to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100%, so there is nothing for the description to add about parameters. The baseline of 4 applies because no parameter documentation burden exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Report which Korean sources are configured and reachable right now.' It then names the concrete checks involved (KCI REST key, two keyless OAI endpoints) and explicitly lists what is not covered, making the tool's scope unmistakable. This clearly distinguishes it from the sibling kci_* and oak_* tools, which are searching and harvesting tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use case clear: checking current configuration and reachability of Korean sources. It does not name sibling alternatives explicitly, but it frames itself as a status/diagnostic tool, implying it should be used before or alongside harvest/search operations rather than as a content-fetching tool. It does not include explicit 'when not to use' guidance, but the scope is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Harvest Open Access Korea by OAI-PMH — no API key required.
date_from/date_to are YYYY-MM-DD ingest datestamps. OAK declares no set
hierarchy and — verified 19 Aug 2026 — sends no resumptionToken, so a
window returns at most about 99 records and there is no way to ask for the
rest. When the cap is hit this tool says so and tells you to narrow the
window; it will not present a truncated window as a complete one.
Windows are lumpy: a single repository's bulk deposit can fill one entirely, so the tool also reports which holding organisation dominates.
| Name | Required | Description | Default |
|---|---|---|---|
| date_to | Yes | ||
| contains | No | ||
| date_from | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It discloses the ~99-record cap, the absence of resumptionToken, the explicit self-reporting behavior when the cap is hit, and the refusal to present a truncated window as complete. It also discloses the dominant-holding-organization reporting behavior, which exceeds typical expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded: purpose first, then parameter format, then limits and behavior. The paragraphs are longer than minimal but every sentence adds operational value—technical details like no resumptionToken and the verified date justify the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, required parameters, operational limits, and result caveats, while an output schema exists to handle return values. It is slightly incomplete because 'contains' is not explained and no explicit routing to sibling tools is provided, but the core invocation is fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clearly defines date_from and date_to as YYYY-MM-DD ingest datestamps, which is essential. However, the optional 'contains' parameter is never mentioned, leaving one parameter semantically unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb ('Harvest'), target ('Open Access Korea'), method ('by OAI-PMH'), and a key requirement ('no API key required'). This clearly differentiates it from the KCI-oriented sibling tools even though no sibling is named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete usage context: ingest-date windows, YYYY-MM-DD format, no set hierarchy, no resumptionToken, and the need to narrow the window when the cap is hit. It stops short of explicitly naming alternatives or saying when not to use this tool, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One OAK record by OAI identifier (oai:oak.go.kr:NNNNNNNN, or the bare number).
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It only states the input format and that the result is one record; it does not explicitly confirm read-only behavior, what happens on missing identifiers, authentication needs, or any error conditions. The phrase 'One OAK record' is too vague to describe the tool's behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the resource and immediately gives the critical identifier format in parentheses. Every word adds value, and the example formats improve clarity without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description covers the essential input knowledge (identifier format) and the resource name. However, it lacks any usage context relative to sibling tools and does not state expected behavior or edge cases. It is minimally sufficient for invoking the tool, but not thoroughly contextual.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a 'string' type and the title 'Identifier', with 0% description coverage. The description compensates by explaining the accepted input formats: full OAI identifier with prefix or bare number. This is essential semantic information for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (a single OAK record) and the key identifier format (OAI identifier or bare number). It implies a retrieval operation even though the verb is not explicit. It is distinguishable from sibling tools like kci_article and oak_harvest by naming OAK records and the identifier-based lookup, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It implies usage when you have an OAI identifier, but no exclusions or sibling comparisons are provided. An agent must infer the appropriate context from the identifier format alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.5.0kci_articlekci_harvestkci_journal_metricskci_referenceskci_searchkorea_sources_statusoak_harvestoak_recordScored across 8 tools
Each tool targets a different function—search, record detail, references, journal metrics, OAI harvesting, or source status—and the descriptions explicitly distinguish overlapping endpoints such as kci_search vs kci_harvest. The KCI search/detail pair is clearly separated by 'use kci_article to repair records returned by kci_search', so an agent should not confuse them. No two tools appear to do the same thing.
All tool names are lowercase, snake_case, and consistently source-prefixed (kci_, oak_, korea_). However, the set mixes noun-style retrieval names (kci_article, kci_references, kci_journal_metrics, oak_record) with verb-style names (kci_search, kci_harvest, oak_harvest), so it is readable but not a uniform verb_noun convention. This is a minor deviation rather than chaos.
Eight tools is a well-scoped size for a Korean scholarship metadata server covering two source families plus a status tool. Each tool contributes a distinct capability—search, detail, references, metrics, harvesting, and operational health—so none feels redundant or out of place.
The set covers KCI search, detail, references, journal metrics, and OAI harvesting, plus OAK harvesting, OAK record retrieval, and source status. The main minor gaps are the lack of an OAK search endpoint and the hard ~99-record harvest cap, but the tool descriptions explicitly document these and offer workarounds such as narrowing windows or using kci_article to enrich search results.
IEEE Xplore MCP — BYOK wrapper over the IEEE Xplore Metadata Search API
MCP server for Altmetric APIs - track research attention across news, policy, social media, and more
OpenAlex MCP — wraps the OpenAlex API (scholarly works, free, no auth)
Crossref MCP — wraps the Crossref REST API (academic papers, free, no auth)
