@mseep/korean-dart-mcp 0.9.3

package/build/tools/index.js

@@ -0,0 +1,66 @@
+/**
+ * DART MCP 도구 레지스트리 — 15개
+ *
+ * v0.7.0 통폐합:
+ *   - get_financials 가 get_full_financials 흡수 (scope: summary/full)
+ *   - buffett_quality_snapshot 가 quality_compare 흡수 (corps 배열)
+ *   - search_disclosures 가 list_recent_filings 흡수 (preset + 페이지 병렬화)
+ */
+import { resolveCorpCodeTool } from "./resolve-corp-code.js";
+import { searchDisclosuresTool } from "./search-disclosures.js";
+import { getCompanyTool } from "./get-company.js";
+import { getFinancialsTool } from "./get-financials.js";
+import { downloadDocumentTool } from "./download-document.js";
+import { getXbrlTool } from "./get-xbrl.js";
+import { getPeriodicReportTool } from "./get-periodic-report.js";
+import { getShareholdersTool } from "./get-shareholders.js";
+import { getExecutiveCompensationTool } from "./get-executive-compensation.js";
+import { getMajorHoldingsTool } from "./get-major-holdings.js";
+import { getCorporateEventTool } from "./get-corporate-event.js";
+import { insiderSignalTool } from "./insider-signal.js";
+import { disclosureAnomalyTool } from "./disclosure-anomaly.js";
+import { buffettQualitySnapshotTool } from "./buffett-quality-snapshot.js";
+import { getAttachmentsTool } from "./get-attachments.js";
+/**
+ * 15개 도구.
+ *
+ *  기본 조회 (7):
+ *   [x]  1. resolve_corp_code
+ *   [x]  2. search_disclosures            (preset + all_pages 병렬 통합)
+ *   [x]  3. get_company
+ *   [x]  4. get_financials                (scope: summary/full 통합)
+ *   [x]  5. download_document             (format: markdown/raw/text)
+ *   [x]  6. get_xbrl
+ *   [x]  7. get_periodic_report           (29 섹션 enum)
+ *
+ *  합성 래퍼 (4):
+ *   [x]  8. get_shareholders
+ *   [x]  9. get_executive_compensation
+ *   [x] 10. get_major_holdings
+ *   [x] 11. get_corporate_event           (36 enum + timeline mode)
+ *
+ *  애널리스트 프레임 (3 · 킬러):
+ *   [x] 12. insider_signal
+ *   [x] 13. disclosure_anomaly
+ *   [x] 14. buffett_quality_snapshot      (corps 배열 → 1개=snapshot / 2+=compare)
+ *
+ *  원문 분석 (1):
+ *   [x] 15. get_attachments               (kordoc + ZIP 재귀)
+ */
+export const TOOL_REGISTRY = [
+    resolveCorpCodeTool,
+    searchDisclosuresTool,
+    getCompanyTool,
+    getFinancialsTool,
+    downloadDocumentTool,
+    getXbrlTool,
+    getPeriodicReportTool,
+    getShareholdersTool,
+    getExecutiveCompensationTool,
+    getMajorHoldingsTool,
+    getCorporateEventTool,
+    insiderSignalTool,
+    disclosureAnomalyTool,
+    buffettQualitySnapshotTool,
+    getAttachmentsTool,
+];

package/build/tools/insider-signal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * insider_signal — 임원·주요주주 거래 시그널 집계 (킬러 포인트)
+ *
+ * 기반 데이터: elestock.json (DS004 임원·주요주주 소유보고)
+ *
+ * 기존 Python 래퍼는 raw 테이블만 반환. 여기서는 버핏·피셔 식 "내부자가 자기 돈으로 사는가" 를
+ * 정량화해서 LLM 에 바로 해석 가능한 시그널 단위로 제공:
+ *   - 매수자 / 매도자 수
+ *   - 순증감 주식수
+ *   - 분기 단위 "cluster": N명 이상 같은 방향 거래
+ *   - 등기임원 vs 미등기, 임원 vs 주요주주 구분
+ *
+ * 주의: 이는 투자 권유가 아니라 LLM 이 경영진 시그널을 해석하는 데이터 프레임 제공.
+ */
+export declare const insiderSignalTool: import("./_helpers.js").ToolDef;

