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

airealty-lawmcp — 基于法制处国家法令信息 OPEN API 的法令 MCP 服务

可在 Claude 等 MCP 客户端中直接查询韩国法令、条文、附表、沿革、判例和解释案例。 上游服务为法制处国家法令信息共享 OPEN API（open.law.go.kr），所有响应均为只读。

连接 — 两种方式

分步安装与使用指南（Claude Code、Claude 应用、Cursor、自行配置密钥、限额与错误表）：USER_GUIDE.md

1. 托管服务（需要令牌）— 无需安装，一行即可

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

向运营者（[email protected]）申请令牌，每位用户会获得单独的令牌。每个令牌的限额为每秒 2 次、突发 10 次、每天 2,000 次（按 tools/call 计）；超出限额时会返回 429 和 Retry-After。 在 Claude 应用（claude.ai·Desktop）中，前往 设置 → 连接器 → 添加自定义连接器，填入相同的 URL，并设置请求标头 Authorization: Bearer <토큰>（输入请求标头是仅对组织 Owner 开放的 Beta 功能）。

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 <이름> 签发令牌（令牌值只会在签发时显示一次）· 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 零点重置 — 每日上限对应的 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 公开地址）标注。是否可用于商业用途，请遵循法制处的使用指南。

许可证

MIT — LICENSE。