korean-law-mcp 2.3.0 → 2.3.1

package/README.md

@@ -14,7 +14,15 @@
 
 ---
 
-## v2.3.0 변경사항
+## v2.3.1 변경사항
+
+- **URL 쿼리 API 키 지원** — 원격 MCP 접속 시 `?oc=your-key`로 API 키를 URL에 포함 가능. 매 요청마다 키를 전달할 필요 없이 세션 전체에 자동 적용. Claude.ai 등 커스텀 헤더 설정이 어려운 웹 클라이언트에서 유용.
+- **체인 도구 자동 전문 조회** — `chain_ordinance_compare`가 자치법규 검색 후 상위 1건 전문을 자동 조회하여 반환. 별도로 `get_ordinance`를 호출할 필요 없음.
+- **lite 프로필 도구 라우팅 개선** — 체인/메타 도구 description을 INPUT 의도 기반으로 재작성. 예시 포함으로 Claude 웹이 자치법규 검색·조회 등 올바른 도구를 선택하도록 개선.
+- **도구 힌트 execute_tool 경로 통일** — 비lite 도구 안내를 `execute_tool()` 호출 예시로 변경. Claude 웹이 존재하지 않는 도구를 직접 호출하는 문제 방지.
+
+<details>
+<summary>v2.3.0 변경사항</summary>
 
 - **도구 프로필 (lite/full)** — 웹 클라이언트(Claude.ai 등)용 lite 프로필 도입. 89개 → 14개로 자동 축소하여 컨텍스트 소비 87% 절감. `/mcp?profile=lite`로 사용.
   - **체인 8개** + 핵심 직접 도구 4개 + 메타 도구 2개 = 14개로 동일 기능 커버