package/build/tools/insider-signal.js

@@ -0,0 +1,208 @@
+/**
+ * insider_signal — 임원·주요주주 거래 시그널 집계 (킬러 포인트)
+ *
+ * 기반 데이터: elestock.json (DS004 임원·주요주주 소유보고)
+ *
+ * 기존 Python 래퍼는 raw 테이블만 반환. 여기서는 버핏·피셔 식 "내부자가 자기 돈으로 사는가" 를
+ * 정량화해서 LLM 에 바로 해석 가능한 시그널 단위로 제공:
+ *   - 매수자 / 매도자 수
+ *   - 순증감 주식수
+ *   - 분기 단위 "cluster": N명 이상 같은 방향 거래
+ *   - 등기임원 vs 미등기, 임원 vs 주요주주 구분
+ *
+ * 주의: 이는 투자 권유가 아니라 LLM 이 경영진 시그널을 해석하는 데이터 프레임 제공.
+ */
+import { z } from "zod";
+import { defineTool, normalizeDate, resolveCorp } from "./_helpers.js";
+const Input = z.object({
+    corp: z.string().min(1).describe("회사명/종목코드/corp_code"),
+    start: z.string().optional().describe("기간 시작 (YYYY-MM-DD / YYYYMMDD)"),
+    end: z.string().optional().describe("기간 종료"),
+    cluster_threshold: z
+        .number()
+        .int()
+        .min(2)
+        .default(3)
+        .describe("cluster 인정 최소 인원 (기본 3: 분기 내 같은 방향 거래 3명 이상)"),
+    reporters_topn: z
+        .number()
+        .int()
+        .min(0)
+        .max(50)
+        .default(5)
+        .describe("분기별 reporters 명단 상위 N (절대값 큰 순). 대형사는 분기당 수백명 → 디폴트 5. 0=빈 배열."),
+});
+/** "-1,234" 또는 "1234" 같은 문자열 → 숫자. 파싱 실패 시 0. */
+function toInt(v) {
+    if (!v)
+        return 0;
+    const n = Number(v.replace(/[,\s]/g, ""));
+    return Number.isFinite(n) ? n : 0;
+}
+/** DART는 rcept_dt 를 "YYYY-MM-DD" 또는 "YYYYMMDD" 둘 다 쓴다. 8자리 숫자로 정규화. */
+function normalizeRcept(s) {
+    if (!s)
+        return null;
+    const digits = s.replace(/\D/g, "");
+    return /^\d{8}$/.test(digits) ? digits : null;
+}
+function quarterOf(yyyymmdd) {
+    if (!/^\d{8}$/.test(yyyymmdd))
+        return "unknown";
+    const y = yyyymmdd.slice(0, 4);
+    const m = parseInt(yyyymmdd.slice(4, 6), 10);
+    const q = Math.ceil(m / 3);
+    return `${y}Q${q}`;
+}
+export const insiderSignalTool = defineTool({
+    name: "insider_signal",
+    description: "임원·주요주주 거래(DS004 elestock)를 매수·매도 클러스터로 집계. " +
+        "기간 내 순증감·매수자수·분기별 클러스터 여부 산출. " +
+        "버핏 철학의 '경영진 본인 돈으로 매수' 시그널을 LLM 해석 가능한 단위로 제공.",
+    input: Input,
+    handler: async (ctx, args) => {
+        const record = resolveCorp(ctx.resolver, args.corp);
+        const startYmd = args.start ? normalizeDate(args.start) : null;
+        const endYmd = args.end ? normalizeDate(args.end) : null;
+        const raw = await ctx.client.getJson("elestock.json", {
+            corp_code: record.corp_code,
+        });
+        if (raw.status !== "000" && raw.status !== "013") {
+            throw new Error(`DART elestock 오류 [${raw.status}]: ${raw.message}`);
+        }
+        const all = raw.list ?? [];
+        // 기간 필터 (YYYY-MM-DD / YYYYMMDD 모두 수용)
+        const filtered = all
+            .map((it) => ({ it, ymd: normalizeRcept(it.rcept_dt) }))
+            .filter(({ ymd }) => {
+            if (!ymd)
+                return false;
+            if (startYmd && ymd < startYmd)
+                return false;
+            if (endYmd && ymd > endYmd)
+                return false;
+            return true;
+        })
+            .map(({ it, ymd }) => ({ ...it, rcept_dt: ymd }));
+        // 집계
+        let buyCount = 0; // 매수(증가) 건수
+        let sellCount = 0; // 매도(감소) 건수
+        let netChange = 0; // 순증감 수량
+        const buyers = new Set();
+        const sellers = new Set();
+        const byQuarter = {};
+        for (const item of filtered) {
+            const delta = toInt(item.sp_stock_lmp_irds_cnt);
+            if (delta === 0)
+                continue;
+            const name = item.repror ?? "(unknown)";
+            const role = item.isu_exctv_ofcps ||
+                item.isu_main_shrholdr ||
+                (item.isu_exctv_rgist_at === "Y" ? "등기임원" : "관계자");
+            const q = quarterOf(item.rcept_dt ?? "");
+            byQuarter[q] ?? (byQuarter[q] = {
+                buyers: new Set(),
+                sellers: new Set(),
+                netChange: 0,
+                reporters: [],
+            });
+            byQuarter[q].netChange += delta;
+            byQuarter[q].reporters.push({ name, change: delta, role });
+            netChange += delta;
+            if (delta > 0) {
+                buyCount++;
+                buyers.add(name);
+                byQuarter[q].buyers.add(name);
+            }
+            else {
+                sellCount++;
+                sellers.add(name);
+                byQuarter[q].sellers.add(name);
+            }
+        }
+        const clusters = Object.entries(byQuarter)
+            .map(([quarter, agg]) => {
+            const buyers_n = agg.buyers.size;
+            const sellers_n = agg.sellers.size;
+            const direction = buyers_n >= args.cluster_threshold && buyers_n > sellers_n
+                ? "buy_cluster"
+                : sellers_n >= args.cluster_threshold && sellers_n > buyers_n
+                    ? "sell_cluster"
+                    : "mixed_or_thin";
+            // reporters 는 |change| 큰 순 상위 N 만 (대형사 폭발 방지)
+            const sortedReporters = [...agg.reporters].sort((a, b) => Math.abs(b.change) - Math.abs(a.change));
+            const topReporters = sortedReporters.slice(0, args.reporters_topn);
+            return {
+                quarter,
+                buyers: buyers_n,
+                sellers: sellers_n,
+                net_change: agg.netChange,
+                cluster: direction,
+                reporters_total: agg.reporters.length,
+                reporters_truncated: agg.reporters.length > args.reporters_topn,
+                reporters: topReporters,
+            };
+        })
+            .sort((a, b) => b.quarter.localeCompare(a.quarter));
+        const strongestCluster = clusters.find((c) => c.cluster === "buy_cluster") ??
+            clusters.find((c) => c.cluster === "sell_cluster") ??
+            null;
+        const signal = buyers.size >= args.cluster_threshold && buyers.size > sellers.size * 2
+            ? "strong_buy_cluster"
+            : sellers.size >= args.cluster_threshold && sellers.size > buyers.size * 2
+                ? "strong_sell_cluster"
+                : "neutral_or_mixed";
+        const summary_text = buildInsiderSummary({
+            corpName: record.corp_name,
+            reports: filtered.length,
+            buyCount,
+            sellCount,
+            buyers: buyers.size,
+            sellers: sellers.size,
+            netChange,
+            signal,
+            strongestCluster,
+            startYmd,
+            endYmd,
+        });
+        return {
+            resolved: record,
+            period: { start: startYmd, end: endYmd },
+            cluster_threshold: args.cluster_threshold,
+            summary_text,
+            summary: {
+                reports_total: filtered.length,
+                buy_events: buyCount,
+                sell_events: sellCount,
+                unique_buyers: buyers.size,
+                unique_sellers: sellers.size,
+                net_change_shares: netChange,
+                signal,
+                strongest_quarter: strongestCluster?.quarter ?? null,
+            },
+            quarterly_clusters: clusters,
+            note: "DART 는 변동사유(장내매수/증여/유상증자 등)를 구분하지 않음. 순수 자발적 매수/매도 해석 시 raw items 의 report_tp·chg_rsn 참조 권장.",
+        };
+    },
+});
+function buildInsiderSummary(p) {
+    const periodStr = p.startYmd || p.endYmd
+        ? `${p.startYmd ?? "처음"}~${p.endYmd ?? "현재"}`
+        : "전체 보고 기간";
+    if (p.reports === 0)
+        return `${p.corpName}: ${periodStr} 임원·주요주주 변동 보고 없음.`;
+    const netStr = p.netChange === 0
+        ? "순증감 0"
+        : p.netChange > 0
+            ? `순매수 +${p.netChange.toLocaleString("ko-KR")}주`
+            : `순매도 ${p.netChange.toLocaleString("ko-KR")}주`;
+    const signalStr = p.signal === "strong_buy_cluster"
+        ? "→ 내부자 매수 클러스터 시그널"
+        : p.signal === "strong_sell_cluster"
+            ? "→ 내부자 매도 클러스터 시그널"
+            : "→ 중립/혼조";
+    const clusterStr = p.strongestCluster
+        ? ` 최강 클러스터: ${p.strongestCluster.quarter} (매수 ${p.strongestCluster.buyers}명/매도 ${p.strongestCluster.sellers}명).`
+        : "";
+    return `${p.corpName} ${periodStr}: ${p.reports}건 보고 (매수 ${p.buyCount} / 매도 ${p.sellCount}). 고유 매수자 ${p.buyers}명 / 매도자 ${p.sellers}명, ${netStr}. ${signalStr}.${clusterStr}`;
+}

