mcportal

MCPortal

data.go.kr とグローバルな MCP エコシステムをつなぐ、欠けていた橋渡し役です。 MCPortal は韓国の公共 API 仕様を標準的な OpenAPI 3.1 に正規化し、 MCP サーバーにコンパイルします。また、すべての外部への呼び出しに対して、バックオフとキャッシュを備えた 厳格な日次予算を適用します。完全なオープンソースで、完全にセルフホスト可能です。

韓国語のドキュメント：README.ko.md — この英語版 README が 正式なドキュメントであり、韓国語版はその翻訳です。

正確性に関する免責事項

data.go.kr は「残りの利用枠」を取得するエンドポイントを公開していません。そのため、MCPortal の利用台帳に記録されるのは MCPortal 経由で行われた呼び出しのみであり、これは可能な限りの推定値です。同じ serviceKey を使って MCPortal の外部（別のスクリプト、ポータルのコンソール、別のツールなど）で行われた呼び出しは 台帳に記録されないため、台帳の値は実際の消費量の常に下限の概算となります。信頼すべきなのはこの推定値ではなく、**厳格な予算上限 (CALL_BUDGET)**です。台帳の値が誤っていても、厳格なガードによって日次上限を超える呼び出しは物理的に ブロックされます。そのため、利用枠超過によるアカウントへの制裁を防ぐ安全策は、常に CALL_BUDGET です。

API キーなしで利用できる範囲

API キーなしで利用可能	data.go.kr サービスキーが必要
録画・再生用カセットの再生	ライブ API 呼び出し
録画モードのテスト（合成トランスポート上で実行）を含む、テストスイート全体（pytest）	ライブレスポンスのサンプリング
コミット済みの仕様とそのカセットから MCP サーバーを起動すること（mcportal serve <id> --replay）— リポジトリのチェックアウトから、またはそこを参照する PyPI インストールから（注 1）	まだカセットのない API のアドホックな変換
コンパイルのデモ（examples/compile_demo.py）の再生成	新しいカセットの記録
プリセットバンドルの再生成と一覧表示（mcportal compile / mcportal presets）— 0.2.0 以降、wheel に同梱（注 1）	未解決のレスポンススキーマのサンプリング（mcportal sample）
クォータの状態確認（mcportal quota status）	キーが必要なベンチマーク項目 K1～K3
ベンチマークハーネスの実行（benchmarks/PROTOCOL.md にある、キー不要の 5 項目）	—

MCPortal のデモ、開発、CI のすべての処理は、キーなしで実行できます。録画・再生レイヤーは、以前に記録したカセットを再生するため、同じレスポンスの流れを再現でき、serviceKey がなくてもテストスイート全体を成功させられます。仕様から MCP への変換は、すでにビルド時に行われています — コンパイル済みアーティファクトは specs/ の下にコミットされています。そのため、リポジトリをクローンし、MCP サーバーを起動してツール呼び出しに応答する場合も、キーは不要です。mcportal serve 15000115 --replay を実行すると、環境内のどこにも serviceKey がない状態で、stdio 経由で 8 つのツールを提供できます。

あえて「クローン」と書いています。再生にはカセットが必要です。カセットは上流からのレスポンスを記録したもので、wheel には含まれず、リポジトリ内に置かれています（注 1）。そのため、pip install mcportal だけでは、--presets-root <path> または MCPORTAL_PRESETS=<path> を指定してチェックアウトを参照させるまで、再生できるものはありません。4 つのバンドルのうち 3 つにはカセットがあります。15081808 はサンプリング対象から意図的に除外されていたため、リポジトリにもカセットがありません（下記の プリセット を参照）。そのバンドルだけはライブ専用です。

キーが必要なのは限られた用途だけです。data.go.kr へのライブ通信と、まだカセットのない API のサンプリングまたは変換です。

