korean-law-mcp 4.5.2 → 4.6.0

package/build/lib/citation-content-matcher.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 법령 조문 인용 내용 일치 검증
+ *
+ * LLM이 "제5조(목적)"로 인용한 내용이 실제 제5조의 본문/제목과 의미적으로
+ * 일치하는가를 다층 매칭으로 판정한다. 존재 검증만으로는 "존재하는 조문에
+ * 엉뚱한 내용 환각"을 잡지 못하기 때문.
+ *
+ * 레이어:
+ *  L1 (exact)   — 정규화 후 연속 30자+ 공통 substring
+ *  L2 (jaccard) — 문자 bigram Jaccard ≥ 0.25 (조사/어미 차이에 robust)
+ *
+ * ⚠️ LexDiff(lib/citation-content-matcher.ts)에서 이식한 순수함수. 수정 시
+ *    원본 확인 필수 (CLAUDE.md 규칙 1: LexDiff 이식 코드 무단 수정 금지).
+ *    단, normalizeLegalText의 zero-width/NBSP 제거는 유니코드 이스케이프가
+ *    소스에 실제 제어문자로 박히는 것을 피하려 코드포인트 비교로 재구현함
+ *    (동작 동일).
+ */
+export type MatchMethod = 'exact' | 'token-jaccard' | 'semantic' | 'mismatch';
+export interface ContentMatchResult {
+    matched: boolean;
+    method: MatchMethod;
+    score: number;
+    normalizedLenClaim: number;
+    normalizedLenActual: number;
+}
+/**
+ * 법률 텍스트 정규화:
+ *  - 원문자 ①②③ → (1)(2)(3)
+ *  - 「」, 『』 괄호 제거
+ *  - 중점/구분자(·•) → 공백
+ *  - whitespace 단일 공백
+ *  - NBSP(U+00A0)/zero-width 제거·치환
+ */
+export declare function normalizeLegalText(s: string): string;
+/**
+ * LLM claim 텍스트와 실제 조문 본문/제목을 비교해 일치 여부 판정.
+ * claim 또는 actual이 비어있으면 matched=false.
+ */
+export declare function matchCitationContent(claim: string, actual: string): ContentMatchResult;

package/build/lib/citation-content-matcher.js