package/build/tools/resolve-corp-code.d.ts

@@ -0,0 +1,7 @@
+/**
+ * resolve_corp_code — 회사명·종목코드 → corp_code 조회
+ *
+ * 모든 DART 엔드포인트는 8자리 corp_code 를 요구하지만, LLM 은 보통 회사명만 안다.
+ * 서버가 기동 시 덤프를 SQLite 에 선적재해두므로 LIKE 검색이 수 ms 이내.
+ */
+export declare const resolveCorpCodeTool: import("./_helpers.js").ToolDef;

package/build/tools/resolve-corp-code.js

@@ -0,0 +1,40 @@
+/**
+ * resolve_corp_code — 회사명·종목코드 → corp_code 조회
+ *
+ * 모든 DART 엔드포인트는 8자리 corp_code 를 요구하지만, LLM 은 보통 회사명만 안다.
+ * 서버가 기동 시 덤프를 SQLite 에 선적재해두므로 LIKE 검색이 수 ms 이내.
+ */
+import { z } from "zod";
+import { defineTool } from "./_helpers.js";
+const Input = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("회사명(한/영), 6자리 종목코드, 또는 8자리 corp_code"),
+    limit: z.number().int().min(1).max(50).default(10).describe("최대 반환 개수"),
+});
+export const resolveCorpCodeTool = defineTool({
+    name: "resolve_corp_code",
+    description: "회사명 또는 종목코드로 OpenDART corp_code 를 조회합니다. " +
+        "상장사·정확일치·짧은 이름 순으로 정렬해 반환. " +
+        "모든 다른 도구에 회사명을 바로 넘겨도 내부에서 자동 해결되지만, " +
+        "결과가 모호할 때 후보를 확인하는 용도로 사용하세요.",
+    input: Input,
+    handler: async (ctx, args) => {
+        const q = args.query.trim();
+        const direct = /^\d{8}$/.test(q)
+            ? ctx.resolver.byCorpCode(q)
+            : /^\d{6}$/.test(q)
+                ? ctx.resolver.byStockCode(q)
+                : undefined;
+        if (direct) {
+            return { query: args.query, count: 1, results: [direct] };
+        }
+        const results = ctx.resolver.search(args.query, args.limit);
+        return {
+            query: args.query,
+            count: results.length,
+            results,
+        };
+    },
+});

