@@ -1,4 +1,4 @@
-# Korean Law MCP - System Architecture
+# Korean Law MCP - System Architecture
 
 > **v2.3.2** | Last Updated: April 2026
 
@@ -7,153 +7,153 @@
 ## High-Level Architecture
 
 ```
-?뚢??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??
-??                    MCP Client (Claude ??                    ??
-?붴??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?р??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?р??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??
+┌──────────────────────────────────────────────────────────────┐
+│                     MCP Client (Claude 등)                    │
+└────────────────────┬────────────────────┬────────────────────┘
               STDIO Mode              HTTP Mode
             (Local Desktop)        (Remote: Fly.io)
-                     ??                   ??
-?뚢??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?쇄??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?쇄??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??
-??              Korean Law MCP Server (v2.3.2)                  ??
-??                                                              ??
-?? ?뚢??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??  ??
-?? ??    Tool Registry (89 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 ??寃⑸━, ALS)       ??  ??
-?? ?? ??cache.ts            (LRU + TTL)                    ??  ??
-?? ?붴??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??  ??
-??                            ??                                ??
-?? ?뚢??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??  ??
-?? ??       Server Layer                                    ??  ??
-?? ?? ??http-server.ts  (Streamable HTTP stateless, MCP ?쒖?)?? ??
-?? ?붴??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??  ??
-?붴??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?р??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??
-                            ??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/...)          ??
-?붴??€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€?€??
+                     │                    │
+┌────────────────────▼────────────────────▼────────────────────┐
+│               Korean Law MCP Server (v2.3.2)                  │
+│                                                               │
+│  ┌───────────────────────────────────────────────────────┐   │
+│  │     Tool Registry (98 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 키 격리, ALS)       │   │
+│  │  • cache.ts            (LRU + TTL)                    │   │
+│  └───────────────────────────────────────────────────────┘   │
+│                             ▲                                 │
+│  ┌───────────────────────────────────────────────────────┐   │
+│  │        Server Layer                                    │   │
+│  │  • http-server.ts  (Streamable HTTP stateless, MCP 표준)│  │
+│  └───────────────────────────────────────────────────────┘   │
+└───────────────────────────┬───────────────────────────────────┘
+                            │ 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**: 97媛??꾧뎄瑜?`tool-registry.ts`??`allTools[]`???깅줉
+1. **Separation of Concerns**: Tools → Shared Libs → API Client
+2. **Single Responsibility**: 파일당 200줄 미만, 단일 기능
+3. **Centralized Tool Registry**: 98개 도구를 `tool-registry.ts`의 `allTools[]`에 등록
 4. **Type Safety**: TypeScript strict mode + Zod validation
-5. **Stateless HTTP**: MCP StreamableHTTP stateless 紐⑤뱶 ???붿껌留덈떎 fresh Server+Transport, AsyncLocalStorage濡??붿껌蹂?API ??寃⑸━ (?ъ떆?뫢룹뒪耳€?쇱븘???댁꽦)
+5. **Stateless HTTP**: MCP StreamableHTTP stateless 모드 — 요청마다 fresh Server+Transport, AsyncLocalStorage로 요청별 API 키 격리 (재시작·스케일아웃 내성)
 6. **Network Resilience**: 30s timeout, 3 retries with exponential backoff
-7. **Dual Interface**: MCP ?쒕쾭 + CLI ?숈떆 吏€??
+7. **Dual Interface**: MCP 서버 + CLI 동시 지원
 
 ---
 
 ## Component Deep Dive
 
 ### Entry Point (`src/index.ts`)
 
-- MCP ?쒕쾭 珥덇린??
-- CLI ?몄옄 ?뚯떛 (`--mode stdio|sse|http`, `--port`)
-- `registerTools(server, apiClient)` ?몄텧濡?97媛??꾧뎄 ?쇨큵 ?깅줉
+- MCP 서버 초기화
+- CLI 인자 파싱 (`--mode stdio|sse|http`, `--port`)
+- `registerTools(server, apiClient)` 호출로 98개 도구 일괄 등록
 
 ### Tool Registry (`src/tool-registry.ts`)
 
-紐⑤뱺 ?꾧뎄瑜?`allTools[]` 諛곗뿴濡?愿€由? 媛??꾧뎄??`{ name, description, schema, handler }` 援ъ“.
-- `ListToolsRequest` ??allTools?먯꽌 name/description/inputSchema 諛섑솚
-- `CallToolRequest` ??name?쇰줈 留ㅼ묶 ??handler ?ㅽ뻾
-- `unwrapZodEffects()`: `.refine()` ?곸슜??Zod ?ㅽ궎留덈? MCP JSON Schema濡?蹂€??
+모든 도구를 `allTools[]` 배열로 관리. 각 도구는 `{ name, description, schema, handler }` 구조.
+- `ListToolsRequest` → allTools에서 name/description/inputSchema 반환
+- `CallToolRequest` → name으로 매칭 후 handler 실행
+- `unwrapZodEffects()`: `.refine()` 적용된 Zod 스키마를 MCP JSON Schema로 변환
 
 ### CLI (`src/cli.ts`)
 
-- `korean-law <tool> --param value` ?뺥깭濡?97媛??꾧뎄 吏곸젒 ?ㅽ뻾
-- `korean-law list [--category ...]`: ?꾧뎄 紐⑸줉/移댄뀒怨좊━ ?꾪꽣
-- `korean-law help <tool>`: ?꾧뎄 ?곸꽭 ?뚮씪誘명꽣
-- `--json-input`: JSON?쇰줈 蹂듯빀 ?뚮씪誘명꽣 ?꾨떖
+- `korean-law <tool> --param value` 형태로 98개 도구 직접 실행
+- `korean-law list [--category ...]`: 도구 목록/카테고리 필터
+- `korean-law help <tool>`: 도구 상세 파라미터
+- `--json-input`: JSON으로 복합 파라미터 전달
 
 ### API Client (`src/lib/api-client.ts`)
 
-- 踰뺤젣泥?API URL 援ъ꽦 + HTTP ?붿껌
-- HTML ?먮윭 ?섏씠吏€ 媛먯? (JSON/XML ?€??HTML 諛섑솚 ??
-- ?꾨찓?몃퀎 硫붿꽌?? `searchLaw()`, `getLawText()`, `getAnnexes()` ??
+- 법제처 API URL 구성 + HTTP 요청
+- HTML 에러 페이지 감지 (JSON/XML 대신 HTML 반환 시)
+- 도메인별 메서드: `searchLaw()`, `getLawText()`, `getAnnexes()` 등
 
 ### Cache (`src/lib/cache.ts`)
 
-- LRU 罹먯떆 + TTL (寃€??1?쒓컙, 議곕Ц 24?쒓컙)
-- 理쒕? 100 ?뷀듃由? 1?쒓컙留덈떎 expired ?뺣━
+- LRU 캐시 + TTL (검색 1시간, 조문 24시간)
+- 최대 100 엔트리, 1시간마다 expired 정리
 
 ### Annex File Parser (`src/lib/annex-file-parser.ts`)
 
-蹂꾪몴/?쒖떇 ?뚯씪 ?먮룞 ?뚯떛:
-- **HWPX** (?좏삎, ZIP 湲곕컲): `jszip` + `@xmldom/xmldom` ??Markdown ?뚯씠釉?
-- **HWP** (援ы삎, OLE 湲곕컲): `hwp.js` ??`paragraph.content` + `controls[].content` ?뚯씠釉?異붿텧
-- **PDF**: ?뚯떛 遺덇? ??留곹겕 諛섑솚
+별표/서식 파일 자동 파싱:
+- **HWPX** (신형, ZIP 기반): `jszip` + `@xmldom/xmldom` → Markdown 테이블
+- **HWP** (구형, OLE 기반): `hwp.js` → `paragraph.content` + `controls[].content` 테이블 추출
+- **PDF**: 파싱 불가 → 링크 반환
 
 ---
 
 ## Data Flow Patterns
 
-### Pattern 1: 寃€????議고쉶 (2-step)
+### Pattern 1: 검색 → 조회 (2-step)
 
 ```
