korean-law-mcp: Instructions file for Claude Code

CLAUDE.md

⚠️ 배포 — 통합 호스트 (2026-07-02부터)

프로덕션은 이 레포가 아니라 gomdori-mcp 통합 호스트(fly 앱 korean-law-mcp 1대, MCP 5종 동거)가 서빙한다.

• 공식 주소: https://mcp.gomdori.app/law (구 korean-law-mcp.fly.dev/mcp는 하위호환으로 유지)
• 반영 절차: 이 레포 커밋·푸시 → npm publish → npm 전파 대기(npm view korean-law-mcp version이 새 버전을 반환할 때까지 — 보통 30초 안쪽. 전파 전에 배포하면 이미지가 옛 버전을 설치한다) → ~/workspace/gomdori-mcp/Dockerfile의 [email protected] 핀 갱신 → cd ~/workspace/gomdori-mcp && fly deploy -c fly.production.toml → GitHub Release 생성(gh release create vX.Y.Z) → gomdori-mcp/scripts/verify-deploy.sh 로 사용자 경로 반영 확인
  • 릴리스는 배포와 항상 같이 간다 — npm 게시만 하고 Release 를 빠뜨리면 이 레포의 릴리스 이력에 구멍이 남는다(v4.10.0·v4.11.0 이 그렇게 비었다가 2026-08-17 에 소급 생성됐다). 노트 본문은 CHANGELOG 의 해당 절을 옮긴다.
  • .github/workflows/publish.yml(GitHub Release → OIDC trusted publishing + provenance)은 npm 쪽 trusted publisher 등록이 아직 안 됐다. 그래서 게시는 위 로컬 npm publish 가 정규 경로이고, Release 는 그 뒤에 만든다 — 워크플로는 같은 버전이 이미 레지스트리에 있으면 게시를 건너뛰고 검증(typecheck·test·build·verify:package·audit)만 릴리스 시점에 재확인한다.
• 🚫 이 레포에서 fly deploy 직접 실행 절대 금지 — 통합 이미지를 law 단독 이미지로 덮어써 stats·patent·archhub·school까지 전부 죽는다. 자세한 배경: docs/FLY-COST.md

Korean Law MCP Server v4.12.0 - 법제처 42개 API → 10개 통합 도구 (내부 98개) + 9개 시나리오 + 자연어 CLI + HTTP stateless + 판례 토큰 74% 감축 + legal_research (체인 8종 통합, task 파라미터) + legal_analysis (인용검증·판례생사·행위시법·영향그래프 통합, mode 파라미터) + time_travel (시점 diff) + action_plan (이럴 땐 이렇게, 5단계 안내) + 시행예정 감지 (search_law가 제명변경·미시행 개정 자동 병기) + ordinance_radar (조례 정비 레이더 — 근거 상위법 개정 자동 대조, v4.7.0) + 인용 검증 표기 내성 (낫표·가운뎃점·같은 법 조응, v4.9.0) + 폐지 감지 (검색 0건 시 폐지 법령·행정규칙 연혁 추적 — 폐지사유·후속 통합 규정 자동 안내, v4.10.0)

Structure

src/
├── index.ts              # 엔트리포인트 (STDIO/HTTP 모드)
├── cli.ts                # CLI v2.0 (자연어 라우팅 + REPL)
├── tool-registry.ts      # 98개 도구 등록, V3_EXPOSED 10개만 노출 (TOOL_COUNTS 파생값)
├── tools/                # 도구 구현 (76개 파일, scenarios/ 포함)
├── lib/
│   ├── api-client.ts     # API 클라이언트 (throwIfError/checkHtmlError 통일)
│   ├── query-router.ts   # 자연어 → 도구 라우팅 엔진 (verify/비교/시간필터 패턴 포함)
│   ├── fetch-with-retry.ts  # 타임아웃/재시도 + maskSensitiveUrl (API키 로그 유출 방지)
│   ├── session-state.ts  # 요청별 API 키·취소 신호·실행 예산 격리 (AsyncLocalStorage, stateless)
│   ├── execution-limits.ts  # 요청 단위 실행 예산 (upstream 호출 수·본문 byte) + env 정수 검증
│   ├── response-body.ts  # 예산·취소가 걸린 업스트림 본문 리더 (response.text() 대체)
│   ├── rate-limit.ts     # 토큰버킷 + 롤링 일일 캡 (폴백 쿼터 게이트, now 주입 테스트)
│   ├── xml-parser.ts     # 공통 XML 파싱
│   ├── errors.ts         # 에러 표준화
│   ├── schemas.ts        # 날짜/응답크기 검증 (truncateResponse)
│   ├── search-normalizer.ts  # 검색어 정규화 (LexDiff, 약칭 표제 60건 — LAW_ALIAS_ENTRIES 항목 수 기준)
│   ├── upcoming-laws.ts  # 시행예정 법령 감지 (eflaw 보조검색 — 제명변경·미시행 개정 병기)
│   ├── abolished-laws.ts # 폐지 감지 (법령=eflaw·행정규칙=nw=2 연혁 — 폐지사유·후속 통합 규정 안내)
│   ├── law-parser.ts     # JO 코드 변환 (LexDiff)
│   ├── annex-file-parser.ts  # 별표 파일 파서 (kordoc 통합 파서)
│   ├── tool-profiles.ts  # 도구 카테고리 + TOOL_ALIASES (한국어 별칭 매칭)
│   ├── article-parser.ts # 조문 파서 (항/호/목 단일객체 정규화)
│   ├── decision-compact.ts # 판례 토큰 최적화 + compactLongSections (14도메인 후처리)
│   ├── cache.ts          # LRU 캐시 (TTL, 만료 우선 eviction)
│   ├── three-tier-parser.ts  # 3단 비교 파서
│   ├── cli-format.ts     # CLI 출력 포맷팅
│   ├── cli-executor.ts   # CLI 쿼리 실행 엔진
│   ├── risk-rules.ts     # 문서 분석 리스크 규칙
│   ├── date-parser.ts    # 자연어 날짜 파서
│   ├── document-analysis.ts  # 문서유형 분류/금액추출/리스크 탐지
│   └── types.ts          # 공통 타입
└── server/               # HTTP 서버 (Express)
    ├── http-config.ts    # 보안 env 시작 시점 검증 (bind host·trust proxy·각종 한도)
    └── http-server.ts    # Streamable HTTP stateless + scrubError + 연결 끊김 취소 전파