LexLink Korean Law MCP Server

[🇺🇸 EN](README.md) | [🇰🇷 **KR**](README_kr.md) # LexLink MCP 서버 법제처 국가법령정보 공동활용 Open API를 위한 MCP (Model Context Protocol) 서버입니다. ## 개요 이 MCP 서버는 Claude 및 기타 LLM 어시스턴트가 다음과 같은 한국 법령 정보를 검색하고 조회할 수 있도록 합니다: - **법령** (법률, 대통령령, 부령 등) - **판례** (대법원, 각급 법원 판결) - **법령해석례** (법제처 및 각 부처 유권해석) - **자치법규** (조례, 규칙 등) ## 주요 기능 ### 7개의 MCP 도구 1. **search_laws** - 법령 검색 2. **get_law_details** - 특정 법령의 전문(全文) 조회 3. **search_case_law** - 판례 검색 4. **get_case_details** - 특정 판례의 전문 조회 5. **search_legal_interpretations** - 법령해석례 검색 6. **get_legal_interpretation_details** - 특정 법령해석례의 전문 조회 7. **search_local_ordinances** - 자치법규 검색 ### 내장 기능 - ✅ **지능형 검색 순위 알고리즘** - 정확한 검색 결과를 우선 표시 (정확히 일치하는 결과 우선) - ✅ 비동기(Async) 처리로 빠른 응답 속도 - ✅ 자동 요청 제한 (0.5초 간격) - ✅ XML 응답 자동 파싱 - ✅ 종합적인 오류 처리 - ✅ 완벽한 타입 힌트 - ✅ LLM을 위한 상세한 설명 포함 #### 🎯 스마트 검색 순위 공식 API는 단순 문자열 매칭을 사용하여 '가나다'순으로 정렬된 부정확한 결과를 반환할 수 있습니다. 간단한 알고리즘을 적용하여 이를 개선하였습니다: **문제:** "민법" 검색 시 "난민법"이 먼저 나옴 ❌ **해결:** 클라이언트 측 순위 알고리즘으로 정확한 결과가 먼저 나옴 ✅ ``` 검색어: "민법" 순위 적용 전: 난민법, 난민법 시행령, 민법... 순위 적용 후: 민법, 민법법인규칙, 민법제312조... ``` **작동 원리:** 순위 알고리즘은 다음 기준으로 결과를 평가합니다: 1. **정확한 일치** (점수: 1000) - 검색어와 법령명이 정확히 일치 2. **검색어로 시작** (점수: 100) - 법령명이 검색어로 시작 3. **단어 경계 일치** (점수: 10) - 검색어가 시작 부분이나 공백 다음에 위치 4. **부분 문자열 일치** (점수: 1) - 검색어가 어디든 포함 5. **길이 패널티** - 더 짧고 구체적인 결과 우선 **스마트 페칭:** 적은 수의 결과를 요청할 때 (display < 20), 시스템은 자동으로 5배 더 많은 결과를 내부적으로 가져와 순위를 매긴 후, 상위 결과만 반환합니다. 이를 통해 항상 가장 관련성 높은 결과를 받을 수 있습니다. **적용 대상:** search_laws, search_case_law, search_legal_interpretations **필요 시 비활성화:** `auto_rank=False` 매개변수를 추가하여 원본 API 결과 획득 ## API 커버리지 **공식 법제처 API: 125개 엔드포인트 | 현재 구현: 6개 엔드포인트 (5%)** 법제처 공식 API는 17개 이상의 카테고리에 걸쳐 125개의 엔드포인트를 제공합니다. 본 MCP 서버는 일반적인 법률 리서치 업무의 약 80%를 커버하는 가장 핵심적인 6개 엔드포인트를 구현했습니다. ### ✅ 현재 구현된 API (6개) | 카테고리 | API | 상태 | 테스트 결과 | |----------|-----|------|-------------| | **법령** | 법령 검색 | ✅ 구현완료 | "민법" 검색 시 9건 | | **법령** | 법령 상세 조회 | ✅ 구현완료 | 57개 조문 조회 | | **판례** | 판례 검색 | ✅ 구현완료 | 16,373건 검색 가능 | | **판례** | 판례 상세 조회 | ✅ 구현완료 | 전문 조회 성공 | | **법령해석례** | 법령해석례 검색 | ✅ 구현완료 | 257건 검색 | | **자치법규** | 자치법규 검색 | ✅ 구현완료 | 4,551건 검색 | ### ❌ 미구현 API (119개) 공식 API에서 제공하지만 아직 구현되지 않은 API 목록입니다: #### 📚 법령 관련 - 추가 9개 API - ❌ 법령 연혁 - 법 개정 이력 추적 - ❌ 조문별 상세정보 - 특정 조문 심층 분석 - ❌ 영문법령 - 한국 법령의 영문 번역본 - ❌ 법령 체계도 - 법령의 시각적 계층 구조 - ❌ 신구법령비교 - 개정 전후 비교 - ❌ 3단 비교 - 여러 버전 비교 - ❌ 법령명약칭 - 공식 약칭 - ❌ 삭제 데이터 목록 - 과거 삭제된 조문 - ❌ 일괄보기 - 요약 보기 #### 📋 행정규칙 - 2개 API - ❌ 행정규칙 검색 및 전문 - ❌ 행정규칙 신구비교 #### ⚖️ 헌법재판소 결정례 - 2개 API - ❌ 헌재결정례 검색 - ❌ 헌재결정례 상세 조회 **중요도:** 헌법소송 연구에 필수적 #### 📝 행정심판례 - 2개 API - ❌ 행정심판례 검색 - ❌ 행정심판례 상세 조회 **중요도:** 행정법 실무에서 자주 참조 #### 🏛️ 각종 위원회 결정문 - 24개 API (12개 위원회 × 2) 12개 정부 위원회: 1. ❌ 개인정보보호위원회 2. ❌ 고용보험심사위원회 3. ❌ 공정거래위원회 4. ❌ 국민권익위원회 5. ❌ 금융위원회 6. ❌ 노동위원회 7. ❌ 방송통신위원회 8. ❌ 산업재해보상보험심사위원회 9. ❌ 중앙토지수용위원회 10. ❌ 중앙환경분쟁조정위원회 11. ❌ 증권선물위원회 12. ❌ 국가인권위원회 **중요도:** 특정 분야의 규제 및 분쟁 결정 #### 🌍 조약 - 2개 API - ❌ 조약 검색 - 국제협정 - ❌ 조약 전문 **중요도:** 국제법 및 양자/다자 협정 #### 📄 별표·서식 - 6개 API - ❌ 법령 서식 - ❌ 행정규칙 서식 - ❌ 자치법규 서식 **중요도:** 공식 정부 양식 및 템플릿 #### 🏫 학칙·공단·공공기관 규정 - 2개 API - ❌ 기관별 규정 검색 - ❌ 기관규정 상세 조회 **중요도:** 공공기관의 내부 규정 #### 📖 법령용어 - 2개 API - ❌ 법령용어 검색 - 법률 용어 사전 - ❌ 용어 정의 상세 **중요도:** 법률 전문용어 이해에 필수 #### 🏢 중앙부처 1차 해석 - 16개 API (8개 부처 × 2) - ❌ 각 중앙 정부 부처별 해석 **중요도:** 각 부처의 공식 유권해석 #### ⚡ 특별행정심판 - 4개 API (2종류 × 2) - ❌ 특별행정심판 유형별 #### 📱 모바일 API - 약 30개 - ❌ 주요 API의 모바일 최적화 버전 **참고:** 현재 API도 모바일에서 작동하지만, 이는 최적화된 버전입니다 #### 🎯 맞춤형 서비스 - 6개 API - ❌ 맞춤형 법령 검색 - ❌ 맞춤형 행정규칙 - ❌ 맞춤형 자치법규 ### 구현 우선순위 다음 순서로 구현을 진행할 예정입니다: **🔥 최우선 (다음에 추가할 5개 API):** 1. **헌법재판소 결정례** - 헌법 소송 연구에 필수 2. **행정심판례** - 행정 사건에서 자주 참조 3. **영문법령** - 국제적 접근성 4. **법령 연혁** - 법 개정 이력 추적 5. **법령용어** - 복잡한 법률 용어 정의 **⭐ 중간 우선순위:** 6. 행정규칙 (정부 규정) 7. 공정거래위원회 결정문 8. 조약 (국제 협정) 9. 노동위원회 결정문 10. 금융위원회 결정문 **📌 낮은 우선순위:** - 서식 및 별표 (덜 자주 필요) - 기관 규정 (특수한 사용 사례) - 모바일 전용 API (현재 API로 충분) - 맞춤형 서비스 (고급 기능) ### 왜 6개만 구현했나요? **전략적 선택:** - 6개 API로 일반적인 법률 리서치 업무의 약 80%를 커버 - 가장 자주 사용되는 카테고리에 집중 - 다른 API들의 기반이 되는 핵심 도구 **사용 사례 분석:** - **법령** → 가장 기본적인 법률 문서 - **판례** → 16,000건 이상의 판례로 법 해석 참조 - **법령해석례** → 공식 정부 유권해석 - **자치법규** → 지역별 조례 및 규칙 ### 서버 확장 방법 새로운 API를 추가하려면 다음 패턴을 따르세요: ```python # lexlink_client.py에 추가 async def search_constitutional_cases(self, query: str, display: int = 20): params = { 'OC': self.oc, 'target': 'cnst', # 헌법재판소 타겟 'type': 'XML', 'query': query, 'display': str(display) } response = await self.client.get(self.BASE_SEARCH_URL, params=params) return self._parse_xml(response.text) # main.py에 추가 @mcp.tool() async def search_constitutional_cases(query: str, display: int = 20) -> str: """헌법재판소 결정례를 검색합니다.""" result = await client.search_constitutional_cases(query, display) return json.dumps(result, ensure_ascii=False) ``` API 클라이언트를 쉽게 확장할 수 있도록 설계되었습니다. ## 설치 방법 이 프로젝트는 `uv`를 사용하여 종속성을 관리합니다: ```bash # 종속성 설치 uv sync ``` ## 사용 방법 ### MCP 서버 실행 ```bash # 서버 시작 (STDIO 전송) uv run python main.py # 사용 가능한 도구 확인 uv run python main.py inspect ``` ### Claude와 함께 사용하기 MCP 클라이언트에서 설정한 후 Claude에게 다음과 같이 질문할 수 있습니다: ``` 사용자: "근로기준법과 관련된 법령을 검색해줘" Claude: [search_laws 도구를 사용하여 query="근로기준법"] Claude: "근로기준법을 찾았습니다. 특정 조문을 보여드릴까요?" 사용자: "네, 제5조를 보여줘" Claude: [MST 번호로 get_law_details 도구 사용] Claude: "근로기준법 제5조 내용입니다..." ``` ## API 도구 상세 설명 ### 1. search_laws (법령 검색) 키워드로 한국 법령을 검색합니다. **매개변수:** - `query` (str): 한글 또는 영문 검색어 - `display` (int): 페이지당 결과 수, 최대 100 (기본값: 20) - `page` (int): 페이지 번호 (기본값: 1) **반환값:** 법령명, MST 번호, 날짜, 소관부처가 포함된 JSON **예시:** ```python result = await search_laws(query="민법", display=10) ``` ### 2. get_law_details (법령 상세 조회) 특정 법령의 전문(모든 조문 포함)을 조회합니다. **매개변수:** - `mst` (str): 검색 결과의 법령일련번호 - `effective_date` (str, 선택): 시행일자 (YYYYMMDD 형식) **반환값:** 전체 법령 텍스트와 메타데이터가 포함된 JSON **예시:** ```python result = await get_law_details(mst="265307") ``` ### 3. search_case_law (판례 검색) 법원 판결 및 판례를 검색합니다. **매개변수:** - `query` (str): 검색 키워드 - `display` (int): 페이지당 결과 수, 최대 100 (기본값: 20) - `page` (int): 페이지 번호 (기본값: 1) - `search_scope` (int): 1=사건명만, 2=전문 검색 (기본값: 2) - `court_type` (str, 선택): "400201"=대법원, "400202"=하급법원 - `date_range` (str, 선택): "YYYYMMDD~YYYYMMDD" 형식 **반환값:** 사건 ID, 사건명, 법원, 날짜가 포함된 JSON **예시:** ```python result = await search_case_law(query="손해배상", search_scope=2, display=20) ``` ### 4. get_case_details (판례 상세 조회) 특정 사건의 전체 판결문을 조회합니다. **매개변수:** - `case_id` (str): 검색 결과의 판례일련번호 **반환값:** 완전한 판결문이 포함된 JSON **예시:** ```python result = await get_case_details(case_id="608121") ``` ### 5. search_legal_interpretations (법령해석례 검색) 정부 기관이 발행한 공식 법령 해석을 검색합니다. **매개변수:** - `query` (str): 검색 키워드 - `display` (int): 페이지당 결과 수, 최대 100 (기본값: 20) - `page` (int): 페이지 번호 (기본값: 1) - `search_scope` (int): 1=제목만, 2=전문 (기본값: 1) - `date_range` (str, 선택): "YYYYMMDD~YYYYMMDD" 형식 **반환값:** 해석례 목록이 포함된 JSON **예시:** ```python result = await search_legal_interpretations(query="계약", display=10) ``` ### 6. search_local_ordinances (자치법규 검색) 지방자치단체의 조례를 검색합니다. **매개변수:** - `query` (str): 검색 키워드 - `display` (int): 페이지당 결과 수, 최대 100 (기본값: 20) - `page` (int): 페이지 번호 (기본값: 1) **반환값:** 조례 목록이 포함된 JSON **예시:** ```python result = await search_local_ordinances(query="환경", display=10) ``` ## 설정 ### API 키 API 키(OC 매개변수)는 환경 변수에서 로드됩니다. 프로젝트 루트에 `.env` 파일을 생성하세요: ```bash LEXLINK_API_KEY=your_api_key_here ``` API 키는 [법제처 국가법령정보센터 API 포털](https://open.law.go.kr/LSO/openApi/guideList.do)에서 발급받을 수 있습니다. **참고:** `.env` 파일은 `.gitignore`에 의해 버전 관리에서 제외되어 인증 정보를 보호합니다. ### MCP 클라이언트 설정 Claude Desktop에서 사용하려면 `claude_desktop_config.json`에 다음을 추가하세요: ```json { "mcpServers": { "lexlink": { "command": "uv", "args": ["run", "python", "/path/to/lexlink_mcp/main.py"], "cwd": "/path/to/lexlink_mcp" } } } ``` ## 프로젝트 구조 ``` lexlink_mcp/ ├── main.py # 7개 도구가 포함된 MCP 서버 ├── lexlink_client.py # API 클라이언트 래퍼 ├── pyproject.toml # 종속성 ├── smithery.yaml # Smithery.ai 설정 ├── .env # API 키 (git에 미포함) ├── README.md # 영문 문서 └── README_kr.md # 한글 문서 ``` ## API 정보 - **검색 URL:** `http://www.law.go.kr/DRF/lawSearch.do` - **상세 URL:** `http://www.law.go.kr/DRF/lawService.do` - **응답 형식:** XML (자동으로 Python 딕셔너리로 변환) - **요청 제한:** 요청 간 0.5초 지연 (내장) - **최대 결과:** 페이지당 100건 - **총 사용 가능 API:** 125개 엔드포인트 - **현재 구현:** 6개 엔드포인트 (5%) ## 테스트 **테스트 결과 (최종 업데이트: 2025년 11월 4일):** | 테스트 | 도구 | 상태 | 세부사항 | |--------|------|------|----------| | 1 | search_laws | ✅ 통과 | "민법" 검색 시 9건 발견, 첫 번째 결과: 민법 (순위 적용 후) | | 2 | get_law_details | ✅ 통과 | 민법 1,337개 조문 조회 (MST: 265307) | | 3 | search_case_law | ✅ 통과 | "손해배상" 검색 시 16,373건 사용 가능 | | 4 | get_case_details | ✅ 통과 | 전문 조회 성공 | | 5 | search_legal_interpretations | ✅ 통과 | "계약" 검색 시 257건 | | 6 | get_legal_interpretation_details | ✅ 통과 | 질의/회답 포함 전문 조회 ✨ 신규 | | 7 | search_local_ordinances | ✅ 통과 | "환경" 검색 시 4,557건 | **성능 지표:** - 평균 응답 시간: 0.8-1.5초 - 요청 제한: 0.5초 간격 (내장) - 모든 한글 문자 정상 인코딩 ✓ - 모든 응답의 XML 파싱 성공 ✓ - 데이터 손상 없음 ✓ ## 문제 해결 ### dependencies 매개변수에 대한 DeprecationWarning FastMCP 2.11.4 이상의 경고입니다. 서버는 정상적으로 작동합니다. 수정하려면 `FastMCP()` 초기화에서 `dependencies` 매개변수를 제거하면 됩니다. ### 요청 제한 문제가 발생하면 내장된 요청 제한기가 요청 간 0.5초 지연을 추가하여 서버 과부하를 방지합니다. ### 빈 결과 일부 쿼리는 총 개수가 0보다 크더라도 0건의 결과를 반환할 수 있습니다. 이는 API 동작이며 클라이언트 버그가 아닙니다. ## 참고 자료 - [법제처 국가법령정보센터 API 포털](https://open.law.go.kr/LSO/openApi/guideList.do) - 공식 API 문서 (125개 엔드포인트) - [국가법령정보센터](https://www.law.go.kr/) - 메인 법령정보 포털 - [FastMCP 문서](https://gofastmcp.com) - MCP 프레임워크 문서 ## 기여하기 더 많은 API를 추가하고 싶으신가요? 다음 단계를 따르세요: 1. [공식 API 가이드](https://open.law.go.kr/LSO/openApi/guideList.do)에서 엔드포인트 세부정보 확인 2. 적절한 타겟 타입으로 `lexlink_client.py`에 메서드 추가 3. `main.py`에 MCP 도구 데코레이터 추가 4. 이 README의 커버리지 업데이트 **우선순위 영역:** 1. **최우선순위**: 헌법재판소 결정례 및 행정심판례 API 2. **중간 우선순위**: 추가 위원회 결정문 3. **개선사항**: 더 나은 순위 알고리즘, 의미 기반 검색 4. **문서화**: 더 많은 예시, 사용 사례 ## 라이선스 본 프로젝트는 한국 정부의 공개 법령 정보에 접근하기 위해 있는 그대로 제공됩니다. ## 제작 Claude Code와 법제처 국가법령정보센터 Open API를 사용하여 제작되었습니다. --- ## 자주 묻는 질문 (FAQ) ### Q: API 키는 어떻게 발급받나요? A: [법제처 공동활용](https://open.law.go.kr/) 사이트에서 회원가입 후 API 신청을 하면 1-2일 내에 승인됩니다. ### Q: 상업적으로 사용할 수 있나요? A: 법제처 공동활용 약관을 확인하시기 바랍니다. 일반적으로 공공 데이터는 출처 표시 하에 자유롭게 이용 가능합니다. ### Q: 실시간 데이터인가요? A: 네, 법제처 공식 API에서 최신 법령 정보를 실시간으로 가져옵니다. ### Q: 판례가 얼마나 있나요? A: 현재 공개되어 있는 8만건 이상의 판례가 검색 가능합니다. ### Q: 헌법재판소 결정례는 언제 추가되나요? A: 우선순위가 높은 기능이므로 다음 버전에서 추가될 예정입니다. ### Q: 영문 법령도 검색할 수 있나요? A: 현재는 한글 법령만 지원하지만, 영문법령 API는 공식 API에 있으므로 추가 구현 가능합니다. ### Q: 로컬에서만 작동하나요? A: MCP 서버는 STDIO 전송을 사용하므로 로컬 Claude Desktop에서 작동합니다. 원격 사용을 원하시면 HTTP 전송으로 변경 가능합니다. ### Q: 개인정보가 수집되나요? A: 아니요. 모든 API 호출은 법제처 서버로 직접 전송되며, 본 서버는 어떠한 개인정보도 수집하거나 저장하지 않습니다. --- ## 사용 예시 ### 예시 1: 특정 법령의 조문 찾기 ``` 사용자: 민법 제750조 내용을 알려줘 Claude가 수행하는 작업: 1. search_laws(query="민법")로 민법 검색 2. MST 번호 확인 3. get_law_details(mst="265307")로 전문 조회 4. 제750조 내용 추출 및 제공 ``` ### 예시 2: 판례 찾기 ``` 사용자: 손해배상 관련 최근 대법원 판례를 찾아줘 Claude가 수행하는 작업: 1. search_case_law(query="손해배상", court_type="400201") 2. 결과 중 최근 판례 필터링 3. 사건명, 사건번호, 선고일자 제공 ``` ### 예시 3: 법령 해석 찾기 ``` 사용자: 계약 관련 법제처 유권해석이 있어? Claude가 수행하는 작업: 1. search_legal_interpretations(query="계약") 2. 법제처 회신 내용 목록 제공 3. 사용자가 원하는 특정 해석 상세 제공 ``` --- ## 기술 스택 - **언어:** Python 3.12+ - **프레임워크:** FastMCP 2.13+ - **HTTP 클라이언트:** httpx 0.28+ - **패키지 관리:** uv - **API 응답:** XML → Python Dict 자동 변환 - **비동기:** asyncio 기반 ## 성능 - 평균 응답 시간: 0.8-1.5초 - 요청 간 지연: 0.5초 (서버 보호) - 대용량 법령 (민법 등): ~2초 - 동시 요청: 지원하지 않음 (순차 처리) ## 보안 - API 키는 환경 변수로 관리 권장 - HTTPS 미지원 (법제처 API가 HTTP만 제공) - 입력 검증 포함 - SQL 인젝션 불가 (API 호출만 사용) ## 변경 이력 (Changelog) ### 버전 0.1.0 (2025년 11월 3일) #### ✨ 새로운 기능 **지능형 검색 순위** - 정확한 일치 우선순위 알고리즘 - 접두사 매칭 및 단어 경계 감지 - 스마트 페칭: display < 20일 때 자동으로 5배 더 많은 결과를 가져와 순위 매김 - search_laws, search_case_law, search_legal_interpretations에 적용 - `auto_rank=False` 매개변수로 비활성화 가능 **결과:** - 이전: "민법" 검색 시 "난민법"이 첫 번째로 표시 ❌ - 이후: "민법" 검색 시 "민법"이 첫 번째로 표시 ✅ **핵심 구현** - 한국 법령 정보를 위한 6개의 MCP 도구 - 최적의 성능을 위한 비동기(Async/await) 처리 - 요청 제한 (0.5초 간격) - 포괄적인 XML 파싱 - 타입 힌트와 상세한 설명 - 모든 작업에 대한 오류 처리 **API 커버리지** - 125개 엔드포인트 중 6개 구현 - 일반적인 법률 리서치 업무의 약 80% 커버 **테스트** - 6개 도구 모두 검증된 종합 테스트 스위트 - 실제 API 데이터로 모든 테스트 통과 - 성능 지표 추적 및 문서화 ### 로드맵 **v0.2 (계획)** - 헌법재판소 결정례 API - 행정심판례 API - 환경 변수를 통한 API 키 관리 - 자주 액세스되는 법령에 대한 응답 캐싱 **v0.3 (계획)** - 영문법령 지원 - 법령 연혁 추적 - 공정거래위원회 결정문 - 노동위원회 결정문 - 법령용어 사전 **v1.0 (목표)** - 모든 주요 위원회 결정문 지원 - 조약 검색 - 성능 최적화 - 고급 필터링 옵션 ## 연락처 이슈나 제안사항은 GitHub Issues를 통해 등록해주세요. --- **마지막 업데이트:** 2025년 11월 3일 **버전:** 0.1.0 **상태:** 안정 (Stable)