korean-law-mcp 2.3.0 → 2.3.2

package/README.md

@@ -14,12 +14,24 @@
 
 ---
 
-## v2.3.0 변경사항
+## v2.3 변경사항
 
-- **도구 프로필 (lite/full)** — 웹 클라이언트(Claude.ai 등)용 lite 프로필 도입. 89개 → 14개로 자동 축소하여 컨텍스트 소비 87% 절감. `/mcp?profile=lite`로 사용.
-  - **체인 8개** + 핵심 직접 도구 4개 + 메타 도구 2개 = 14개로 동일 기능 커버
-  - `discover_tools`: 의도/카테고리로 숨겨진 전문 도구 검색
-  - `execute_tool`: discover로 찾은 도구를 프록시 실행
+**원격 MCP 주소** (`your-key` 부분에 [법제처 Open API](https://open.law.go.kr/LSO/openApi/guideResult.do)에서 발급받은 본인 인증키(OC)를 넣으세요):
+
+| 프로필 | URL | 도구 수 | 용도 |
+|--------|-----|---------|------|
+| lite | `https://korean-law-mcp.fly.dev/mcp?profile=lite&oc=your-key` | 14개 | Claude.ai 등 웹 클라이언트 (컨텍스트 87% 절감) |
+| full | `https://korean-law-mcp.fly.dev/mcp?oc=your-key` | 89개 | Claude Desktop, Cursor 등 네이티브 클라이언트 |
+
+예시: 발급받은 인증키가 `honggildong`이면 → `https://korean-law-mcp.fly.dev/mcp?profile=lite&oc=honggildong`
+
+> lite는 체인 8개 + 핵심 4개 + 메타 2개로 동일 기능 커버. 특수 도구는 `discover_tools` → `execute_tool`로 접근.
+
+- **도구 프로필 (lite/full)** — 89개 → 14개 자동 축소. 체인 도구가 내부에서 하위 도구를 직접 호출하므로 기능 손실 없음.
+- **URL 쿼리 API 키** — `?oc=your-key`로 세션 전체에 API 키 자동 적용. 커스텀 헤더 설정이 어려운 웹 클라이언트에서 필수.
+- **체인 자동 전문 조회** — `chain_ordinance_compare`가 자치법규 검색 후 상위 1건 전문을 자동 조회. 별도 `get_ordinance` 호출 불필요.
+- **lite 도구 라우팅 개선** — 체인/메타 도구 description을 사용자 질문 의도 기반으로 재작성 + 예시 포함. Claude 웹이 "광진구 복무 조례" 같은 자치법규 질문에도 정확한 도구 선택.
+- **도구 힌트 통일** — 비lite 도구 안내를 `execute_tool()` 호출 예시로 변경. 존재하지 않는 도구 직접 호출 문제 방지.
 - **kordoc 통합 파서** — 자체 HWP5/HWPX/PDF 파서 5개를 [kordoc](https://github.com/chrisryugj/kordoc) 통합 파서로 교체. 의존성 경량화.
 
 <details>
@@ -54,81 +66,154 @@
 
 ---
 
-## 빠른 시작
+## 설치 및 사용법
 
-### MCP 서버 (Claude Desktop / Cursor / Windsurf)
+### 0단계: API 키 발급 (무료, 1분)
 
-```bash
-npm install -g korean-law-mcp
+모든 방법에 공통으로 필요한 **법제처 Open API 인증키(OC)**를 먼저 발급받으세요.
+
+1. [법제처 Open API 신청 페이지](https://open.law.go.kr/LSO/openApi/guideList.do)에 접속합니다.
+2. 회원가입 후 로그인합니다.
+3. **"Open API 사용 신청"** 버튼을 누릅니다.
+4. 신청서를 작성하면 **인증키(OC)**가 발급됩니다. (예: `honggildong`)
+5. 이 인증키를 아래 설정에서 사용합니다.
+
+---
+
+### 방법 1: Claude.ai 웹에서 바로 사용 (설치 없음, 가장 쉬움)
+
+아무것도 설치하지 않고, 주소 하나만 입력하면 됩니다. Claude Pro/Max/Team/Enterprise 요금제가 필요합니다 (Free는 커넥터 1개만 가능).
+
+**커넥터 추가 방법:**
+
+1. [claude.ai](https://claude.ai)에 로그인합니다.
+2. 왼쪽 사이드바 하단의 **본인 이름**을 클릭합니다.
+3. **"설정"** (또는 Settings)을 선택합니다.
+4. **"커넥터"** (또는 Connectors) 메뉴로 들어갑니다.
+5. **"커스텀 커넥터"** 영역에서 **"커스텀 커넥터 추가"** 버튼을 클릭합니다.
+6. 아래 내용을 입력합니다:
+   - **이름**: `korean-law` (원하는 이름 아무거나 OK)
+   - **URL**: 아래 주소를 붙여넣으세요. `honggildong` 부분을 **0단계에서 발급받은 본인 인증키**로 바꾸세요:
+
+```
+https://korean-law-mcp.fly.dev/mcp?profile=lite&oc=honggildong
 ```
 
-MCP 클라이언트 설정에 추가:
+7. **추가** 버튼을 누르면 등록 완료!
+
+**도구 활성화 (중요!):**
+
+8. 추가한 커넥터의 **"구성"** (또는 Configure)을 클릭합니다.
+9. 도구 목록이 나오면, 모든 도구를 **"항상 사용"** (또는 Always allow)으로 설정합니다.
+10. 이렇게 하면 매번 승인할 필요 없이 AI가 바로 법령을 검색할 수 있습니다.
+
+**사용하기:**
+
+11. 채팅 화면으로 돌아가서 "근로기준법 제74조 알려줘"라고 입력하면 끝!
+
+> **참고**: 커넥터 URL을 수정하려면 삭제 후 다시 추가해야 합니다.
+
+> **lite vs full 차이**: 위 주소는 lite 모드(14개 도구)입니다. 14개로도 89개 전체 기능을 사용할 수 있어요 — AI가 필요할 때 나머지 도구를 알아서 꺼내 씁니다. 모든 도구를 직접 보고 싶으면 주소에서 `profile=lite&`를 빼면 됩니다.
+
+---
+
+### 방법 2: AI 데스크톱 앱에서 사용 (설치 없음)
+
+Claude Desktop, Cursor, Windsurf 같은 **데스크톱 앱**을 쓰고 있다면, 설정 파일에 아래 내용을 추가하세요.
+
+**설정 파일 위치 찾기:**
+
+| 앱 이름 | Windows | Mac |
+|---------|---------|-----|
+| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Cursor | 프로젝트 폴더 안 `.cursor/mcp.json` | 프로젝트 폴더 안 `.cursor/mcp.json` |
+| Windsurf | 프로젝트 폴더 안 `.windsurf/mcp.json` | 프로젝트 폴더 안 `.windsurf/mcp.json` |
+
+**설정 파일에 추가할 내용** (`honggildong`을 본인 인증키로 바꾸세요):
 
 ```json
 {
   "mcpServers": {
     "korean-law": {
-      "command": "korean-law-mcp",
-      "env": {
-        "LAW_OC": "your-api-key"
-      }
+      "url": "https://korean-law-mcp.fly.dev/mcp?oc=honggildong"
     }
   }
 }
 ```
 
-API 키는 [법제처 Open API](https://open.law.go.kr/LSO/openApi/guideResult.do)에서 무료 발급.
+> 이미 다른 MCP 서버가 설정되어 있다면, `"mcpServers": { ... }` 안에 `"korean-law": { ... }` 부분만 추가하면 됩니다.
 
-| 클라이언트 | 설정 파일 |
-|-----------|----------|
-| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` (Win) / `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) |
-| Cursor | `.cursor/mcp.json` |
-| Windsurf | `.windsurf/mcp.json` |
-| Continue | `~/.continue/config.json` |
-| Zed | `~/.config/zed/settings.json` |
+저장 후 앱을 **재시작**하면 법령 도구가 활성화됩니다.
 
-### 원격 MCP (설치 없이 바로)
+---
 
-```json
-{
-  "mcpServers": {
-    "korean-law": {
-      "url": "https://korean-law-mcp.fly.dev/mcp"
-    }
-  }
-}
+### 방법 3: 내 컴퓨터에 직접 설치 (오프라인 가능)
+
+인터넷 없이 쓰고 싶거나, 원격 서버를 거치지 않으려면 직접 설치할 수 있습니다.
+
+**사전 준비:** [Node.js](https://nodejs.org) 18 이상이 설치되어 있어야 합니다.
+
+**1. 터미널(명령 프롬프트)을 열고 설치합니다:**
+
+```bash
+npm install -g korean-law-mcp
 ```
 
-**Claude.ai 등 웹 클라이언트** — 컨텍스트 절약을 위해 lite 프로필 권장:
+**2. AI 앱 설정 파일에 아래 내용을 추가합니다** (`honggildong`을 본인 인증키로 바꾸세요):
 
 ```json
 {
   "mcpServers": {
     "korean-law": {
-      "url": "https://korean-law-mcp.fly.dev/mcp?profile=lite"
+      "command": "korean-law-mcp",
+      "env": {
+        "LAW_OC": "honggildong"
+      }
     }
   }
 }
 ```
 
-> lite 프로필은 체인 8개 + 핵심 4개 + 메타 2개 = **14개 도구**로 동일 기능 커버. 특수 도구가 필요하면 `discover_tools` → `execute_tool`로 접근.
+**3. 앱을 재시작하면 완료!**
+
+---
+
+### 방법 4: 터미널(CLI)에서 직접 사용
 
-### CLI
+개발자라면 터미널에서 직접 법령을 검색할 수 있습니다.
 
 ```bash
+# 설치
 npm install -g korean-law-mcp
-export LAW_OC=your-api-key
-
-korean-law search_law --query "관세법"
-korean-law get_law_text --mst 160001 --jo "제38조"
-korean-law search_precedents --query "부당해고"
-korean-law list                          # 89개 전체 도구 목록
-korean-law list --category 판례          # 카테고리별 필터
-korean-law help search_law               # 도구 도움말
+
+# 인증키 설정 (honggildong을 본인 키로 바꾸세요)
+export LAW_OC=honggildong        # Mac/Linux
+set LAW_OC=honggildong           # Windows CMD
+$env:LAW_OC="honggildong"       # Windows PowerShell
+
+# 사용 예시
+korean-law "민법 제1조"                    # 자연어로 바로 조회
+korean-law search_law --query "관세법"     # 도구 직접 호출
+korean-law list                            # 89개 전체 도구 목록
+korean-law list --category 판례            # 카테고리별 필터
+korean-law help search_law                 # 도구별 도움말
 ```
 
 ---
 
+### API 키 전달 방법 정리
+
+여러 방법으로 인증키를 전달할 수 있습니다. 위에서부터 우선 적용됩니다:
+
+| 방법 | 사용법 | 언제 쓰나 |
+|------|--------|-----------|
+| URL에 포함 | 주소 끝에 `?oc=내키` | 웹 클라이언트에서 가장 간편 |
+| HTTP 헤더 | `apikey: 내키` | 프로그래밍으로 연동할 때 |
+| 환경변수 | `LAW_OC=내키` | 로컬 설치(방법 3, 4) |
+| 도구 파라미터 | `apiKey: "내키"` | 특정 요청만 다른 키 쓸 때 |
+
+---
+
 ## 사용 예시
 
 ```

package/build/lib/api-client.js

@@ -81,28 +81,9 @@ export class LawApiClient {
         const response = await fetchWithRetry(url);
         this.throwIfError(response, "getLawText");
         const text = await response.text();
-        if (text.includes("<!DOCTYPE html") || text.includes("<html")) {
-            let errorMsg = "법령을 찾을 수 없습니다.";
-            if (params.jo) {
-                errorMsg += "\n\n💡 개선 방법:";
-                errorMsg += "\n   1. 전체 법령 조회 (조문 범위 확인):";
-                if (params.mst) {
-                    errorMsg += `\n      get_law_text(mst="${params.mst}")`;
-                }
-                else if (params.lawId) {
-                    errorMsg += `\n      get_law_text(lawId="${params.lawId}")`;
-                }
-                errorMsg += "\n\n   2. 키워드 검색:";
-                errorMsg += `\n      search_all(query="관련 키워드")`;
-                errorMsg += "\n\n   3. 법령 검색:";
-                errorMsg += `\n      search_law(query="법령명")`;
-                errorMsg += "\n\n   ℹ️  일부 법령은 조문 수가 적습니다 (예: 약사법 시행령 제1~39조)";
-            }
-            else {
-                errorMsg += " MST 또는 법령명을 확인해주세요.";
-            }
-            throw new Error(errorMsg);
-        }
+        this.checkHtmlError(text, params.jo
+            ? `법령 조문(${params.jo})을 찾을 수 없습니다. MST/lawId와 조문번호를 확인해주세요.`
+            : "법령을 찾을 수 없습니다. MST 또는 법령명을 확인해주세요.");
         return text;
     }
     /**

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

@@ -5,5 +5,20 @@
 export declare function flattenContent(value: any): string;
 /** 항 배열에서 내용 추출 (재귀적으로 호/목 처리) */
 export declare function extractHangContent(hangInput: any[] | any): string;
+/**
+ * 조문단위 객체를 텍스트로 포맷팅 (law-text, batch-articles, article-detail 공통)
+ * 조문 헤더(제X조 제목) + 본문 + 항/호/목을 결합하여 반환
+ */
+export declare function formatArticleUnit(unit: {
+    조문여부?: string;
+    조문번호?: string;
+    조문가지번호?: string;
+    조문제목?: string;
+    조문내용?: unknown;
+    항?: unknown;
+}): {
+    header: string;
+    body: string;
+} | null;
 /** HTML 정리 - 엔티티 디코딩 순서 중요: & 최후 처리 (이중 인코딩 방지) */
 export declare function cleanHtml(text: string): string;

package/build/lib/article-parser.js

@@ -61,6 +61,57 @@ export function extractHangContent(hangInput) {
     }
     return content;
 }
+/**
+ * 조문단위 객체를 텍스트로 포맷팅 (law-text, batch-articles, article-detail 공통)
+ * 조문 헤더(제X조 제목) + 본문 + 항/호/목을 결합하여 반환
+ */
+export function formatArticleUnit(unit) {
+    if (unit.조문여부 !== "조문")
+        return null;
+    const joNum = unit.조문번호 || "";
+    const joBranch = unit.조문가지번호 || "";
+    const joTitle = unit.조문제목 || "";
+    // 헤더
+    let header = "";
+    if (joNum) {
+        const displayNum = joBranch && joBranch !== "0" ? `제${joNum}조의${joBranch}` : `제${joNum}조`;
+        header = joTitle ? `${displayNum} ${joTitle}` : displayNum;
+    }
+    // 본문: 조문내용에서 헤더 패턴 제거
+    let mainContent = "";
+    if (unit.조문내용) {
+        const contentStr = flattenContent(unit.조문내용);
+        if (contentStr) {
+            const headerMatch = contentStr.match(/^(제\d+조(?:의\d+)?\s*(?:\([^)]+\))?)[\s\S]*/);
+            if (headerMatch) {
+                const bodyPart = contentStr.substring(headerMatch[1].length).trim();
+                mainContent = bodyPart || contentStr;
+            }
+            else {
+                mainContent = contentStr;
+            }
+        }
+    }
+    // 항/호/목
+    let paraContent = "";
+    if (unit.항) {
+        paraContent = extractHangContent(unit.항);
+    }
+    // 결합
+    let body = "";
+    if (mainContent) {
+        body = mainContent;
+        if (paraContent)
+            body += "\n" + paraContent;
+    }
+    else {
+        body = paraContent;
+    }
+    // HTML 정리
+    if (body)
+        body = cleanHtml(body);
+    return { header, body };
+}
 /** HTML 정리 - 엔티티 디코딩 순서 중요: & 최후 처리 (이중 인코딩 방지) */
 export function cleanHtml(text) {
     return text

package/build/lib/errors.d.ts

@@ -21,9 +21,6 @@ export declare class LawApiError extends Error {
     code: ErrorCode;
     suggestions: string[];
     constructor(message: string, code: ErrorCode, suggestions?: string[]);
-    /**
-     * 사용자 친화적 포맷
-     */
     format(): string;
 }
 /**
@@ -35,15 +32,3 @@ export declare class LawApiError extends Error {
  *   💡 제안: ...
  */
 export declare function formatToolError(error: unknown, context?: string): ToolResponse;
-/**
- * 법령 없음 에러
- */
-export declare function notFoundError(lawName: string, suggestions?: string[]): LawApiError;
-/**
- * API 에러
- */
-export declare function apiError(status: number, endpoint?: string): LawApiError;
-/**
- * 파라미터 검증 에러
- */
-export declare function invalidParamError(param: string, expected: string): LawApiError;

package/build/lib/errors.js

@@ -22,15 +22,12 @@ export class LawApiError extends Error {
         this.code = code;
         this.suggestions = suggestions;
     }
-    /**
-     * 사용자 친화적 포맷
-     */
     format() {
-        let result = `❌ ${this.message}`;
+        let result = `[ERROR] ${this.message}`;
         if (this.suggestions.length > 0) {
-            result += "\n\n💡 개선 방법:";
+            result += "\n제안:";
             this.suggestions.forEach((s, i) => {
-                result += `\n   ${i + 1}. ${s}`;
+                result += `\n  ${i + 1}. ${s}`;
             });
         }
         return result;
@@ -73,49 +70,19 @@ export function formatToolError(error, context) {
         msg = String(error);
         suggestions = [];
     }
-    // 구조화된 텍스트 조립
     const lines = [];
-    lines.push(`❌ [${code}] ${msg}`);
+    lines.push(`[${code}] ${msg}`);
     if (context) {
-        lines.push(`🔧 도구: ${context}`);
+        lines.push(`도구: ${context}`);
     }
     if (suggestions.length > 0) {
-        lines.push("💡 제안:");
+        lines.push("제안:");
         suggestions.forEach((s, i) => {
-            lines.push(`   ${i + 1}. ${s}`);
+            lines.push(`  ${i + 1}. ${s}`);
         });
     }
-    else {
-        lines.push("💡 제안: (없음)");
-    }
     return {
         content: [{ type: "text", text: lines.join("\n") }],
         isError: true,
     };
 }
-/**
- * 법령 없음 에러
- */
-export function notFoundError(lawName, suggestions) {
-    return new LawApiError(`'${lawName}'을(를) 찾을 수 없습니다.`, ErrorCodes.NOT_FOUND, suggestions || [
-        `search_law(query="${lawName}")로 법령 검색`,
-        "법령명 철자 확인",
-    ]);
-}
-/**
- * API 에러
- */
-export function apiError(status, endpoint) {
-    const suggestions = status === 429
-        ? ["잠시 후 다시 시도", "요청 빈도 줄이기"]
-        : status >= 500
-            ? ["법제처 API 상태 확인", "잠시 후 다시 시도"]
-            : ["요청 파라미터 확인"];
-    return new LawApiError(`API 오류 (${status})${endpoint ? ` - ${endpoint}` : ""}`, status === 429 ? ErrorCodes.RATE_LIMITED : ErrorCodes.API_ERROR, suggestions);
-}
-/**
- * 파라미터 검증 에러
- */
-export function invalidParamError(param, expected) {
-    return new LawApiError(`잘못된 파라미터: ${param}`, ErrorCodes.INVALID_PARAM, [`${param}는 ${expected} 형식이어야 합니다.`]);
-}

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

@@ -28,8 +28,7 @@ export async function fetchWithRetry(url, options = {}) {
             }
             // Retryable error - check if we have retries left
             if (attempt < retries) {
-                const baseDelay = retryDelay * Math.pow(2, attempt);
-                const delay = baseDelay + Math.random() * baseDelay * 0.5;
+                const delay = getRetryDelay(response, retryDelay, attempt);
                 await sleep(delay);
                 continue;
             }
@@ -49,8 +48,7 @@ export async function fetchWithRetry(url, options = {}) {
             }
             // Retry on network errors
             if (attempt < retries) {
-                const baseDelay = retryDelay * Math.pow(2, attempt);
-                const delay = baseDelay + Math.random() * baseDelay * 0.5;
+                const delay = getRetryDelay(null, retryDelay, attempt);
                 await sleep(delay);
                 continue;
             }
@@ -58,6 +56,20 @@ export async function fetchWithRetry(url, options = {}) {
     }
     throw lastError || new Error("Request failed after retries");
 }
+/** Retry-After 헤더 우선, 없으면 exponential backoff + jitter */
+function getRetryDelay(response, retryDelay, attempt) {
+    if (response) {
+        const retryAfter = response.headers.get("Retry-After");
+        if (retryAfter) {
+            const seconds = Number(retryAfter);
+            if (!isNaN(seconds) && seconds > 0) {
+                return seconds * 1000;
+            }
+        }
+    }
+    const baseDelay = retryDelay * Math.pow(2, attempt);
+    return baseDelay + Math.random() * baseDelay * 0.5;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/build/lib/schemas.d.ts

@@ -10,10 +10,6 @@ export declare const dateSchema: z.ZodString;
  * 선택적 날짜 스키마
  */
 export declare const optionalDateSchema: z.ZodOptional<z.ZodString>;
-/**
- * API 키 스키마
- */
-export declare const apiKeySchema: z.ZodOptional<z.ZodString>;
 /**
  * 페이지네이션 스키마
  */
@@ -21,10 +17,6 @@ export declare const paginationSchema: z.ZodObject<{
     display: z.ZodDefault<z.ZodNumber>;
     page: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
-/**
- * 날짜 포맷터 (YYYYMMDD → "2024년 1월 1일")
- */
-export declare function formatDateKorean(dateStr: string | undefined | null): string;
 /**
  * 응답 크기 제한 (50KB)
  */

package/build/lib/schemas.js

@@ -30,10 +30,6 @@ export const dateSchema = z
  * 선택적 날짜 스키마
  */
 export const optionalDateSchema = dateSchema.optional();
-/**
- * API 키 스키마
- */
-export const apiKeySchema = z.string().optional().describe("API 키 (생략시 환경변수 사용)");
 /**
  * 페이지네이션 스키마
  */
@@ -41,17 +37,6 @@ export const paginationSchema = z.object({
     display: z.number().min(1).max(100).default(20).describe("결과 수 (기본:20, 최대:100)"),
     page: z.number().min(1).default(1).describe("페이지 번호 (기본:1)"),
 });
-/**
- * 날짜 포맷터 (YYYYMMDD → "2024년 1월 1일")
- */
-export function formatDateKorean(dateStr) {
-    if (!dateStr || dateStr.length < 8)
-        return dateStr || "N/A";
-    const y = dateStr.substring(0, 4);
-    const m = parseInt(dateStr.substring(4, 6), 10);
-    const d = parseInt(dateStr.substring(6, 8), 10);
-    return `${y}년 ${m}월 ${d}일`;
-}
 /**
  * 응답 크기 제한 (50KB)
  */