@mseep/korean-dart-mcp 0.9.3

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

@@ -0,0 +1,15 @@
+/**
+ * get_financials — 재무정보 통합 (주요계정 summary + 전체 재무제표 full)
+ *
+ * scope="summary" (기본): fnlttSinglAcnt / fnlttMultiAcnt 주요계정
+ *   - corps 1개 → 단일사 API
+ *   - corps 2+  → 다중사 비교 API
+ * scope="full": fnlttSinglAcntAll 전체 재무제표 (수백~천여 행)
+ *   - corps 1개 전용 (여러 개면 에러)
+ *   - fs 로 연결(CFS) / 별도(OFS) 선택
+ *
+ * 참고:
+ *   summary: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003&apiId=2019016
+ *   full:    https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003&apiId=2019020
+ */
+export declare const getFinancialsTool: import("./_helpers.js").ToolDef;

package/build/tools/get-financials.js

@@ -0,0 +1,127 @@
+/**
+ * get_financials — 재무정보 통합 (주요계정 summary + 전체 재무제표 full)
+ *
+ * scope="summary" (기본): fnlttSinglAcnt / fnlttMultiAcnt 주요계정
+ *   - corps 1개 → 단일사 API
+ *   - corps 2+  → 다중사 비교 API
+ * scope="full": fnlttSinglAcntAll 전체 재무제표 (수백~천여 행)
+ *   - corps 1개 전용 (여러 개면 에러)
+ *   - fs 로 연결(CFS) / 별도(OFS) 선택
+ *
+ * 참고:
+ *   summary: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003&apiId=2019016
+ *   full:    https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003&apiId=2019020
+ */
+import { z } from "zod";
+import { defineTool, resolveCorp } from "./_helpers.js";
+const REPORT_CODE = {
+    q1: "11013",
+    half: "11012",
+    q3: "11014",
+    annual: "11011",
+};
+const FS_DIV = {
+    consolidated: "CFS",
+    separate: "OFS",
+};
+const Input = z
+    .object({
+    corps: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("회사 배열. scope=summary 면 1개(단일) 또는 2+(다중사 비교). full 은 1개만."),
+    year: z.number().int().min(2015),
+    report: z
+        .enum(["q1", "half", "q3", "annual"])
+        .default("annual")
+        .describe("q1/half/q3/annual"),
+    scope: z
+        .enum(["summary", "full"])
+        .default("summary")
+        .describe("summary: 주요계정 8~10행 (빠름). full: 전체 재무제표(BS/IS/CF/CIS/SCE) 수백~천여 행"),
+    fs: z
+        .enum(["consolidated", "separate"])
+        .default("consolidated")
+        .describe("scope=full 시 연결(consolidated)/별도(separate) 선택"),
+    sj_div: z
+        .array(z.enum(["BS", "IS", "CF", "CIS", "SCE"]))
+        .optional()
+        .describe("scope=full 시 재무제표 종류 필터 (미지정 시 BS+IS — 기본 응답 사이즈 ~70% 절감). " +
+        "BS=재무상태표, IS=손익계산서, CF=현금흐름표, CIS=포괄손익계산서, SCE=자본변동표. " +
+        "전체 받으려면 [\"BS\",\"IS\",\"CF\",\"CIS\",\"SCE\"] 명시."),
+})
+    .refine((v) => v.scope !== "full" || v.corps.length === 1, {
+    message: "scope=full 은 corps 1개만 지원 (다중사 전체 재무제표 API 없음)",
+});
+export const getFinancialsTool = defineTool({
+    name: "get_financials",
+    description: "재무정보 조회 — scope=summary(주요계정, 단일/다중사 자동) 또는 full(전체 재무제표, 단일사). " +
+        "summary 는 매출·영업이익·당기순이익·자산/부채/자본 핵심만, full 은 BS/IS/CF 전체 수백 행.",
+    input: Input,
+    handler: async (ctx, args) => {
+        const records = args.corps.map((c) => resolveCorp(ctx.resolver, c));
+        const reprt_code = REPORT_CODE[args.report];
+        const bsns_year = String(args.year);
+        if (args.scope === "full") {
+            const raw = await ctx.client.getJson("fnlttSinglAcntAll.json", {
+                corp_code: records[0].corp_code,
+                bsns_year,
+                reprt_code,
+                fs_div: FS_DIV[args.fs],
+            });
+            if (raw.status !== "000") {
+                throw new Error(`DART 응답 오류 [${raw.status}]: ${raw.message}`);
+            }
+            const allItems = raw.list ?? [];
+            const filterDivs = args.sj_div ?? ["BS", "IS"];
+            const filterSet = new Set(filterDivs);
+            const items = allItems.filter((it) => filterSet.has(String(it.sj_div)));
+            return {
+                mode: "full",
+                resolved: records,
+                year: args.year,
+                report: args.report,
+                fs: args.fs,
+                sj_div_filter: filterDivs,
+                total_count: allItems.length,
+                count: items.length,
+                items,
+            };
+        }
+        // summary 모드
+        if (records.length === 1) {
+            const raw = await ctx.client.getJson("fnlttSinglAcnt.json", {
+                corp_code: records[0].corp_code,
+                bsns_year,
+                reprt_code,
+            });
+            if (raw.status !== "000") {
+                throw new Error(`DART 응답 오류 [${raw.status}]: ${raw.message}`);
+            }
+            return {
+                mode: "summary_single",
+                resolved: records,
+                year: args.year,
+                report: args.report,
+                items: raw.list ?? [],
+            };
+        }
+        // 다중사 — corp_code 콤마 연결
+        const corp_code = records.map((r) => r.corp_code).join(",");
+        const raw = await ctx.client.getJson("fnlttMultiAcnt.json", {
+            corp_code,
+            bsns_year,
+            reprt_code,
+        });
+        if (raw.status !== "000") {
+            throw new Error(`DART 응답 오류 [${raw.status}]: ${raw.message}`);
+        }
+        return {
+            mode: "summary_multi",
+            resolved: records,
+            year: args.year,
+            report: args.report,
+            items: raw.list ?? [],
+        };
+    },
+});

