airealty 한국 법령 (법제처 OPEN API)

airealty-lawmcp — 法制処 国家法令情報 OPEN API 上の法令 MCP サーバー

韓国の法令・条文・別表・沿革・判例・解釈例を、Claude などの MCP クライアントからすぐに検索できるサーバーです。 アップストリームは法制処国家法令情報共同活用 OPEN API（open.law.go.kr）で、すべて読み取り専用の応答を返します。

接続する — 2 つの方法

手順ごとのインストール・利用ガイド（Claude Code・Claude アプリ・Cursor、自分のキーの設定、上限・エラー表）：USER_GUIDE.md

1. ホスティングサーバー（トークンが必要）— インストール不要、1 行で接続

claude mcp add --transport http airealty-law https://law.airealty.co.kr/mcp --header "Authorization: Bearer <발급받은 토큰>"

トークンは運営者（[email protected]）に依頼すると、ユーザーごとに発行されます。トークンごとに、1 秒あたり 2 回・バースト 10 回・1 日 2,000 回（tools/call 基準）の制限があり、超過すると 429 と Retry-After が返されます。 Claude アプリ（claude.ai・Desktop）では、設定 → コネクター → カスタムコネクターを追加に同じ URL を入力し、リクエストヘッダー Authorization: Bearer <トークン> を設定します（リクエストヘッダーの入力は、組織の Owner のみに表示されるベータ機能です）。

2. ローカルインストール（自分の法制処キー）— 上限を自分だけで使います

1. open.law.go.kr に登録 → OPEN API を申請（承認まで 1～2 日）→ API認証キー管理で認証値（OC）をコピーします。

2. git clone https://github.com/conoc612-a11y/airealty-lawmcp && cd airealty-lawmcp && npm install
   claude mcp add airealty-law -e openlaw_API_KEY=<내 인증값> -- node /절대경로/airealty-lawmcp/src/index.js
   

   인증값은 환경변수 openlaw_API_KEY 또는 저장소 상위 폴더의 keys.env(openlaw_API_KEY=…)에서 읽고, 어디에도 출력하지 않습니다.

도구

코어 12(항상 노출): statute_find article_get statute_outline annex_get statute_history source_search source_get citation_audit precedent_trace contract_risk_scan research_run toolbox 카탈로그 12(toolbox 로 호출): term_lookup abbreviation_list change_feed jo_code article_refs link_build precedent_similar ordinance_link admin_rule_diff semantic_article_search english_statute article_with_cases

research_run 시나리오: rent_dispute housing_subscription redevelopment_procedure brokerage_duty zoning_check tax_on_transfer contract_check version_at statute_map amendment_watch. source_search 원천 20종 중 특별행정심판 2종은 acr_adjudication·civil_service_appeal. term_lookup 모드: define from_everyday to_everyday articles. article_get 은 format(기본 structured: 항·호 트리 + head, text: 평문만)으로 같은 본문을 두 번 싣지 않습니다.

모든 도구는 같은 봉투 {ok,total,returned,page?,items,warnings,notes,next,meta} / 오류 {ok:false,error:{code,message,retryable,hint?,candidates?}} 를 돌려주고, annotations.readOnlyHint=true 입니다.

직접 띄우기

npm install
npm test                            # 빌드 검사(tools/list ≤13KB · 코어 12 · 카탈로그 12) + 단위 테스트(모의 업스트림, 네트워크 없음)
node src/index.js                   # stdio MCP
node src/http-server.js             # Streamable HTTP 127.0.0.1:3457/mcp (POST 전용, GET/DELETE 405, /healthz)
LAWMCP_LIVE_URL=http://127.0.0.1:3457/mcp npm run test:live   # 실업스트림 B1~B11(서버 떠 있어야 함)
node tools/bench.js --out bench.json                           # cold start 5회 + B1~B11 5회

公開ホスティング（HTTP）の設定

