korean-law-mcp 2.1.6 → 2.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Chris
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Chris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,279 +1,198 @@
-# Korean Law MCP Server & CLI
-
-법제처 Open API 기반 한국 법령 MCP 서버 + CLI. 64개 도구로 법령, 판례, 행정규칙, 자치법규, 법령해석례 등을 검색·조회·분석할 수 있다.
-
-[![MCP Compatible](https://img.shields.io/badge/MCP-1.27-blue)](https://modelcontextprotocol.io)
-[![CLI](https://img.shields.io/badge/CLI-korean--law-green)](#cli-사용법)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
-
-## 주요 특징
-
-- **MCP + CLI 동시 지원**: MCP 서버(Claude Desktop 등)와 CLI(터미널/스크립트) 모두 사용 가능
-- **법률 도메인 특화**: 약칭 자동 인식(`화관법` → `화학물질관리법`), 조문번호 변환(`제38조` ↔ `003800`), 3단 위임 구조 시각화
-- **별표/별지서식 본문 추출**: HWPX·HWP 파일을 자동 다운로드 → 텍스트/표를 Markdown으로 변환. PDF는 링크 반환
-- **64개 도구**: 법령·판례·행정규칙·자치법규·헌재결정·행정심판·조세심판·관세해석·법령용어 등 포괄
-- **캐시**: 검색 1시간, 조문 24시간 TTL
-
-## 설치
-
-### 사전 준비
-
-- Node.js 18+
-- [법제처 API 키](https://open.law.go.kr/LSO/openApi/guideResult.do) (무료)
-
-### npm 글로벌 설치
-
-```bash
-npm install -g korean-law-mcp
-```
-
-### MCP 클라이언트 설정
-
-아래 JSON을 각 클라이언트 설정 파일에 추가한다.
-
-```json
-{
-  "mcpServers": {
-    "korean-law": {
-      "command": "korean-law-mcp",
-      "env": {
-        "LAW_OC": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-| 클라이언트 | 설정 파일 |
-|-----------|----------|
-| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` (Win) / `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) |
-| Cursor | `.cursor/mcp.json` |
-| Windsurf | `.windsurf/mcp.json` |
-| Continue | `~/.continue/config.json` (배열 형식: `"mcpServers": [...]`) |
-| Zed | `~/.config/zed/settings.json` (`"context_servers"` 키 사용) |
-
-설정 후 클라이언트를 재시작하면 바로 사용 가능.
-
-### 원격 MCP (설치 없이 바로 사용)
-
-공개 엔드포인트를 MCP 클라이언트에 등록하면 설치 없이 사용 가능하다.
-
-```json
-{
-  "mcpServers": {
-    "korean-law": {
-      "url": "https://korean-law-mcp.fly.dev/mcp"
-    }
-  }
-}
-```
-
-> API 키를 헤더로 전달하려면 `x-law-oc` 헤더를 사용한다.
-
-## CLI 사용법
-
-MCP 클라이언트 없이 터미널에서 직접 64개 도구를 실행할 수 있다.
-
-### CLI 실행
-
-```bash
-# 글로벌 설치 후
-npm install -g korean-law-mcp
-export LAW_OC=your-api-key
-
-# 법령 검색
-korean-law search_law --query "관세법"
-
-# 조문 조회
-korean-law get_law_text --mst 160001 --jo "제38조"
-
-# 판례 검색
-korean-law search_precedents --query "부당해고"
-
-# 도구 목록
-korean-law list
-
-# 카테고리별 필터
-korean-law list --category 판례
-
-# 도구 상세 도움말
-korean-law help search_law
-
-# JSON으로 파라미터 전달
-korean-law get_law_text --json-input '{"mst":"160001","jo":"제38조"}'
-```
-
-### npm run으로 실행 (로컬 개발)
-
-```bash
-npm run cli -- search_law --query "민법"
-npm run cli -- list
-```
-
-### 파이프 조합
-
-```bash
-# 검색 결과에서 MST만 추출
-korean-law search_law --query "관세법" | grep MST
-
-# 여러 법령 순차 조회
-for mst in 160001 160002; do
-  korean-law get_law_text --mst "$mst" --jo "제1조"
-done
-```
-
-### Docker / 자체 배포
-
-```bash
-docker build -t korean-law-mcp .
-docker run -e LAW_OC=your-api-key -p 3000:3000 korean-law-mcp
-```
-
-MCP 엔드포인트: `https://your-host:3000/mcp`
-
-## 도구 목록 (64개)
-
-### 검색 (11개)
-
-| 도구 | 설명 |
-|------|------|
-| `search_law` | 법령 검색 (약칭 자동 인식) |
-| `search_admin_rule` | 행정규칙 검색 (훈령/예규/고시) |
-| `search_ordinance` | 자치법규 검색 |
-| `search_precedents` | 판례 검색 |
-| `search_interpretations` | 법령해석례 검색 |
-| `search_all` | 통합 검색 |
-| `suggest_law_names` | 법령명 자동완성 |
-| `advanced_search` | 고급 검색 (기간/키워드 필터) |
-| `get_law_history` | 날짜별 법령 변경이력 |
-| `get_annexes` | 별표/별지서식 조회 + HWPX/HWP 본문 추출 |
-| `parse_jo_code` | 조문번호 ↔ JO 코드 변환 |
-
-### 조회 (9개)
-
-| 도구 | 설명 |
-|------|------|
-| `get_law_text` | 법령 조문 전문 |
-| `get_admin_rule` | 행정규칙 전문 |
-| `get_ordinance` | 자치법규 전문 |
-| `get_precedent_text` | 판례 전문 |
-| `get_interpretation_text` | 법령해석례 전문 |
-| `get_batch_articles` | 여러 조문 일괄 조회 (`laws` 배열로 복수 법령 지원) |
-| `get_article_with_precedents` | 조문 + 관련 판례 |
-| `compare_old_new` | 신구법 대조 |
-| `get_three_tier` | 법률→시행령→시행규칙 3단 비교 |
-
-### 분석 (9개)
-
-| 도구 | 설명 |
-|------|------|
-| `compare_articles` | 법령 간 조문 비교 |
-| `get_law_tree` | 위임 구조 트리 |
-| `get_article_history` | 조문 개정 연혁 |
-| `summarize_precedent` | 판례 요약 |
-| `extract_precedent_keywords` | 판례 키워드 추출 |
-| `find_similar_precedents` | 유사 판례 검색 |
-| `get_law_statistics` | 법령 통계 |
-| `parse_article_links` | 조문 내 참조 파싱 |
-| `get_external_links` | 외부 링크 생성 |
-
-### 전문 분야 (4개)
-
-| 도구 | 설명 |
-|------|------|
-| `search_tax_tribunal_decisions` | 조세심판원 재결례 검색 |
-| `get_tax_tribunal_decision_text` | 재결례 전문 |
-| `search_customs_interpretations` | 관세청 법령해석 검색 |
-| `get_customs_interpretation_text` | 관세 해석 전문 |
-
-### 헌재·행심·위원회 결정 (6개)
-
-| 도구 | 설명 |
-|------|------|
-| `search_constitutional_decisions` | 헌법재판소 결정례 검색 |
-| `get_constitutional_decision_text` | 헌재 결정 전문 |
-| `search_admin_appeals` | 행정심판례 검색 |
-| `get_admin_appeal_text` | 행정심판 전문 |
-| `search_ftc_decisions` / `search_nlrc_decisions` / `search_pipc_decisions` | 공정위/노동위/개보위 결정 검색 |
-| `get_ftc_decision_text` / `get_nlrc_decision_text` / `get_pipc_decision_text` | 결정 전문 |
-
-### 지식베이스 (7개)
-
-| 도구 | 설명 |
-|------|------|
-| `get_legal_term_kb` | 법령용어 지식베이스 검색 |
-| `get_legal_term_detail` | 용어 상세 정의 |
-| `get_daily_term` | 일상용어 검색 |
-| `get_daily_to_legal` | 일상용어 → 법령용어 |
-| `get_legal_to_daily` | 법령용어 → 일상용어 |
-| `get_term_articles` | 용어 사용 조문 |
-| `get_related_laws` | 관련법령 조회 |
-
-### 기타 (2개)
-
-| 도구 | 설명 |
-|------|------|
-| `search_ai_law` | 자연어 지능형 검색 (`lawTypes` 필터 지원) |
-| `search_english_law` / `get_english_law_text` | 영문법령 검색/조회 |
-| `search_historical_law` / `get_historical_law` | 연혁법령 검색/조회 |
-| `search_legal_terms` | 법령용어 사전 검색 |
-
-### 체인 도구 (7개)
-
-여러 도구를 자동 조합하여 복합 리서치를 한 번의 호출로 수행한다.
-
-| 도구 | 설명 |
-|------|------|
-| `chain_law_system` | 법체계 파악 (법령검색→3단비교→조문 일괄 조회) |
-| `chain_action_basis` | 처분/허가 근거 확인 (법체계→해석례→판례→행심 병렬) |
-| `chain_dispute_prep` | 불복/쟁송 대비 (판례+행심+전문결정례 병렬) |
-| `chain_amendment_track` | 개정 추적 (신구대조+조문이력) |
-| `chain_ordinance_compare` | 조례 비교 연구 (상위법→전국 조례 검색) |
-| `chain_full_research` | 종합 리서치 (AI검색→법령→판례→해석) |
-| `chain_procedure_detail` | 절차/비용/서식 (법체계→별표→시행규칙별표) |
-
-## 사용 예시
-
-```
-사용자: "관세법 제38조 알려줘"
-→ search_law("관세법") → MST 획득 → get_law_text(mst, jo="003800")
-
-사용자: "화관법 최근 개정 비교"
-→ "화관법" → "화학물질관리법" 자동 변환 → compare_old_new(mst)
-
-사용자: "근로기준법 제74조 해석례"
-→ search_interpretations("근로기준법 제74조") → get_interpretation_text(id)
-
-사용자: "산업안전보건법 별표1 내용 알려줘"
-→ get_annexes(lawName="산업안전보건법 별표1") → HWPX 파일 다운로드 → 표/텍스트 Markdown 변환
-```
-
-## 환경변수
-
-| 변수 | 필수 | 기본값 | 설명 |
-|------|------|--------|------|
-| `LAW_OC` | O | - | 법제처 API 키 ([발급](https://open.law.go.kr/LSO/openApi/guideResult.do)) |
-| `PORT` | X | 3000 | HTTP 서버 포트 |
-| `CORS_ORIGIN` | X | `*` | CORS 허용 오리진 (프로덕션 배포 시 반드시 설정 권장) |
-| `RATE_LIMIT_RPM` | X | 60 | IP당 분당 요청 제한 (0=비활성화) |
-
-## 문서
-
-- [docs/API.md](docs/API.md) - 64개 도구 레퍼런스
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - 시스템 설계
-- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - 개발 가이드
-
-## 라이선스
-
-MIT - [LICENSE](LICENSE) 참조
-
-## 감사
-
-- [법제처](https://www.law.go.kr) Open API
-- [LexDiff](https://github.com/chrisryugj/lexdiff) 검색어 정규화 코드
-- [Anthropic](https://anthropic.com) MCP 프로토콜
-
----
-
-<sub>Made by 류주임 @ 광진구청 AI동호회 AI.Do</sub>
+# Korean Law MCP
+
+**대한민국 법령 검색·조회·분석 89개 도구** — 법령, 판례, 행정규칙, 자치법규, 조약, 해석례를 AI 어시스턴트나 터미널에서 바로 사용.
+
+[![npm version](https://img.shields.io/npm/v/korean-law-mcp.svg)](https://www.npmjs.com/package/korean-law-mcp)
+[![MCP 1.27](https://img.shields.io/badge/MCP-1.27-blue)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> 법제처 Open API 기반 MCP 서버 + CLI. Claude Desktop, Cursor, Windsurf, Zed, Claude.ai 등에서 바로 사용 가능.
+
+[English](./README-EN.md)
+
+![Korean Law MCP 데모](./demo.gif)
+
+---
+
+## v2.3.0 변경사항
+
+- **도구 프로필 (lite/full)** — 웹 클라이언트(Claude.ai 등)용 lite 프로필 도입. 89개 → 14개로 자동 축소하여 컨텍스트 소비 87% 절감. `/mcp?profile=lite`로 사용.
+  - **체인 8개** + 핵심 직접 도구 4개 + 메타 도구 2개 = 14개로 동일 기능 커버
+  - `discover_tools`: 의도/카테고리로 숨겨진 전문 도구 검색
+  - `execute_tool`: discover로 찾은 도구를 프록시 실행
+- **kordoc 통합 파서** — 자체 HWP5/HWPX/PDF 파서 5개를 [kordoc](https://github.com/chrisryugj/kordoc) 통합 파서로 교체. 의존성 경량화.
+
+<details>
+<summary>v2.2.0 변경사항</summary>
+
+- **23개 신규 도구 (64 → 87)** — 조약, 법령-자치법규 연계, 학칙/공단/공공기관 규정, 특별행정심판, 감사원 결정, 조항상세, 문서분석, 행정규칙 신구대조 등 대폭 확장.
+- **문서분석 엔진** — 8종 문서유형 분류, 17개 리스크규칙, 금액/기간 추출, 조항 충돌 탐지.
+- **법령-자치법규 연계 (4개 도구)** — 법률↔조례 위임 체인을 양방향 추적.
+- **조약 지원 (2개 도구)** — 대한민국이 체결한 양자/다자 조약 검색 및 전문 조회.
+- **보안 강화** — CORS 오리진 제어, API 키 헤더 전용, 보안 헤더, 세션 ID 마스킹.
+
+</details>
+
+<details>
+<summary>v1.8.0 – v1.9.0 기능</summary>
+
+- **체인 도구 8개** — 복합 리서치를 한 번의 호출로: `chain_full_research`(AI검색→법령→판례→해석), `chain_law_system`, `chain_action_basis`, `chain_dispute_prep`, `chain_amendment_track`, `chain_ordinance_compare`, `chain_procedure_detail`.
+- **일괄 조문 조회** — `get_batch_articles`가 `laws` 배열로 복수 법령 한 번에 조회.
+- **AI 검색 법령종류 필터** — `search_ai_law`에 `lawTypes` 필터 추가.
+- **구조화 에러 포맷** — `[에러코드] + 도구명 + 제안` 형식으로 64개 도구 통일.
+- **HWP 테이블 수정** — 구형 HWP 파서에서 `paragraph.controls[].content` 경로의 테이블 추출 지원.
+
+</details>
+
+---
+
+## 왜 만들었나
+
+대한민국에는 **1,600개 이상의 현행 법률**, **10,000개 이상의 행정규칙**, 그리고 대법원·헌법재판소·조세심판원·관세청까지 이어지는 방대한 판례 체계가 있습니다. 이 모든 게 [법제처](https://www.law.go.kr)라는 하나의 사이트에 있지만, 개발자 경험은 최악입니다.
+
+이 프로젝트는 그 전체 법령 시스템을 **89개 구조화된 도구**로 감싸서, AI 어시스턴트나 스크립트에서 바로 호출할 수 있게 만듭니다. 법제처를 백 번째 수동 검색하다 지친 공무원이 만들었습니다.
+
+---
+
+## 빠른 시작
+
+### MCP 서버 (Claude Desktop / Cursor / Windsurf)
+
+```bash
+npm install -g korean-law-mcp
+```
+
+MCP 클라이언트 설정에 추가:
+
+```json
+{
+  "mcpServers": {
+    "korean-law": {
+      "command": "korean-law-mcp",
+      "env": {
+        "LAW_OC": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+API 키는 [법제처 Open API](https://open.law.go.kr/LSO/openApi/guideResult.do)에서 무료 발급.
+
+| 클라이언트 | 설정 파일 |
+|-----------|----------|
+| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` (Win) / `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) |
+| Cursor | `.cursor/mcp.json` |
+| Windsurf | `.windsurf/mcp.json` |
+| Continue | `~/.continue/config.json` |
+| Zed | `~/.config/zed/settings.json` |
+
+### 원격 MCP (설치 없이 바로)
+
+```json
+{
+  "mcpServers": {
+    "korean-law": {
+      "url": "https://korean-law-mcp.fly.dev/mcp"
+    }
+  }
+}
+```
+
+**Claude.ai 등 웹 클라이언트** — 컨텍스트 절약을 위해 lite 프로필 권장:
+
+```json
+{
+  "mcpServers": {
+    "korean-law": {
+      "url": "https://korean-law-mcp.fly.dev/mcp?profile=lite"
+    }
+  }
+}
+```
+
+> lite 프로필은 체인 8개 + 핵심 4개 + 메타 2개 = **14개 도구**로 동일 기능 커버. 특수 도구가 필요하면 `discover_tools` → `execute_tool`로 접근.
+
+### CLI
+
+```bash
+npm install -g korean-law-mcp
+export LAW_OC=your-api-key
+
+korean-law search_law --query "관세법"
+korean-law get_law_text --mst 160001 --jo "제38조"
+korean-law search_precedents --query "부당해고"
+korean-law list                          # 89개 전체 도구 목록
+korean-law list --category 판례          # 카테고리별 필터
+korean-law help search_law               # 도구 도움말
+```
+
+---
+
+## 사용 예시
+
+```
+"관세법 제38조 알려줘"
+→ search_law("관세법") → MST 획득 → get_law_text(mst, jo="003800")
+
+"화관법 최근 개정 비교"
+→ "화관법" → "화학물질관리법" 자동 변환 → compare_old_new(mst)
+
+"근로기준법 제74조 해석례"
+→ search_interpretations("근로기준법 제74조") → get_interpretation_text(id)
+
+"산업안전보건법 별표1 내용 알려줘"
+→ get_annexes(lawName="산업안전보건법 별표1") → HWPX 파일 다운로드 → 표/텍스트 Markdown 변환
+```
+
+---
+
+## 도구 목록 (89개)
+
+| 카테고리 | 개수 | 주요 도구 |
+|----------|------|----------|
+| **검색** | 11 | `search_law`, `search_precedents`, `search_all`, `get_annexes` |
+| **조회** | 9 | `get_law_text`, `get_batch_articles`, `compare_old_new`, `get_three_tier` |
+| **분석** | 10 | `compare_articles`, `get_law_tree`, `summarize_precedent`, `analyze_document` |
+| **전문: 조세/관세** | 4 | `search_tax_tribunal_decisions`, `search_customs_interpretations` |
+| **전문: 헌재/행심** | 4 | `search_constitutional_decisions`, `search_admin_appeals` |
+| **전문: 위원회 결정** | 8 | 공정위, 개보위, 노동위, 감사원 |
+| **특별행정심판** | 4 | `search_acr_special_appeals`, `search_appeal_review_decisions` |
+| **법령-자치법규 연계** | 4 | `get_linked_ordinances`, `get_delegated_laws` |
+| **조약** | 2 | `search_treaties`, `get_treaty_text` |
+| **학칙/공단/공공기관** | 6 | `search_school_rules`, `search_public_corp_rules`, `search_public_institution_rules` |
+| **지식베이스** | 7 | `get_legal_term_kb`, `get_daily_to_legal`, `get_related_laws` |
+| **체인** | 8 | `chain_full_research`, `chain_law_system`, `chain_document_review` |
+| **메타** | 2 | `discover_tools`, `execute_tool` (lite 프로필용) |
+| **기타** | 10 | AI 검색, 영문법령, 연혁법령, 법령용어, 약칭, 법체계도, 행정규칙비교 |
+
+전체 도구 상세는 [영문 README](./README-EN.md#tool-categories-89-total) 참조.
+
+---
+
+## 주요 특징
+
+- **89개 법률 도구** — 법령, 판례, 행정규칙, 자치법규, 헌재결정, 조세심판, 관세해석, 조약, 학칙/공단/공공기관 규정, 법령용어
+- **MCP + CLI** — Claude Desktop에서도, 터미널에서도 같은 89개 도구 사용
+- **법률 도메인 특화** — 약칭 자동 인식(`화관법` → `화학물질관리법`), 조문번호 변환(`제38조` ↔ `003800`), 3단 위임 구조 시각화
+- **별표/별지서식 본문 추출** — HWPX·HWP 파일 자동 다운로드 → 표/텍스트를 Markdown 변환
+- **8개 체인 도구** — 복합 리서치를 한 번의 호출로 (예: `chain_full_research`: AI검색→법령→판례→해석)
+- **도구 프로필** — 웹 클라이언트용 lite(14개), 파워유저용 full(89개) 자동 선택
+- **캐시** — 검색 1시간, 조문 24시간 TTL
+- **원격 엔드포인트** — 설치 없이 `https://korean-law-mcp.fly.dev/mcp`로 바로 사용
+
+---
+
+## 문서
+
+- [docs/API.md](docs/API.md) — 89개 도구 레퍼런스 (프로필 포함)
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 시스템 설계
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — 개발 가이드
+
+## 라이선스
+
+[MIT](./LICENSE)
+
+---
+
+<sub>Made by 류주임 @ 광진구청 AI동호회 AI.Do</sub>