korean-law-mcp

Korean Law MCP - System Architecture

v1.9.0 Last Updated: March 2026

High-Level Architecture

┌──────────────────────────────────────────────────────────────┐
│                     MCP Client (Claude 등)                    │
└────────────────────┬────────────────────┬────────────────────┘
              STDIO Mode              HTTP Mode
            (Local Desktop)        (Remote: Fly.io)
                     │                    │
┌────────────────────▼────────────────────▼────────────────────┐
│               Korean Law MCP Server (v1.9.0)                  │
│                                                               │
│  ┌───────────────────────────────────────────────────────┐   │
│  │     Tool Registry (64 Zod-Validated Tools)            │   │
│  │         tool-registry.ts → allTools[]                 │   │
│  ├───────────────────────────────────────────────────────┤   │
│  │  검색 (11)   │ 조회 (9)      │ 분석 (9)              │   │
│  │  전문 (4)    │ 헌재/행심 (6) │ 지식베이스 (7)        │   │
│  │  기타 (4)    │ 체인 (7)      │ CLI 인터페이스        │   │
│  └───────────────────────────────────────────────────────┘   │
│                             ▲                                 │
│  ┌───────────────────────────────────────────────────────┐   │
│  │            Shared Libraries (src/lib/ 13개)           │   │
│  ├───────────────────────────────────────────────────────┤   │
│  │  • api-client.ts       (API 호출 + 캐시)              │   │
│  │  • xml-parser.ts       (6개 도메인 파서)              │   │
│  │  • annex-file-parser.ts (HWPX/HWP/PDF 파싱)          │   │
│  │  • search-normalizer.ts (약칭 해석, LexDiff)          │   │
│  │  • law-parser.ts       (JO 코드 변환, LexDiff)        │   │
│  │  • errors.ts           (LawApiError + 구조화된 에러)   │   │
│  │  • schemas.ts          (날짜/크기 검증)                │   │
│  │  • fetch-with-retry.ts (30s timeout, 3 retries)       │   │
│  │  • session-state.ts    (멀티세션 API 키 격리)          │   │
│  │  • cache.ts            (LRU + TTL)                    │   │
│  └───────────────────────────────────────────────────────┘   │
│                             ▲                                 │
│  ┌───────────────────────────────────────────────────────┐   │
│  │        Server Layer                                    │   │
│  │  • http-server.ts  (Streamable HTTP, MCP 표준)        │   │
│  │  • sse-server.ts   (SSE 레거시)                        │   │
│  └───────────────────────────────────────────────────────┘   │
└───────────────────────────┬───────────────────────────────────┘
                            │ HTTPS
                            ▼
┌──────────────────────────────────────────────────────────────┐
│         Korea Ministry of Government Legislation API          │
│                    (law.go.kr Open API)                       │
├──────────────────────────────────────────────────────────────┤
│  lawSearch.do  - 검색 (law/admrul/ordin/prec/expc/...)       │
│  lawService.do - 조회 (eflaw/admrul/ordin/prec/...)          │
└──────────────────────────────────────────────────────────────┘

Key Architectural Principles

  1. Separation of Concerns: Tools → Shared Libs → API Client
  2. Single Responsibility: 파일당 200줄 미만, 단일 기능
  3. Centralized Tool Registry: 64개 도구를 tool-registry.ts의 allTools[]에 등록
  4. Type Safety: TypeScript strict mode + Zod validation
  5. Session Isolation: 멀티세션 API 키 격리 (race condition 방지)
  6. Network Resilience: 30s timeout, 3 retries with exponential backoff
  7. Dual Interface: MCP 서버 + CLI 동시 지원

Component Deep Dive

Entry Point (src/index.ts)

Tool Registry (src/tool-registry.ts)

모든 도구를 allTools[] 배열로 관리. 각 도구는 { name, description, schema, handler } 구조.

CLI (src/cli.ts)

API Client (src/lib/api-client.ts)

Cache (src/lib/cache.ts)

Annex File Parser (src/lib/annex-file-parser.ts)

별표/서식 파일 자동 파싱:

Data Flow Patterns

Pattern 1: 검색 → 조회 (2-step)

search_law("근로기준법") → mst: 276787
  ↓
get_law_text(mst="276787", jo="제74조")

Pattern 2: 배치 조회 (1 API call)

get_batch_articles(mst="279811", articles=["제38조","제39조","제40조"])
  → 전체 법령 1회 조회 후 조문 필터링

Pattern 3: 체인 도구 (자동 다단계)

chain_full_research(query="음주운전 처벌")
  → search_ai_law → get_law_text → search_precedents → search_interpretations
  → 병렬 실행, 섹션별 응답 결합

Pattern 4: 별표 본문 추출

get_annexes(lawName="여권법 시행령", bylSeq="000000")
  → 파일 다운로드 → 매직바이트 감지 → HWPX/HWP/PDF 분기
  → HWP: controls 내 테이블 추출 → Markdown 변환

Performance Optimizations

최적화 효과
search_all 병렬 API 호출 1200ms → 450ms (63% 감소)
get_batch_articles 1회 조회 N API calls → 1 API call
체인 도구 병렬 섹션 순차 대비 2~3배 빠름
LRU 캐시 (hit rate ~82%) 반복 조회 85% 응답 시간 감소
truncateSections() 체인 응답 크기 최적화

Deployment Architecture

Local (STDIO)

{
  "mcpServers": {
    "korean-law": {
      "command": "korean-law-mcp",
      "env": { "LAW_OC": "your-key" }
    }
  }
}

Remote (Fly.io)

{
  "mcpServers": {
    "korean-law": {
      "url": "https://korean-law-mcp.fly.dev/mcp"
    }
  }
}

Docker (자체 호스팅)

docker build -t korean-law-mcp .
docker run -e LAW_OC=your-key -p 3000:3000 korean-law-mcp

Security

This site is open source. Improve this page.