MCPortal

The missing bridge between data.go.kr and the global MCP ecosystem. MCPortal normalizes Korean public-API specifications into standard OpenAPI 3.1, compiles them into MCP servers, and puts every outbound call behind a hard daily budget with backoff and caching. Fully open source, fully self-hosted.

한국어 문서: README.ko.md — this English README is the canonical document and the Korean file is a translation of it.

Accuracy disclaimer

data.go.kr publishes no "remaining quota" endpoint. MCPortal's usage ledger therefore counts only the calls that went through MCPortal, which makes it a best-effort estimate. Calls that the same serviceKey spends outside MCPortal — another script, the portal console, a different tool — never reach the ledger, so the ledger value is always a lower-bound approximation of real consumption. The axis of trust is not that estimate but the hard budget cap (CALL_BUDGET). Even when the ledger is wrong, the hard guard physically blocks calls beyond the daily cap, so the safety line against quota-related account sanctions always comes from CALL_BUDGET.

The no-key boundary

Every demo, development and CI path in MCPortal runs without a key. The record/replay layer replays cassettes that were recorded earlier, so the same response flow can be reproduced and the whole test suite can go green with no serviceKey present. Spec-to-MCP conversion has already happened at build time — the compiled artifacts are committed under specs/ — so clone the repository and even standing up an MCP server and answering tool calls needs no key: mcportal serve 15000115 --replay serves eight tools over stdio with no serviceKey anywhere in the environment.

That sentence says clone on purpose. Replay needs a cassette, and cassettes are recorded upstream responses that stay in the repository instead of going out in the wheel (note 1), so a bare pip install mcportal has nothing to replay until it is pointed at a checkout with --presets-root <path> or MCPORTAL_PRESETS=<path>. Cassettes exist for three of the four bundles — 15081808 has none in the repository either, because it was deliberately left out of sampling (see Presets below), so that one bundle is live-only.

What does need a key is narrow: live traffic to data.go.kr, and sampling or converting an API that has no cassette yet.

Note 1 — what the wheel carries, and what it does not. Since 0.2.0, the published wheel carries the four preset bundles (16 bundle files plus the two presets/ documents, measured on the built artifact), so a plain pip install mcportal can run mcportal presets with no checkout. Since 0.2.2 the wheel also carries the three sampled_schemas.json files — 15000115, 15101612 and 15102108; 15081808 has none, because it was deliberately left out of sampling. They ship because mcportal compile --check needs them: --check does not diff files, it re-synthesizes openapi.json from its source + curation + sampled layers, so without the sampled layer an installed copy cannot reproduce the very openapi.json it shipped. On 0.2.1 as published, compile --check from a plain install reports 3 of 4 drifted and exits 3 (measured 2026-08-15); on that version pass --presets-root <checkout>/presets. 0.2.2 restores it to 4 of 4 matched, exit 0, from the install alone. Those three files carry only the field names and types inferred from the responses — zero response values — and that structure already ships inside openapi.json, so nothing is exposed that the wheel did not already carry. What the wheel still leaves out is the recorded upstream traffic itself: cassettes/ and samples/ stay in the repository only, which is why mcportal serve --replay is a checkout path. To use a different bundle set — or to give a PyPI install the cassettes — point MCPortal at a checkout with --presets-root <path> or the environment variable MCPORTAL_PRESETS=<path>. When mcportal presets finds no bundle it prints the paths it searched.

Key-free reproduction walkthrough

# 1) Compile a spec from synthetic fixtures (zero network, zero credentials).
python examples/compile_demo.py
#    -> specs/demo/openapi.json + specs/demo/samples/*.json
#    Re-running produces byte-identical output; the determinism check is
#    built into the script.

# 2) Stand up an MCP server over stdio from a committed bundle (no key).
#    Needs the [mcp] extra. --replay reads presets/<id>/cassettes/<id>.json,
#    which exists for 15000115, 15101612 and 15102108; 15081808 has none.
mcportal serve 15000115 --replay
#    -> 8 tools over stdio, zero credentials. On a PyPI install add
#    --presets-root <checkout>/presets (note 1).
#
#    The same thing without the CLI, against any spec plus any cassette:
python -c "from mcportal.mcp import build_server; \
build_server('specs/demo/openapi.json', mode='replay', \
cassette_path='<cassette path>')"
#    specs/demo/ commits the spec and the samples, not a cassette, so
#    <cassette path> must point at one you recorded yourself. That a server
#    really stands up and answers a tool call without a key is proven by the
#    last case in tests/test_mcp_wiring.py, which builds a synthetic cassette
#    in tmp_path. presets/<id>/openapi.json fits the same slot.

# 3) Regenerate the preset bundles from real published specs (no key).
#    Works from a checkout, and — since 0.2.2 started carrying the sampled
#    layer — from a plain pip install too (note 1). On 0.2.1 as published from
#    PyPI, or to point at a different bundle set, pass --presets-root <path>
#    or set MCPORTAL_PRESETS=<path>.
mcportal presets            # list
mcportal compile --check    # byte-compare committed vs regenerated (exit 3 on drift)

# 4) The whole test suite (no live network, no key, no real data).
pytest -q

Install

pip install mcportal            # core runtime (single dependency: httpx)
pip install "mcportal[mcp]"     # + the MCP conversion layer (fastmcp)

Dependency policy: the core runtime depends on httpx and nothing else. The spec-normalizing compiler (mcportal.compiler) uses only the standard library and httpx. fastmcp is required solely by mcportal.mcp and ships as the optional [mcp] extra — without it, import mcportal and the entire test suite still work, and calling into the MCP layer raises a Korean ImportError that explains how to install it. The [mcp] extra also declares anyio, because the sync-to-async bridge imports anyio.to_thread directly; httpx pulls anyio in transitively, but a direct import deserves a direct declaration so that pins and lockfiles constrain it.

import mcportal does not import mcportal.mcp — that is what keeps the import working without fastmcp installed. The MCP symbols are resolved lazily on first attribute access through a module __getattr__ (PEP 562), so from mcportal.mcp import build_server and mcportal.build_server refer to the same object. Either spelling is fine.

Single-key principle (no multi-key rotation)

MCPortal's data.go.kr profile does not support multi-key rotation. data.go.kr issues one key per development account and meters a daily call limit against it; cycling several keys to escape that limit risks violating the service's operating policy and inviting account sanctions. MCPortal respects the structure as it is and accepts a single key. When the limit is too low, the supported answer is data.go.kr's own path — registering a use case and applying for the operational tier — not more keys.

CLI

The CLI uses the standard library argparse only. Zero new runtime dependencies is a binding rule for this project, so even the terminal tables are laid out by hand (Hangul counted as double width, ASCII rules, safe on a Windows cp949 console).

mcportal quota status [--ledger PATH] [--budget N] [--day YYYY-MM-DD]
                      [--key-fp FP | --key-env VAR] [--json]
mcportal compile [PRESET_ID ...] [--presets-root PATH] [--check] [--json]
mcportal presets [--presets-root PATH] [--json] [--verbose]
mcportal sample PRESET_ID ... --key-env VAR [--budget N] [--count N]
                [--ledger PATH] [--presets-root PATH] [--json]
mcportal serve PRESET_ID [--replay | --key-env VAR] [--presets-root PATH]
                         [--name TEXT]