注 1 — wheel に含まれるもの、含まれないもの。 0.2.0 以降、公開済みの wheel には 4 つのプリセットバンドルが含まれています（ビルド済みアーティファクトで計測した、バンドルファイル 16 個と presets/ 内のドキュメント 2 個）。そのため、通常の pip install mcportal だけで、チェックアウトなしに mcportal presets を実行できます。 0.2.2 以降、wheel には 3 つの sampled_schemas.json ファイル（15000115、15101612、15102108）も含まれています。15081808 はサンプリング対象から意図的に除外されているため、ファイルがありません。mcportal compile --check の実行に必要なため、これらを同梱しています。--check はファイルを差分比較するのではなく、ソース、キュレーション、サンプリングの各レイヤーから openapi.json を再合成します。そのため、サンプリングレイヤーがないと、インストールしたコピーで同梱の openapi.json 自体を再現できません。公開済みの 0.2.1 では、通常のインストールから compile --check を実行すると、4 件中 3 件が不一致として報告され、終了コード 3 が返されます（2026-08-15 に計測）。このバージョンでは、--presets-root <checkout>/presets を指定してください。0.2.2 では、インストールのみで 4 件すべてが一致し、終了コード 0 が返されます。 これら 3 つのファイルに含まれるのは、レスポンスから推定されたフィールド名と型のみで、レスポンス値は一切ありません。また、その構造はすでに openapi.json に含まれているため、wheel にすでに含まれているもの以外が公開されることはありません。wheel に引き続き含まれないのは、記録済みの上流トラフィックそのものです。cassettes/ と samples/ はリポジトリ内にのみ置かれているため、mcportal serve --replay はチェックアウトから実行する必要があります。別のバンドルセットを使用する場合や、PyPI インストールにカセットを使わせる場合は、--presets-root <path> または環境変数 MCPORTAL_PRESETS=<path> を指定して、MCPortal にチェックアウトを参照させてください。 mcportal presets は、バンドルが見つからない場合、検索したパスを表示します。

キー不要の再現手順

# 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

インストール

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

依存関係の方針：コアランタイムの依存先は httpx のみです。 仕様正規化コンパイラー（mcportal.compiler）は、標準ライブラリーと httpx のみを使用します。fastmcp は mcportal.mcp のみに必要で、オプションの [mcp] エクストラとして提供されます。これがインストールされていなくても、import mcportal とテストスイート全体は引き続き動作し、MCP レイヤーを呼び出すと、インストール方法を説明する韓国語の ImportError が発生します。また、[mcp] エクストラでは anyio も宣言しています。これは、同期から非同期へのブリッジが anyio.to_thread を直接インポートするためです。httpx は推移的に anyio を取り込みますが、直接インポートする依存関係は直接宣言することで、バージョン固定やロックファイルで制約できるようにします。

import mcportal は mcportal.mcp を インポートしません。これにより、fastmcp がインストールされていなくてもインポートできます。MCP シンボルは、モジュールの __getattr__ を介して、最初に属性へアクセスしたときに遅延解決されます（PEP 562）。そのため、from mcportal.mcp import build_server と mcportal.build_server は同じオブジェクトを参照します。どちらの書き方でも問題ありません。

単一キーの原則（複数キーのローテーションはしない）

MCPortal の data.go.kr プロファイルは、複数キーのローテーションに対応していません。 data.go.kr は各開発アカウントに 1 つのキーを発行し、そのキーに対して 1 日あたりの呼び出し上限を適用します。この上限を回避するために複数のキーを切り替えると、サービスの運用ポリシーに違反し、アカウントへの制裁を招くおそれがあります。MCPortal はこの仕組みをそのまま尊重し、単一のキーを受け付けます。上限が低すぎる場合に推奨される対応は、data.go.kr が定める手続き、つまり利用事例を登録して運用ティアを申請することであり、キーを増やすことではありません。

CLI

CLI では標準ライブラリの argparse のみを使用します。新たなランタイム依存関係を一切追加しないことは、このプロジェクトにおける必須ルールです。そのため、ターミナルの表も手作業でレイアウトしています（ハングルは全角幅として計算し、ASCII の罫線を使い、Windows の cp949 コンソールでも安全に表示できます）。

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]

サブコマンド	説明
quota status	今日の使用量（KST）、予算、残りの予算、キーのフィンガープリントごとの状態を表示します。**台帳は読み取り専用（mode=ro）で開かれ、作成されることはありません。**予算の解決順序は --budget > CALL_BUDGET > プロファイルのデフォルトで、どの方法が使われたかも出力に示されます
compile	プリセットバンドルを再生成します。内容に変更のないファイルは書き換えられません。--check は何も書き込まず、バイト単位の比較のみを行います
presets	バンドルを表形式で一覧表示します。--verbose を指定するとキュレーションの注記が表示されます
sample	未解決のままのレスポンススキーマを埋めるライブサンプリングを実行し、推定されたスキーマ、レスポンスボディ、再生可能なカセットを書き込みます。キーが必要な唯一のサブコマンドです。キーは、--key-env VAR で指定された環境変数からのみ取得され、リテラル引数として渡すことはできません
serve	1 つのバンドルを stdio 経由の MCP サーバーとして起動します。デフォルトの --replay ではキーは不要です。--key-env VAR を指定すると、同じクォータガードを通じてライブで動作します。[mcp] エクストラが必要です。リポジトリのチェックアウトを前提としてドキュメント化されています。--replay は presets/<id>/cassettes/<id>.json を読み込みますが、このファイルは wheel に含まれていません（注 1）。そのため、PyPI からインストールした場合は --presets-root <checkout>/presets を渡すか、MCPORTAL_PRESETS=<checkout>/presets を設定してください。4 つのバンドルのうち 3 つにはカセットがありますが、15081808 はリポジトリ内にもカセットがないため、ライブでのみ動作します。stdout はプロトコル専用です。バナーを含む、人が読めるすべての行は stderr に出力されます

