@mseep/korean-dart-mcp 0.9.3

package/build/tools/get-attachments.js

@@ -0,0 +1,339 @@
+/**
+ * get_attachments — 공시 첨부파일 목록 조회 + HWP/PDF → 마크다운 추출
+ *
+ * OpenDART API 는 첨부파일 직접 엔드포인트가 없다. DART 뷰어 HTML 을 스크래핑해야 한다.
+ * OpenDartReader 도 동일 패턴. 사실상 업계 표준.
+ *
+ *   1. 뷰어 HTML  `/dsaf001/main.do?rcpNo=...`  →  JS 변수 `node1['dcmNo']` 추출
+ *   2. 다운로드 페이지  `/pdf/download/main.do?rcp_no=&dcm_no=`  →  `<td class="tL">` 파싱
+ *   3. 각 첨부 URL (`/pdf/download/pdf.do?...` 등) fetch → Buffer
+ *   4. kordoc.parse() 로 HWP/HWPX/PDF/DOCX/XLSX → 마크다운
+ *
+ * mode="list" — 첨부 목록만 반환 (가볍고 빠름, 파일명·download_url·format 힌트)
+ * mode="extract" — 지정한 파일을 다운로드·파싱해 마크다운 반환
+ */
+import { z } from "zod";
+import { parse as kordocParse } from "kordoc";
+import { defineTool } from "./_helpers.js";
+import { safeUnzipToMemory } from "../utils/safe-zip.js";
+const USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36";
+const DART_ORIGIN = "https://dart.fss.or.kr";
+const Input = z
+    .object({
+    rcept_no: z
+        .string()
+        .regex(/^\d{14}$/)
+        .describe("접수번호 14자리"),
+    mode: z
+        .enum(["list", "extract"])
+        .default("list")
+        .describe("list: 첨부 목록만. extract: 파일 하나 다운·파싱해 마크다운"),
+    filename: z
+        .string()
+        .optional()
+        .describe("extract 모드에서 정확한 파일명 (부분일치 폴백 없음)"),
+    index: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("extract 모드에서 0-based index (filename 우선)"),
+    truncate_at: z
+        .number()
+        .int()
+        .min(1000)
+        .default(100000)
+        .describe("extract 마크다운 최대 길이"),
+    outline_max_items: z
+        .number()
+        .int()
+        .min(0)
+        .max(500)
+        .default(50)
+        .describe("outline(목차) 최대 항목 수. 사업보고서 outline 은 수천 개 → 디폴트 50. 0=outline 생략."),
+    zip_index: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("ZIP 첨부 extract 시 내부 파일 index (0-based). 미지정 & ZIP 인 경우 내부 파일 목록만 반환."),
+})
+    .refine((v) => v.mode !== "extract" || v.filename !== undefined || v.index !== undefined, { message: "extract 모드엔 filename 또는 index 중 하나 필수" });
+const EXT_FORMAT = [
+    [/\.hwpx$/i, "hwpx"],
+    [/\.hwp$/i, "hwp"],
+    [/\.pdf$/i, "pdf"],
+    [/\.docx$/i, "docx"],
+    [/\.doc$/i, "doc"],
+    [/\.xlsx$/i, "xlsx"],
+    [/\.xls$/i, "xls"],
+    [/\.zip$/i, "zip"],
+    [/\.html?$/i, "html"],
+];
+function detectFormat(filename) {
+    for (const [re, fmt] of EXT_FORMAT) {
+        if (re.test(filename))
+            return fmt;
+    }
+    return "unknown";
+}
+/** 뷰어 HTML 에서 첫 번째 `node[12]['dcmNo']` 추출. 단일-페이지 viewDoc() 도 폴백. */
+function extractDcmNo(html, rcptNo) {
+    const nodeRe = new RegExp(`node[12]\\['rcpNo'\\]\\s*=\\s*"${rcptNo}";\\s*node[12]\\['dcmNo'\\]\\s*=\\s*"(\\d+)"`);
+    const nodeMatch = nodeRe.exec(html);
+    if (nodeMatch)
+        return nodeMatch[1];
+    const singleRe = /viewDoc\('(\d+)',\s*'(\d+)'/;
+    const s = singleRe.exec(html);
+    return s?.[2] ?? null;
+}
+/** 다운로드 페이지 HTML 에서 첨부 테이블 행 추출. 주석 블록은 먼저 제거. */
+function parseAttachmentTable(html) {
+    const cleaned = html.replace(/<!--[\s\S]*?-->/g, "");
+    const rowRe = /<td class="tL">\s*([^<]+?)\s*<\/td>\s*<td>\s*<a class="btnFile"\s+href="([^"]+)"/g;
+    const rows = [];
+    for (const m of cleaned.matchAll(rowRe)) {
+        rows.push({ filename: m[1].trim(), href: m[2] });
+    }
+    return rows;
+}
+async function fetchHtml(url) {
+    const res = await fetch(url, { headers: { "User-Agent": USER_AGENT } });
+    if (!res.ok)
+        throw new Error(`DART viewer fetch 실패: ${url} → HTTP ${res.status}`);
+    return await res.text();
+}
+async function fetchBinary(url) {
+    const res = await fetch(url, { headers: { "User-Agent": USER_AGENT } });
+    if (!res.ok)
+        throw new Error(`DART 첨부 다운로드 실패: ${url} → HTTP ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+function extractZipEntries(buf) {
+    return safeUnzipToMemory(buf);
+}
+async function listAttachments(rcept_no) {
+    const viewerUrl = `${DART_ORIGIN}/dsaf001/main.do?rcpNo=${rcept_no}`;
+    const viewerHtml = await fetchHtml(viewerUrl);
+    const dcm_no = extractDcmNo(viewerHtml, rcept_no);
+    if (!dcm_no) {
+        // 거래소공시(pblntf_ty=I) 등 일부는 DART 뷰어에 dcm_no 가 내재되지 않아
+        // 첨부파일 다운로드 링크 자체가 존재하지 않는다. DART 표준 API·스크래핑 모두
+        // 접근 불가. 본문 텍스트가 필요하면 download_document 로 원문 XML 조회.
+        return {
+            dcm_no: null,
+            viewer_url: viewerUrl,
+            download_page_url: null,
+            attachments: [],
+            supported: false,
+            unsupported_reason: "DART 뷰어에 dcm_no 가 내재되지 않음 (거래소공시 등). 첨부 직접 접근 불가. 대안: download_document(rcept_no) 로 원문 XML 조회.",
+        };
+    }
+    const dlPageUrl = `${DART_ORIGIN}/pdf/download/main.do?rcp_no=${rcept_no}&dcm_no=${dcm_no}`;
+    const dlHtml = await fetchHtml(dlPageUrl);
+    const rows = parseAttachmentTable(dlHtml);
+    const attachments = rows.map((r, i) => ({
+        index: i,
+        filename: r.filename,
+        download_url: r.href.startsWith("http") ? r.href : `${DART_ORIGIN}${r.href}`,
+        format: detectFormat(r.filename),
+    }));
+    return {
+        dcm_no,
+        viewer_url: viewerUrl,
+        download_page_url: dlPageUrl,
+        attachments,
+        supported: true,
+    };
+}
+export const getAttachmentsTool = defineTool({
+    name: "get_attachments",
+    description: "공시 첨부파일(HWP/PDF/DOCX/XLSX)을 목록 조회(mode=list) 하거나 다운받아 마크다운으로 추출(mode=extract). " +
+        "DART 뷰어 HTML 스크래핑 기반 — OpenDART 표준 API 에 첨부 엔드포인트가 없어 공식 뷰어를 통해 접근. " +
+        "extract 모드는 kordoc 엔진으로 HWP/HWPX/PDF/DOCX/XLSX → 마크다운 변환.",
+    input: Input,
+    handler: async (_ctx, args) => {
+        const info = await listAttachments(args.rcept_no);
+        // outline 잘라내기 헬퍼 — 사업보고서 PDF 는 수천 항목 outline 이라 응답 폭발
+        const truncOutline = (o) => {
+            if (!o)
+                return null;
+            if (!Array.isArray(o))
+                return { items: o, total: 1, truncated: false };
+            const total = o.length;
+            if (args.outline_max_items === 0) {
+                return { items: [], total, truncated: total > 0 };
+            }
+            const items = o.slice(0, args.outline_max_items);
+            return { items, total, truncated: total > args.outline_max_items };
+        };
+        if (args.mode === "list") {
+            return {
+                rcept_no: args.rcept_no,
+                supported: info.supported,
+                dcm_no: info.dcm_no,
+                viewer_url: info.viewer_url,
+                download_page_url: info.download_page_url,
+                count: info.attachments.length,
+                attachments: info.attachments,
+                unsupported_reason: info.unsupported_reason ?? null,
+            };
+        }
+        if (!info.supported) {
+            return {
+                rcept_no: args.rcept_no,
+                supported: false,
+                viewer_url: info.viewer_url,
+                unsupported_reason: info.unsupported_reason,
+                suggestion: {
+                    tool: "download_document",
+                    args: { rcept_no: args.rcept_no, format: "markdown" },
+                },
+            };
+        }
+        // extract 모드
+        let target;
+        if (args.filename) {
+            target = info.attachments.find((a) => a.filename === args.filename);
+            if (!target) {
+                throw new Error(`파일명 일치 없음: "${args.filename}". 사용 가능: ${info.attachments
+                    .map((a) => a.filename)
+                    .join(" / ")}`);
+            }
+        }
+        else if (args.index !== undefined) {
+            target = info.attachments[args.index];
+            if (!target) {
+                throw new Error(`index 범위 초과: ${args.index} (총 ${info.attachments.length}개)`);
+            }
+        }
+        if (!target) {
+            throw new Error("extract 모드엔 filename 또는 index 필수");
+        }
+        if (target.format === "unknown") {
+            return {
+                rcept_no: args.rcept_no,
+                filename: target.filename,
+                format: target.format,
+                download_url: target.download_url,
+                supported: false,
+                note: "확장자로 포맷 판별 실패. download_url 로 직접 받아 확인.",
+            };
+        }
+        if (target.format === "zip") {
+            // XBRL ZIP 은 전용 get_xbrl 로 처리하는 게 적절
+            if (/XBRL/i.test(target.filename)) {
+                return {
+                    rcept_no: args.rcept_no,
+                    filename: target.filename,
+                    format: "zip",
+                    download_url: target.download_url,
+                    supported: false,
+                    note: "XBRL ZIP 은 get_xbrl(rcept_no) 로 조회 — 파싱된 재무제표 + 원본 파일 경로 제공.",
+                };
+            }
+            const zipBuf = await fetchBinary(target.download_url);
+            const innerFiles = await extractZipEntries(zipBuf);
+            const parsable = innerFiles
+                .map((f, i) => ({ ...f, index: i, format: detectFormat(f.name) }))
+                .filter((f) => f.format !== "zip" && f.format !== "unknown");
+            if (args.zip_index === undefined) {
+                return {
+                    rcept_no: args.rcept_no,
+                    filename: target.filename,
+                    format: "zip",
+                    download_url: target.download_url,
+                    size_bytes: zipBuf.length,
+                    zip_mode: "list",
+                    total_entries: innerFiles.length,
+                    parsable_count: parsable.length,
+                    entries: parsable.map((f) => ({
+                        index: f.index,
+                        name: f.name,
+                        size_bytes: f.data.length,
+                        format: f.format,
+                    })),
+                    note: "zip_index 를 지정하면 해당 파일을 kordoc 으로 파싱한다.",
+                };
+            }
+            const inner = innerFiles[args.zip_index];
+            if (!inner) {
+                throw new Error(`zip_index 범위 초과: ${args.zip_index} (ZIP 내부 ${innerFiles.length}개)`);
+            }
+            const innerFmt = detectFormat(inner.name);
+            if (innerFmt === "unknown" || innerFmt === "zip") {
+                return {
+                    rcept_no: args.rcept_no,
+                    filename: target.filename,
+                    zip_inner_filename: inner.name,
+                    zip_inner_format: innerFmt,
+                    size_bytes: inner.data.length,
+                    supported: false,
+                    note: "내부 파일이 ZIP 또는 알 수 없는 포맷. 재귀 파싱 미지원.",
+                };
+            }
+            const innerSize = inner.data.length;
+            const innerParsed = await kordocParse(inner.data);
+            if (!innerParsed.success) {
+                return {
+                    rcept_no: args.rcept_no,
+                    filename: target.filename,
+                    zip_inner_filename: inner.name,
+                    zip_inner_format: innerFmt,
+                    size_bytes: innerSize,
+                    supported: false,
+                    error: innerParsed.error,
+                    error_code: innerParsed.code,
+                };
+            }
+            const innerMd = innerParsed.markdown ?? "";
+            const innerTruncated = innerMd.length > args.truncate_at;
+            return {
+                rcept_no: args.rcept_no,
+                filename: target.filename,
+                zip_inner_filename: inner.name,
+                zip_inner_format: innerFmt,
+                file_type_detected: innerParsed.fileType,
+                size_bytes: innerSize,
+                char_count: innerMd.length,
+                truncated: innerTruncated,
+                markdown: innerTruncated ? innerMd.slice(0, args.truncate_at) : innerMd,
+                warnings: innerParsed.warnings ?? [],
+                outline: truncOutline(innerParsed.outline),
+                metadata: innerParsed.metadata ?? null,
+            };
+        }
+        const buf = await fetchBinary(target.download_url);
+        // kordoc 내부에서 ArrayBuffer 를 detach 할 수 있어 파싱 전에 크기 캡처
+        const sizeBytes = buf.length;
+        const parsed = await kordocParse(buf);
+        if (!parsed.success) {
+            return {
+                rcept_no: args.rcept_no,
+                filename: target.filename,
+                format: target.format,
+                download_url: target.download_url,
+                size_bytes: sizeBytes,
+                supported: false,
+                error: parsed.error,
+                error_code: parsed.code,
+            };
+        }
+        const md = parsed.markdown ?? "";
+        const truncated = md.length > args.truncate_at;
+        return {
+            rcept_no: args.rcept_no,
+            filename: target.filename,
+            format: target.format,
+            file_type_detected: parsed.fileType,
+            download_url: target.download_url,
+            size_bytes: sizeBytes,
+            char_count: md.length,
+            truncated,
+            markdown: truncated ? md.slice(0, args.truncate_at) : md,
+            warnings: parsed.warnings ?? [],
+            outline: truncOutline(parsed.outline),
+            metadata: parsed.metadata ?? null,
+        };
+    },
+});

package/build/tools/get-company.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_company — 기업개황 조회 (company.json)
+ *
+ * 업종·설립일·대표자·주소·홈페이지 등 기본 정보.
+ * 참고: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001&apiId=2019002
+ */
+export declare const getCompanyTool: import("./_helpers.js").ToolDef;

package/build/tools/get-company.js

@@ -0,0 +1,32 @@
+/**
+ * get_company — 기업개황 조회 (company.json)
+ *
+ * 업종·설립일·대표자·주소·홈페이지 등 기본 정보.
+ * 참고: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001&apiId=2019002
+ */
+import { z } from "zod";
+import { defineTool, resolveCorp } from "./_helpers.js";
+const Input = z.object({
+    corp: z
+        .string()
+        .min(1)
+        .describe("회사명/종목코드/corp_code"),
+});
+export const getCompanyTool = defineTool({
+    name: "get_company",
+    description: "기업의 개황(업종·설립일·대표자·주소·홈페이지·종목코드 등)을 조회합니다.",
+    input: Input,
+    handler: async (ctx, args) => {
+        const record = resolveCorp(ctx.resolver, args.corp);
+        const raw = await ctx.client.getJson("company.json", {
+            corp_code: record.corp_code,
+        });
+        if (raw.status !== "000") {
+            throw new Error(`DART 응답 오류 [${raw.status}]: ${raw.message}`);
+        }
+        return {
+            resolved: record,
+            company: raw,
+        };
+    },
+});

package/build/tools/get-corporate-event.d.ts

@@ -0,0 +1,14 @@
+/**
+ * get_corporate_event — DS005 주요사항보고서 36개 이벤트 enum + timeline 모드
+ *
+ * ## mode: "single"
+ *   단일 event_type 조회. OpenDartReader dart_event 와 동일한 매핑.
+ *
+ * ## mode: "timeline"  ← 킬러 포인트
+ *   지정 기간 동안 **자본 관련 주요 이벤트 전부**를 병렬 조회해 날짜순 통합.
+ *   기존 Python 래퍼(단일 조회만 가능)에서는 불가능한 "자본 스트레스 내러티브" 뷰.
+ *   LLM 가 바로 "최근 3년 CB 2회 + 자사주 처분 → 조달 압박" 스토리 생성 가능.
+ *
+ * 매핑 출처: FinanceData/OpenDartReader dart_event.py
+ */
+export declare const getCorporateEventTool: import("./_helpers.js").ToolDef;

package/build/tools/get-corporate-event.js

@@ -0,0 +1,180 @@
+/**
+ * get_corporate_event — DS005 주요사항보고서 36개 이벤트 enum + timeline 모드
+ *
+ * ## mode: "single"
+ *   단일 event_type 조회. OpenDartReader dart_event 와 동일한 매핑.
+ *
+ * ## mode: "timeline"  ← 킬러 포인트
+ *   지정 기간 동안 **자본 관련 주요 이벤트 전부**를 병렬 조회해 날짜순 통합.
+ *   기존 Python 래퍼(단일 조회만 가능)에서는 불가능한 "자본 스트레스 내러티브" 뷰.
+ *   LLM 가 바로 "최근 3년 CB 2회 + 자사주 처분 → 조달 압박" 스토리 생성 가능.
+ *
+ * 매핑 출처: FinanceData/OpenDartReader dart_event.py
+ */
+import { z } from "zod";
+import { defineTool, normalizeDate, resolveCorp } from "./_helpers.js";
+const EVENT = {
+    // 부실/법적 이슈
+    default_occurrence: { endpoint: "dfOcr", ko: "부도발생", capital: false },
+    business_suspension: { endpoint: "bsnSp", ko: "영업정지", capital: false },
+    rehabilitation_filing: { endpoint: "ctrcvsBgrq", ko: "회생절차 개시신청", capital: false },
+    dissolution_cause: { endpoint: "dsRsOcr", ko: "해산사유 발생", capital: false },
+    bank_management_start: { endpoint: "bnkMngtPcbg", ko: "채권은행 관리절차 개시", capital: false },
+    bank_management_stop: { endpoint: "bnkMngtPcsp", ko: "채권은행 관리절차 중단", capital: false },
+    litigation: { endpoint: "lwstLg", ko: "소송 등 제기", capital: false },
+    // 자본 증감
+    rights_offering: { endpoint: "piicDecsn", ko: "유상증자 결정", capital: true },
+    bonus_issue: { endpoint: "fricDecsn", ko: "무상증자 결정", capital: true },
+    rights_bonus_combo: { endpoint: "pifricDecsn", ko: "유무상증자 결정", capital: true },
+    capital_reduction: { endpoint: "crDecsn", ko: "감자 결정", capital: true },
+    // 사채 발행
+    cb_issuance: { endpoint: "cvbdIsDecsn", ko: "전환사채(CB) 발행결정", capital: true },
+    bw_issuance: { endpoint: "bdwtIsDecsn", ko: "신주인수권부사채(BW) 발행결정", capital: true },
+    eb_issuance: { endpoint: "exbdIsDecsn", ko: "교환사채(EB) 발행결정", capital: true },
+    cocobond_issuance: { endpoint: "wdCocobdIsDecsn", ko: "상각형 조건부자본증권 발행결정", capital: true },
+    // 자기주식
+    treasury_acquisition: { endpoint: "tsstkAqDecsn", ko: "자기주식 취득 결정", capital: true },
+    treasury_disposal: { endpoint: "tsstkDpDecsn", ko: "자기주식 처분 결정", capital: true },
+    treasury_trust_contract: { endpoint: "tsstkAqTrctrCnsDecsn", ko: "자기주식취득 신탁계약 체결", capital: true },
+    treasury_trust_cancel: { endpoint: "tsstkAqTrctrCcDecsn", ko: "자기주식취득 신탁계약 해지", capital: true },
+    // 지배구조 변경 (합병·분할·교환)
+    stock_exchange: { endpoint: "stkExtrDecsn", ko: "주식교환·이전 결정", capital: true },
+    company_split_merger: { endpoint: "cmpDvmgDecsn", ko: "회사분할합병 결정", capital: true },
+    company_split: { endpoint: "cmpDvDecsn", ko: "회사분할 결정", capital: true },
+    company_merger: { endpoint: "cmpMgDecsn", ko: "회사합병 결정", capital: true },
+    // 자산·영업 양수도
+    asset_transfer_etc: { endpoint: "astInhtrfEtcPtbkOpt", ko: "자산양수도(기타)·풋백옵션", capital: true },
+    tangible_asset_transfer: { endpoint: "tgastTrfDecsn", ko: "유형자산 양도 결정", capital: true },
+    tangible_asset_acquisition: { endpoint: "tgastInhDecsn", ko: "유형자산 양수 결정", capital: true },
+    other_corp_stock_transfer: { endpoint: "otcprStkInvscrTrfDecsn", ko: "타법인 주식·출자증권 양도", capital: true },
+    other_corp_stock_acquisition: { endpoint: "otcprStkInvscrInhDecsn", ko: "타법인 주식·출자증권 양수", capital: true },
+    business_transfer: { endpoint: "bsnTrfDecsn", ko: "영업양도 결정", capital: true },
+    business_acquisition: { endpoint: "bsnInhDecsn", ko: "영업양수 결정", capital: true },
+    bond_with_stock_right_acquisition: { endpoint: "stkrtbdInhDecsn", ko: "주권관련 사채권 양수", capital: true },
+    bond_with_stock_right_transfer: { endpoint: "stkrtbdTrfDecsn", ko: "주권관련 사채권 양도", capital: true },
+    // 해외 상장
+    overseas_listing_decision: { endpoint: "ovLstDecsn", ko: "해외상장 결정", capital: false },
+    overseas_delisting_decision: { endpoint: "ovDlstDecsn", ko: "해외상장폐지 결정", capital: false },
+    overseas_listing: { endpoint: "ovLst", ko: "해외상장", capital: false },
+    overseas_delisting: { endpoint: "ovDlst", ko: "해외상장폐지", capital: false },
+};
+const EVENT_TYPES = Object.keys(EVENT);
+const Input = z
+    .object({
+    corp: z.string().min(1).describe("회사명/종목코드/corp_code"),
+    mode: z
+        .enum(["single", "timeline"])
+        .default("single")
+        .describe("single: 단일 event_type 조회. timeline: 여러 자본 관련 이벤트를 날짜순 통합 (킬러 모드)"),
+    event_type: z
+        .enum(EVENT_TYPES)
+        .optional()
+        .describe("single 모드 필수. 36개 이벤트 중 하나"),
+    event_types: z
+        .array(z.enum(EVENT_TYPES))
+        .optional()
+        .describe("timeline 모드용 수동 선택. 미지정 시 자본 관련 이벤트(capital=true) 전체 자동 선택"),
+    start: z.string().optional().describe("시작일 (YYYY-MM-DD / YYYYMMDD)"),
+    end: z.string().optional().describe("종료일 (YYYY-MM-DD / YYYYMMDD)"),
+})
+    .refine((v) => v.mode !== "single" || !!v.event_type, { message: "mode=single 일 때 event_type 필수" });
+async function fetchEvent(ctx, corp_code, type, bgn_de, end_de) {
+    const meta = EVENT[type];
+    try {
+        const raw = await ctx.client.getJson(`${meta.endpoint}.json`, {
+            corp_code,
+            bgn_de,
+            end_de,
+        });
+        if (raw.status !== "000") {
+            return { type, endpoint: meta.endpoint, status: raw.status, message: raw.message, items: [] };
+        }
+        return {
+            type,
+            endpoint: meta.endpoint,
+            status: raw.status,
+            count: raw.list?.length ?? 0,
+            items: raw.list ?? [],
+        };
+    }
+    catch (e) {
+        return {
+            type,
+            endpoint: meta.endpoint,
+            error: e instanceof Error ? e.message : String(e),
+            items: [],
+        };
+    }
+}
+/** DART 응답 rcept_dt (접수일자) 을 YYYY-MM-DD 로 변환. YYYYMMDD / YYYY-MM-DD 모두 수용. */
+function pickEventDate(item) {
+    const d = item.rcept_dt || item.ctrt_cnsdt || item.fd_dcsn_cnsdt || "";
+    const digits = d.replace(/\D/g, "");
+    const m = /^(\d{4})(\d{2})(\d{2})$/.exec(digits);
+    return m ? `${m[1]}-${m[2]}-${m[3]}` : d;
+}
+export const getCorporateEventTool = defineTool({
+    name: "get_corporate_event",
+    description: "DS005 주요사항보고서 36종 이벤트 조회. " +
+        "mode='single' 은 단일 event_type 상세, " +
+        "mode='timeline' 은 자본 관련 이벤트(증자·감자·CB/BW/EB·자사주·합병분할·영업양수도 등)를 지정 기간 병렬 수집 후 날짜순 통합. " +
+        "timeline 은 '최근 N년 자본 스트레스 내러티브' 를 한 번에 뽑기 위한 킬러 모드.",
+    input: Input,
+    handler: async (ctx, args) => {
+        const record = resolveCorp(ctx.resolver, args.corp);
+        const bgn_de = args.start ? normalizeDate(args.start) : undefined;
+        const end_de = args.end ? normalizeDate(args.end) : undefined;
+        if (args.mode === "single") {
+            const result = await fetchEvent(ctx, record.corp_code, args.event_type, bgn_de, end_de);
+            return {
+                mode: "single",
+                resolved: record,
+                period: { start: bgn_de ?? null, end: end_de ?? null },
+                ...result,
+            };
+        }
+        // timeline 모드
+        const targets = args.event_types ??
+            Object.entries(EVENT)
+                .filter(([, meta]) => meta.capital)
+                .map(([k]) => k);
+        const sections = await Promise.all(targets.map((t) => fetchEvent(ctx, record.corp_code, t, bgn_de, end_de)));
+        // 통합 타임라인: 각 item 에 event_type/ko 메타 주입하고 날짜 역순 정렬
+        const timeline = [];
+        for (const section of sections) {
+            if (!section.items)
+                continue;
+            for (const item of section.items) {
+                timeline.push({
+                    event_type: section.type,
+                    event_ko: EVENT[section.type].ko,
+                    date: pickEventDate(item),
+                    ...item,
+                });
+            }
+        }
+        timeline.sort((a, b) => String(b.date).localeCompare(String(a.date)));
+        const typeCounts = {};
+        for (const entry of timeline) {
+            const t = String(entry.event_type);
+            typeCounts[t] = (typeCounts[t] ?? 0) + 1;
+        }
+        return {
+            mode: "timeline",
+            resolved: record,
+            period: { start: bgn_de ?? null, end: end_de ?? null },
+            event_types: targets,
+            total_events: timeline.length,
+            event_type_counts: typeCounts,
+            timeline,
+            sections_meta: sections.map((s) => ({
+                type: s.type,
+                endpoint: s.endpoint,
+                status: s.status ?? null,
+                count: s.count ?? 0,
+                message: s.message ?? null,
+                error: s.error ?? null,
+            })),
+        };
+    },
+});

package/build/tools/get-executive-compensation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * get_executive_compensation — 임원 보수 6개 섹션 병렬 합성
+ *
+ *  - 전체 보수 (hmvAuditAllSttus)
+ *  - 개인별 5억 이상 (hmvAuditIndvdlBySttus)
+ *  - 상위 5명 (indvdlByPay)
+ *  - 미등기 임원 (unrstExctvMendngSttus)
+ *  - 주총 승인금액 (drctrAdtAllMendngSttusGmtsckConfmAmount)
+ *  - 유형별 지급금액 (drctrAdtAllMendngSttusMendngPymntamtTyCl)
+ *
+ * "이 회사 연봉 구조 다 보여줘" 를 1회 호출로.
+ */
+export declare const getExecutiveCompensationTool: import("./_helpers.js").ToolDef;

package/build/tools/get-executive-compensation.js

@@ -0,0 +1,89 @@
+/**
+ * get_executive_compensation — 임원 보수 6개 섹션 병렬 합성
+ *
+ *  - 전체 보수 (hmvAuditAllSttus)
+ *  - 개인별 5억 이상 (hmvAuditIndvdlBySttus)
+ *  - 상위 5명 (indvdlByPay)
+ *  - 미등기 임원 (unrstExctvMendngSttus)
+ *  - 주총 승인금액 (drctrAdtAllMendngSttusGmtsckConfmAmount)
+ *  - 유형별 지급금액 (drctrAdtAllMendngSttusMendngPymntamtTyCl)
+ *
+ * "이 회사 연봉 구조 다 보여줘" 를 1회 호출로.
+ */
+import { z } from "zod";
+import { defineTool, resolveCorp } from "./_helpers.js";
+const REPORT_CODE = {
+    q1: "11013",
+    half: "11012",
+    q3: "11014",
+    annual: "11011",
+};
+const SECTIONS = {
+    total: "hmvAuditAllSttus",
+    individual_5eok: "hmvAuditIndvdlBySttus",
+    top5: "indvdlByPay",
+    unregistered: "unrstExctvMendngSttus",
+    approval_limit: "drctrAdtAllMendngSttusGmtsckConfmAmount",
+    by_type: "drctrAdtAllMendngSttusMendngPymntamtTyCl",
+};
+const Input = z.object({
+    corp: z.string().min(1).describe("회사명/종목코드/corp_code"),
+    year: z.number().int().min(2015),
+    report: z.enum(["q1", "half", "q3", "annual"]).default("annual"),
+    sections: z
+        .array(z.enum(Object.keys(SECTIONS)))
+        .optional()
+        .describe("조회할 섹션 (미지정 시 6개 모두). total=전체 평균, individual_5eok=개인별 5억↑, top5=상위 5인, unregistered=미등기 임원, approval_limit=주총 승인한도, by_type=직책별 지급금액"),
+});
+export const getExecutiveCompensationTool = defineTool({
+    name: "get_executive_compensation",
+    description: "임원 보수 6개 섹션을 한 번에 합성 조회: 전체·개인별 5억 이상·상위 5인·미등기·주총 승인금액·유형별. " +
+        "(단일 섹션은 get_periodic_report 로도 조회 가능.)",
+    input: Input,
+    handler: async (ctx, args) => {
+        const record = resolveCorp(ctx.resolver, args.corp);
+        const reprt_code = REPORT_CODE[args.report];
+        const bsns_year = String(args.year);
+        const targets = args.sections ?? Object.keys(SECTIONS);
+        const results = await Promise.all(targets.map(async (key) => {
+            const endpoint = SECTIONS[key];
+            try {
+                const raw = await ctx.client.getJson(`${endpoint}.json`, {
+                    corp_code: record.corp_code,
+                    bsns_year,
+                    reprt_code,
+                });
+                if (raw.status !== "000") {
+                    return {
+                        section: key,
+                        endpoint,
+                        status: raw.status,
+                        message: raw.message,
+                        items: [],
+                    };
+                }
+                return {
+                    section: key,
+                    endpoint,
+                    status: raw.status,
+                    count: raw.list?.length ?? 0,
+                    items: raw.list ?? [],
+                };
+            }
+            catch (e) {
+                return {
+                    section: key,
+                    endpoint,
+                    error: e instanceof Error ? e.message : String(e),
+                    items: [],
+                };
+            }
+        }));
+        return {
+            resolved: record,
+            year: args.year,
+            report: args.report,
+            sections: results,
+        };
+    },
+});