package/build/tools/get-major-holdings.d.ts

@@ -0,0 +1,10 @@
+/**
+ * get_major_holdings — DS004 지분공시 2개 엔드포인트 합성
+ *
+ *  - majorstock.json : 대량보유 상황보고 (5% 룰)
+ *  - elestock.json   : 임원·주요주주 소유보고
+ *
+ * 두 테이블 모두 특정 사업연도·보고서 코드 파라미터 없이 corp_code 만으로 동작.
+ * 두 관점(외부 5%+ 주주 vs 임원 본인 보유)을 한 번에 묶어 지분 구조 전체 뷰 제공.
+ */
+export declare const getMajorHoldingsTool: import("./_helpers.js").ToolDef;

package/build/tools/get-major-holdings.js

@@ -0,0 +1,117 @@
+/**
+ * get_major_holdings — DS004 지분공시 2개 엔드포인트 합성
+ *
+ *  - majorstock.json : 대량보유 상황보고 (5% 룰)
+ *  - elestock.json   : 임원·주요주주 소유보고
+ *
+ * 두 테이블 모두 특정 사업연도·보고서 코드 파라미터 없이 corp_code 만으로 동작.
+ * 두 관점(외부 5%+ 주주 vs 임원 본인 보유)을 한 번에 묶어 지분 구조 전체 뷰 제공.
+ */
+import { z } from "zod";
+import { defineTool, normalizeDate, resolveCorp } from "./_helpers.js";
+const Input = z.object({
+    corp: z.string().min(1).describe("회사명/종목코드/corp_code"),
+    include: z
+        .array(z.enum(["majorstock", "elestock"]))
+        .optional()
+        .describe("조회 대상 (미지정 시 둘 다). majorstock=대량보유 5%룰, elestock=임원·주요주주 본인 보유"),
+    start: z
+        .string()
+        .optional()
+        .describe("기간 시작 (YYYY-MM-DD / YYYYMMDD). 미지정 시 최근 3년."),
+    end: z
+        .string()
+        .optional()
+        .describe("기간 종료 (미지정 시 오늘)"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(2000)
+        .default(200)
+        .describe("최대 반환 행 수 (각 kind 별). 대형 상장사는 누적 수만 건 → 디폴트 200."),
+});
+function normalizeRcept(s) {
+    if (!s)
+        return null;
+    const digits = s.replace(/\D/g, "");
+    return /^\d{8}$/.test(digits) ? digits : null;
+}
+function defaultStart() {
+    const d = new Date();
+    d.setFullYear(d.getFullYear() - 3);
+    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 todayYmd() {
+    const d = new Date();
+    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}`;
+}
+export const getMajorHoldingsTool = defineTool({
+    name: "get_major_holdings",
+    description: "지분공시 2종 합성 조회: 대량보유(5%룰) + 임원·주요주주 본인 소유. " +
+        "내부자·외부 대주주 지분 이력을 한 번에 스냅샷.",
+    input: Input,
+    handler: async (ctx, args) => {
+        const record = resolveCorp(ctx.resolver, args.corp);
+        const targets = args.include ?? ["majorstock", "elestock"];
+        const startYmd = args.start ? normalizeDate(args.start) : defaultStart();
+        const endYmd = args.end ? normalizeDate(args.end) : todayYmd();
+        const results = await Promise.all(targets.map(async (kind) => {
+            try {
+                const raw = await ctx.client.getJson(`${kind}.json`, {
+                    corp_code: record.corp_code,
+                });
+                if (raw.status !== "000") {
+                    return {
+                        kind,
+                        status: raw.status,
+                        message: raw.message,
+                        total_count: 0,
+                        count: 0,
+                        items: [],
+                    };
+                }
+                const all = raw.list ?? [];
+                const filtered = all.filter((it) => {
+                    const ymd = normalizeRcept(it.rcept_dt);
+                    if (!ymd)
+                        return false;
+                    return ymd >= startYmd && ymd <= endYmd;
+                });
+                // 최신 순으로 잘라 limit 적용
+                filtered.sort((a, b) => String(b.rcept_dt ?? "").localeCompare(String(a.rcept_dt ?? "")));
+                const items = filtered.slice(0, args.limit);
+                return {
+                    kind,
+                    status: raw.status,
+                    total_count: all.length,
+                    filtered_count: filtered.length,
+                    count: items.length,
+                    truncated: filtered.length > args.limit,
+                    items,
+                };
+            }
+            catch (e) {
+                return {
+                    kind,
+                    error: e instanceof Error ? e.message : String(e),
+                    total_count: 0,
+                    count: 0,
+                    items: [],
+                };
+            }
+        }));
+        return {
+            resolved: record,
+            period: { start: startYmd, end: endYmd },
+            limit: args.limit,
+            results,
+        };
+    },
+});

package/build/tools/get-periodic-report.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_periodic_report — 정기보고서 주요정보 (DS002, 29개 엔드포인트 enum 압축)
+ *
+ * MCP 도구 폭발 방지를 위해 정기보고서 내 29개 섹션 조회를 `report_type` 파라미터로 단일화.
+ * 매핑 출처: FinanceData/OpenDartReader (https://github.com/FinanceData/OpenDartReader/blob/master/dart_report.py)
+ */
+export declare const getPeriodicReportTool: import("./_helpers.js").ToolDef;

package/build/tools/get-periodic-report.js

@@ -0,0 +1,100 @@
+/**
+ * get_periodic_report — 정기보고서 주요정보 (DS002, 29개 엔드포인트 enum 압축)
+ *
+ * MCP 도구 폭발 방지를 위해 정기보고서 내 29개 섹션 조회를 `report_type` 파라미터로 단일화.
+ * 매핑 출처: FinanceData/OpenDartReader (https://github.com/FinanceData/OpenDartReader/blob/master/dart_report.py)
+ */
+import { z } from "zod";
+import { defineTool, resolveCorp } from "./_helpers.js";
+const REPORT_CODE = {
+    q1: "11013",
+    half: "11012",
+    q3: "11014",
+    annual: "11011",
+};
+// report_type → OpenDART 엔드포인트 파일 (확장자 .json 은 클라이언트에서 붙임)
+const ENDPOINT = {
+    // 주주/지분
+    largest_shareholder: "hyslrSttus", // 최대주주 현황
+    largest_shareholder_changes: "hyslrChgSttus", // 최대주주 변동
+    minority_shareholders: "mrhlSttus", // 소액주주 현황
+    total_stocks: "stockTotqySttus", // 주식의 총수 현황
+    // 임직원
+    executives: "exctvSttus", // 임원 현황
+    employees: "empSttus", // 직원 현황
+    outside_director_changes: "outcmpnyDrctrNdChangeSttus", // 사외이사·변동
+    // 보수
+    executive_compensation_total: "hmvAuditAllSttus", // 임원·감사 전체 보수
+    executive_compensation_individual: "hmvAuditIndvdlBySttus", // 개인별 5억 이상
+    individual_pay_top5: "indvdlByPay", // 상위 5명 개인별 보수
+    unregistered_executive_comp: "unrstExctvMendngSttus", // 미등기임원 보수
+    director_total_comp_approval: "drctrAdtAllMendngSttusGmtsckConfmAmount", // 주총 승인금액
+    director_total_comp_by_type: "drctrAdtAllMendngSttusMendngPymntamtTyCl", // 유형별 지급금액
+    // 회계감사
+    auditor_opinion: "accnutAdtorNmNdAdtOpinion", // 회계감사인 및 의견
+    audit_service_contract: "adtServcCnclsSttus", // 감사용역 체결현황
+    non_audit_service_contract: "accnutAdtorNonAdtServcCnclsSttus", // 비감사용역 체결
+    // 자본/주식
+    capital_increase_decrease: "irdsSttus", // 증자(감자) 현황
+    dividends: "alotMatter", // 배당
+    treasury_stock: "tesstkAcqsDspsSttus", // 자기주식 취득·처분
+    // 자금사용
+    private_placement_fund_use: "prvsrpCptalUseDtls", // 사모자금 사용내역
+    public_offering_fund_use: "pssrpCptalUseDtls", // 공모자금 사용내역
+    // 타법인 출자
+    other_company_investment: "otrCprInvstmntSttus", // 타법인 출자현황
+    // 채무증권 발행/잔액
+    debt_securities_issuance: "detScritsIsuAcmslt", // 채무증권 발행실적
+    cp_unredeemed: "entrprsBilScritsNrdmpBlce", // 기업어음 미상환
+    short_term_bond_unredeemed: "srtpdPsndbtNrdmpBlce", // 단기사채 미상환
+    corp_bond_unredeemed: "cprndNrdmpBlce", // 회사채 미상환
+    hybrid_capital_unredeemed: "newCaplScritsNrdmpBlce", // 신종자본증권 미상환
+    contingent_capital_unredeemed: "cndlCaplScritsNrdmpBlce", // 조건부자본증권 미상환
+};
+const REPORT_TYPES = Object.keys(ENDPOINT);
+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"),
+    report_type: z
+        .enum(REPORT_TYPES)
+        .describe("섹션 29종: 주주(largest_shareholder·largest_shareholder_changes·minority_shareholders·total_stocks) / " +
+        "임직원(executives·employees·outside_director_changes) / " +
+        "보수(executive_compensation_total·executive_compensation_individual·individual_pay_top5·unregistered_executive_comp·director_total_comp_approval·director_total_comp_by_type) / " +
+        "회계감사(auditor_opinion·audit_service_contract·non_audit_service_contract) / " +
+        "자본(capital_increase_decrease·dividends·treasury_stock) / " +
+        "자금사용(private_placement_fund_use·public_offering_fund_use) / " +
+        "타법인출자(other_company_investment) / " +
+        "채무증권(debt_securities_issuance·cp_unredeemed·short_term_bond_unredeemed·corp_bond_unredeemed·hybrid_capital_unredeemed·contingent_capital_unredeemed)"),
+});
+export const getPeriodicReportTool = defineTool({
+    name: "get_periodic_report",
+    description: "사업보고서 내 29개 세부 섹션을 report_type enum 으로 단일 도구 호출. " +
+        "예: 최대주주 현황·임원 보수·감사인·배당·자기주식·회사채 미상환 등. " +
+        "(정기보고서 전체 원문이 필요하면 download_document.)",
+    input: Input,
+    handler: async (ctx, args) => {
+        const endpoint = ENDPOINT[args.report_type];
+        if (!endpoint) {
+            throw new Error(`알 수 없는 report_type: ${args.report_type}`);
+        }
+        const record = resolveCorp(ctx.resolver, args.corp);
+        const raw = await ctx.client.getJson(`${endpoint}.json`, {
+            corp_code: record.corp_code,
+            bsns_year: String(args.year),
+            reprt_code: REPORT_CODE[args.report],
+        });
+        if (raw.status !== "000") {
+            throw new Error(`DART 응답 오류 [${raw.status}]: ${raw.message}`);
+        }
+        return {
+            resolved: record,
+            year: args.year,
+            report: args.report,
+            report_type: args.report_type,
+            endpoint,
+            count: raw.list?.length ?? 0,
+            items: raw.list ?? [],
+        };
+    },
+});

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

@@ -0,0 +1,13 @@
+/**
+ * get_shareholders — 지배구조 4개 섹션을 병렬로 합성해 단일 뷰로 반환
+ *
+ * 정기보고서 내 지배구조 관련 4개 섹션을 한 번의 도구 호출로 수집.
+ *  - 최대주주 현황 (hyslrSttus)
+ *  - 최대주주 변동 (hyslrChgSttus)
+ *  - 소액주주 현황 (mrhlSttus)
+ *  - 주식의 총수 (stockTotqySttus)
+ *
+ * 같은 기간을 get_periodic_report 로 4번 호출하는 것 대비 1/4 왕복.
+ * 섹션 단일 조회가 필요하면 get_periodic_report.
+ */
+export declare const getShareholdersTool: import("./_helpers.js").ToolDef;

package/build/tools/get-shareholders.js

@@ -0,0 +1,87 @@
+/**
+ * get_shareholders — 지배구조 4개 섹션을 병렬로 합성해 단일 뷰로 반환
+ *
+ * 정기보고서 내 지배구조 관련 4개 섹션을 한 번의 도구 호출로 수집.
+ *  - 최대주주 현황 (hyslrSttus)
+ *  - 최대주주 변동 (hyslrChgSttus)
+ *  - 소액주주 현황 (mrhlSttus)
+ *  - 주식의 총수 (stockTotqySttus)
+ *
+ * 같은 기간을 get_periodic_report 로 4번 호출하는 것 대비 1/4 왕복.
+ * 섹션 단일 조회가 필요하면 get_periodic_report.
+ */
+import { z } from "zod";
+import { defineTool, resolveCorp } from "./_helpers.js";
+const REPORT_CODE = {
+    q1: "11013",
+    half: "11012",
+    q3: "11014",
+    annual: "11011",
+};
+const SECTIONS = {
+    largest_shareholder: "hyslrSttus",
+    largest_shareholder_changes: "hyslrChgSttus",
+    minority_shareholders: "mrhlSttus",
+    total_stocks: "stockTotqySttus",
+};
+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("조회할 섹션 (미지정 시 4개 모두)"),
+});
+export const getShareholdersTool = defineTool({
+    name: "get_shareholders",
+    description: "지배구조 스냅샷: 최대주주·변동·소액주주·주식총수 4개 섹션을 한 번에 합성 조회. " +
+        "(특정 섹션만 필요하면 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,
+        };
+    },
+});

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

@@ -0,0 +1,12 @@
+/**
+ * get_xbrl — 재무제표 XBRL 원본 또는 마크다운 변환
+ *
+ * format:
+ *   - "raw" (기본): ZIP 을 해제해 파일시스템에 저장.
+ *   - "markdown" (v0.8.0+): whitelist 기반 BS/IS/CF 3개 표.
+ *   - "markdown_full" (v0.9.0+): presentation linkbase 기반 전체 계정 + 계산 검증.
+ *     택소노미에서 직접 추출하므로 업종별(금융/보험 등) 고유 계정에도 자동 대응.
+ *
+ * 참고: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003&apiId=2019019
+ */
+export declare const getXbrlTool: import("./_helpers.js").ToolDef;

package/build/tools/get-xbrl.js

@@ -0,0 +1,96 @@
+/**
+ * get_xbrl — 재무제표 XBRL 원본 또는 마크다운 변환
+ *
+ * format:
+ *   - "raw" (기본): ZIP 을 해제해 파일시스템에 저장.
+ *   - "markdown" (v0.8.0+): whitelist 기반 BS/IS/CF 3개 표.
+ *   - "markdown_full" (v0.9.0+): presentation linkbase 기반 전체 계정 + 계산 검증.
+ *     택소노미에서 직접 추출하므로 업종별(금융/보험 등) 고유 계정에도 자동 대응.
+ *
+ * 참고: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003&apiId=2019019
+ */
+import { z } from "zod";
+import { homedir } from "node:os";
+import { defineTool } from "./_helpers.js";
+import { parseXbrlZip, buildStatements, buildStatementsFull, renderMarkdown, } from "../lib/xbrl-parser.js";
+import { safeUnzipToDisk, defaultXbrlOutDir } from "../utils/safe-zip.js";
+const REPORT_CODE = {
+    q1: "11013",
+    half: "11012",
+    q3: "11014",
+    annual: "11011",
+};
+const Input = z.object({
+    rcept_no: z.string().regex(/^\d{14}$/).describe("접수번호 14자리"),
+    report: z
+        .enum(["q1", "half", "q3", "annual"])
+        .default("annual")
+        .describe("보고서 종류"),
+    format: z
+        .enum(["raw", "markdown", "markdown_full"])
+        .default("raw")
+        .describe('raw: ZIP 파일시스템 저장. markdown: whitelist 50태그 마크다운. markdown_full(v0.9.0+): taxonomy 전체 계정 + 계산 검증.'),
+    fs_div: z
+        .enum(["consolidated", "separate"])
+        .default("consolidated")
+        .describe('markdown/markdown_full 전용: 연결/별도 기준'),
+    sections: z
+        .array(z.enum(["BS", "IS", "CF"]))
+        .default(["BS", "IS", "CF"])
+        .describe('markdown/markdown_full 전용: 생성할 재무제표 종류'),
+    out_dir: z
+        .string()
+        .optional()
+        .describe('format="raw" 전용: 저장 디렉터리 (미지정 시 ~/.korean-dart-mcp/xbrl/{rcept_no}_{report}/)'),
+});
+export const getXbrlTool = defineTool({
+    name: "get_xbrl",
+    description: "재무제표 XBRL 조회 — format 선택: " +
+        "raw=원본 ZIP 파일시스템 해제, " +
+        "markdown=whitelist 50태그 3년 3열 (~8KB), " +
+        "markdown_full=taxonomy 전체 계정 + 계산 검증 (업종별 자동 대응, ~30-60KB).",
+    input: Input,
+    handler: async (ctx, args) => {
+        const reprt_code = REPORT_CODE[args.report];
+        const buf = await ctx.client.getZip("fnlttXbrl.xml", {
+            rcept_no: args.rcept_no,
+            reprt_code,
+        });
+        if (args.format === "markdown" || args.format === "markdown_full") {
+            const full = args.format === "markdown_full";
+            const data = await parseXbrlZip(buf, { loadTaxonomy: full });
+            const st = full
+                ? buildStatementsFull(data, { fs_div: args.fs_div, sections: args.sections })
+                : buildStatements(data, { fs_div: args.fs_div, sections: args.sections });
+            const md = renderMarkdown(st);
+            return {
+                rcept_no: args.rcept_no,
+                report: args.report,
+                format: args.format,
+                fs_div: args.fs_div,
+                entity_id: data.entityId,
+                periods: st.periods,
+                statements: st.statements,
+                validations: st.validations,
+                markdown: md,
+                meta: {
+                    total_facts: data.facts.length,
+                    total_contexts: data.contexts.size,
+                    labels_loaded: data.labels.size,
+                    presentation_roles: data.taxonomy?.presentations.length,
+                    calculation_roles: data.taxonomy?.calculations.length,
+                },
+            };
+        }
+        // raw 모드 — 기존 동작 (zip slip · zip bomb 방어 포함)
+        const outDir = args.out_dir ?? defaultXbrlOutDir(homedir(), args.rcept_no, reprt_code);
+        const files = await safeUnzipToDisk(buf, outDir);
+        return {
+            rcept_no: args.rcept_no,
+            report: args.report,
+            format: "raw",
+            dir: outDir,
+            files,
+        };
+    },
+});

package/build/tools/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 type { ToolCtx, ToolDef } from "./_helpers.js";
+export type ToolContext = ToolCtx;
+export type ToolDefinition = ToolDef;
+/**
+ * 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 declare const TOOL_REGISTRY: ToolDef[];