終了コード：0 成功（「台帳なし」、「プリセットなし」、「変更なし」を含みます。空の状態は失敗ではありません）／1 実行失敗／2 使用方法エラー／3 compile --check で差分を検出／130 ユーザーによる割り込み。

--json は stdout に JSON のみを出力します（人間向けの文章は混在しないため、パイプで安全に使用できます）。また、すべてのエラーを stderr に送ります。どの経路でも生のサービスキーが表示されることはありません。--key-env であっても、環境変数からキーを読み込み、フィンガープリントはローカルで計算されます。台帳には生のキーが保存されないため、CLI が表示できるのはフィンガープリントだけです。

プリセット — 3つのサービス、4つのデータセット

presets/ には、data.go.kr で実際に公開されている仕様をもとに作成したバンドルが格納されています。目的は、すべての生成ツールの説明が「リスト照会」になってしまう素朴な仕様変換の失敗を、コードではなくデータで解決する方法を示すことです。

ID	サービス	分野	ソースの種類	操作数	公開されているデータライセンス
15000115	法制処 — 国家法令情報共有サービス	法令	rest_doc_manual	8	KOGL Type 1（表示）
15081808	国税庁 — 事業者登録の有効性・状態照会	事業者登録	odcloud_swagger	2	制限の記載なし
15101612	関税庁 — 国別貿易	通関	gw_swagger	1	制限の記載なし
15102108	関税庁 — 輸出入概要	通関	gw_swagger	1	制限の記載なし

ライセンスの表記は、各バンドルに記録された取得日に data.go.kr に表示されていた内容です。分野ごとに3つのサービスがあり、通関だけが2つのデータセットを持つため、すべての文書で**「3つのサービス（4つのデータセット）」**と記載しています。

12個のレスポンススキーマのうち10個は未解決でしたが、2026-08-09 のライブサンプリングで10個すべてが確定しました（15000115 が8個、15101612 が1個、15102108 が1個 — 各操作につき1回、合計10回の呼び出し）。推定したスキーマは各バンドルの sampled_schemas.json に、レスポンスボディは samples/ に、リクエスト／レスポンスのペアは cassettes/ に保存されているため、キーなしでオフライン再生できます。サンプリング済みのバンドルでは、info.x-mcportal に generation_mode: "sampled" が記録されます。

残りの2つの操作（15081808）は、未解決だったことはありません — そのソースにはレスポンススキーマが宣言されています。このバンドルは、リクエストボディに事業者登録番号が含まれるため、意図的にサンプリング対象から除外しました。そのため、スキーマは宣言されていますが、実測はされていません。MCPortal はどちらの状態も隠しません。ライブでの件数は、生成されたドキュメントの info.x-mcportal.schema_inference.unresolved に記録され、各バンドルで未確認の事項は、それぞれの presets/<id>/README.md に記載されています。未検証の内容を検証済みであるかのように書くことは、このプロジェクトのルールに反します。

バンドルはコミットされる4つのファイルで構成され、サンプリングの記録がある場合はそれも含まれます。

presets/<id>/
├─ source.json           <- the spec document plus source URL, acquisition date, sha256
├─ curation.json         <- human-checked descriptions, examples, hints
├─ openapi.json          <- the merge of both layers (the committed artifact)
├─ README.md             <- provenance and open questions for this dataset
├─ sampled_schemas.json  <- schemas inferred from live samples (sampled bundles only)
├─ samples/              <- scrubbed response bodies from those calls
└─ cassettes/            <- request/response pairs for offline replay

上部の4つのファイルは wheel に含まれます。また、0.2.2 以降は sampled_schemas.json が存在する場合、それも含まれます — 4つのバンドルのうち3つです。これは、これがないと compile --check で openapi.json を再合成できないためです（注1）。記録されたトラフィックである samples/ と cassettes/ は、リポジトリにのみ含まれます。

