search_treaties

Instructions

Implementation Reference

• src/tools/treaties.ts:21-78 (handler)

  Main handler function for the search_treaties tool. Calls the LawApiClient to search treaties (lawSearch.do endpoint with target='trty'), parses the XML response via parseTreatyXML, and formats results into a text response including treaty serial number, name, number, conclusion date, effective date, type, and detail link.

  export async function searchTreaties(
    apiClient: LawApiClient,
    args: SearchTreatiesInput
  ): Promise<{ content: Array<{ type: string, text: string }>, isError?: boolean }> {
    try {
      const extraParams: Record<string, string> = {
        display: String(args.display || 20),
        page: String(args.page || 1),
      }
      if (args.query) extraParams.query = args.query
      if (args.cls) extraParams.cls = args.cls
      if (args.natCd) extraParams.natCd = args.natCd
      if (args.eftYd) extraParams.eftYd = args.eftYd
      if (args.concYd) extraParams.concYd = args.concYd
      if (args.sort) extraParams.sort = args.sort
  
      const xmlText = await apiClient.fetchApi({
        endpoint: "lawSearch.do",
        target: "trty",
        extraParams,
        apiKey: args.apiKey,
      })
  
      const result = parseTreatyXML(xmlText)
      const treaties = result.items
  
      if (result.totalCnt === 0) {
        const kw = args.query || "관련 키워드"
        const hint = [
          "검색 결과가 없습니다.\n\n개선 방법:",
          `  1. 단순 키워드: search_treaties(query="${kw.split(/\s+/)[0]}")`,
          `  2. 법령 검색: search_law(query="${kw}")`,
        ].join("\n")
        return { content: [{ type: "text", text: hint }], isError: true }
      }
  
      let output = `조약 검색 결과 (총 ${result.totalCnt}건, ${result.page}페이지):\n\n`
  
      for (const t of treaties) {
        output += `[${t.조약일련번호}] ${t.조약명}\n`
        output += `  조약번호: ${t.조약번호 || "N/A"}\n`
        output += `  체결일: ${t.체결일자 || "N/A"}\n`
        output += `  발효일: ${t.발효일자 || "N/A"}\n`
        output += `  구분: ${t.조약구분 || "N/A"}\n`
        if (t.조약상세링크) {
          output += `  링크: ${t.조약상세링크}\n`
        }
        output += `\n`
      }
  
      output += `\n전문을 조회하려면 get_treaty_text Tool을 사용하세요.\n`
  
      return { content: [{ type: "text", text: truncateResponse(output) }] }
    } catch (error) {
      const msg = error instanceof Error ? error.message : String(error)
      return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true }
    }
  }

• src/tools/treaties.ts:6-17 (schema)

  Zod validation schema for search_treaties input. Fields: query (keyword), cls (treaty type: 1=bilateral, 2=multilateral), natCd (country code), eftYd (effective date YYYYMMDD), concYd (conclusion date YYYYMMDD), display (1-100, default 20), page (default 1), sort (by name or date), and optional apiKey.

  export const searchTreatiesSchema = z.object({
    query: z.string().optional().describe("검색 키워드 (예: '투자보장', '범죄인인도')"),
    cls: z.enum(["1", "2"]).optional().describe("조약구분 (1=양자조약, 2=다자조약)"),
    natCd: z.string().optional().describe("국가코드 (예: 'US', 'JP')"),
    eftYd: z.string().optional().describe("발효일 (YYYYMMDD)"),
    concYd: z.string().optional().describe("체결일 (YYYYMMDD)"),
    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"]).optional()
      .describe("정렬: lasc/ldes(조약명), dasc/ddes(날짜)"),
    apiKey: z.string().optional().describe("법제처 Open API 인증키(OC). 사용자가 제공한 경우 전달"),
  })

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

  Registration of search_treaties in the tool registry. Maps the name 'search_treaties' to its schema (searchTreatiesSchema) and handler (searchTreaties) within the treaties section of the allTools array.

  // === 조약 ===
  {
    name: "search_treaties",
    description: "[조약] 조약(양자/다자) 검색. 국가코드·체결일·발효일 필터 가능.",
    schema: searchTreatiesSchema,
    handler: searchTreaties
  },

• src/lib/xml-parser.ts:236-258 (helper)

  Helper type (TreatyItem) and XML parser (parseTreatyXML) used by the search_treaties handler. Parses the 'TrtySearch' root tag with 'Trty' item tags, extracting treaty serial number, name, number, signature date (mapped as 체결일자), effective date, type, and detail link.

   * 조약 검색 결과 파싱
   */
  export interface TreatyItem {
    조약일련번호: string
    조약명: string
    조약번호: string
    체결일자: string
    발효일자: string
    조약구분: string
    조약상세링크: string
  }
  
  export function parseTreatyXML(xml: string) {
    return parseSearchXML<TreatyItem>(xml, "TrtySearch", "Trty", (content) => ({
      조약일련번호: extractTag(content, "조약일련번호"),
      조약명: extractTag(content, "조약명"),
      조약번호: extractTag(content, "조약번호"),
      체결일자: extractTag(content, "서명일자"),
      발효일자: extractTag(content, "발효일자"),
      조약구분: extractTag(content, "조약구분명"),
      조약상세링크: extractTag(content, "조약상세링크")
    }))
  }