@@ -0,0 +1,159 @@
+/**
+ * 법령 조문 인용 내용 일치 검증
+ *
+ * LLM이 "제5조(목적)"로 인용한 내용이 실제 제5조의 본문/제목과 의미적으로
+ * 일치하는가를 다층 매칭으로 판정한다. 존재 검증만으로는 "존재하는 조문에
+ * 엉뚱한 내용 환각"을 잡지 못하기 때문.
+ *
+ * 레이어:
+ *  L1 (exact)   — 정규화 후 연속 30자+ 공통 substring
+ *  L2 (jaccard) — 문자 bigram Jaccard ≥ 0.25 (조사/어미 차이에 robust)
+ *
+ * ⚠️ LexDiff(lib/citation-content-matcher.ts)에서 이식한 순수함수. 수정 시
+ *    원본 확인 필수 (CLAUDE.md 규칙 1: LexDiff 이식 코드 무단 수정 금지).
+ *    단, normalizeLegalText의 zero-width/NBSP 제거는 유니코드 이스케이프가
+ *    소스에 실제 제어문자로 박히는 것을 피하려 코드포인트 비교로 재구현함
+ *    (동작 동일).
+ */
+const MIN_EXACT_LEN = 30;
+// 문자 bigram jaccard의 실전 threshold. 완전히 관련 없는 법령 조문 간 값은
+// 0.05~0.10 수준. 어순/조사 paraphrase로 공통 의미를 유지하면 0.25~0.50.
+const JACCARD_THRESHOLD = 0.25;
+const CIRCLED = '①②③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮';
+// zero-width: U+200B ZWSP, U+200C ZWNJ, U+200D ZWJ, U+FEFF BOM
+function isZeroWidth(cp) {
+    return cp === 0x200b || cp === 0x200c || cp === 0x200d || cp === 0xfeff;
+}
+/**
+ * 법률 텍스트 정규화:
+ *  - 원문자 ①②③ → (1)(2)(3)
+ *  - 「」, 『』 괄호 제거
+ *  - 중점/구분자(·•) → 공백
+ *  - whitespace 단일 공백
+ *  - NBSP(U+00A0)/zero-width 제거·치환
+ */
+export function normalizeLegalText(s) {
+    if (!s)
+        return '';
+    // NBSP→공백, zero-width 제거 (코드포인트 비교 — 소스에 제어문자 미포함)
+    let cleaned = '';
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (isZeroWidth(cp))
+            continue;
+        cleaned += cp === 0x00a0 ? ' ' : ch;
+    }
+    return cleaned
+        .replace(/[①②③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮]/g, (m) => `(${CIRCLED.indexOf(m) + 1})`)
+        .replace(/[「『]/g, '')
+        .replace(/[」』]/g, '')
+        .replace(/[·•]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * 한국어는 교착어라 조사/어미가 단어에 붙어 word-level jaccard 신뢰도 낮음.
+ * 문자 bigram(연속 두 글자)을 토큰으로 사용하면 "관세를" vs "관세" 같은
+ * 미세한 어미 차이에도 overlap이 발생해 robust.
+ * 구두점/공백은 bigram 생성 전에 제거.
+ */
+function tokenize(s) {
+    const compact = normalizeLegalText(s)
+        .toLowerCase()
+        .replace(/[\s,.?!;:()[\]{}"'`~<>/\\|+=*&^%$#@!-]+/gu, '');
+    if (compact.length < 2)
+        return compact ? [compact] : [];
+    const grams = [];
+    for (let i = 0; i < compact.length - 1; i++) {
+        grams.push(compact.slice(i, i + 2));
+    }
+    return grams;
+}
+/** Rolling-hash 없이도 실용적으로 충분한 최장 공통 substring 길이 (small inputs) */
+function longestCommonSubstringLen(a, b) {
+    if (!a || !b)
+        return 0;
+    // DP O(n*m). 조문 본문은 일반적으로 수천자 이내 → 실사용에서 문제없음.
+    // 메모리 절감 위해 이전 행만 보관.
+    const n = a.length, m = b.length;
+    if (n === 0 || m === 0)
+        return 0;
+    let prev = new Uint16Array(m + 1);
+    let curr = new Uint16Array(m + 1);
+    let best = 0;
+    for (let i = 1; i <= n; i++) {
+        for (let j = 1; j <= m; j++) {
+            if (a.charCodeAt(i - 1) === b.charCodeAt(j - 1)) {
+                const v = prev[j - 1] + 1;
+                curr[j] = v;
+                if (v > best)
+                    best = v;
+            }
+            else {
+                curr[j] = 0;
+            }
+        }
+        ;
+        [prev, curr] = [curr, prev];
+        curr.fill(0);
+    }
+    return best;
+}
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+/**
+ * LLM claim 텍스트와 실제 조문 본문/제목을 비교해 일치 여부 판정.
+ * claim 또는 actual이 비어있으면 matched=false.
+ */
+export function matchCitationContent(claim, actual) {
+    const c = normalizeLegalText(claim);
+    const a = normalizeLegalText(actual);
+    if (!c || !a) {
+        return { matched: false, method: 'mismatch', score: 0, normalizedLenClaim: c.length, normalizedLenActual: a.length };
+    }
+    // 과도하게 짧은 claim은 exact만으로 판정 곤란 — jaccard도 low. actual에 포함만 되면 통과.
+    if (c.length < MIN_EXACT_LEN) {
+        if (a.includes(c)) {
+            return { matched: true, method: 'exact', score: 1, normalizedLenClaim: c.length, normalizedLenActual: a.length };
+        }
+    }
+    // L1: 연속 substring
+    const lcs = longestCommonSubstringLen(c, a);
+    if (lcs >= MIN_EXACT_LEN) {
+        return {
+            matched: true,
+            method: 'exact',
+            score: Math.min(1, lcs / Math.max(1, c.length)),
+            normalizedLenClaim: c.length,
+            normalizedLenActual: a.length,
+        };
+    }
+    // L2: token jaccard
+    const tc = new Set(tokenize(c));
+    const ta = new Set(tokenize(a));
+    const jscore = jaccard(tc, ta);
+    if (jscore >= JACCARD_THRESHOLD) {
+        return {
+            matched: true,
+            method: 'token-jaccard',
+            score: jscore,
+            normalizedLenClaim: c.length,
+            normalizedLenActual: a.length,
+        };
+    }
+    return {
+        matched: false,
+        method: 'mismatch',
+        score: Math.max(lcs / Math.max(1, c.length), jscore),
+        normalizedLenClaim: c.length,
+        normalizedLenActual: a.length,
+    };
+}

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

@@ -3,6 +3,7 @@
  * - Exponential backoff for 429, 503, 504
  * - AbortController for timeout
  */
+import { followLawAntibot } from "./law-antibot.js";
 /**
  * URL에서 민감 정보(API 키) 마스킹 — 에러 메시지/로그 노출 방지.
  * 법제처 API는 ?OC=KEY 쿼리 파라미터로 키를 받으므로 해당 값만 *** 처리.
@@ -62,7 +63,7 @@ export async function fetchWithRetry(url, options = {}) {
         if (!headers.has("referer") && isLawGoKrHost(url))
             headers.set("referer", DEFAULT_REFERER);
         try {
-            const response = await fetch(url, {
+            let response = await fetch(url, {
                 ...fetchOptions,
                 headers,
                 signal: controller.signal,
@@ -70,6 +71,16 @@ export async function fetchWithRetry(url, options = {}) {
             clearTimeout(timeoutId);
             // Success or non-retryable error
             if (response.ok || !retryOn.includes(response.status)) {
+                // law.go.kr JS 안티봇 페이지(클라우드 IP에서 location.assign 리다이렉트) 우회.
+                // 로컬/등록 IP에서는 no-op. Fly 등 클라우드 배포에서 UA/Referer로 안 뚫릴 때의 방어층.
+                if (response.ok && isLawGoKrHost(url)) {
+                    try {
+                        const bypassed = await followLawAntibot(response, url, headers, timeout);
+                        if (bypassed)
+                            response = bypassed;
+                    }
+                    catch { /* 우회 실패 시 원본 응답으로 진행 */ }
+                }
                 // 200인데 빈 본문/HTML(법제처 점검·과부하 페이지)이면 일시 장애로 보고 재시도.
                 // 이를 막지 않으면 XML 파서가 "missing root element"로 터진다.
                 if (response.ok && attempt < retries) {

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

@@ -0,0 +1,26 @@
+/**
+ * law.go.kr JS 안티봇 우회 (클라우드 IP 대응)
+ *
+ * 법제처는 클라우드 IP(GCP/AWS/Fly 등)에서 온 요청에 API 데이터 대신
+ * `location.assign(...)` JS 리다이렉트 페이지를 반환할 때가 있다. 이 페이지의
+ * 난독화된 URL을 파싱해 토큰 URL로 재요청하면 우회된다.
+ * (LexLink-ko-mcp client.py의 `_follow_antibot` 접근을 이식)
+ *
+ * 로컬/등록 IP에서는 이 페이지가 오지 않으므로 평상시엔 no-op이다. Fly 등
+ * 클라우드 배포에서 UA/Referer만으로 뚫리지 않는 경우의 방어층.
+ *
+ * 한계: Node fetch(undici)는 쿠키 jar가 없어 "안티봇 홉이 심은 세션 쿠키로
+ * 원본 재시도 성공" 경로는 제한적이다. 주 경로는 토큰 URL 직접 파싱이다.
+ */
+/**
+ * 안티봇 JS의 두 난독화 패턴에서 리다이렉트 경로를 복원한다.
+ *
+ * - 패턴 A(concat): `x={t:'..',h:'..',o:'..'}; return x.t+x.h+x.o`
+ * - 패턴 B(substr): `x={o:'..',c:N},z=M; return o.substr(0,c)+o.substr(c+z)`
+ */
+export declare function parseAntibotUrl(html: string): string | null;
+/**
+ * 응답이 JS 안티봇 페이지면 우회한 새 Response를, 아니면 null(원본 유지)을 반환.
+ * 최대 maxHops까지 location.assign 리다이렉트를 추적한다.
+ */
+export declare function followLawAntibot(response: Response, originalUrl: string, headers: Headers, timeout: number, maxHops?: number): Promise<Response | null>;

package/build/lib/law-antibot.js

@@ -0,0 +1,89 @@
+/**
+ * law.go.kr JS 안티봇 우회 (클라우드 IP 대응)
+ *
+ * 법제처는 클라우드 IP(GCP/AWS/Fly 등)에서 온 요청에 API 데이터 대신
+ * `location.assign(...)` JS 리다이렉트 페이지를 반환할 때가 있다. 이 페이지의
+ * 난독화된 URL을 파싱해 토큰 URL로 재요청하면 우회된다.
+ * (LexLink-ko-mcp client.py의 `_follow_antibot` 접근을 이식)
+ *
+ * 로컬/등록 IP에서는 이 페이지가 오지 않으므로 평상시엔 no-op이다. Fly 등
+ * 클라우드 배포에서 UA/Referer만으로 뚫리지 않는 경우의 방어층.
+ *
+ * 한계: Node fetch(undici)는 쿠키 jar가 없어 "안티봇 홉이 심은 세션 쿠키로
+ * 원본 재시도 성공" 경로는 제한적이다. 주 경로는 토큰 URL 직접 파싱이다.
+ */
+/**
+ * 안티봇 JS의 두 난독화 패턴에서 리다이렉트 경로를 복원한다.
+ *
+ * - 패턴 A(concat): `x={t:'..',h:'..',o:'..'}; return x.t+x.h+x.o`
+ * - 패턴 B(substr): `x={o:'..',c:N},z=M; return o.substr(0,c)+o.substr(c+z)`
+ */
+export function parseAntibotUrl(html) {
+    // 패턴 A: 3분할 concat (t + h + o)
+    const a = html.match(/t:'([^']*)',h:'([^']*)'/);
+    if (a) {
+        const o = html.match(/o:'([^']*)'/);
+        if (o)
+            return a[1] + a[2] + o[1];
+    }
+    // 패턴 B: substring 슬라이싱
+    const b = html.match(/o:'([^']*)',c:(\d+)},z=(\d+)/);
+    if (b) {
+        const o = b[1];
+        const c = Number(b[2]);
+        const z = Number(b[3]);
+        return o.slice(0, c) + o.slice(c + z);
+    }
+    return null;
+}
+/** timeout이 걸린 단발 fetch */
+async function fetchOnce(url, headers, timeout) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        return await fetch(url, { headers, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * 응답이 JS 안티봇 페이지면 우회한 새 Response를, 아니면 null(원본 유지)을 반환.
+ * 최대 maxHops까지 location.assign 리다이렉트를 추적한다.
+ */
+export async function followLawAntibot(response, originalUrl, headers, timeout, maxHops = 3) {
+    let current = response;
+    let hopped = false;
+    for (let hop = 0; hop < maxHops; hop++) {
+        let text;
+        try {
+            text = await current.clone().text();
+        }
+        catch {
+            return hopped ? current : null;
+        }
+        // 안티봇 페이지가 아니면 종료 (첫 홉이면 변경 없음 = null)
+        if (!text.includes("location.assign")) {
+            return hopped ? current : null;
+        }
+        const path = parseAntibotUrl(text);
+        if (!path)
+            return hopped ? current : null;
+        // path는 보통 절대경로(/DRF/...). 원본 URL의 origin에 붙인다.
+        let nextUrl;
+        try {
+            nextUrl = new URL(path, originalUrl).toString();
+        }
+        catch {
+            return hopped ? current : null;
+        }
+        const next = await fetchOnce(nextUrl, headers, timeout);
+        hopped = true;
+        // 토큰 URL이 404면 원본을 한 번 더 시도 (홉이 세션을 세팅했을 수 있음)
+        if (next.status === 404) {
+            return await fetchOnce(originalUrl, headers, timeout);
+        }
+        current = next;
+    }
+    return current;
+}

package/build/tools/verify-citations.js

@@ -21,6 +21,7 @@ import { parseHangNumber } from "../lib/article-parser.js";
 import { truncateResponse } from "../lib/schemas.js";
 import { formatToolError } from "../lib/errors.js";
 import { toArray } from "../lib/xml-parser.js";
+import { matchCitationContent } from "../lib/citation-content-matcher.js";
 export const VerifyCitationsSchema = z.object({
     text: z.string().min(1).describe("검증할 법률 텍스트 (LLM 답변/계약서/판결문 등). 조문 인용이 포함된 문자열"),
     maxCitations: z.number().min(1).max(30).optional().default(15).describe("검증할 최대 인용 개수 (기본 15, 많을수록 느림)"),
@@ -32,6 +33,23 @@ const ARTICLE_REGEX = /제\s*(\d+)\s*조(?:\s*의\s*(\d+))?(?:\s*제\s*(\d+)\s*
 const LAW_NAME_REGEX = /([가-힣][가-힣·ㆍ\s]{0,30}?(?:법률|법|시행령|시행규칙|규칙|규정|조례))$/;
 // 법령명 앞에 붙는 한국어 접속사·부사·수식어 제거 — "또한 상법" → "상법"
 const LAW_NAME_STOPWORDS = /^(또한|그리고|하며|따라서|따라|위해|위하여|의한|의하여|따른|해당|관련|이에|아울러|본|이|저|그|또|및|또는|혹은|한편|더불어|이어|이는|즉|결국|결과적으로|실제로|특히)\s+/u;
+// 인용 바로 뒤 "(제목)"에서 조문 제목 claim 추출 — 내용검증용.
+// 개정이력·날짜·항호 참조 괄호는 조문 제목이 아니므로 제외.
+function extractClaimTitle(after) {
+    const m = after.match(/^\s*\(([^)]{1,40})\)/);
+    if (!m)
+        return undefined;
+    const t = m[1].trim();
+    if (!/[가-힣]/.test(t))
+        return undefined; // 한글 없으면 제목 아님
+    if (/(개정|신설|삭제|전문개정|본조신설)/.test(t))
+        return undefined; // 개정이력 괄호
+    if (/\d{4}\s*\.\s*\d/.test(t))
+        return undefined; // 날짜(2020. 1. …)
+    if (/^제?\s*\d+\s*(항|호|목|조)/.test(t))
+        return undefined; // 항/호/목 참조
+    return t;
+}
 function parseCitations(text, maxCitations) {
     const citations = [];
     const seen = new Set();
@@ -64,6 +82,9 @@ function parseCitations(text, maxCitations) {
         if (seen.has(key))
             continue;
         seen.add(key);
+        // 조문 번호 바로 뒤 "(제목)" 캡처 — 내용검증(matchCitationContent)용
+        const afterIdx = m.index + raw.length;
+        const claimTitle = extractClaimTitle(text.slice(afterIdx, afterIdx + 45));
         citations.push({
             raw: raw.trim(),
             lawName,
@@ -73,6 +94,7 @@ function parseCitations(text, maxCitations) {
             ho: hoStr ? parseInt(hoStr, 10) : undefined,
             joCode,
             displayArticle,
+            claimTitle,
         });
     }
     return citations;
@@ -144,6 +166,14 @@ async function verifyOne(apiClient, cite, apiKey) {
         // 3단계: 항 검증 (명시된 경우)
         const joTitle = found.조문제목 ? `(${found.조문제목})` : "";
         const officialLabel = `${chosen.lawName} ${cite.displayArticle}`;
+        // 내용검증: 인용한 조문 제목이 실제 조문제목과 일치하는지 (lexdiff matchCitationContent 이식).
+        // "존재하는 조문에 엉뚱한 제목 붙인 환각"(예: 제750조(계약해제) ← 실제 불법행위) 탐지.
+        if (cite.claimTitle && found.조문제목) {
+            const cm = matchCitationContent(cite.claimTitle, String(found.조문제목));
+            if (!cm.matched) {
+                return `✗ ${officialLabel} — [CONTENT_MISMATCH] 인용 제목 '${cite.claimTitle}' ≠ 실제 조문제목 '${found.조문제목}' (단순 표기차이 아니면 인용 오류)`;
+            }
+        }
         if (cite.hang) {
             const rawHang = found.항;
             const hangs = toArray(rawHang);
@@ -160,7 +190,7 @@ async function verifyOne(apiClient, cite, apiKey) {
             }
             return `✗ ${officialLabel}${joTitle} — [NOT_FOUND] 제${cite.hang}항 없음 (최대 제${maxHang}항)`;
         }
-        return `✓ ${officialLabel}${joTitle} 실존`;
+        return `✓ ${officialLabel}${joTitle} 실존${cite.claimTitle ? " · 제목 일치" : ""}`;
     }
     catch (e) {
         return `⚠ ${formatCitationLabel(cite, chosen.lawName)} — 조문 조회 실패: ${e instanceof Error ? e.message : String(e)}`;
@@ -192,7 +222,7 @@ export async function verifyCitations(apiClient, input) {
             output += `${line}\n`;
         }
         if (hasHallucination) {
-            output += `\n⚠️ [HALLUCINATION_DETECTED] ${failCount}건 인용이 법제처 DB에 실존하지 않습니다.\n`;
+            output += `\n⚠️ [HALLUCINATION_DETECTED] ${failCount}건 인용이 법제처 DB에 실존하지 않거나 인용 내용(조문 제목)이 실제와 불일치합니다.\n`;
             output += `   LLM이 지어낸 인용일 가능성이 높습니다. 원문을 수정하거나 사용자에게 '인용 오류'를 명시 보고하세요.\n`;
             output += `   절대로 "검증 완료"로 답변하지 마세요.\n`;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "korean-law-mcp",
-  "version": "4.5.2",
+  "version": "4.6.0",
   "description": "법제처 42개 API → 9개 MCP 도구. 법령·판례·조례·조약 + 다단계 리서치(legal_research, 8 task) + 정밀분석(legal_analysis: 인용검증·판례생사·행위시법·영향그래프) + 시점 비교(time_travel) + 상황별 5단계 안내(action_plan) + 국세청 해석례(nts)",
   "type": "module",
   "main": "build/index.js",