• 下位レイヤーには、分野に関する知識が一切含まれていません。 mcportal.compiler.curation は、キュレーションデータを読み込み、検証して統合する汎用エンジンです。コードには機関名もデータセット名も登場せず、ソース文字列をスキャンするテストでこれを強制しています。
• キュレーションによって仕様の事実が変わることはありません。 説明、例、タグ、ヒントを追加します。パラメーターの型、位置、必須かどうか、および操作のパスとメソッドは、ソース仕様で宣言された内容のままです。事実を修正できるのは2つの方法だけで、どちらも文書化された reason が必要です。レスポンススキーマを未解決に降格する方法と、パラメーターを削除する方法です。
• 同じ入力であれば、openapi.json はバイト単位で完全に同一に再生成されます。CI のゲートとして mcportal compile --check を使用してください（差分がある場合の終了コードは3です）。ただし、info.x-mcportal.tool_version にはパッケージのバージョンが含まれるため、バージョンを上げると4つの成果物すべてが変わります。その場合は再生成するのが慣例です。

規約と未対応項目は presets/README.md に、仕様メタデータの出典と利用条件は presets/NOTICE-DATA.md に記載されています。

アーキテクチャ

コンパイル時には2つのレイヤー、実行時には1つのガード付きチェーンです。

COMPILE TIME  (offline: no key, no network)

  spec documents                      +--------------------------------+
   - odcloud OAS (JSON)               | lower layer: the compiler      |
   - gateway Swagger 2.0 / 3.x  --->  | zero domain knowledge          |
   - hand-mapped usage guide          | sources -> SourceSpec -> IR    |
                                      +---------------+----------------+
                                                      |
  curation.json                                       |
  (human-checked descriptions,  --------------->    merge
   examples, hints)                    upper layer: data, not code
                                                      |
                                                      v
                                         openapi.json (committed;
                                         byte-identical on rebuild)

RUN TIME  (one MCP tool call)

  MCP client
      |  tool call
      v
  FastMCP server            <- built by FastMCP.from_openapi() from openapi.json
      |
      v
  sync/async bridge  ->  MCPortalTransport
                            |-- quota guard      token bucket + SQLite ledger
                            |                    + CALL_BUDGET hard cap + backoff
                            |-- key injection    the key never enters the spec
                            |-- TTL cache
                            |-- record / replay  cassettes, scrubbed on write
                            |-- normalization    XML -> JSON, EUC-KR, error codes
                            v
                     data.go.kr      (or the cassette, in replay mode)

この構成には、明示しておくべき重要な点が2つあります。

• ツール定義は手作業で生成されません。 FastMCP.from_openapi() が仕様からツールへの変換を担います。MCPortal はその前の段階（仕様の正規化）と、その後の段階（クォータと衛生管理）を担います。バージョン系列の違いは、実行時のシグネチャイントロスペクションで吸収します。クラスが FastMCP.from_openapi を公開していればそれを使用し、そうでなければ FastMCP(providers=[OpenAPIProvider(...)]) の構築にフォールバックします。これはバージョンチェックではなく機能の有無の確認です。from_openapi は 2.x 専用のエントリーポイントではなく、3.x 系列にも存在します。依存関係は fastmcp==2.14.7 に固定しています。これは、カセット再生のもとで実際に動作確認済みの組み合わせだからです。既知の重大な境界は 4.0 です。HTTP スタックが httpx2>=2.5 に移行するため、このトランスポートの基盤である httpx.AsyncBaseTransport ブリッジが動作しなくなります（4.0 ではディストリビューションも fastmcp-slim に再分割されます）。固定の理由は pyproject.toml の固定指定の隣に記録されています。
• サービスキーが漏れる余地はありません。 コンパイラーは security も securitySchemes も出力せず、ソースからキーのパラメーターを削除するため、キーが MCP ツールの引数、仕様ファイル、プロンプトログに含まれることはありません。トランスポート側で注入されるという事実だけが、info.x-mcportal.key_injection: "transport" として残ります。

ガードは、すべてのデフォルト経路に組み込まれています。予算の解決順序は create_client(budget=...) > CALL_BUDGET 環境変数 > プロファイルのデフォルトです。引数を省略してもガードは組み込まれます。ハード上限を信頼の軸とする README で、ガードが気づかないうちに消えてしまうことは許されません。処理中の予約は before_call で確保し、after_call で解放するため、MCP サーバーがツール呼び出しを並行して実行する場合でも上限が守られます。

ベンチマーク

測定計画は事前登録されています。 benchmarks/PROTOCOL.md には、ハーネスが作成される前に測定項目、反復回数、統計上の定義、制限事項が定められており、ハーネスはこの文書に記載されていないものを測定しません。結果ファイルにはプロトコルのフィンガープリントが埋め込まれるため、どのリビジョンで数値が得られたかを後から確認できます。

