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

airealty-lawmcp — 법제처 국가법령정보 OPEN API 위의 법령 MCP 서버

대한민국 법령·조문·별표·연혁·판례·해석례를 Claude 등 MCP 클라이언트에서 바로 찾아보는 서버입니다. 업스트림은 법제처 국가법령정보 공동활용 OPEN API(open.law.go.kr)이며, 응답은 모두 읽기 전용입니다.

연결하기 — 두 가지 방법

단계별 설치·이용 안내(Claude Code·Claude 앱·Cursor, 자기 키 설치, 한도·오류 표): USERGUIDE.md**

1. 호스팅 서버(토큰 필요) — 설치 없이 한 줄

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

토큰은 운영자(conoc612@gmail.com)에게 요청하면 사용자별로 발급됩니다. 토큰마다 초당 2회·버스트 10회·하루 2,000회(tools/call 기준)로 제한되며, 넘으면 429 와 Retry-After 를 돌려줍니다. Claude 앱(claude.ai·Desktop)에서는 설정 → 커넥터 → 커스텀 커넥터 추가 에 같은 URL 을 넣고 요청 헤더 Authorization: Bearer <토큰> 을 지정합니다(요청 헤더 입력은 조직 Owner 에게만 보이는 베타 기능입니다).

2. 로컬 설치(자기 법제처 키) — 한도를 혼자 씁니다

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

1. open.law.go.kr 가입 → OPEN API 신청(승인 1~2일) → API인증키관리 에서 인증값(OC) 복사.
2. bash

인증값은 환경변수 `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) LAWMCPLIVEURL=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`

### 환경변수

Shortened. The full README is on GitHub.