search_admin_appeals

Instructions

Implementation Reference

• src/tools/admin-appeals.ts:19-91 (handler)

  Main handler function for the search_admin_appeals tool. Calls the LawApiClient to search administrative appeal decisions, parses the XML response, formats results, and handles errors.

  export async function searchAdminAppeals(
    apiClient: LawApiClient,
    args: SearchAdminAppealsInput
  ): Promise<{ content: Array<{ type: string, text: string }>, isError?: boolean }> {
    try {
      const extraParams: Record<string, string> = {
        display: (args.display || 20).toString(),
        page: (args.page || 1).toString(),
      };
      if (args.query) extraParams.query = args.query;
      if (args.sort) extraParams.sort = args.sort;
  
      const xmlText = await apiClient.fetchApi({
        endpoint: "lawSearch.do",
        target: "decc",
        extraParams,
        apiKey: args.apiKey,
      });
  
      // 공통 파서 사용
      const result = parseAdminAppealXMLShared(xmlText);
      const totalCount = result.totalCnt;
      const currentPage = result.page;
      const appeals = result.items;
  
      if (totalCount === 0) {
        let errorMsg = "검색 결과가 없습니다.";
        errorMsg += `\n\n💡 개선 방법:`;
        errorMsg += `\n   1. 단순 키워드 사용:`;
        if (args.query) {
          const words = args.query.split(/\s+/);
          if (words.length > 1) {
            errorMsg += `\n      search_admin_appeals(query="${words[0]}")`;
          }
        }
        errorMsg += `\n\n   2. 일반 판례 검색:`;
        errorMsg += `\n      search_precedents(query="${args.query || '관련 키워드'}")`;
  
        return {
          content: [{
            type: "text",
            text: errorMsg
          }],
          isError: true
        };
      }
  
      let output = `행정심판례 검색 결과 (총 ${totalCount}건, ${currentPage}페이지):\n\n`;
  
      for (const appeal of appeals) {
        output += `[${appeal.행정심판재결례일련번호}] ${appeal.사건명}\n`;
        output += `  사건번호: ${appeal.사건번호 || "N/A"}\n`;
        output += `  의결일: ${appeal.의결일자 || "N/A"}\n`;
        output += `  재결청: ${appeal.재결청 || "N/A"}\n`;
        output += `  재결구분: ${appeal.재결구분명 || "N/A"}\n`;
        if (appeal.행정심판례상세링크) {
          output += `  링크: ${appeal.행정심판례상세링크}\n`;
        }
        output += `\n`;
      }
  
      output += `\n💡 전문을 조회하려면 get_admin_appeal_text(id="행정심판재결례일련번호")를 사용하세요.`;
  
      return {
        content: [{
          type: "text",
          text: output
        }]
      };
    } catch (error) {
      return formatToolError(error, "search_admin_appeals")
    }
  }

• src/tools/admin-appeals.ts:8-15 (schema)

  Zod schema defining input parameters for search_admin_appeals: query, display count (max 100), page, sort option, and optional apiKey.

  export const searchAdminAppealsSchema = z.object({
    query: z.string().optional().describe("검색 키워드 (예: '취소처분', '영업정지', '과태료')"),
    display: z.number().min(1).max(100).default(20).describe("페이지당 결과 개수 (기본값: 20, 최대: 100)"),
    page: z.number().min(1).default(1).describe("페이지 번호 (기본값: 1)"),
    sort: z.enum(["lasc", "ldes", "dasc", "ddes", "nasc", "ndes"]).optional()
      .describe("정렬 옵션: lasc/ldes (재결례명순), dasc/ddes (의결일자순), nasc/ndes (사건번호순)"),
    apiKey: z.string().optional().describe("법제처 Open API 인증키(OC). 사용자가 제공한 경우 전달"),
  });

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

  Registration of the search_admin_appeals tool in the central tool registry with its name, description, schema, and handler reference.

  {
    name: "search_admin_appeals",
    description: "[행심] 행정심판례 검색.",
    schema: searchAdminAppealsSchema,
    handler: searchAdminAppeals
  },

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

  Import of searchAdminAppeals and its schema from the admin-appeals module into the tool registry.

  import { searchAdminAppeals, searchAdminAppealsSchema, getAdminAppealText, getAdminAppealTextSchema } from "./tools/admin-appeals.js"

• src/lib/query-router.ts:349-361 (helper)

  Query router pattern that routes queries containing '행정심판' or '행심' to the search_admin_appeals tool.

  // ── 10. 행정심판 ──
  {
    name: "admin_appeal",
    patterns: [
      /행정심판|행심/,
    ],
    tool: "search_admin_appeals",
    extract: (query) => ({
      query: query.replace(/행정심판례?|행심/g, "").replace(/\s+/g, " ").trim(),
    }),
    reason: "행정심판 키워드 → 행정심판례 검색",
    priority: 10,
  },