• トークンは node tools/token.js add <이름> で発行します（値はそのとき 1 回だけ表示されます）。revoke <이름>・list も使用できます。ファイル ~/.config/airealty-lawmcp/tokens.txt に残るのは 이름 sha256(토큰) のみです。サーバーは 5 秒ごとにファイルの変更を反映するため、再起動は不要です。
• 認証の強制：LAWMCP_HOST がループバックアドレスではない場合、LAWMCP_REQUIRE_AUTH=1 の場合、またはトークン設定があるのに有効なトークンが 0 個の場合、終了コード 2 で終了します。トークンのないサーバーでも、cf-connecting-ip・x-forwarded-for が付いた（プロキシを経由した）リクエストには 401 を返します。JSON-RPC のバッチ（配列）は 400 で拒否します（上限の回避を防ぐため）。
• トークンの取得元：LAWMCP_TOKENS_FILE（ファイル、ハッシュまたは平文の行）または LAWMCP_TOKENS（이름:토큰,… の平文）。比較には sha256 と timingSafeEqual を使用し、ログには名前のみを記録します。
• トークンごとの上限（tools/call のみカウント）：LAWMCP_TOKEN_RATE_PER_SEC（2）・LAWMCP_TOKEN_BURST（10）・LAWMCP_TOKEN_DAILY（2000、UTC の午前 0 時にリセット — 1 日の上限に達した場合の Retry-After は最大 86400 秒）。
• /healthz は、トークンがない場合は ok・version のみを返し、トークンがある場合はキャッシュ・アップストリーム・上限・ウォームアップの状態も返します。
• ブラウザーの Origin はローカル（localhost・127.0.0.1）のみ許可されます。LAWMCP_ALLOWED_ORIGINS（カンマ区切り）で追加できます。それ以外の Origin は 403 になります。
• HTTPS は Cloudflare Tunnel などの前段で終端します。サーバー自体は平文 HTTP です。
• コンテナー：docker build -t airealty-lawmcp . && docker run -e openlaw_API_KEY=… -e LAWMCP_TOKENS=me:… -p 3457:3457 airealty-lawmcp

環境変数

LAWMCP_PORT（3457）・LAWMCP_HOST（127.0.0.1）・LAWMCP_CONCURRENCY（4、1～8）・LAWMCP_RATE_PER_SEC（5）・LAWMCP_BURST（8）— アップストリーム全体の上限 · LAWMCP_BUCKET_FILE（共有バケット用ファイル）・LAWMCP_CACHE_DIR（ディスクキャッシュ：辞書・条文番号インデックスは 24h・体系図の概要は 7d・判例リストは 6h — キーなし）・LAWMCP_HIERARCHY_BUDGET_MS（1200）· LAWMCP_PREWARM（既定値 1：サーバー起動後、src/prewarm.js のリストにある 38 件の法令のインデックス・体系図をバックグラウンドで事前に取得します。0 で無効）・LAWMCP_DEBUG（stderr のエラーログ）。

ウォームアップ・期限切れデータの更新は、drf.call(..., {background:true}) レーン経由でのみ実行されます。フォアグラウンドのリクエストが進行中の場合、またはバケットの空きが 2 トークン未満の場合は待機し、フォアグラウンドのリクエストが同じキーに合流した場合は、直ちに実行されます。/healthz の prewarm・auth に状態が表示されます。

構成

src/drf.js（呼び出し・バケット・再試行・サーキットブレーカー・バックグラウンドレーン）・cache.js・diskcache.js・article_index.js（条文番号インデックス）・hierarchy_cache.js（体系図の概要）・prewarm.js・dictionary.js（法令名辞書）・resolver.js（名前解決）・versions.js（版の選択）・articles.js（条文の構造化）・ citations.js+casenos.js（引用の抽出）・sources.js（20 種類の情報源）・risk/（文書リスクのルール・エンジン）・tools/*（ツール）・registry.js・stdio.js・http-server.js・auth.js（トークン・トークンごとの上限）。

プライバシー・出典

サーバーはリクエスト本文（検索語・文書テキスト）を法制処 API の呼び出しにのみ使用し、保存しません。ディスクキャッシュに残るのは法令由来のデータ（辞書・条文番号インデックス・体系図の概要・判例リスト）のみで、ユーザー入力や認証値は含まれません。ログに残るのはトークンの名前と回数のみです。 法令情報の著作権は法制処に帰属し、出典は応答の link（www.law.go.kr の公開 URL）に記載されます。商用利用の可否については、法制処の利用案内に従ってください。

ライセンス

MIT — LICENSE。