package/build/tools/search-disclosures.d.ts

@@ -0,0 +1,14 @@
+/**
+ * search_disclosures — 공시 검색 + 프리셋 배치 + 페이지 병렬화
+ *
+ * 세 모드 지원:
+ *   1. 페이지 모드 (기본): 단일 페이지 (page+size)
+ *   2. 프리셋 모드: `preset` 지정 → DART pblntf_ty + report_nm 정규식 자동 + 전량 수집
+ *   3. 전량 모드: `all_pages: true` → 필터 없이 기간 전체 병렬 수집
+ *
+ * 페이지 병렬화: 1페이지 먼저 → total_page 확인 → 나머지 병렬 (동시 5개)
+ * 기존 list_recent_filings 는 이 도구의 preset 모드로 흡수.
+ *
+ * 참고: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001&apiId=2019018
+ */
+export declare const searchDisclosuresTool: import("./_helpers.js").ToolDef;

package/build/tools/search-disclosures.js

@@ -0,0 +1,300 @@
+/**
+ * search_disclosures — 공시 검색 + 프리셋 배치 + 페이지 병렬화
+ *
+ * 세 모드 지원:
+ *   1. 페이지 모드 (기본): 단일 페이지 (page+size)
+ *   2. 프리셋 모드: `preset` 지정 → DART pblntf_ty + report_nm 정규식 자동 + 전량 수집
+ *   3. 전량 모드: `all_pages: true` → 필터 없이 기간 전체 병렬 수집
+ *
+ * 페이지 병렬화: 1페이지 먼저 → total_page 확인 → 나머지 병렬 (동시 5개)
+ * 기존 list_recent_filings 는 이 도구의 preset 모드로 흡수.
+ *
+ * 참고: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001&apiId=2019018
+ */
+import { z } from "zod";
+import { defineTool, normalizeDate, resolveCorp } from "./_helpers.js";
+// OpenDART 공시유형 (pblntf_ty) — enum 노출용 별칭
+const KIND_MAP = {
+    periodic: "A",
+    major: "B",
+    issuance: "C",
+    holdings: "D",
+    other: "E",
+    audit: "F",
+    fund: "G",
+    abs: "H",
+    exchange: "I",
+    ftc: "J",
+};
+const PRESETS = {
+    // 자기주식
+    treasury_buy: { kind: "B", keyword: /자기주식.*취득/, label: "자기주식 취득 결정" },
+    treasury_sell: { kind: "B", keyword: /자기주식.*처분/, label: "자기주식 처분 결정" },
+    treasury_trust: { kind: "B", keyword: /자기주식.*신탁/, label: "자기주식 신탁 계약" },
+    // 사채 발행
+    cb_issue: { kind: "B", keyword: /전환사채/, label: "전환사채(CB) 발행결정" },
+    bw_issue: { kind: "B", keyword: /신주인수권부사채/, label: "신주인수권부사채(BW) 발행결정" },
+    eb_issue: { kind: "B", keyword: /교환사채/, label: "교환사채(EB) 발행결정" },
+    // 자본 증감
+    rights_offering: { kind: "B", keyword: /유상증자/, label: "유상증자 결정" },
+    bonus_issue: { kind: "B", keyword: /무상증자/, label: "무상증자 결정" },
+    capital_reduction: { kind: "B", keyword: /감자/, label: "감자 결정" },
+    // 지배구조
+    merger: { kind: "B", keyword: /합병/, label: "합병 결정" },
+    split: { kind: "B", keyword: /분할/, label: "분할 결정" },
+    stock_exchange: { kind: "B", keyword: /주식교환|주식이전/, label: "주식교환·이전" },
+    // 양수도
+    business_transfer: { kind: "B", keyword: /영업양도/, label: "영업양도" },
+    business_acquisition: { kind: "B", keyword: /영업양수/, label: "영업양수" },
+    // 지분
+    large_holding_5pct: { kind: "D", keyword: null, label: "지분공시 전체(5%룰+임원지분)" },
+    // 정기공시
+    annual_report: { kind: "A", keyword: /사업보고서/, label: "사업보고서" },
+    half_report: { kind: "A", keyword: /반기보고서/, label: "반기보고서" },
+    quarterly_report: { kind: "A", keyword: /분기보고서/, label: "분기보고서" },
+    // 감사
+    audit_report: { kind: "F", keyword: null, label: "외부감사 관련 공시 전체" },
+    // 정정
+    correction_all: {
+        kind: null,
+        keyword: /\[기재정정\]|\[첨부정정\]|\[첨부추가\]/,
+        label: "정정공시 전체",
+    },
+    // 부실/소송
+    insolvency: {
+        kind: "B",
+        keyword: /부도발생|영업정지|회생절차|해산사유|채권은행/,
+        label: "부실·법적 리스크",
+    },
+    litigation: { kind: "B", keyword: /소송/, label: "소송 제기" },
+};
+const PRESET_KEYS = Object.keys(PRESETS);
+const Input = z.object({
+    corp: z.string().optional().describe("회사명/종목코드/corp_code. 생략 시 전체"),
+    begin: z.string().optional().describe("시작일 YYYY-MM-DD (생략 시 기본값)"),
+    end: z.string().optional().describe("종료일 (생략 시 오늘)"),
+    days: z
+        .number()
+        .int()
+        .min(1)
+        .max(365)
+        .optional()
+        .describe("begin 대신 오늘 기준 과거 N일 (preset 모드 기본 7, 일반 90)"),
+    kind: z
+        .enum(Object.keys(KIND_MAP))
+        .optional()
+        .describe("공시유형: periodic/major/issuance/holdings/audit/other/fund/abs/exchange/ftc"),
+    preset: z
+        .enum(PRESET_KEYS)
+        .optional()
+        .describe("프리셋 22종: treasury_buy/sell/trust · cb/bw/eb_issue · rights_offering/bonus_issue/capital_reduction · merger/split/stock_exchange · business_transfer/acquisition · large_holding_5pct · annual_report/half_report/quarterly_report · audit_report · correction_all · insolvency · litigation. 지정 시 kind·키워드 자동 + 전량 페이지 병렬 수집."),
+    final_only: z.boolean().default(false).describe("최종보고서만 (정정공시 제외)"),
+    include_corrections: z
+        .boolean()
+        .default(false)
+        .describe("정정공시 포함 (preset 모드 전용). correction_all 은 자동 true."),
+    all_pages: z
+        .boolean()
+        .default(false)
+        .describe("preset 없이도 기간 전체를 병렬 수집. true 시 page/size 대신 limit 적용."),
+    page: z.number().int().min(1).default(1).describe("페이지 모드 시 페이지 번호"),
+    size: z.number().int().min(1).max(100).default(20).describe("페이지 모드 시 페이지 크기"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(3000)
+        .default(500)
+        .describe("배치 모드 최종 반환 개수 상한"),
+    concurrency: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .default(5)
+        .describe("배치 모드 페이지 병렬 동시성 (1~10, 기본 5). 높이면 빠르지만 DART 일일 20,000건 한도/분당 쿼터 근접 위험."),
+});
+function ymd(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}${m}${day}`;
+}
+function daysAgo(n) {
+    const d = new Date();
+    d.setDate(d.getDate() - n);
+    return ymd(d);
+}
+function parseYmd(s) {
+    return new Date(parseInt(s.slice(0, 4), 10), parseInt(s.slice(4, 6), 10) - 1, parseInt(s.slice(6, 8), 10));
+}
+function daysBetween(a, b) {
+    const ms = parseYmd(b).getTime() - parseYmd(a).getTime();
+    return Math.floor(ms / (24 * 3600 * 1000));
+}
+/** [bgn, end] 구간을 chunkDays 이하로 분할. 마지막 청크는 end 고정. */
+function splitDateRange(bgn, end, chunkDays) {
+    const out = [];
+    let cursor = parseYmd(bgn);
+    const last = parseYmd(end);
+    while (cursor.getTime() <= last.getTime()) {
+        const chunkEnd = new Date(cursor);
+        chunkEnd.setDate(chunkEnd.getDate() + chunkDays - 1);
+        if (chunkEnd.getTime() > last.getTime())
+            chunkEnd.setTime(last.getTime());
+        out.push({ bgn: ymd(cursor), end: ymd(chunkEnd) });
+        cursor = new Date(chunkEnd);
+        cursor.setDate(cursor.getDate() + 1);
+    }
+    return out;
+}
+/** total_page 파악 후 2..N 페이지 병렬 수집 (동시성 제한). */
+async function fetchAllPages(client, baseParams, concurrency = 5) {
+    const first = await client.getJson("list.json", {
+        ...baseParams,
+        page_no: 1,
+        page_count: 100,
+    });
+    if (first.status === "013")
+        return { items: [], totalPages: 0 };
+    if (first.status !== "000") {
+        throw new Error(`DART list 오류 [${first.status}]: ${first.message}`);
+    }
+    const items = [...(first.list ?? [])];
+    const totalPages = Math.min(first.total_page ?? 1, 30); // 상한 30 페이지(=3000건)
+    if (totalPages <= 1)
+        return { items, totalPages };
+    const pages = [];
+    for (let p = 2; p <= totalPages; p++)
+        pages.push(p);
+    for (let i = 0; i < pages.length; i += concurrency) {
+        const batch = pages.slice(i, i + concurrency);
+        const responses = await Promise.all(batch.map((p) => client.getJson("list.json", {
+            ...baseParams,
+            page_no: p,
+            page_count: 100,
+        })));
+        for (const r of responses) {
+            if (r.status === "000")
+                items.push(...(r.list ?? []));
+        }
+    }
+    return { items, totalPages };
+}
+export const searchDisclosuresTool = defineTool({
+    name: "search_disclosures",
+    description: "DART 공시 검색 (3 모드): " +
+        "기본(단일 페이지, page+size), preset(22개 프리셋 자동 필터+전량 병렬), all_pages(프리셋 없이 기간 전체 병렬). " +
+        "rcp_no(rcept_no) 로 download_document / get_attachments 연동.",
+    input: Input,
+    handler: async (ctx, args) => {
+        const isBatch = Boolean(args.preset) || args.all_pages;
+        // 기간 기본값
+        const defaultDays = args.preset ? 7 : 90;
+        const end_de = args.end ? normalizeDate(args.end) : ymd(new Date());
+        const bgn_de = args.begin
+            ? normalizeDate(args.begin)
+            : daysAgo(args.days ?? defaultDays);
+        // corp 해석
+        let corp_code;
+        let resolved = null;
+        if (args.corp) {
+            const r = resolveCorp(ctx.resolver, args.corp);
+            corp_code = r.corp_code;
+            resolved = { corp_code: r.corp_code, corp_name: r.corp_name };
+        }
+        // 프리셋 적용 → kind 자동
+        const preset = args.preset ? PRESETS[args.preset] : null;
+        const pblntf_ty = preset?.kind ?? (args.kind ? KIND_MAP[args.kind] : undefined);
+        const baseParams = {
+            corp_code,
+            bgn_de,
+            end_de,
+            pblntf_ty,
+            last_reprt_at: args.final_only ? "Y" : undefined,
+        };
+        if (!isBatch) {
+            // === 단일 페이지 모드 ===
+            const raw = await ctx.client.getJson("list.json", {
+                ...baseParams,
+                page_no: args.page,
+                page_count: args.size,
+            });
+            if (raw.status === "013") {
+                return {
+                    mode: "page",
+                    period: { start: bgn_de, end: end_de },
+                    corp: resolved,
+                    total_count: 0,
+                    page: args.page,
+                    total_pages: 0,
+                    items: [],
+                };
+            }
+            if (raw.status !== "000") {
+                throw new Error(`DART 응답 오류 [${raw.status}]: ${raw.message}`);
+            }
+            return {
+                mode: "page",
+                period: { start: bgn_de, end: end_de },
+                corp: resolved,
+                total_count: raw.total_count ?? 0,
+                page: raw.page_no ?? args.page,
+                total_pages: raw.total_page ?? 1,
+                items: raw.list ?? [],
+            };
+        }
+        // === 배치 모드 (preset 또는 all_pages) ===
+        // OpenDART 제약: corp_code 없이 list.json 호출 시 bgn_de~end_de 는 90일(3개월) 이내.
+        // 기간 > 90일 && 회사 미지정 시 90일 청크로 자동 분할 (v0.9.0+).
+        // 청크 상한: bgn_de=1900 같은 악의·실수 입력에서 수천 chunks 폭발 방지.
+        const MAX_CHUNKS = 40; // ≈10년 × 4 청크/년
+        const rangeDays = daysBetween(bgn_de, end_de);
+        const needsSplit = !corp_code && rangeDays > 90;
+        const chunks = needsSplit
+            ? splitDateRange(bgn_de, end_de, 90)
+            : [{ bgn: bgn_de, end: end_de }];
+        if (chunks.length > MAX_CHUNKS) {
+            throw new Error(`기간이 너무 깁니다 (${chunks.length} chunks > 상한 ${MAX_CHUNKS}). corp 지정 또는 기간 축소 필요.`);
+        }
+        let collected = [];
+        let totalPages = 0;
+        for (const chunk of chunks) {
+            const { items, totalPages: tp } = await fetchAllPages(ctx.client, { ...baseParams, bgn_de: chunk.bgn, end_de: chunk.end }, args.concurrency);
+            collected.push(...items);
+            totalPages += tp;
+        }
+        const includeCorrections = args.include_corrections || args.preset === "correction_all";
+        const filtered = collected.filter((item) => {
+            if (!includeCorrections && /\[(기재정정|첨부정정|첨부추가)\]/.test(item.report_nm)) {
+                return false;
+            }
+            if (preset?.keyword && !preset.keyword.test(item.report_nm))
+                return false;
+            return true;
+        });
+        const limited = filtered.slice(0, args.limit);
+        return {
+            mode: "batch",
+            preset: args.preset ?? null,
+            preset_label: preset?.label ?? null,
+            period: { start: bgn_de, end: end_de },
+            corp: resolved,
+            include_corrections: includeCorrections,
+            chunks: chunks.length > 1 ? chunks.length : undefined,
+            pages_fetched: totalPages,
+            total_fetched: collected.length,
+            matched: filtered.length,
+            returned: limited.length,
+            items: limited.map((it) => ({
+                rcept_no: it.rcept_no,
+                rcept_dt: it.rcept_dt,
+                corp_name: it.corp_name,
+                corp_code: it.corp_code,
+                corp_cls: it.corp_cls,
+                report_nm: it.report_nm,
+                flr_nm: it.flr_nm ?? null,
+            })),
+        };
+    },
+});