search_legal_terms

Instructions

Implementation Reference

• src/tools/legal-terms.ts:17-99 (handler)

  The main handler function `searchLegalTerms` that executes the tool logic. It calls the LawApiClient to search legal terminology (법령용어), parses XML results, and formats the output. Uses `parseSearchXML` with rootTag 'LsTrmSearch' and itemTag 'lstrm'. Handles empty results with suggestions and errors via `formatToolError`.

  export async function searchLegalTerms(
    apiClient: LawApiClient,
    args: SearchLegalTermsInput
  ): Promise<{ content: Array<{ type: string, text: string }>, isError?: boolean }> {
    try {
      const xmlText = await apiClient.fetchApi({
        endpoint: "lawSearch.do",
        target: "lstrm",
        extraParams: {
          query: args.query,
          display: (args.display || 20).toString(),
          page: (args.page || 1).toString(),
        },
        apiKey: args.apiKey,
      });
      // parseSearchXML 사용 (rootTag: LsTrmSearch, itemTag: lstrm)
      const { totalCnt, page: currentPage, items: terms } = parseSearchXML(
        xmlText, "LsTrmSearch", "lstrm",
        (content) => ({
          용어명: extractTag(content, "법령용어명") || extractTag(content, "용어명") || extractTag(content, "용어"),
          용어ID: extractTag(content, "법령용어ID"),
          용어정의: extractTag(content, "용어정의") || extractTag(content, "정의"),
          관련법령: extractTag(content, "관련법령") || extractTag(content, "법령명"),
          일상용어: extractTag(content, "일상용어"),
          영문용어: extractTag(content, "영문용어") || extractTag(content, "영문"),
          상세링크: extractTag(content, "법령용어상세링크") || extractTag(content, "법령용어상세검색"),
        }),
        { useIndexOf: true }
      );
  
      const totalCount = totalCnt;
  
      if (totalCount === 0) {
        let errorMsg = "검색 결과가 없습니다.";
        errorMsg += `\n\n💡 개선 방법:`;
        errorMsg += `\n   1. 단순 용어로 검색:`;
        errorMsg += `\n      search_legal_terms(query="채권")`;
        errorMsg += `\n\n   2. 유사 용어 시도:`;
        errorMsg += `\n      - "선의" / "악의" (법률상 의미)`;
        errorMsg += `\n      - "하자" / "담보" / "보증"`;
        errorMsg += `\n\n   3. 법령 검색으로 용어 사용례 확인:`;
        errorMsg += `\n      search_law(query="${args.query}")`;
  
        return {
          content: [{
            type: "text",
            text: errorMsg
          }],
          isError: true
        };
      }
  
      let output = `법령용어 검색 결과 (총 ${totalCount}건, ${currentPage}페이지):\n\n`;
  
      for (const term of terms) {
        output += `📌 ${term.용어명}\n`;
        if (term.용어정의) {
          output += `   정의: ${term.용어정의}\n`;
        }
        if (term.관련법령) {
          output += `   관련법령: ${term.관련법령}\n`;
        }
        if (term.일상용어) {
          output += `   일상용어: ${term.일상용어}\n`;
        }
        if (term.영문용어) {
          output += `   영문: ${term.영문용어}\n`;
        }
        output += `\n`;
      }
  
      output += `\n💡 법령에서 용어 사용례를 확인하려면 search_law(query="용어명")을 사용하세요.`;
  
      return {
        content: [{
          type: "text",
          text: truncateResponse(output)
        }]
      };
    } catch (error) {
      return formatToolError(error, "search_legal_terms");
    }
  }

• src/tools/legal-terms.ts:8-13 (schema)

  Zod schema `searchLegalTermsSchema` defining input validation: query (string), display (number 1-100, default 20), page (number >=1, default 1), apiKey (optional string).

  export const searchLegalTermsSchema = z.object({
    query: z.string().describe("검색할 법령용어 (예: '선의', '악의', '하자', '채권')"),
    display: z.number().min(1).max(100).default(20).describe("페이지당 결과 개수 (기본값: 20, 최대: 100)"),
    page: z.number().min(1).default(1).describe("페이지 번호 (기본값: 1)"),
    apiKey: z.string().optional().describe("법제처 Open API 인증키(OC). 사용자가 제공한 경우 전달"),
  });

• src/tool-registry.ts:518-522 (registration)

  Tool registration entry mapping the name 'search_legal_terms' to the schema and handler, with description '[용어사전] 법령용어 정의·해설 검색.'

  {
    name: "search_legal_terms",
    description: "[용어사전] 법령용어 정의·해설 검색.",
    schema: searchLegalTermsSchema,
    handler: searchLegalTerms

• src/tool-registry.ts:47-47 (registration)

  Import of `searchLegalTerms` and `searchLegalTermsSchema` from './tools/legal-terms.js' in the registry.

  import { searchLegalTerms, searchLegalTermsSchema } from "./tools/legal-terms.js"

• src/lib/query-router.ts:392-403 (helper)

  Query router entry that routes natural language queries (e.g., '법률용어', '법령용어', '용어정의', '뜻') to the 'search_legal_terms' tool with a pattern-based extract function.

  {
    name: "legal_terms",
    patterns: [
      /법률?\s*용어|법령\s*용어|용어\s*정의|용어\s*뜻|뭐야$|뜻이?$/,
    ],
    tool: "search_legal_terms",
    extract: (query) => ({
      query: query.replace(/법률?용어|법령용어|용어정의|뜻이?|뭐야|의$/g, "").replace(/\s+/g, " ").trim(),
    }),
    reason: "용어 키워드 → 법령용어 검색",
    priority: 10,
  },