korean-law-mcp 3.2.3 → 3.5.3

package/README.md

@@ -1,6 +1,6 @@
 # Korean Law MCP
 
-**법제처 41개 API를 15개 도구로.** 법령, 판례, 행정규칙, 자치법규, 조약, 해석례를 AI 어시스턴트나 터미널에서 바로 사용.
+**법제처 41개 API를 16개 도구로.** 법령, 판례, 행정규칙, 자치법규, 조약, 해석례 + **LLM 환각 방지 인용 검증**을 AI 어시스턴트나 터미널에서 바로 사용.
 
 [![npm version](https://img.shields.io/npm/v/korean-law-mcp.svg)](https://www.npmjs.com/package/korean-law-mcp)
 [![MCP 1.27](https://img.shields.io/badge/MCP-1.27-blue)](https://modelcontextprotocol.io)
@@ -14,7 +14,29 @@
 
 ---
 
-## v3.2.0 — 이제 이런 것도 됩니다
+## v3.5 — AI 법률 답변의 환각을 잡아내다
+
+**LLM이 지어낸 가짜 조문을 실시간으로 탐지.** 법제처 공식 DB로 모든 인용을 교차검증.
+
+```
+"민법 제750조에 따라 불법행위 손해배상을 청구하고,
+ 근로기준법 제60조 제1항은 연차유급휴가를 규정하며,
+ 상법 제401조의2 제7항에 따라 이사 책임을 물을 수 있고,
+ 형법 제9999조는 가중처벌을 정한다"
+```
+
+→ `verify_citations` 한 번으로 (실제 법제처 API 교차검증 결과):
+
+- ✓ 민법 제750조(불법행위의 내용) 실존
+- ✓ 근로기준법 제60조(연차 유급휴가) 제1항 실존
+- ✗ **상법 제401조의2 — 제7항 없음 (최대 제2항)**
+- ✗ **형법 제9999조 — 해당 조문 없음 (존재 범위: 제1조~제372조)**
+
+**ChatGPT·Claude가 쓴 법률 답변을 그대로 믿지 마세요.** 법률 AI 서비스, 로펌, 학생, 계약서 검토에서 신뢰도 체크 필수.
+
+---
+
+## v3.2.0+ — 자연어로 복합 분석
 
 사용법은 똑같습니다. **그냥 자연어로 물어보세요.** AI가 질문을 알아듣고, 필요한 분석을 자동으로 추가해줍니다.
 
@@ -81,11 +103,69 @@
 > 모든 결과 끝에 **"이어서 할 수 있는 조회"**가 제안됩니다. 복사해서 바로 이어가세요.
 
 <details>
-<summary>v3.2.1~v3.2.3 변경 이력</summary>
+<summary>v3.2.1~v3.5.3 변경 이력</summary>
+
+**v3.5.3** — `verify_citations` 실증 검증 후 3개 치명 버그 수정
+
+실제 법제처 API로 5건 테스트 → false negative 3건 발견 → 근본 원인 수정:
+
+- **"민법" → "난민법" 부분매칭 오매칭** — 기존 `chains.ts`의 `findLaws`/`scoreLawRelevance`가 이미 해결해둔 로직인데 verify_citations가 재사용하지 않고 자체 로직으로 중복 구현했던 것. 공용 모듈 `lib/law-search.ts`로 추출하여 양쪽 재사용 (중복 제거)
+- **원숫자(①②③…) 항번호 파싱 실패** — 법제처 API가 `항번호`를 `"① "` 형태로 리턴하는데 기존 `parseInt(raw.replace(/[^\d]/g, ""))`가 유니코드 원숫자를 제거해 NaN. 근로기준법 제60조 제1항이 실존함에도 "최대 제0항" 오판정 → `lib/article-parser.ts`에 `parseHangNumber()` 원숫자 매핑 유틸 추가
+- **짧은 법령명 검색 누락** — 법제처 lawSearch API가 `display=20`에서 "상법"을 결과 34번째로 리턴. `apiClient.searchLaw`에 display 파라미터 추가, verify_citations는 `searchDisplay=100`으로 호출
+
+검증 후 5/5 정확 판정 (위 예시 결과가 그 출력).
+
+**v3.5.2** — kordoc 2.3.0 → 2.4.0 업데이트 (별표/서식 파싱 엔진)
+
+**v3.5.1** — lite/full 프로필 체계 제거 (V3_EXPOSED 16개 고정 노출 도입 후 실질 미사용). `tool-profiles.ts`에서 `LITE_TOOLS`/`parseProfile`/`filterToolsByProfile` 제거, 헬스 엔드포인트 거짓 `profiles` 필드 → 정확한 `tools: { exposed: 16, total: 92 }` 로 교체. Breaking change 아님 (`?profile=lite`도 이미 무시되던 값)
+
+**v3.5.0** — Killer feature: `verify_citations` 인용 검증 + Critical 핫픽스 + 보안 강화
+
+- **`verify_citations`** 신규 — LLM 환각 방지. 사용자 텍스트에서 조문 인용 정규식 추출 + 직전 30자 lookback으로 법령명 역추적 + 법제처 DB 병렬 교차검증. 결과: ✓(실존) / ✗(없음, 존재 범위 제시) / ⚠(법령명 불명확)
+- **Critical 핫픽스** — v3.4.0 `full` 파라미터가 12개 도메인(tax_tribunal, customs, ftc, pipc, nlrc, acr, treaty, interpretation 등)에서 스키마에 필드가 없어 묵묵히 무시되던 문제 수정. `unified-decisions.ts`가 하위 핸들러 응답을 받은 뒤 `compactLongSections()` 후처리로 계단식 축약 일괄 적용
+- **보안 High 2건** — `fetch-with-retry.ts` 타임아웃/네트워크 에러에 API 키 포함 URL이 로그로 유출되던 문제 → `maskSensitiveUrl()`로 `OC=***` 마스킹. `trust proxy true` → `TRUST_PROXY` 환경변수(기본 `1`), X-Forwarded-For 스푸핑 rate limit 우회 차단
+- **품질 3건** — `decision-compact.ts` 날짜 정규식 경계 가드, TAIL 경계 `". "` 오탐 제거, `stripRepeatedSummary` 종료점 정확 탐지
+- **UX** — 체인 8개 description 구체화(LLM이 체인 선택 가능), 검색 결과 "💡 다음: get_law_text(...)" 힌트, `search_law` 약칭/오타 확장 자동 재시도, `query-router` 패턴 5개 추가, `discover_tools` 별칭 매칭 27개
+
+**v3.4.0** — 판례 응답 토큰 평균 74% 감축 + `get_decision_text`에 `full` 파라미터 추가
+
+법령 RAG 관점에서 판례 응답 구조를 재해석: 판시사항·판결요지·주문은 규범 재사용의 핵심이라 full 유지, "이유" 전문은 사안별 사실관계 나열이라 LLM이 대부분 소비만 하고 버림. 이 비대칭을 활용해 판례/헌재/행심(`precedent`/`constitutional`/`admin_appeal`) 3개 도메인에 **계단식 축약 + structured ref densify** 적용. `lib/decision-compact.ts` 신규:
+
+- **`compactBody`** — 전문/이유 섹션을 앞 800자 + 중략 마커 + 뒤 400자로 축약. 판결 종결어미(`~다.`, `~라 할 것이다.`)와 문장 경계 가드 내장. `minSave` 가드로 짧은 본문(1300자 이하)은 skip
+- **`densifyLawRefs`** — 참조조문의 괄호 설명 제거 (`제390조(채무불이행과 손해배상)` → `제390조`). 평균 40~55% 절감
+- **`densifyPrecedentRefs`** — 참조판례의 "선고"/"판결" 제거 + 날짜 공백 압축 (`2020. 3. 26. 선고 2018두56077 판결` → `2020.3.26. 2018두56077`)
+- **`stripRepeatedSummary`** — 법제처 API가 판시/요지를 본문 앞쪽에 또 섞어 보내는 케이스 탐지·제거
+
+`get_decision_text`에 `full?: boolean` 파라미터 추가. 미지정(기본)=축약, `true`=전문. 응답 중간의 `⋯ 중략 N자 (full=true로 전문 조회) ⋯` 마커가 재호출 힌트 역할.
+
+**실측 (실제 법제처 API, 고정 ID 8건)**:
+
+| 도메인 | Before avg | After avg | 절감 |
+|---|---:|---:|---:|
+| 판례 | 5,230 chars | 3,049 chars | **-42%** |
+| 헌재 | 8,368 chars | 1,703 chars | **-80%** |
+| 행심 | 8,429 chars | 1,491 chars | **-82%** |
+| **종합** | **7,606 chars (1,901 tok)** | **1,960 chars (490 tok)** | **-74%** |
+
+긴 결정례(15,000자↑)에서 **80~89%** 절감이 가장 두드러짐. 짧은 본문은 `minSave` 가드로 원본 유지. 품질 손실 없음 (판시·요지·주문은 항상 full).
+
+부가로 **ListTools 페이로드도 -14%** (9,671 → 8,296 bytes, 344 토큰↓): `chain_*` 8개 description 간결화, `search_decisions`/`get_decision_text` 필드 describe에서 17 도메인 이중 기재 제거.
+
+**v3.3.1** — 법령 약칭 사전 대폭 확장 (11 → 52개, +41)
+
+lexdiff에서 "산안기준규칙" 질의가 법제처 aiSearch의 키워드 부분매칭으로 **국가표준기본법**으로 환각되던 사례가 발견돼 `resolveLawAlias`의 `LAW_ALIAS_ENTRIES`를 대폭 보강. 다빈도 노무/안전(산안법·중처법·근기법 등), 개인정보/정보통신(개보법·정보통신망법), 청렴/이해충돌(청탁금지법·이해충돌방지법), 공공계약(국가계약법·지방계약법), 부동산/임대차(주임법·상임법·부거법), 공정거래(공정거래법·하도급법·약관법·표시광고법·가맹사업법), 금융(자본시장법·특금법·전금법), 도시계획(국토계획법·도정법), 환경(감염병예방법·대기환경법), 운수(여객운수법·화물운수법), 민·형사 절차(민소법·형소법·민집법), 사회보험(국건법·산재보험법·고보법), 통신(전기통신사업법) 커버. `api-client.ts`/`law-parser.ts`가 이미 `resolveLawAlias`를 사용 중이라 **데이터 추가만으로 기존 검색 경로가 자동 혜택**. 신규 41개 + 회귀 4개 포함 **45/45 테스트 통과**.
+
+**v3.3.0** — HTTP stateless 모드 전환 + kordoc 2.3.0
+
+원격 서버(`korean-law-mcp.fly.dev`)가 주기적으로 OOM kill로 재시작되면서 기존 세션 ID가 무효화되던 문제를 근본 해결. MCP 공식 stateless 패턴(`sessionIdGenerator: undefined`)으로 전환하여 매 요청마다 fresh `Server + Transport`를 생성, 요청 종료 시 즉시 해제. in-memory 세션 Map·InMemoryEventStore·idle cleanup 전부 제거로 누수 원인 소거. 재시작·스케일아웃·배포 모두 무손실. `GET /mcp`·`DELETE /mcp`는 공식 예제와 동일하게 `405`. API 키는 `AsyncLocalStorage`로 요청 단위 격리 (race condition 방지).
+
+- **HTTP stateless 전환** — [src/server/http-server.ts](src/server/http-server.ts) (참고: `@modelcontextprotocol/sdk/examples/server/simpleStatelessStreamableHttp.js`)
+- **kordoc 2.2.5 → 2.3.0** — 별표/서식 파싱 엔진 업데이트
+- **세션 관리 코드 완전 제거** — `sessions` Map, `MAX_SESSIONS`, idle cleanup `setInterval`, `InMemoryEventStore`, POST/GET/DELETE 분기 로직 삭제 (v3.2.3의 LRU eviction 접근을 대체)
 
-**v3.2.3** — HTTP 세션 안정성 개선. `MAX_SESSIONS` 기본값 100→500 상향 + LRU eviction 도입. 한도 도달 시 503 에러 대신 가장 오래된 세션을 자동 제거하고 새 세션을 수락. 세션 폭주로 인한 원격 서버 접속 불가 현상 해소.
+**v3.2.3** — HTTP 세션 안정성 중간 개선. `MAX_SESSIONS` 100→500 + LRU eviction. _v3.3.0의 stateless 전환으로 대체됨._
 
-**v3.2.2** — 별표/서식 조회 도구(`get_annexes`)를 기본 노출 도구에 추가. **노출 도구 수 14 → 15개** (별표 조회가 `discover_tools`를 거치지 않고 바로 호출 가능). 환불·감경 키워드 질의 시 별표 자동 조회 로직 추가.
+**v3.2.2** — 별표/서식 조회 도구(`get_annexes`)를 기본 노출 도구에 추가. **노출 도구 수 14 → 15개**. 환불·감경 키워드 질의 시 별표 자동 조회 로직 추가.
 
 **v3.2.1** — kordoc 2.2.5 업데이트.
 

package/build/index.js

@@ -9,14 +9,13 @@ import { LawApiClient } from "./lib/api-client.js";
 import { registerTools } from "./tool-registry.js";
 import { startHTTPServer } from "./server/http-server.js";
 import { VERSION } from "./version.js";
-import { parseProfile } from "./lib/tool-profiles.js";
 // API 클라이언트 초기화 (LAW_OC 또는 KOREAN_LAW_API_KEY 지원)
 const LAW_OC = process.env.LAW_OC || process.env.KOREAN_LAW_API_KEY || "";
 const apiClient = new LawApiClient({ apiKey: LAW_OC });
 // MCP 서버 팩토리 (HTTP 모드: 세션마다 새 인스턴스 필요)
-function createServer(profile) {
+function createServer() {
     const s = new Server({ name: "korean-law", version: VERSION }, { capabilities: { tools: {} } });
-    registerTools(s, apiClient, profile ?? "full");
+    registerTools(s, apiClient);
     return s;
 }
 // 서버 시작
@@ -40,9 +39,7 @@ async function main() {
         // stdout 오염 방지: MCP JSON-RPC 프로토콜 보호
         const stderrWrite = (...args) => process.stderr.write(args.map(String).join(" ") + "\n");
         console.log = console.warn = console.info = console.debug = stderrWrite;
-        // MCP_PROFILE 환경변수로 프로필 선택 (기본: full)
-        const profile = parseProfile(process.env.MCP_PROFILE);
-        const server = createServer(profile);
+        const server = createServer();
         const transport = new StdioServerTransport();
         await server.connect(transport);
     }

package/build/lib/api-client.d.ts

@@ -9,7 +9,7 @@ export declare class LawApiClient {
     /**
      * API 키 결정 순서:
      * 1. 요청별 override 키
-     * 2. 현재 세션의 API 키 (HTTP 모드)
+     * 2. 현재 요청 컨텍스트의 API 키 (HTTP stateless 모드)
      * 3. 환경변수 LAW_OC
      * 4. 생성자에서 받은 기본 키
      */
@@ -22,8 +22,9 @@ export declare class LawApiClient {
     private checkHtmlError;
     /**
      * 법령 검색
+     * @param display 결과 개수 (기본값 법제처 API default, 짧은 법령명("상법" 등) 정확 매칭 찾으려면 큰 값 권장)
      */
-    searchLaw(query: string, apiKey?: string): Promise<string>;
+    searchLaw(query: string, apiKey?: string, display?: number): Promise<string>;
     /**
      * 현행법령 조회
      */

package/build/lib/api-client.js

@@ -3,7 +3,7 @@
  */
 import { normalizeLawSearchText, resolveLawAlias } from "./search-normalizer.js";
 import { fetchWithRetry } from "./fetch-with-retry.js";
-import { sessionStore, getSessionApiKey } from "./session-state.js";
+import { requestContext } from "./session-state.js";
 const LAW_API_BASE = "https://www.law.go.kr/DRF";
 export class LawApiClient {
     constructor(config) {
@@ -12,14 +12,13 @@ export class LawApiClient {
     /**
      * API 키 결정 순서:
      * 1. 요청별 override 키
-     * 2. 현재 세션의 API 키 (HTTP 모드)
+     * 2. 현재 요청 컨텍스트의 API 키 (HTTP stateless 모드)
      * 3. 환경변수 LAW_OC
      * 4. 생성자에서 받은 기본 키
      */
     getApiKey(overrideKey) {
-        const currentSessionId = sessionStore.getStore();
-        const sessionApiKey = currentSessionId ? getSessionApiKey(currentSessionId) : undefined;
-        const key = overrideKey || sessionApiKey || process.env.LAW_OC || process.env.KOREAN_LAW_API_KEY || this.defaultApiKey;
+        const ctxApiKey = requestContext.getStore()?.apiKey;
+        const key = overrideKey || ctxApiKey || process.env.LAW_OC || process.env.KOREAN_LAW_API_KEY || this.defaultApiKey;
         if (!key) {
             throw new Error("API 키가 필요합니다. 법제처(https://open.law.go.kr/LSO/openApi/guideResult.do)에서 발급받으세요.");
         }
@@ -57,8 +56,9 @@ export class LawApiClient {
     }
     /**
      * 법령 검색
+     * @param display 결과 개수 (기본값 법제처 API default, 짧은 법령명("상법" 등) 정확 매칭 찾으려면 큰 값 권장)
      */
-    async searchLaw(query, apiKey) {
+    async searchLaw(query, apiKey, display) {
         const normalizedQuery = normalizeLawSearchText(query);
         const aliasResolution = resolveLawAlias(normalizedQuery);
         const finalQuery = aliasResolution.canonical;
@@ -68,6 +68,8 @@ export class LawApiClient {
             target: "law",
             query: finalQuery,
         });
+        if (display && display > 0)
+            params.append("display", String(display));
         const url = `${LAW_API_BASE}/lawSearch.do?${params.toString()}`;
         const response = await fetchWithRetry(url);
         await this.throwIfError(response, "searchLaw");

package/build/lib/article-parser.d.ts

@@ -20,5 +20,6 @@ export declare function formatArticleUnit(unit: {
     header: string;
     body: string;
 } | null;
+export declare function parseHangNumber(raw: unknown): number;
 /** HTML 정리 - 엔티티 디코딩 순서 중요: & 최후 처리 (이중 인코딩 방지) */
 export declare function cleanHtml(text: string): string;

package/build/lib/article-parser.js

@@ -112,6 +112,24 @@ export function formatArticleUnit(unit) {
         body = cleanHtml(body);
     return { header, body };
 }
+/**
+ * 항번호 문자열을 숫자로 변환.
+ * 법제처 API는 항번호를 원숫자(①②③…)로 돌려주는 경우가 많아 일반 숫자 추출만 하면 NaN.
+ * 원숫자 ①=1 … ⑳=20 매핑 + fallback으로 일반 숫자 추출.
+ */
+const CIRCLED_DIGITS = "①②③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲⑳";
+export function parseHangNumber(raw) {
+    const s = String(raw ?? "").trim();
+    if (!s)
+        return NaN;
+    // 원숫자 매핑 (첫 글자 기준)
+    const circledIdx = CIRCLED_DIGITS.indexOf(s[0]);
+    if (circledIdx >= 0)
+        return circledIdx + 1;
+    // 일반 숫자 매칭 (예: "1", "제1항", "제 1 항")
+    const numMatch = s.match(/\d+/);
+    return numMatch ? parseInt(numMatch[0], 10) : NaN;
+}
 /** HTML 정리 - 엔티티 디코딩 순서 중요: & 최후 처리 (이중 인코딩 방지) */
 export function cleanHtml(text) {
     return text

package/build/lib/decision-compact.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Decision Compact — 판례/헌재/행심 응답 토큰 최적화 유틸
+ *
+ * B. compactBody: 본문("이유"/"전문")을 "앞 800자 + 중략 + 뒤 400자"로 계단식 축약.
+ *    판시사항/판결요지/주문은 이미 별도 필드로 분리 반환되므로 본문에만 적용.
+ *    문장 경계(마침표·판례 특유 종결어미)를 존중하여 중간 절단 방지.
+ *
+ * C. densifyLawRefs / densifyPrecedentRefs: 참조조문·참조판례의 서지 잉여 제거.
+ *    괄호 안 조문명, "선고"/"판결" 군더더기, 날짜 공백 압축. 구조 유지 + 압축.
+ *
+ * D. compactLongSections: 통합 후처리용. 응답 텍스트에서 알려진 긴 섹션 헤더
+ *    ("이유:", "전문:", "회답:" 등)를 찾아 해당 섹션 본문에 compactBody 적용.
+ *    unified-decisions.ts가 도메인별 스키마를 바꾸지 않고 full=false 기본값을
+ *    강제하기 위해 사용.
+ *
+ * 안전성: 모든 함수는 매칭 실패 / 빈 입력 / 짧은 입력 시 **원본 그대로 반환**.
+ */
+export interface CompactOptions {
+    /** true 시 축약 비활성 → 원본 반환 */
+    full?: boolean;
+    /** 앞쪽 보존 길이 (기본 800자) */
+    headSize?: number;
+    /** 뒤쪽 보존 길이 (기본 400자) */
+    tailSize?: number;
+    /** head+tail+minSave 이하면 축약 안 함 (기본 500자) */
+    minSave?: number;
+}
+/**
+ * 본문 계단식 축약
+ * - 앞 800자 + 중략 마커 + 뒤 400자
+ * - 문장 경계 가드: 마침표/판례 종결어미/빈 줄에서 끊기
+ * - head 기준 50% 이상 위치에 경계 없으면 원시 슬라이스 사용 (fallback)
+ */
+export declare function compactBody(text: string, opts?: CompactOptions): string;
+/**
+ * 참조조문 densify
+ *
+ * 압축 전략:
+ *   1) 조문명 괄호 설명 제거: "제390조(채무불이행과 손해배상)" → "제390조"
+ *   2) 연속 공백/구분자 정리
+ *
+ * 조문명 괄호는 평균 15~30자 × 참조조문 5~10개 = 150~300자 절감 (40%).
+ * 법령명 자체는 건드리지 않음 — LLM이 후속 도구 호출 시 파싱 필요.
+ */
+export declare function densifyLawRefs(text: string): string;
+/**
+ * 참조판례 densify
+ *
+ * 압축 전략:
+ *   1) "선고" 생략: "대법원 2020. 3. 26. 선고 2018두56077 판결" → "대법원 2020.3.26. 2018두56077"
+ *   2) 날짜 공백 압축: "2020. 3. 26." → "2020.3.26."
+ *   3) "판결" 접미어 제거
+ *   4) 구분자 정리
+ */
+export declare function densifyPrecedentRefs(text: string): string;
+/**
+ * 본문에서 판시사항/판결요지가 반복 등장하면 제거
+ *
+ * 법제처 API 판례 응답은 `판시사항`, `판결요지`가 별도 필드로 나오지만
+ * `판례내용`(전문) 앞쪽에 같은 내용이 반복되는 케이스가 많다.
+ * 이미 상단에 렌더된 부분을 본문에서 제거하여 LLM 중복 소비 방지.
+ *
+ * 경계 탐지: 요약의 앞 80자로 시작점(idx)을, 요약의 끝 60자로 실제 종료점(endIdx)을
+ * 탐지. 끝 매칭이 실패하면 보수적으로 s.length만큼만 제거하여 본문 다른 내용이
+ * 같이 날아가는 사고 방지.
+ */
+export declare function stripRepeatedSummary(body: string, summaries: Array<string | undefined>): string;
+export declare function compactLongSections(text: string): string;

package/build/lib/decision-compact.js

@@ -0,0 +1,229 @@
+/**
+ * Decision Compact — 판례/헌재/행심 응답 토큰 최적화 유틸
+ *
+ * B. compactBody: 본문("이유"/"전문")을 "앞 800자 + 중략 + 뒤 400자"로 계단식 축약.
+ *    판시사항/판결요지/주문은 이미 별도 필드로 분리 반환되므로 본문에만 적용.
+ *    문장 경계(마침표·판례 특유 종결어미)를 존중하여 중간 절단 방지.
+ *
+ * C. densifyLawRefs / densifyPrecedentRefs: 참조조문·참조판례의 서지 잉여 제거.
+ *    괄호 안 조문명, "선고"/"판결" 군더더기, 날짜 공백 압축. 구조 유지 + 압축.
+ *
+ * D. compactLongSections: 통합 후처리용. 응답 텍스트에서 알려진 긴 섹션 헤더
+ *    ("이유:", "전문:", "회답:" 등)를 찾아 해당 섹션 본문에 compactBody 적용.
+ *    unified-decisions.ts가 도메인별 스키마를 바꾸지 않고 full=false 기본값을
+ *    강제하기 위해 사용.
+ *
+ * 안전성: 모든 함수는 매칭 실패 / 빈 입력 / 짧은 입력 시 **원본 그대로 반환**.
+ */
+/**
+ * 본문 계단식 축약
+ * - 앞 800자 + 중략 마커 + 뒤 400자
+ * - 문장 경계 가드: 마침표/판례 종결어미/빈 줄에서 끊기
+ * - head 기준 50% 이상 위치에 경계 없으면 원시 슬라이스 사용 (fallback)
+ */
+export function compactBody(text, opts = {}) {
+    if (opts.full || !text)
+        return text;
+    const HEAD = opts.headSize ?? 800;
+    const TAIL = opts.tailSize ?? 400;
+    const MIN_SAVE = opts.minSave ?? 500;
+    // 짧으면 축약 이득 없음 → 원본
+    if (text.length <= HEAD + TAIL + MIN_SAVE)
+        return text;
+    // HEAD — 앞에서 HEAD자까지 중 문장 끝에서 자르기
+    const headRaw = text.slice(0, HEAD);
+    const headBoundaries = [
+        headRaw.lastIndexOf("다.\n"),
+        headRaw.lastIndexOf("라.\n"),
+        headRaw.lastIndexOf("다. "),
+        headRaw.lastIndexOf("라. "),
+        headRaw.lastIndexOf(".\n\n"),
+        headRaw.lastIndexOf("\n\n"),
+        headRaw.lastIndexOf(". "),
+    ];
+    const headCutCandidate = Math.max(...headBoundaries);
+    const headCut = headCutCandidate > HEAD * 0.5 ? headCutCandidate + 2 : HEAD;
+    const head = text.slice(0, headCut).trimEnd();
+    // TAIL — 뒤에서 TAIL자 범위 중 문장 시작에서 자르기
+    // ". " 경계는 소수점("1,234.00 원")/영문 약어("No. 3") 오탐 위험으로 제외.
+    // 판례 한국어 특성상 "다." / "라." 종결어미가 지배적이라 이걸로 충분.
+    const tailStart = text.length - TAIL;
+    const tailRaw = text.slice(tailStart);
+    const tailBoundaryIdx = [
+        tailRaw.indexOf("\n\n"),
+        tailRaw.indexOf("다.\n"),
+        tailRaw.indexOf("라.\n"),
+        tailRaw.indexOf("다. "),
+        tailRaw.indexOf("라. "),
+        tailRaw.indexOf("한다. "),
+    ]
+        .filter((i) => i >= 0)
+        .sort((a, b) => a - b)[0];
+    const tailFrom = tailBoundaryIdx !== undefined && tailBoundaryIdx < TAIL * 0.5
+        ? tailStart + tailBoundaryIdx + 2
+        : tailStart;
+    const tail = text.slice(tailFrom).trimStart();
+    const omitted = text.length - head.length - tail.length;
+    if (omitted < MIN_SAVE)
+        return text; // 실질 절감 미달 시 원본
+    return `${head}\n\n⋯ 중략 ${omitted.toLocaleString()}자 (full=true로 전문 조회) ⋯\n\n${tail}`;
+}
+/**
+ * 참조조문 densify
+ *
+ * 압축 전략:
+ *   1) 조문명 괄호 설명 제거: "제390조(채무불이행과 손해배상)" → "제390조"
+ *   2) 연속 공백/구분자 정리
+ *
+ * 조문명 괄호는 평균 15~30자 × 참조조문 5~10개 = 150~300자 절감 (40%).
+ * 법령명 자체는 건드리지 않음 — LLM이 후속 도구 호출 시 파싱 필요.
+ */
+export function densifyLawRefs(text) {
+    if (!text)
+        return text;
+    const original = text;
+    // 1) 조문 뒤 괄호 설명 제거
+    //    "제390조(채무불이행과 손해배상)" → "제390조"
+    //    "제1항(적용범위)" → "제1항"
+    //    길이 3~40자 괄호만 타겟 (짧은 건 의미 있을 수 있음)
+    let compact = text.replace(/(제\d+조(?:의\d+)?|제\d+항|제\d+호)\s*\([^)]{3,40}\)/g, "$1");
+    // 2) 공백/구분자 정리
+    compact = compact
+        .replace(/\s*,\s*/g, ", ")
+        .replace(/\s*\/\s*/g, " / ")
+        .replace(/[ \t]{2,}/g, " ")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    // 실질 절감 없으면 원본
+    if (compact.length >= original.length * 0.95)
+        return original;
+    return compact;
+}
+/**
+ * 참조판례 densify
+ *
+ * 압축 전략:
+ *   1) "선고" 생략: "대법원 2020. 3. 26. 선고 2018두56077 판결" → "대법원 2020.3.26. 2018두56077"
+ *   2) 날짜 공백 압축: "2020. 3. 26." → "2020.3.26."
+ *   3) "판결" 접미어 제거
+ *   4) 구분자 정리
+ */
+export function densifyPrecedentRefs(text) {
+    if (!text)
+        return text;
+    const original = text;
+    let compact = text
+        // "선고" 앞뒤 공백 포함 제거
+        .replace(/\s*선고\s*/g, " ")
+        // "판결" 접미어 (공백 포함) 제거
+        .replace(/\s*판결(?=[\s,/;]|$)/g, "")
+        // 날짜 공백 압축: "2020. 3. 26." → "2020.3.26."
+        // 경계 가드: 시작/공백/구분자/괄호 뒤의 4자리 연도만 대상
+        // (문서 중간 "제2020." 같은 오탐 방지)
+        .replace(/(^|[\s,(\[;/])(\d{4})\.\s*(\d{1,2})\.\s*(\d{1,2})\./g, "$1$2.$3.$4.")
+        // "[동지] ", "[공보 생략]" 같은 부가표기 제거
+        .replace(/\s*\[[^\]]{2,15}\]\s*/g, " ")
+        // 연속 공백
+        .replace(/[ \t]{2,}/g, " ")
+        .replace(/\s*,\s*/g, ", ")
+        .trim();
+    if (compact.length >= original.length * 0.95)
+        return original;
+    return compact;
+}
+/**
+ * 본문에서 판시사항/판결요지가 반복 등장하면 제거
+ *
+ * 법제처 API 판례 응답은 `판시사항`, `판결요지`가 별도 필드로 나오지만
+ * `판례내용`(전문) 앞쪽에 같은 내용이 반복되는 케이스가 많다.
+ * 이미 상단에 렌더된 부분을 본문에서 제거하여 LLM 중복 소비 방지.
+ *
+ * 경계 탐지: 요약의 앞 80자로 시작점(idx)을, 요약의 끝 60자로 실제 종료점(endIdx)을
+ * 탐지. 끝 매칭이 실패하면 보수적으로 s.length만큼만 제거하여 본문 다른 내용이
+ * 같이 날아가는 사고 방지.
+ */
+export function stripRepeatedSummary(body, summaries) {
+    if (!body)
+        return body;
+    let result = body;
+    for (const s of summaries) {
+        if (!s || s.length < 20)
+            continue;
+        const trimmed = s.trim();
+        const headLen = Math.min(80, trimmed.length);
+        const head = trimmed.slice(0, headLen);
+        if (head.length < 20)
+            continue;
+        // 본문 앞 25% 안에서 동일 구간 탐지
+        const zone = result.slice(0, Math.floor(result.length * 0.25));
+        const idx = zone.indexOf(head);
+        if (idx < 0)
+            continue;
+        // 실제 종료점 탐지: 요약의 끝 60자를 본문에서 찾아 정확한 end 위치 계산
+        const tailLen = Math.min(60, trimmed.length - headLen);
+        let end;
+        if (tailLen >= 20) {
+            const tail = trimmed.slice(trimmed.length - tailLen);
+            // idx 이후 ±20% 범위 내에서만 tail 매칭 (다른 위치 오탐 방지)
+            const searchZone = result.slice(idx, Math.min(idx + Math.floor(trimmed.length * 1.3), result.length));
+            const tailIdxInZone = searchZone.indexOf(tail);
+            end = tailIdxInZone >= 0
+                ? idx + tailIdxInZone + tail.length
+                : Math.min(idx + trimmed.length, result.length);
+        }
+        else {
+            end = Math.min(idx + trimmed.length, result.length);
+        }
+        result = result.slice(0, idx) + result.slice(end);
+    }
+    return result;
+}
+/**
+ * 통합 후처리 축약 — unified-decisions.ts용
+ *
+ * 응답 포맷(도구별 getter 핸들러가 출력하는 텍스트)에서 알려진 긴 섹션
+ * 헤더("이유:", "전문:", "회답:" 등)를 찾아 해당 섹션 본문에 compactBody 적용.
+ *
+ * 이미 compactBody가 적용된 도메인(precedent, constitutional, admin_appeal)은
+ * unified-decisions.ts에서 skip 리스트로 관리되므로 여기서는 무조건 적용.
+ *
+ * 안전성:
+ *   - 알려진 섹션 헤더가 없으면 원본 반환
+ *   - 이미 "⋯ 중략 N자" 마커가 있으면 원본 반환 (이중 축약 방지)
+ *   - 본문이 짧으면 compactBody가 원본 반환
+ */
+const KNOWN_SECTION_HEADERS = [
+    "이유",
+    "전문",
+    "결정내용",
+    "본문",
+    "회답",
+    "재결이유",
+    "판결이유",
+    "판례내용",
+    "심판요지",
+    "의결내용",
+    "결정이유",
+    "조문내용",
+];
+export function compactLongSections(text) {
+    if (!text || text.length < 1500)
+        return text;
+    // 이미 축약된 경우 skip
+    if (text.includes("⋯ 중략 ") && text.includes("(full=true로 전문 조회)"))
+        return text;
+    const pattern = new RegExp(`\\n(${KNOWN_SECTION_HEADERS.join("|")}):\\n`, "g");
+    let lastMatch = null;
+    let m;
+    while ((m = pattern.exec(text)) !== null) {
+        lastMatch = m;
+    }
+    if (!lastMatch)
+        return text;
+    const sectionStart = lastMatch.index + lastMatch[0].length;
+    const body = text.slice(sectionStart);
+    const compacted = compactBody(body, { full: false });
+    if (compacted === body)
+        return text;
+    return text.slice(0, sectionStart) + compacted;
+}

package/build/lib/fetch-with-retry.d.ts

@@ -3,6 +3,12 @@
  * - Exponential backoff for 429, 503, 504
  * - AbortController for timeout
  */
+/**
+ * URL에서 민감 정보(API 키) 마스킹 — 에러 메시지/로그 노출 방지.
+ * 법제처 API는 ?OC=KEY 쿼리 파라미터로 키를 받으므로 해당 값만 *** 처리.
+ * 추가 방어로 일반적인 키 파라미터 이름들도 마스킹.
+ */
+export declare function maskSensitiveUrl(url: string): string;
 export interface FetchWithRetryOptions extends RequestInit {
     /** Request timeout in ms (default: 30000) */
     timeout?: number;

package/build/lib/fetch-with-retry.js

@@ -3,6 +3,16 @@
  * - Exponential backoff for 429, 503, 504
  * - AbortController for timeout
  */
+/**
+ * URL에서 민감 정보(API 키) 마스킹 — 에러 메시지/로그 노출 방지.
+ * 법제처 API는 ?OC=KEY 쿼리 파라미터로 키를 받으므로 해당 값만 *** 처리.
+ * 추가 방어로 일반적인 키 파라미터 이름들도 마스킹.
+ */
+export function maskSensitiveUrl(url) {
+    if (!url)
+        return url;
+    return url.replace(/([?&](?:oc|OC|apikey|apiKey|api_key|authKey|auth_key|key)=)[^&]+/g, "$1***");
+}
 const DEFAULT_TIMEOUT = 30000;
 const DEFAULT_RETRIES = 3;
 const DEFAULT_RETRY_DELAY = 1000;
@@ -37,13 +47,15 @@ export async function fetchWithRetry(url, options = {}) {
         }
         catch (error) {
             clearTimeout(timeoutId);
-            // Timeout or network error
+            // Timeout or network error — URL에서 API 키 제거 후 에러 생성
             if (error instanceof Error) {
                 if (error.name === "AbortError") {
-                    lastError = new Error(`Request timeout after ${timeout}ms for ${url}`);
+                    lastError = new Error(`Request timeout after ${timeout}ms for ${maskSensitiveUrl(url)}`);
                 }
                 else {
-                    lastError = error;
+                    // fetch 네이티브 에러 메시지에도 URL이 포함될 수 있음
+                    const masked = maskSensitiveUrl(error.message);
+                    lastError = masked !== error.message ? new Error(masked) : error;
                 }
             }
             // Retry on network errors

package/build/lib/law-search.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 공용 법령 검색 유틸 — chains / verify_citations 등에서 공유.
+ *
+ * 핵심: 법제처 lawSearch API는 부분 문자열 매칭 특성이 있어 "민법" → "난민법"
+ * 같은 엉뚱한 매칭이 발생한다. scoreLawRelevance로 정확 매칭 우선 정렬하여
+ * 첫 결과 신뢰 가능하게 만든다.
+ */
+import type { LawApiClient } from "./api-client.js";
+export interface LawInfo {
+    lawName: string;
+    lawId: string;
+    mst: string;
+    lawType: string;
+}
+/** 법령명이 아닌 부가 키워드 제거 (법제처 lawSearch API는 법령명 검색이므로) */
+export declare const NON_LAW_NAME_RE: RegExp;
+export declare function stripNonLawKeywords(query: string): string;
+/** XML에서 법령 정보 파싱 */
+export declare function parseLawXml(xmlText: string, max: number): LawInfo[];
+/** 쿼리 대비 법령명 관련도 점수 (높을수록 관련) */
+export declare function scoreLawRelevance(lawName: string, query: string, queryWords: string[]): number;
+/**
+ * 법령 검색 + 관련도 정렬 + 캐싱.
+ * 1차: 원본 쿼리 → 2차: 부가키워드 제거 → 3차: 법령명 패턴 직접 추출
+ * 이후 scoreLawRelevance로 정렬.
+ *
+ * @param searchDisplay 법제처 API display 파라미터 — 짧은 법령명("상법"은 100개 중 34번째)
+ *                      정확 매칭 찾으려면 크게(100+). 기본 20은 체인 도구용.
+ */
+export declare function findLaws(apiClient: LawApiClient, query: string, apiKey?: string, max?: number, searchDisplay?: number): Promise<LawInfo[]>;