{ "markdown": "\n\n# MCPortal\n\n**The missing bridge between data.go.kr and the global MCP ecosystem.** MCPortal\nnormalizes Korean public-API specifications into standard OpenAPI 3.1, compiles\nthem into MCP servers, and puts every outbound call behind a hard daily budget\nwith backoff and caching. Fully open source, fully self-hosted.\n\n한국어 문서: [`README.ko.md`](README.ko.md) — this English README is the\ncanonical document and the Korean file is a translation of it.\n\n> **Accuracy disclaimer**\n>\n> data.go.kr publishes no \"remaining quota\" endpoint. MCPortal's usage ledger\n> therefore counts **only the calls that went through MCPortal**, which makes it\n> a best-effort estimate. Calls that the same `serviceKey` spends outside\n> MCPortal — another script, the portal console, a different tool — never reach\n> the ledger, so the ledger value is always a lower-bound approximation of real\n> consumption. The axis of trust is not that estimate but the **hard budget cap\n> (`CALL_BUDGET`)**. Even when the ledger is wrong, the hard guard physically\n> blocks calls beyond the daily cap, so the safety line against quota-related\n> account sanctions always comes from `CALL_BUDGET`.\n\n## The no-key boundary\n\n| Works without any API key | Needs a data.go.kr service key |\n| --- | --- |\n| Replaying record/replay cassettes | Live API calls |\n| The full test suite (`pytest`), including the record-mode tests, which run on synthetic transports | Live response sampling |\n| Standing up an MCP server from a committed spec plus its cassette (`mcportal serve --replay`) — from a repo checkout, or from a PyPI install pointed at one (note 1) | Ad-hoc conversion of an API that has no cassette yet |\n| Regenerating the compile demo (`examples/compile_demo.py`) | Recording new cassettes |\n| Regenerating and listing the preset bundles (`mcportal compile` / `mcportal presets`) — bundled in the wheel since 0.2.0 (note 1) | Sampling a response schema that is still unresolved (`mcportal sample`) |\n| Reading quota status (`mcportal quota status`) | The key-dependent benchmark items K1–K3 |\n| Running the benchmark harness (the five key-free items in `benchmarks/PROTOCOL.md`) | — |\n\nEvery demo, development and CI path in MCPortal runs without a key. The\nrecord/replay layer replays cassettes that were recorded earlier, so the same\nresponse flow can be reproduced and the whole test suite can go green with no\n`serviceKey` present. **Spec-to-MCP conversion has already happened at build\ntime** — the compiled artifacts are committed under `specs/` — so **clone the\nrepository and even standing up an MCP server and answering tool calls needs no\nkey**: `mcportal serve 15000115 --replay` serves eight tools over stdio with no\n`serviceKey` anywhere in the environment.\n\nThat sentence says *clone* on purpose. Replay needs a cassette, and cassettes\nare recorded upstream responses that stay in the repository instead of going out\nin the wheel (note 1), so a bare `pip install mcportal` has nothing to replay\nuntil it is pointed at a checkout with `--presets-root ` or\n`MCPORTAL_PRESETS=`. Cassettes exist for three of the four bundles —\n`15081808` has none in the repository either, because it was deliberately left\nout of sampling (see *Presets* below), so that one bundle is live-only.\n\nWhat does need a key is narrow: live traffic to data.go.kr, and sampling or\nconverting an API that has no cassette yet.\n\n> **Note 1 — what the wheel carries, and what it does not.**\n> Since 0.2.0, **the published wheel carries the four preset bundles** (16 bundle\n> files plus the two `presets/` documents, measured on the built artifact), so a\n> plain `pip install mcportal` can run `mcportal presets` with no checkout.\n> **Since 0.2.2** the wheel also carries the three `sampled_schemas.json` files\n> — `15000115`, `15101612` and `15102108`; `15081808` has none, because it was\n> deliberately left out of sampling. They ship because `mcportal compile\n> --check` needs them: `--check` does not diff files, it re-synthesizes\n> `openapi.json` from its source + curation + sampled layers, so without the\n> sampled layer an installed copy cannot reproduce the very `openapi.json` it\n> shipped. On 0.2.1 as published, `compile --check` from a plain install reports\n> 3 of 4 drifted and exits 3 (measured 2026-08-15); on that version pass\n> `--presets-root /presets`. 0.2.2 restores it to 4 of 4 matched,\n> exit 0, from the install alone.\n> Those three files carry only the **field names and types inferred from the\n> responses** — zero response values — and that structure already ships inside\n> `openapi.json`, so nothing is exposed that the wheel did not already carry.\n> What the wheel still leaves out is the recorded upstream traffic itself:\n> **`cassettes/` and `samples/` stay in the repository only**, which is why\n> `mcportal serve --replay` is a checkout path. To use a different bundle set —\n> or to give a PyPI install the cassettes — point MCPortal at a checkout with\n> `--presets-root ` or the environment variable `MCPORTAL_PRESETS=`.\n> When `mcportal presets` finds no bundle it prints the paths it searched.\n\n### Key-free reproduction walkthrough\n\n```\n# 1) Compile a spec from synthetic fixtures (zero network, zero credentials).\npython examples/compile_demo.py\n# -> specs/demo/openapi.json + specs/demo/samples/*.json\n# Re-running produces byte-identical output; the determinism check is\n# built into the script.\n\n# 2) Stand up an MCP server over stdio from a committed bundle (no key).\n# Needs the [mcp] extra. --replay reads presets//cassettes/.json,\n# which exists for 15000115, 15101612 and 15102108; 15081808 has none.\nmcportal serve 15000115 --replay\n# -> 8 tools over stdio, zero credentials. On a PyPI install add\n# --presets-root /presets (note 1).\n#\n# The same thing without the CLI, against any spec plus any cassette:\npython -c \"from mcportal.mcp import build_server; \\\nbuild_server('specs/demo/openapi.json', mode='replay', \\\ncassette_path='')\"\n# specs/demo/ commits the spec and the samples, not a cassette, so\n# must point at one you recorded yourself. That a server\n# really stands up and answers a tool call without a key is proven by the\n# last case in tests/test_mcp_wiring.py, which builds a synthetic cassette\n# in tmp_path. presets//openapi.json fits the same slot.\n\n# 3) Regenerate the preset bundles from real published specs (no key).\n# Works from a checkout, and — since 0.2.2 started carrying the sampled\n# layer — from a plain pip install too (note 1). On 0.2.1 as published from\n# PyPI, or to point at a different bundle set, pass --presets-root \n# or set MCPORTAL_PRESETS=.\nmcportal presets # list\nmcportal compile --check # byte-compare committed vs regenerated (exit 3 on drift)\n\n# 4) The whole test suite (no live network, no key, no real data).\npytest -q\n```\n\n## Install\n\n```\npip install mcportal # core runtime (single dependency: httpx)\npip install \"mcportal[mcp]\" # + the MCP conversion layer (fastmcp)\n```\n\n**Dependency policy: the core runtime depends on httpx and nothing else.** The\nspec-normalizing compiler (`mcportal.compiler`) uses only the standard library\nand httpx. [fastmcp](https://github.com/PrefectHQ/fastmcp) is required solely by\n`mcportal.mcp` and ships as the optional `[mcp]` extra — without it,\n`import mcportal` and the entire test suite still work, and calling into the MCP\nlayer raises a Korean `ImportError` that explains how to install it. The `[mcp]`\nextra also declares **anyio**, because the sync-to-async bridge imports\n`anyio.to_thread` directly; httpx pulls anyio in transitively, but a direct\nimport deserves a direct declaration so that pins and lockfiles constrain it.\n\n`import mcportal` does **not** import `mcportal.mcp` — that is what keeps the\nimport working without fastmcp installed. The MCP symbols are resolved lazily on\nfirst attribute access through a module `__getattr__`\n([PEP 562](https://peps.python.org/pep-0562/)), so `from mcportal.mcp import\nbuild_server` and `mcportal.build_server` refer to the same object. Either\nspelling is fine.\n\n### Single-key principle (no multi-key rotation)\n\nMCPortal's data.go.kr profile **does not support multi-key rotation.**\ndata.go.kr issues one key per development account and meters a daily call limit\nagainst it; cycling several keys to escape that limit risks violating the\nservice's operating policy and inviting account sanctions. MCPortal respects the\nstructure as it is and accepts a single key. When the limit is too low, the\nsupported answer is data.go.kr's own path — registering a use case and applying\nfor the operational tier — not more keys.\n\n## CLI\n\nThe CLI uses the standard library `argparse` only. **Zero new runtime\ndependencies** is a binding rule for this project, so even the terminal tables\nare laid out by hand (Hangul counted as double width, ASCII rules, safe on a\nWindows cp949 console).\n\n```\nmcportal quota status [--ledger PATH] [--budget N] [--day YYYY-MM-DD]\n [--key-fp FP | --key-env VAR] [--json]\nmcportal compile [PRESET_ID ...] [--presets-root PATH] [--check] [--json]\nmcportal presets [--presets-root PATH] [--json] [--verbose]\nmcportal sample PRESET_ID ... --key-env VAR [--budget N] [--count N]\n [--ledger PATH] [--presets-root PATH] [--json]\nmcportal serve PRESET_ID [--replay | --key-env VAR] [--presets-root PATH]\n [--name TEXT]\n```\n\n| Subcommand | What it does |\n| --- | --- |\n| `quota status` | Shows today's (KST) usage, budget, remainder and state per key fingerprint. **The ledger is opened read-only (`mode=ro`) and never created.** Budget resolution order is `--budget` > `CALL_BUDGET` > profile default, and the output states which path was taken |\n| `compile` | Regenerates preset bundles. Files whose content is unchanged are not rewritten. `--check` writes nothing and only byte-compares |\n| `presets` | Lists the bundles as a table; `--verbose` expands the curation notes |\n| `sample` | Live sampling that fills in response schemas still marked unresolved, writing the inferred schema, the response bodies and a replayable cassette. It is the one subcommand that needs a key, and the key is taken **only** from the environment variable named by `--key-env VAR`, never as a literal argument |\n| `serve` | Stands one bundle up as an MCP server over stdio. The default `--replay` needs no key; `--key-env VAR` goes live through the same quota guard. Requires the `[mcp]` extra. **Documented against a repo checkout**: `--replay` reads `presets//cassettes/.json`, which the wheel does not carry (note 1), so from a PyPI install pass `--presets-root /presets` or set `MCPORTAL_PRESETS=/presets`. Three of the four bundles have a cassette — `15081808` has none in the repository either, so it serves live only. **stdout is protocol-only**; every human-readable line, banner included, goes to stderr |\n\nExit codes: **0** success (including \"no ledger\", \"no presets\" and \"nothing\nchanged\" — an empty state is not a failure) / **1** execution failure / **2**\nusage error / **3** drift found by `compile --check` / **130** user interrupt.\n\n`--json` prints JSON alone on stdout (no human prose mixed in, so it is\npipe-safe) and sends every error to stderr. **A raw service key is never printed\non any path** — even `--key-env` reads the environment variable and computes the\nfingerprint locally. The ledger stores no raw key, so a fingerprint is the only\nthing the CLI ever had available to show.\n\n## Presets — three services, four datasets\n\n`presets/` holds bundles built from **real published specifications** on\ndata.go.kr. Their purpose is to demonstrate, **in data rather than in code**,\nthe fix for the failure mode of naive spec conversion, where every generated\ntool ends up described as \"list query\".\n\n| ID | Service | Domain | Source kind | Operations | Data licence as published |\n| --- | --- | --- | --- | --- | --- |\n| `15000115` | Ministry of Government Legislation — national law information sharing service | law | `rest_doc_manual` | 8 | KOGL Type 1 (attribution) |\n| `15081808` | National Tax Service — business registration validity and status lookup | business registration | `odcloud_swagger` | 2 | no restriction stated |\n| `15101612` | Korea Customs Service — trade by country | customs | `gw_swagger` | 1 | no restriction stated |\n| `15102108` | Korea Customs Service — import/export summary | customs | `gw_swagger` | 1 | no restriction stated |\n\nLicence wording is what data.go.kr displayed on the acquisition date recorded in\neach bundle. By domain there are **three services**, and only customs has two\ndatasets, which is why every document writes **\"three services (four\ndatasets)\"**.\n\n**Ten of the twelve response schemas were unresolved; live sampling on\n2026-08-09 settled all ten** (`15000115` eight, `15101612` one, `15102108` one —\none call per operation, ten calls total). The inferred schemas are persisted in\neach bundle's `sampled_schemas.json`, the response bodies in `samples/` and the\nrequest/response pairs in `cassettes/`, so the result **replays offline with no\nkey**. Sampled bundles report `generation_mode: \"sampled\"` in\n`info.x-mcportal`.\n\nThe remaining two operations (`15081808`) were never unresolved — that source\ndeclares its response schema. That bundle was deliberately left out of sampling\nbecause its request body carries a business registration number, so its schema is\ndeclared but not measured. MCPortal does not hide either state: the live count is\nwritten into `info.x-mcportal.schema_inference.unresolved` in the generated\ndocument, and what each bundle still does not know is listed in its own\n`presets//README.md`. Writing down something unverified as if it were\nverified is against the rules of this project.\n\nA bundle is four committed files, plus the sampling evidence where it exists:\n\n```\npresets//\n├─ source.json <- the spec document plus source URL, acquisition date, sha256\n├─ curation.json <- human-checked descriptions, examples, hints\n├─ openapi.json <- the merge of both layers (the committed artifact)\n├─ README.md <- provenance and open questions for this dataset\n├─ sampled_schemas.json <- schemas inferred from live samples (sampled bundles only)\n├─ samples/ <- scrubbed response bodies from those calls\n└─ cassettes/ <- request/response pairs for offline replay\n```\n\nThe four files at the top ship in the wheel, and since 0.2.2 so does\n`sampled_schemas.json` where it exists — three of the four bundles — because\n`compile --check` cannot re-synthesize `openapi.json` without it (note 1). The\nrecorded traffic, `samples/` and `cassettes/`, is repository only.\n\n- **The lower layer carries zero lines of domain knowledge.**\n `mcportal.compiler.curation` is a general engine that reads, validates and\n merges curation data; no institution or dataset name appears in the code, and\n a test enforces that by scanning the source strings.\n- **Curation does not change spec facts.** It adds descriptions, examples, tags\n and hints. Parameter type, location and requiredness, and operation path and\n method, remain whatever the source spec declares. Only two channels can\n correct a fact, and both demand a written `reason`: downgrading a response\n schema to unresolved, and removing a parameter.\n- Given the same inputs, `openapi.json` regenerates **byte-identically**. Use\n `mcportal compile --check` as a CI gate (exit code 3 on drift). One caveat:\n `info.x-mcportal.tool_version` carries the package version, so **bumping the\n version changes all four artifacts**, and regenerating is the convention when\n that happens.\n\nConventions and open items are governed by\n[`presets/README.md`](presets/README.md); provenance and terms of use for the\nspec metadata are governed by\n[`presets/NOTICE-DATA.md`](presets/NOTICE-DATA.md).\n\n## Architecture\n\nTwo layers at compile time, one guarded chain at run time.\n\n```\nCOMPILE TIME (offline: no key, no network)\n\n spec documents +--------------------------------+\n - odcloud OAS (JSON) | lower layer: the compiler |\n - gateway Swagger 2.0 / 3.x ---> | zero domain knowledge |\n - hand-mapped usage guide | sources -> SourceSpec -> IR |\n +---------------+----------------+\n |\n curation.json |\n (human-checked descriptions, ---------------> merge\n examples, hints) upper layer: data, not code\n |\n v\n openapi.json (committed;\n byte-identical on rebuild)\n\nRUN TIME (one MCP tool call)\n\n MCP client\n | tool call\n v\n FastMCP server <- built by FastMCP.from_openapi() from openapi.json\n |\n v\n sync/async bridge -> MCPortalTransport\n |-- quota guard token bucket + SQLite ledger\n | + CALL_BUDGET hard cap + backoff\n |-- key injection the key never enters the spec\n |-- TTL cache\n |-- record / replay cassettes, scrubbed on write\n |-- normalization XML -> JSON, EUC-KR, error codes\n v\n data.go.kr (or the cassette, in replay mode)\n```\n\nTwo consequences of that shape are worth stating explicitly.\n\n- **Tool definitions are not hand-generated.** `FastMCP.from_openapi()` owns the\n spec-to-tool conversion; MCPortal contributes the stage before it (spec\n normalization) and the stage after it (quota and hygiene). Version-family\n differences are absorbed by runtime signature introspection: it uses\n `FastMCP.from_openapi` where the class exposes it and otherwise falls back to\n building `FastMCP(providers=[OpenAPIProvider(...)])`. That is a capability\n check rather than a version check — `from_openapi` is **not** a 2.x-only entry\n point, it exists in the 3.x line too. The dependency is pinned to\n `fastmcp==2.14.7` because that is the combination actually exercised under\n cassette replay; the known hard boundary is **4.0**, which moves the HTTP stack\n to `httpx2>=2.5` and therefore breaks the `httpx.AsyncBaseTransport` bridge the\n transport is built on (4.0 also re-splits the distribution into\n `fastmcp-slim`). The rationale is recorded next to the pin in `pyproject.toml`.\n- **The service key has no place to leak into.** The compiler emits no\n `security` or `securitySchemes` and strips key parameters out of the source,\n so the key is never an MCP tool argument, never in a spec file, never in a\n prompt log. Only the fact of transport-side injection survives, as\n `info.x-mcportal.key_injection: \"transport\"`.\n\nThe guard is wired on every default path. Budget resolution is\n`create_client(budget=...)` > the `CALL_BUDGET` environment variable > the\nprofile default, and omitting the argument still wires the guard — a README that\ndeclares the hard cap to be the axis of trust cannot let the guard quietly\nvanish. An in-flight reservation is taken at `before_call` and released at\n`after_call`, so the cap holds even when an MCP server issues concurrent tool\ncalls.\n\n## Benchmarks\n\nThe measurement plan is pre-registered.\n[`benchmarks/PROTOCOL.md`](benchmarks/PROTOCOL.md) fixes the items, repeat\ncounts, statistical definitions and limitations before the harness existed, and\nthe harness measures nothing that is not in that document. Result files embed a\nfingerprint of the protocol, so which revision produced a number stays checkable\nafter the fact.\n\n```\npython benchmarks/harness.py --label