python benchmarks/harness.py --label <label>

キー不要の5項目を測定します（リプレイのラウンドトリップ、スクラブ処理、コンパイルと決定性、クォータガードのオーバーヘッド、FastMCP のビルド）。ネットワーク呼び出しはゼロです。入力はすべて合成データか、コミット済みのプリセットです。外れ値は除外しません。生のサンプルは結果ファイルに含まれるため、誰でも再計算できます。

主な結果：クォータガードのオーバーヘッドは、呼び出しあたり中央値で +0.90 ms です （+901,050 ns。ガードありの中央値は 1.04 ms、ガードなしの中央値は 0.14 ms。ウォームアップ20回後に N = 200。2026-08-09、Windows 10、CPython 3.11.9、httpx 0.28.1、SQLite 3.45.1 で測定）。

この主な結果は環境に依存し、環境も主張の一部です。 2026-08-15 に新規プロビジョニングしたマシンで同じハーネスを再実行したところ、ガードありの中央値は 738.9 us、ガードなしの中央値は 91.0 us となり、増分は +0.65 ms でした。どちらの数値も誤りではありません。絶対コストはホストの SQLite 書き込みレイテンシに左右されるため、第三者が再現する数値はそれぞれの環境のものになります。主な結果を引用する際は測定環境も併記するか、再測定してください。

この数値は絶対増分として捉え、2つの事実も併せて考慮してください。この数値には（WAL ジャーナルモードでの）SQLite の台帳書き込みが含まれます。この書き込みも実際のコストの一部だからです。差し引く基準値は、インメモリの httpx.MockTransport を使った素の httpx.Client であり、ソケットも I/O もありません。そのため、同じ測定値を割合で表すと、必然的に大きな値になり、それ単独では意味をなしません。実際の data.go.kr とのラウンドトリップを基準にすると比較結果は異なりますが、MCPortal はその比較をここでは主張していません。測定していないためです。

これらの数値は MCPortal が自身に追加するレイヤーのコストであり、競合ライブラリとの比較ではありません。 2層設計が有効かどうかを評価する項目（K2 — 素朴な生成とキュレーションにおけるツール呼び出し成功率）は、プロトコルで定義されているだけで、実行されていません。 定義をあらかじめ記述しておくのは意図的です。結果が出た後で都合のよい基準を選ぶのを防ぐためです。0.2.0 で使用したライブキーはレスポンススキーマのサンプリングのみに使われました。キー依存のベンチマーク項目 K1〜K3 は今回のリリースの対象外です。

機械可読なプリセットルート

mcportal presets --json は root と併せて root_source キーを出力し、採用されたプリセットルートの取得元を示します。取得元は argument（明示的な --presets-root）、env:MCPORTAL_PRESETS、discovered（デフォルトの検索で検出）、または none（ルートなし）です。これにより、スクリプトは意図的に指定されたルートと、偶然設定されたルートを見分けられます。

ライセンス

Apache-2.0。詳しくは LICENSE と NOTICE をご覧ください。

データ由来ファイル（テストフィクスチャ、レスポンスサンプル、コンパイラー生成物）の出所と利用条件は、別途 NOTICE-DATA.md で管理しています。

• API の呼び出しによって取得したレスポンスペイロードは、一切コミットしていません。 テストフィクスチャ、カセット、デモ用生成物はすべて合成データであり、キーを使わない再現手順は、これらの合成フィクスチャのみで成り立っています。
• 公開 API の仕様メタデータ（Swagger ドキュメント、リクエスト／レスポンスの表）は、取得元 URL と取得日を記録したうえで presets/ にコミットしています。取得はすべて認証なしで行っており、サービスキーの使用はゼロ、ゲートウェイへのデータ呼び出しもゼロです。仕様書に含まれるサンプル値は、ポータルがドキュメント用に記載したもので、すべてプレースホルダーです。ファイルごとの取得元、利用条件、サンプル値の一覧は presets/NOTICE-DATA.md で管理しています。
• 個人を特定できる情報（実名、実際の事業者登録番号、個人の電話番号、個人のメールアドレス）は一切含まれていません。この記述の対象はバンドルの生成物、すなわち source.json、curation.json、openapi.json、各 README.md です。presets/_raw/ にあるポータルページのスナップショットには、元のページに掲載されていた運営機関の公開ヘルプデスクのメールアドレス（[email protected]）、代表電話番号（1566-0025）、および各データセットの管理部門の代表電話番号が残っています。これらは個人の連絡先ではなく、機関の連絡先です。根拠資料と全一覧は presets/NOTICE-DATA.md §2-1 で管理しています。