메뉴
법제처 OPEN API를 MCP 프로젝트에 통합할 때 사용. lawSearch.do와 lawService.do 엔드포인트, target 파라미터로 기능 구분. 새로운 API 엔드포인트 통합 시 참조.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
BM25 Okapi 알고리즘을 사용하여 법령/판례 API 결과를 관련도 순으로 재랭킹합니다. search_enhance_tools.py와 bm25_search.py 구현 시 참조.
법령/판례 캐시 데이터 관리 시 사용. 캐시 저장/로드, 만료 처리, 지식 그래프 동기화. 성능 최적화 및 API 호출 최소화를 위해 캐싱 구현 시 참조.
도구 실패/API 오류 발생 시 4단계 근본 원인 분석 후 수정. 증상 수정이 아닌 원인 수정. superpowers의 systematic-debugging 기반.
새 도구 개발 또는 버그 수정 시 실패하는 테스트를 먼저 작성하고, 구현 후 통과를 확인. superpowers의 test-driven-development 기반.
도구 개발/개선 완료 선언 전 반드시 실제 API 호출 테스트를 수행하고 증거를 기록할 때 사용. superpowers의 verification-before-completion 기반.
Tool에서 API 호출 시 컨텍스트 처리. streamable-http와 stdio transport 모두 지원. with_context() 패턴으로 전역 컨텍스트 fallback 자동 처리.
| name | api-integration |
| description | 법제처 OPEN API를 MCP 프로젝트에 통합할 때 사용. lawSearch.do와 lawService.do 엔드포인트, target 파라미터로 기능 구분. 새로운 API 엔드포인트 통합 시 참조. |
법제처 OPEN API를 MCP 프로젝트에 통합하는 방법입니다.
모든 도구 개발의 기준점은 api_layout/*.json 파일입니다.
| 항목 | 경로 | 역할 |
|---|---|---|
| API 레이아웃 | src/mcp_kr_legislation/utils/api_layout/*.json | API 정의의 유일한 기준점 |
| 공식 가이드 | https://open.law.go.kr/LSO/openApi/guideList.do | API 레이아웃의 원본 소스 |
| TOOL_CHECKLIST.md | skills/api-integration/TOOL_CHECKLIST.md | 구현 진행 추적 (업데이트만, 근거 아님) |
공식 가이드 → api_crawler.py → api_layout/*.json → 도구 개발 → TOOL_CHECKLIST.md 업데이트
(크롤링) (기준점) (구현) (추적)
주의: TOOL_CHECKLIST.md는 진행 상황을 추적하는 문서입니다.
API 정보가 필요하면 반드시api_layout/*.json을 참조하세요.
api_layout/*.json의 sample_urls 필드로 개발 필요 여부를 결정합니다.
| sample_urls 상태 | 개발 방식 |
|---|---|
| JSON 포함 | ✅ JSON API 직접 호출하여 도구 개발 |
| HTML만 | ❌ 도구 개발 불필요 (JSON 미지원) |
원칙:
sample_urls에 JSON URL이 없으면 해당 API는 도구 개발 대상이 아닙니다.
추출된 API 정보는 JSON 파일로 관리됩니다:
위치: src/mcp_kr_legislation/utils/api_layout/
| 파일 | 카테고리 |
|---|---|
law.json | 법령 |
admin_rule.json | 행정규칙 |
local_ordinance.json | 자치법규 |
precedent.json | 판례 |
committee.json | 위원회결정문 |
ministry_interpretation_1.json | 중앙부처 1차 해석 |
ministry_interpretation_2.json | 중앙부처 2차 해석 |
special_tribunal.json | 특별행정심판 |
| ... | 기타 카테고리 |
{
"category": "법령",
"category_en": "law",
"updated_at": "2026-01-21",
"api_count": 26,
"apis": [
{
"id": "1.1",
"title": "현행법령(시행일) 목록 조회 API",
"request_url": "http://www.law.go.kr/DRF/lawSearch.do?target=eflaw",
"target": "eflaw",
"api_type": "목록조회",
"parameters": [...],
"sample_urls": [...]
}
]
}
| 기능 | URL 패턴 | 설명 |
|---|---|---|
| 목록 조회 | lawSearch.do?target={value} | 검색/목록 반환 |
| 본문 조회 | lawService.do?target={value} | 상세 내용 반환 |
target 값만으로 API 카테고리 구분전체 target 목록: targets.md
from mcp_kr_legislation.apis.client import LegislationClient
from mcp_kr_legislation.config import legislation_config
# 클라이언트 초기화
client = LegislationClient(config=legislation_config)
# 목록 조회
result = client.search(
target="law",
params={"query": "개인정보보호법", "display": 20}
)
# 본문 조회
detail = client.service(
target="law",
params={"ID": "법령ID"}
)
from mcp_kr_legislation.utils.ctx_helper import with_context
@mcp.tool(name="search_law")
def search_law(query: str) -> TextContent:
result = with_context(
None,
"search_law",
lambda context: context.law_api.search(
target="law",
query=query
)
)
return TextContent(type="text", text=str(result))
공통: OC (자동 추가), target (필수), type (JSON/XML/HTML)
검색: query, display (기본 20, 최대 100), page, sort
상세 조회: ID (필수)
python scripts/test_api.py law "개인정보보호법"
# 모든 API 테스트
python scripts/test_regression.py
# 특정 카테고리만 테스트
python scripts/test_regression.py --category 법령
python scripts/test_regression.py --category 판례
# 상세 출력
python scripts/test_regression.py --verbose
python scripts/test_tool_coverage.py
API 가이드의 API 목록과 실제 구현된 도구를 비교하여 미구현/불일치 항목을 확인합니다.
LegislationClient가 환경변수에서 자동 추가REQUEST_TIMEOUT 환경변수로 변경 가능도구가 예상과 다른 결과를 반환하거나 오류가 발생할 경우, 반드시 공식 가이드에서 샘플 URL을 직접 테스트하여 API 동작을 확인해야 합니다.
⚠️ 중요: 공식 가이드에 있는 모든 API는 정상 동작하는 것으로 간주합니다. "지원/미지원" 표현 대신 데이터 건수 확인 및 파라미터 조정으로 대응합니다.
가이드 상세 페이지에는 보통 다음과 같은 샘플 URL이 있습니다:
...lawSearch.do?OC=test&target=XXX&type=JSON......lawSearch.do?OC=test&target=XXX&type=XML......lawSearch.do?OC=test&target=XXX&type=HTML...직접 클릭하여 브라우저에서 응답 확인:
totalCnt 값 확인 (데이터 건수)샘플 URL에서 target=XXX 부분을 확인하여 코드에 적용:
# 샘플 URL 예시
http://www.law.go.kr/DRF/lawSearch.do?OC=test&target=moeCgmExpc&type=JSON&ID=411648
^^^^^^^^^^^
이 값이 target
# 코드에 적용
data = _make_legislation_request("moeCgmExpc", params)
응답 JSON의 루트 키와 데이터 리스트 키를 확인:
{
"CgmExpcSearch": { // 루트 키
"totalCnt": "123",
"CgmExpc": [...] // 데이터 리스트 키
}
}
| 카테고리 | target | 기관/부처 | 검증 방법 |
|---|---|---|---|
| 중앙부처해석 | kostatCgmExpc | 국가데이터처 | 공식 가이드 직접 확인 |
| 중앙부처해석 | kipoCgmExpc | 지식재산처 | 공식 가이드 직접 확인 |
| 중앙부처해석 | naaccCgmExpc | 행정중심복합도시건설청 | 공식 가이드 직접 확인 |
| 특별행정심판 | acrSpecialDecc | 국민권익위원회 | 공식 가이드 직접 확인 |
| 특별행정심판 | adapSpecialDecc | 인사혁신처 소청심사 | 공식 가이드 직접 확인 |
# 중앙부처해석 (기획재정부)
http://www.law.go.kr/DRF/lawSearch.do?OC=test&target=moefCgmExpc&type=JSON&query=조세
# 중앙부처해석 (교육부) - ID 직접 조회
http://www.law.go.kr/DRF/lawService.do?OC=test&target=moeCgmExpc&ID=411648&type=JSON
# 특별행정심판 (조세심판원)
http://www.law.go.kr/DRF/lawSearch.do?OC=test&target=ttSpecialDecc&type=JSON
# 특별행정심판 (국민권익위원회)
http://www.law.go.kr/DRF/lawSearch.do?OC=test&target=acrSpecialDecc&type=JSON
# 법령 검색
http://www.law.go.kr/DRF/lawSearch.do?OC=test&target=law&type=JSON&query=개인정보보호법
Referer: https://open.law.go.kr/ 헤더가 코드에 포함되어 있는가?| 증상 | 원인 | 해결 |
|---|---|---|
| 404 Not Found | target 값 오류 | 공식 가이드에서 정확한 target 확인 |
| 빈 응답 (totalCnt: 0) | 검색어/파라미터 문제 | 다른 검색어 시도 또는 query 없이 호출 |
| JSON 파싱 오류 | HTML 응답 반환됨 | type=JSON 파라미터 확인 |
| 권한 오류 | Referer 헤더 누락 | client.py에 Referer 헤더 추가 |
# 공식 가이드에서 API 정보 크롤링
python src/mcp_kr_legislation/utils/api_crawler.py
# 기존 Markdown 파일을 JSON으로 변환
python src/mcp_kr_legislation/utils/api_md_to_json.py [input_file]