search_taxlaw_documents
Search tax law documents from the Korean National Tax Service, including interpretations, rulings, and court judgments. Retrieve results by query, document type, dates, and tax category.
Instructions
국세법령정보시스템 문서 검색. 세법해석례/질의회신(01-04)과 과세전적부·이의·심사·심판·판례·헌재(05-10)를 검색. 최신 조세심판원 결정례는 NTS가 강세이므로 본 도구 우선; 그래도 없으면 korean-law-mcp의 search_decisions로 병행 확인 권장.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | 검색어. 비우면 선택 문서유형의 최신순 목록 조회 | |
| docType | No | reply | |
| display | No | ||
| page | No | ||
| sort | No | date_desc | |
| fromDate | No | 검색 시작일 YYYYMMDD | |
| toDate | No | 검색 종료일 YYYYMMDD | |
| taxLawCode | No | 세목 코드. 예: 303=법인세, 305=종합소득세 |
Implementation Reference
- src/index.ts:1251-1307 (handler)Main handler for search_taxlaw_documents. Validates dates, resolves docType codes, splits into question/precedent groups, calls searchDocumentGroup for each, deduplicates, and formats results.
async function searchTaxlawDocuments(args: DocumentSearchArgs, fallbackDocType = "reply"): Promise<ToolResponse> { validateDateRange(args.fromDate, args.toDate) const codes = documentCodes(args.docType, fallbackDocType) const groups = splitDocumentCodes(codes) if (groups.length === 0) { throw new TaxlawMcpError("No supported document type selected.", ErrorCodes.INVALID_PARAM) } const settled = await Promise.allSettled(groups.map((group) => searchDocumentGroup(group, args))) const results = settled .filter((s): s is PromiseFulfilledResult<{ group: "question" | "precedent"; codes: string[]; result: TaxlawSearchData["ASIPDI002PR01"] }> => s.status === "fulfilled") .map((s) => s.value) const failedGroups = settled .map((s, idx) => ({ status: s.status, group: groups[idx], reason: s.status === "rejected" ? s.reason : undefined })) .filter((entry) => entry.status === "rejected") if (results.length === 0) { throw failedGroups[0]?.reason ?? new TaxlawMcpError("Taxlaw document search failed.", ErrorCodes.API_ERROR) } const total = results.reduce((sum, entry) => sum + totalCount(entry.result, entry.codes), 0) const rawItems = results .flatMap((entry) => (entry.result.body || []).map((row) => row.dcm).filter((d): d is TaxlawDcm => !!d)) .sort((a, b) => documentDateValue(b) - documentDateValue(a)) const { items: uniqueItems, duplicatesRemoved } = uniqueDocuments(rawItems) const items = uniqueItems.slice(0, asPositiveInt(args.display, 20, 50)) if (total === 0 || items.length === 0) { const label = codes.map((code) => docLabel(code)).join(", ") return notFoundResponse(`국세법령정보시스템 '${args.query || "(전체)"}' ${label} 검색 결과가 없습니다.`, [ "docType을 all 또는 interpretations/disputes로 넓혀 재검색하세요.", "통합검색이 필요하면 search_taxlaw_all을 사용하세요.", "본 도구는 코드 01–10(세법해석례·과세전적부심사·이의·심사·심판·판례·헌재)만 직접 지원합니다. 법제처 해석례(actionId=ASIBGE004MR03), 감사원 심사청구(ASIPDM001MR01), 납세자보호위원회 심의사례(ASIPRC019MR02), 평가심의사례(ASIBGH004MR01)는 list_taxlaw_site_menus + call_taxlaw_action으로 조회하세요.", "korean-law-mcp의 search_decisions(domain=precedent/interpretation/tax_tribunal/constitutional)도 병행 시도하세요. NTS와 법제처는 인덱싱 범위·본문 검색 강도가 달라 한쪽에만 회수되는 사건이 흔합니다(특히 최신 조세심판원 결정례는 NTS, 일부 대법원·헌재 판결은 법제처가 강세).", ]) } const title = codes.length === 1 ? docLabel(codes[0]) : codes.map((code) => docLabel(code)).join(", ") const lines = [ `국세법령정보시스템 문서 검색 결과: ${title}`, `출처: ${TAXLAW_BASE}/action.do (ASIPDI002PR01)`, `검색어: ${args.query || "(전체)"} / 총 ${total.toLocaleString()}건 / page=${asPositiveInt(args.page, 1)}`, "주의: 아래 결과는 국세법령정보시스템 응답에 존재한 항목만 표시합니다.", "", ] if (duplicatesRemoved > 0) { lines.push(`중복 제거: 같은 문서번호/회신번호/제목으로 보이는 ${duplicatesRemoved.toLocaleString()}건은 표시에서 제외했습니다.`, "") } if (failedGroups.length > 0) { const labels = failedGroups.map((entry) => entry.group.kind === "question" ? "세법해석례/질의회신" : "판례·결정례").join(", ") const reasons = failedGroups.map((entry) => entry.reason instanceof Error ? entry.reason.message : String(entry.reason)).join("; ") lines.push(`⚠️ 일부 그룹 조회 실패(표시되지 않음): ${labels} — ${reasons}`, "") } items.forEach((item) => lines.push(formatDocumentSearchItem(item, args.query), "")) return textResponse(truncate(lines.join("\n"), 50000)) } - src/index.ts:1174-1200 (handler)Inner function that calls the NTS taxlaw action.do endpoint (ASIPDI002PR01) to search a specific document group (question interpretations or precedent decisions).
async function searchDocumentGroup( group: { kind: "question" | "precedent"; codes: string[] }, args: DocumentSearchArgs, ): Promise<{ group: "question" | "precedent"; codes: string[]; result: TaxlawSearchData["ASIPDI002PR01"] }> { const display = asPositiveInt(args.display, 20, 50) const page = asPositiveInt(args.page, 1) const sort = sortField(args.sort) const params = { startCount: page, viewCount: display, schDtBase: sort.startsWith("FRS_") ? "FRS_RGT_DTM" : "DCM_RGT_DTM", bltnStrtDt: args.fromDate || "", bltnEndDt: args.toDate || "", collectionName: group.kind === "question" ? "question,question_gr" : "precedent,precedent_gr", dcmClCdCtl: group.codes.map((code) => `001_${code}`), exclVcbCtl: [], icldVcbCtl: args.query ? [args.query] : [], ntstTlawClCdList: args.taxLawCode ? [args.taxLawCode] : [], sortField: sort, } const firstCode = group.codes[0] const referer = group.kind === "question" ? `/qt/USEQTA001M.do?ntstDcmClCd=${firstCode}` : `/pd/USEPDA001M.do?ntstDcmClCd=${firstCode}` const data = await postTaxlawAction<TaxlawSearchData>("ASIPDI002PR01", params, referer) return { group: group.kind, codes: group.codes, result: data.ASIPDI002PR01 } } - src/index.ts:458-479 (schema)Input schema definition for search_taxlaw_documents with query, docType, display, page, sort, fromDate, toDate, taxLawCode fields.
{ name: "search_taxlaw_documents", description: "국세법령정보시스템 문서 검색. 세법해석례/질의회신(01-04)과 과세전적부·이의·심사·심판·판례·헌재(05-10)를 검색. 최신 조세심판원 결정례는 NTS가 강세이므로 본 도구 우선; 그래도 없으면 korean-law-mcp의 search_decisions로 병행 확인 권장.", inputSchema: { type: "object", properties: { query: { type: "string", description: "검색어. 비우면 선택 문서유형의 최신순 목록 조회" }, docType: { type: "string", enum: ["all", "interpretations", "disputes", "advance", "reply", "tax_standard", "written", "tax_pre_review", "objection", "review", "tribunal", "precedent", "constitutional", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10"], default: "reply", }, display: { type: "number", minimum: 1, maximum: 50, default: 20 }, page: { type: "number", minimum: 1, default: 1 }, sort: { type: "string", enum: ["date_desc", "date_asc", "reg_desc", "reg_asc"], default: "date_desc" }, fromDate: { type: "string", pattern: "^\\d{8}$", description: "검색 시작일 YYYYMMDD" }, toDate: { type: "string", pattern: "^\\d{8}$", description: "검색 종료일 YYYYMMDD" }, taxLawCode: { type: "string", description: "세목 코드. 예: 303=법인세, 305=종합소득세" }, }, required: [], additionalProperties: false, }, - src/index.ts:430-649 (registration)Tool registration in the tools array (line 458-480 for search_taxlaw_documents entry). Registered name is 'search_taxlaw_documents'.
const tools = [ { name: "search_taxlaw_all", description: "국세법령정보시스템 통합검색. 법제처 API에 없는 국세청 자료까지 보완 탐색: 별표서식, 국세법령, 세법해석/질의, 판례·결정례, 발간책자, 홈택스 상담사례. korean-law-mcp(법제처 DB)와 병용 권장 — 법조문 본문은 korean-law-mcp의 get_law_text가 정확하고, 본 도구의 statute 컬렉션은 메타·인용 위주.", inputSchema: { type: "object", properties: { query: { type: "string", description: "검색어. 예: 업무용승용차, 법인세 접대비" }, collections: { oneOf: [ { type: "string", enum: ["all", ...INTEGRATED_COLLECTIONS] }, { type: "array", items: { type: "string", enum: ["all", ...INTEGRATED_COLLECTIONS] } }, ], default: "all", description: "검색 컬렉션. all=전체, appendForm=별표서식, statute=국세법령, question=세법해석/질의, precedent=판례·결정례, formerLibrary=발간책자, hometaxCnslThan=홈택스 상담사례", }, displayPerCollection: { type: "number", minimum: 1, maximum: 10, default: 3 }, page: { type: "number", minimum: 1, default: 1 }, sort: { type: "string", enum: ["score", "date_desc"], default: "score" }, fromDate: { type: "string", pattern: "^\\d{8}$", description: "검색 시작일 YYYYMMDD" }, toDate: { type: "string", pattern: "^\\d{8}$", description: "검색 종료일 YYYYMMDD" }, taxLawCode: { type: "string", description: "세목 코드. 예: 303=법인세, 305=종합소득세" }, synonym: { type: "boolean", default: false, description: "동의어 검색 사용 여부" }, }, required: ["query"], additionalProperties: false, }, }, { name: "search_taxlaw_documents", description: "국세법령정보시스템 문서 검색. 세법해석례/질의회신(01-04)과 과세전적부·이의·심사·심판·판례·헌재(05-10)를 검색. 최신 조세심판원 결정례는 NTS가 강세이므로 본 도구 우선; 그래도 없으면 korean-law-mcp의 search_decisions로 병행 확인 권장.", inputSchema: { type: "object", properties: { query: { type: "string", description: "검색어. 비우면 선택 문서유형의 최신순 목록 조회" }, docType: { type: "string", enum: ["all", "interpretations", "disputes", "advance", "reply", "tax_standard", "written", "tax_pre_review", "objection", "review", "tribunal", "precedent", "constitutional", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10"], default: "reply", }, display: { type: "number", minimum: 1, maximum: 50, default: 20 }, page: { type: "number", minimum: 1, default: 1 }, sort: { type: "string", enum: ["date_desc", "date_asc", "reg_desc", "reg_asc"], default: "date_desc" }, fromDate: { type: "string", pattern: "^\\d{8}$", description: "검색 시작일 YYYYMMDD" }, toDate: { type: "string", pattern: "^\\d{8}$", description: "검색 종료일 YYYYMMDD" }, taxLawCode: { type: "string", description: "세목 코드. 예: 303=법인세, 305=종합소득세" }, }, required: [], additionalProperties: false, }, }, { name: "get_taxlaw_document_text", description: "국세법령정보시스템 문서 상세 조회. search_taxlaw_documents/search_taxlaw_all 결과의 DOC_ID/id를 사용.", inputSchema: { type: "object", properties: { id: { type: "string", description: "검색 결과의 DOC_ID 또는 DOCID. 예: 001_200000000000019482 또는 200000000000019482" }, docType: { type: "string", enum: ["advance", "reply", "tax_standard", "written", "tax_pre_review", "objection", "review", "tribunal", "precedent", "constitutional", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10"], description: "알고 있는 경우 문서유형. 미입력 시 질의/판례 상세를 순차 시도" }, full: { type: "boolean", default: false, description: "true면 HTML 원문 변환 텍스트를 더 길게 포함" }, }, required: ["id"], additionalProperties: false, }, }, { name: "get_taxlaw_hometax_counsel_text", description: "국세법령정보시스템 홈택스 상담사례 상세 조회. search_taxlaw_all의 hometaxCnslThan 결과 ID/REQ_STD_ID를 사용.", inputSchema: { type: "object", properties: { id: { type: "string", description: "통합검색 홈택스 상담사례 결과의 ID 또는 REQ_STD_ID. 예: 369" }, }, required: ["id"], additionalProperties: false, }, }, { name: "list_taxlaw_site_menus", description: "국세법령정보시스템 주요 메뉴별 접근 경로와 확인된 action.do 호출 정보를 나열합니다. 고수준 도구가 없는 메뉴는 call_taxlaw_action 또는 get_taxlaw_page_text로 접근합니다.", inputSchema: { type: "object", properties: { query: { type: "string", description: "메뉴명/섹션/키/액션ID 필터. 예: 훈령서식, ASIPDM, 세목별" }, }, required: [], additionalProperties: false, }, }, { name: "call_taxlaw_action", description: "국세법령정보시스템 action.do 원시 호출. list_taxlaw_site_menus의 actionId/defaultParamData 또는 브라우저에서 확인한 actionId를 사용할 수 있습니다.", inputSchema: { type: "object", properties: { actionId: { type: "string", description: "action.do actionId. 예: ASIPDM001MR01" }, paramData: { type: "object", description: "action.do paramData JSON 객체. 미입력 시 {}" }, refererPath: { type: "string", description: "같은 사이트 내 referer 경로. 예: /pd/USEPDM001M.do" }, full: { type: "boolean", default: false, description: "true면 JSON 응답을 더 길게 반환" }, }, required: ["actionId", "refererPath"], additionalProperties: false, }, }, { name: "get_taxlaw_page_text", description: "국세법령정보시스템 HTML/텍스트 페이지를 같은 사이트 경로로 조회해 텍스트로 변환합니다. 정적 자료(예: 세목별요약정보 /html/U_0101.html) 확인용입니다.", inputSchema: { type: "object", properties: { path: { type: "string", description: "같은 사이트 내 경로. 예: /bg/USEBGG001M.do, /html/U_0101.html" }, full: { type: "boolean", default: false }, }, required: ["path"], additionalProperties: false, }, }, { name: "search_taxlaw_interpretations", description: "하위호환용: 세법해석례/질의회신 검색. 내부적으로 search_taxlaw_documents를 사용.", inputSchema: { type: "object", properties: { query: { type: "string" }, docType: { type: "string", enum: ["all", "interpretations", "advance", "reply", "tax_standard", "written", "01", "02", "03", "04"], default: "reply" }, display: { type: "number", minimum: 1, maximum: 50, default: 20 }, page: { type: "number", minimum: 1, default: 1 }, sort: { type: "string", enum: ["date_desc", "date_asc", "reg_desc", "reg_asc"], default: "date_desc" }, fromDate: { type: "string", pattern: "^\\d{8}$" }, toDate: { type: "string", pattern: "^\\d{8}$" }, taxLawCode: { type: "string" }, }, required: [], additionalProperties: false, }, }, { name: "get_taxlaw_interpretation_text", description: "하위호환용: 세법해석례/질의회신 상세 조회. 내부적으로 get_taxlaw_document_text를 사용.", inputSchema: { type: "object", properties: { id: { type: "string" }, full: { type: "boolean", default: false }, }, required: ["id"], additionalProperties: false, }, }, { name: "list_taxlaw_basic_ruling_laws", description: "국세법령정보시스템 기본통칙 법령 목록 조회. get_taxlaw_basic_ruling_text의 lawId 확보용.", inputSchema: { type: "object", properties: { query: { type: "string", description: "법령명 필터. 예: 법인세, 소득세" }, }, required: [], additionalProperties: false, }, }, { name: "get_taxlaw_basic_ruling_text", description: "국세법령정보시스템 기본통칙 본문 조회. list_taxlaw_basic_ruling_laws 결과의 lawId 사용.", inputSchema: { type: "object", properties: { lawId: { type: "string", description: "기본통칙 법령 ID(ntstBscId)" }, year: { type: "string", pattern: "^\\d{4}$", description: "연도. 미입력 시 최신 연도" }, query: { type: "string", description: "통칙 제목/본문 내 필터" }, display: { type: "number", minimum: 1, maximum: 200, default: 30 }, full: { type: "boolean", default: false }, }, required: ["lawId"], additionalProperties: false, }, }, { name: "search_taxlaw_forms", description: "국세법령정보시스템 별표/서식 검색. 전체 서식, 별표, 법령서식, 훈령서식, 자주찾는서식을 탐색.", inputSchema: { type: "object", properties: { query: { type: "string", description: "별표/서식명 검색어" }, kind: { type: "string", enum: ["all", "all_forms", "annex", "form", "legal_form", "instruction_form", "favorite_form"], default: "all" }, lawId: { type: "string", description: "특정 법령 ID(ntstBscId). 미입력 시 전체" }, display: { type: "number", minimum: 1, maximum: 50, default: 20 }, page: { type: "number", minimum: 1, default: 1 }, }, required: [], additionalProperties: false, }, }, { name: "search_taxlaw_publications", description: "국세법령정보시스템 발간책자 검색. 세무안내, 신고안내 등 전자도서관 자료 탐색.", inputSchema: { type: "object", properties: { query: { type: "string", description: "제목 검색어" }, categoryCode: { type: "string", description: "분야 코드. list_taxlaw_publication_categories로 확인. 미입력/All=전체" }, display: { type: "number", minimum: 1, maximum: 50, default: 20 }, page: { type: "number", minimum: 1, default: 1 }, }, required: [], additionalProperties: false, }, }, { name: "list_taxlaw_publication_categories", description: "국세법령정보시스템 발간책자 분야 코드 목록 조회.", inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false, }, }, ] - src/index.ts:1886-1888 (registration)Dispatch in handleToolCall that routes 'search_taxlaw_documents' to the searchTaxlawDocuments handler function.
if (name === "search_taxlaw_documents") { return await searchTaxlawDocuments(input as DocumentSearchArgs) }