@@ -22,6 +30,8 @@
   - `execute_tool`: discover로 찾은 도구를 프록시 실행
 - **kordoc 통합 파서** — 자체 HWP5/HWPX/PDF 파서 5개를 [kordoc](https://github.com/chrisryugj/kordoc) 통합 파서로 교체. 의존성 경량화.
 
+</details>
+
 <details>
 <summary>v2.2.0 변경사항</summary>
 
@@ -89,11 +99,13 @@ API 키는 [법제처 Open API](https://open.law.go.kr/LSO/openApi/guideResult.d
 
 ### 원격 MCP (설치 없이 바로)
 
+API 키를 URL에 포함하여 바로 사용:
+
 ```json
 {
   "mcpServers": {
     "korean-law": {
-      "url": "https://korean-law-mcp.fly.dev/mcp"
+      "url": "https://korean-law-mcp.fly.dev/mcp?oc=your-api-key"
     }
   }
 }
@@ -101,18 +113,22 @@ API 키는 [법제처 Open API](https://open.law.go.kr/LSO/openApi/guideResult.d
 
 **Claude.ai 등 웹 클라이언트** — 컨텍스트 절약을 위해 lite 프로필 권장:
 
-```json
-{
-  "mcpServers": {
-    "korean-law": {
-      "url": "https://korean-law-mcp.fly.dev/mcp?profile=lite"
-    }
-  }
-}
+```
+https://korean-law-mcp.fly.dev/mcp?profile=lite&oc=your-api-key
 ```
 
 > lite 프로필은 체인 8개 + 핵심 4개 + 메타 2개 = **14개 도구**로 동일 기능 커버. 특수 도구가 필요하면 `discover_tools` → `execute_tool`로 접근.
 
+**API 키 전달 방법** (우선순위순):
+
+| 방법 | 예시 | 설명 |
+|------|------|------|
+| URL 쿼리 | `?oc=your-key` | 웹 클라이언트에서 가장 간편. 세션 전체에 자동 적용 |
+| HTTP 헤더 | `apikey: your-key` | `law-oc`, `x-api-key`, `Authorization: Bearer` 등도 지원 |
+| 도구 파라미터 | `apiKey: "your-key"` | 개별 도구 호출 시 직접 전달 |
+
+> API 키는 [법제처 Open API](https://open.law.go.kr/LSO/openApi/guideResult.do)에서 무료 발급.
+
 ### CLI
 
 ```bash

package/build/server/http-server.js

@@ -101,8 +101,10 @@ export async function startHTTPServer(createServer, port) {
     // POST /mcp - 클라이언트 요청 처리
     app.post("/mcp", async (req, res) => {
         console.error(`[POST /mcp] Received request`);
-        // Extract API key from various possible header locations
-        const apiKeyFromHeader = req.headers["apikey"] ||
+        // Extract API key: URL query > header > 기존 세션
+        const apiKeyFromQuery = req.query.oc;
+        const apiKeyFromHeader = apiKeyFromQuery ||
+            req.headers["apikey"] ||
             req.headers["law_oc"] ||
             req.headers["law-oc"] ||
             req.headers["LAW_OC"] ||

package/build/tool-registry.js

@@ -670,6 +670,9 @@ export function registerTools(server, apiClient, profile = "full") {
             };
         }
         catch (error) {
+            console.error(`[CallTool] Error in ${name}:`, error instanceof Error ? error.message : error);
+            if (error instanceof Error && error.stack)
+                console.error(error.stack);
             const errResult = formatToolError(error, name);
             return {
                 content: errResult.content.map(c => ({ type: "text", text: c.text })),

package/build/tools/admin-rule.js

@@ -59,7 +59,7 @@ export async function searchAdminRule(apiClient, input) {
             resultText += `   - 구분: ${ruleType}\n`;
             resultText += `   - 소관부처: ${orgName}\n\n`;
         }
-        resultText += `\n💡 상세 내용을 조회하려면 get_admin_rule Tool을 사용하세요.`;
+        resultText += `\n💡 상세 조회: execute_tool(tool_name="get_admin_rule", params={adminRuleSeq:"일련번호"})`;
         return {
             content: [{
                     type: "text",

package/build/tools/chains.js

@@ -16,6 +16,7 @@ import { searchAdminAppeals } from "./admin-appeals.js";
 import { compareOldNew } from "./comparison.js";
 import { getArticleHistory } from "./article-history.js";
 import { searchOrdinance } from "./ordinance-search.js";
+import { getOrdinance } from "./ordinance.js";
 import { getAnnexes } from "./annex.js";
 import { searchAiLaw } from "./life-law.js";
 import { getLawText } from "./law-text.js";
@@ -382,6 +383,15 @@ export async function chainOrdinanceCompare(apiClient, input) {
         const ordinances = await callTool(searchOrdinance, apiClient, { query: ordinanceQuery, display: 20, apiKey: input.apiKey });
         if (!ordinances.isError)
             parts.push(sec("전국 자치법규 검색 결과", ordinances.text));
+        // Step 3: 상위 1건 전문 자동 조회
+        if (!ordinances.isError) {
+            const seqMatch = ordinances.text.match(/\[(\d+)\]/);
+            if (seqMatch) {
+                const fullText = await callTool(getOrdinance, apiClient, { ordinSeq: seqMatch[1], apiKey: input.apiKey });
+                if (!fullText.isError)
+                    parts.push(sec("조례 전문 (상위 1건)", fullText.text));
+            }
+        }
         // 키워드 확장
         const exp = detectExpansions(input.query);
         if (exp.includes("interpretation")) {

package/build/tools/customs-interpretations.js

@@ -70,7 +70,7 @@ export async function searchCustomsInterpretations(apiClient, args) {
             }
             output += `\n`;
         }
-        output += `\n💡 전문을 조회하려면 get_customs_interpretation_text Tool을 사용하세요.\n`;
+        output += `\n💡 전문 조회: execute_tool(tool_name="get_customs_interpretation_text", params={id:"해석례ID"})\n`;
         return {
             content: [{
                     type: "text",

package/build/tools/interpretations.js

@@ -80,7 +80,7 @@ export async function searchInterpretations(apiClient, args) {
             }
             output += `\n`;
         }
-        output += `\n💡 전문을 조회하려면 get_interpretation_text Tool을 사용하세요.\n`;
+        output += `\n💡 전문 조회: execute_tool(tool_name="get_interpretation_text", params={id:"해석례ID"})\n`;
         return {
             content: [{
                     type: "text",

package/build/tools/law-tree.js

@@ -89,7 +89,7 @@ export async function getLawTree(apiClient, input) {
                 output += `   └─ ... 외 ${structure.rule.length - 5}개 조항\n`;
             }
         }
-        output += `\n\n💡 상세한 위임 관계는 get_three_tier Tool을 사용하세요.`;
+        output += `\n\n💡 위임관계: chain_law_system(query="법령명") 또는 execute_tool(tool_name="get_three_tier", params={mst:"법령MST"})`;
         return {
             content: [{
                     type: "text",

package/build/tools/ordinance-search.js

@@ -79,7 +79,7 @@ export async function searchOrdinance(apiClient, input) {
             }
             output += `\n`;
         }
-        output += `\n💡 전문을 조회하려면 get_ordinance Tool을 사용하세요.\n`;
+        output += `\n💡 전문 조회: execute_tool(tool_name="get_ordinance", params={ordinSeq:"일련번호"})\n`;
         return {
             content: [{
                     type: "text",

package/build/tools/ordinance.js

@@ -77,7 +77,7 @@ export async function getOrdinance(apiClient, input) {
             parentLawHints.forEach(h => { resultText += `   - ${h}\n`; });
         }
         else {
-            resultText += `\n💡 상위법령 확인: search_law 또는 get_related_laws 도구를 사용하세요.`;
+            resultText += `\n💡 상위법령 확인: search_law(query="법령명") 또는 execute_tool(tool_name="get_related_laws", params={query:"키워드"})`;
         }
         return {
             content: [{

package/build/tools/tax-tribunal-decisions.js

@@ -65,7 +65,7 @@ export async function searchTaxTribunalDecisions(apiClient, args) {
             }
             output += `\n`;
         }
-        output += `\n💡 전문을 조회하려면 get_tax_tribunal_decision_text Tool을 사용하세요.\n`;
+        output += `\n💡 전문 조회: execute_tool(tool_name="get_tax_tribunal_decision_text", params={id:"사건ID"})\n`;
         return {
             content: [{
                     type: "text",

package/build/tools/treaties.js

@@ -60,7 +60,7 @@ export async function searchTreaties(apiClient, args) {
             }
             output += `\n`;
         }
-        output += `\n전문을 조회하려면 get_treaty_text Tool을 사용하세요.\n`;
+        output += `\n전문 조회: execute_tool(tool_name="get_treaty_text", params={treatySeq:"조약번호"})\n`;
         return { content: [{ type: "text", text: truncateResponse(output) }] };
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "korean-law-mcp",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "국가법령정보센터 API 기반 MCP 서버 - 한국 법령 조회·비교 도구",
   "type": "module",
   "main": "build/index.js",