-search_law("洹쇰줈湲곗?踰?) ??mst: 276787
-  ??
-get_law_text(mst="276787", jo="??4議?)
+search_law("근로기준법") → mst: 276787
+  ↓
+get_law_text(mst="276787", jo="제74조")
 ```
 
-### Pattern 2: 諛곗튂 議고쉶 (1 API call)
+### Pattern 2: 배치 조회 (1 API call)
 
 ```
-get_batch_articles(mst="279811", articles=["??8議?,"??9議?,"??0議?])
-  ???꾩껜 踰뺣졊 1??議고쉶 ??議곕Ц ?꾪꽣留?
+get_batch_articles(mst="279811", articles=["제38조","제39조","제40조"])
+  → 전체 법령 1회 조회 후 조문 필터링
 ```
 
-### Pattern 3: 泥댁씤 ?꾧뎄 (?먮룞 ?ㅻ떒怨?
+### Pattern 3: 체인 도구 (자동 다단계)
 
 ```
-chain_full_research(query="?뚯＜?댁쟾 泥섎쾶")
-  ??search_ai_law ??get_law_text ??search_precedents ??search_interpretations
-  ??蹂묐젹 ?ㅽ뻾, ?뱀뀡蹂??묐떟 寃고빀
+chain_full_research(query="음주운전 처벌")
+  → search_ai_law → get_law_text → search_precedents → search_interpretations
+  → 병렬 실행, 섹션별 응답 결합
 ```
 
-### Pattern 4: 蹂꾪몴 蹂몃Ц 異붿텧
+### Pattern 4: 별표 본문 추출
 
 ```
-get_annexes(lawName="?ш텒踰??쒗뻾??, bylSeq="000000")
-  ???뚯씪 ?ㅼ슫濡쒕뱶 ??留ㅼ쭅諛붿씠??媛먯? ??HWPX/HWP/PDF 遺꾧린
-  ??HWP: controls ???뚯씠釉?異붿텧 ??Markdown 蹂€??
+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()` | 泥댁씤 ?묐떟 ?ш린 理쒖쟻??|
+| `search_all` 병렬 API 호출 | 1200ms → 450ms (63% 감소) |
+| `get_batch_articles` 1회 조회 | N API calls → 1 API call |
+| 체인 도구 병렬 섹션 | 순차 대비 2~3배 빠름 |
+| LRU 캐시 (hit rate ~82%) | 반복 조회 85% 응답 시간 감소 |
+| `truncateSections()` | 체인 응답 크기 최적화 |
 
 ---
 
@@ -174,9 +174,9 @@ get_annexes(lawName="?ш텒踰??쒗뻾??, bylSeq="000000")
 
 ### Remote (Fly.io)
 
-- **fly.toml**: `nrt` 由ъ쟾, 256MB 硫붾え由? auto suspend/resume
+- **fly.toml**: `nrt` 리전, 256MB 메모리, auto suspend/resume
 - **Dockerfile**: multi-stage build (node:20-alpine)
-- **Health check**: `GET /health` (30珥?媛꾧꺽)
+- **Health check**: `GET /health` (30초 간격)
 - **Endpoint**: `https://korean-law-mcp.fly.dev/mcp`
 
 ```json
@@ -189,7 +189,7 @@ get_annexes(lawName="?ш텒踰??쒗뻾??, bylSeq="000000")
 }
 ```
 
-### Docker (?먯껜 ?몄뒪??
+### Docker (자체 호스팅)
 
 ```bash
 docker build -t korean-law-mcp .
@@ -200,16 +200,16 @@ docker run -e LAW_OC=your-key -p 3000:3000 korean-law-mcp
 
 ## Security
 
-- **API ??*: ?섍꼍蹂€?섎쭔 ?ъ슜, 濡쒓렇???몄텧 湲덉?
-- **?붿껌 寃⑸━**: `session-state.ts`??AsyncLocalStorage濡??붿껌蹂?API ??遺꾨━ (stateless 紐⑤뱶, race condition 諛⑹?)
-- **?낅젰 寃€利?*: Zod ?ㅽ궎留덈줈 紐⑤뱺 ?꾧뎄 ?낅젰 寃€利?
-- **Rate Limiting**: `RATE_LIMIT_RPM` ?섍꼍蹂€??(湲곕낯 60 req/min)
-- **CORS**: `CORS_ORIGIN` ?섍꼍蹂€?섎줈 ?쒗븳
+- **API 키**: 환경변수만 사용, 로그에 노출 금지
+- **요청 격리**: `session-state.ts`의 AsyncLocalStorage로 요청별 API 키 분리 (stateless 모드, race condition 방지)
+- **입력 검증**: Zod 스키마로 모든 도구 입력 검증
+- **Rate Limiting**: `RATE_LIMIT_RPM` 환경변수 (기본 60 req/min)
+- **CORS**: `CORS_ORIGIN` 환경변수로 제한
 
 ---
 
 ## Related Docs
 
-- [API.md](API.md) - 97媛??꾧뎄 ?덊띁?곗뒪
-- [DEVELOPMENT.md](DEVELOPMENT.md) - 媛쒕컻??媛€?대뱶
-- [README.md](../README.md) - ?쒖옉 媛€?대뱶
+- [API.md](API.md) - 98개 도구 레퍼런스
+- [DEVELOPMENT.md](DEVELOPMENT.md) - 개발자 가이드
+- [README.md](../README.md) - 시작 가이드