@mseep/korean-dart-mcp 0.9.3

package/build/tools/disclosure-anomaly.js

@@ -0,0 +1,231 @@
+/**
+ * disclosure_anomaly — 공시·회계 이상 징후 탐지 (킬러 포인트)
+ *
+ * 공시 이력과 감사인·감사의견 이력을 교차해 회계·거버넌스 위험 신호를 점수화.
+ *
+ * 시그널:
+ *   1. 정정공시 비율 — report_nm 에 "[기재정정]"/"[첨부정정]" 포함 비율
+ *   2. 감사인 교체 — 지정 연도 범위의 감사인 이름이 바뀌면 +
+ *   3. 감사의견 비적정 — "적정" 이외 의견(한정/부적정/의견거절)
+ *   4. 자본 스트레스 — 유상증자·CB·자사주 처분 공시 빈도
+ *
+ * 점수 0-100. 해석은 LLM 에게 위임하되, 핵심 flag 와 evidence 를 구조화해서 제공.
+ */
+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("기간 시작 (기본: 3년 전)"),
+    end: z.string().optional().describe("기간 종료 (기본: 오늘)"),
+    audit_years: z
+        .array(z.number().int().min(2015))
+        .optional()
+        .describe("감사인·의견 비교할 연도 (미지정 시 기간의 최근 3년)"),
+});
+function ymd(d) {
+    return d.toISOString().slice(0, 10).replace(/-/g, "");
+}
+function defaultRange(args) {
+    const end = args.end ? normalizeDate(args.end) : ymd(new Date());
+    let bgn;
+    if (args.start) {
+        bgn = normalizeDate(args.start);
+    }
+    else {
+        const d = new Date();
+        d.setFullYear(d.getFullYear() - 3);
+        bgn = ymd(d);
+    }
+    return { bgn_de: bgn, end_de: end };
+}
+export const disclosureAnomalyTool = defineTool({
+    name: "disclosure_anomaly",
+    description: "회계·거버넌스 이상 징후 스코어: 정정공시 비율, 감사인 교체, 감사의견 비적정, 자본 스트레스. " +
+        "점수 0-100 + 개별 flag 와 evidence 를 구조화해 반환. " +
+        "LLM 이 판단을 내릴 수 있는 데이터 프레임 제공 (직접 권고하지 않음).",
+    input: Input,
+    handler: async (ctx, args) => {
+        const record = resolveCorp(ctx.resolver, args.corp);
+        const { bgn_de, end_de } = defaultRange(args);
+        // 1. 공시 목록 수집 (페이지 순회)
+        const disclosures = [];
+        let page_no = 1;
+        while (true) {
+            const raw = await ctx.client.getJson("list.json", {
+                corp_code: record.corp_code,
+                bgn_de,
+                end_de,
+                page_no,
+                page_count: 100,
+            });
+            if (raw.status !== "000") {
+                if (raw.status === "013")
+                    break; // 검색 결과 없음
+                throw new Error(`DART list 오류 [${raw.status}]: ${raw.message}`);
+            }
+            disclosures.push(...(raw.list ?? []));
+            if (!raw.total_page || page_no >= raw.total_page)
+                break;
+            page_no++;
+            if (page_no > 20)
+                break; // 상한
+        }
+        // 정정공시 비율
+        const amendments = disclosures.filter((d) => /\[(기재정정|첨부정정|첨부추가)\]/.test(d.report_nm));
+        const amendment_ratio = disclosures.length
+            ? amendments.length / disclosures.length
+            : 0;
+        // 자본 스트레스 공시 (이벤트 키워드)
+        const capitalStress = disclosures.filter((d) => /(유상증자|전환사채|신주인수권부사채|교환사채|자기주식 처분)/.test(d.report_nm));
+        // 2. 감사인·의견 시계열
+        const endYear = parseInt(end_de.slice(0, 4), 10);
+        const years = args.audit_years && args.audit_years.length > 0
+            ? args.audit_years.slice().sort((a, b) => a - b)
+            : [endYear - 2, endYear - 1, endYear];
+        const auditResults = await Promise.all(years.map(async (year) => {
+            try {
+                const raw = await ctx.client.getJson("accnutAdtorNmNdAdtOpinion.json", {
+                    corp_code: record.corp_code,
+                    bsns_year: String(year),
+                    reprt_code: "11011",
+                });
+                if (raw.status !== "000") {
+                    return { year, status: raw.status, message: raw.message, items: [] };
+                }
+                return { year, status: raw.status, items: raw.list ?? [] };
+            }
+            catch (e) {
+                return {
+                    year,
+                    error: e instanceof Error ? e.message : String(e),
+                    items: [],
+                };
+            }
+        }));
+        const auditTimeline = auditResults.map((r) => ({
+            year: r.year,
+            auditor: r.items[0]?.adt_adtor ?? null,
+            opinion: r.items[0]?.adt_opinion ?? null,
+            emphasis: r.items[0]?.em_ph ?? null,
+            status: r.status ?? null,
+            message: r.message ?? null,
+        }));
+        const auditors = auditTimeline.map((a) => a.auditor).filter((x) => Boolean(x));
+        const uniqueAuditors = Array.from(new Set(auditors));
+        const auditor_changes = Math.max(0, uniqueAuditors.length - 1);
+        const nonCleanOpinions = auditTimeline.filter((a) => a.opinion && !/(적정|unqualified)/i.test(a.opinion));
+        // 3. 점수 계산 (0-100)
+        let score = 0;
+        const flags = [];
+        if (amendment_ratio > 0.2) {
+            flags.push({
+                flag: "high_amendment_ratio",
+                points: 30,
+                evidence: { ratio: amendment_ratio, total: disclosures.length, amended: amendments.length },
+            });
+            score += 30;
+        }
+        else if (amendment_ratio > 0.1) {
+            flags.push({
+                flag: "elevated_amendment_ratio",
+                points: 15,
+                evidence: { ratio: amendment_ratio, total: disclosures.length, amended: amendments.length },
+            });
+            score += 15;
+        }
+        if (auditor_changes >= 1) {
+            const pts = auditor_changes >= 2 ? 30 : 20;
+            flags.push({
+                flag: "auditor_change",
+                points: pts,
+                evidence: { changes: auditor_changes, timeline: auditTimeline },
+            });
+            score += pts;
+        }
+        if (nonCleanOpinions.length > 0) {
+            flags.push({
+                flag: "non_clean_audit_opinion",
+                points: 40,
+                evidence: nonCleanOpinions,
+            });
+            score += 40;
+        }
+        if (capitalStress.length >= 3) {
+            flags.push({
+                flag: "capital_stress_cluster",
+                points: 10,
+                evidence: {
+                    count: capitalStress.length,
+                    samples: capitalStress.slice(0, 5).map((d) => ({
+                        rcept_no: d.rcept_no,
+                        report_nm: d.report_nm,
+                        rcept_dt: d.rcept_dt,
+                    })),
+                },
+            });
+            score += 10;
+        }
+        score = Math.min(100, score);
+        const verdict = score >= 70 ? "red_flag" : score >= 40 ? "warning" : score >= 15 ? "watch" : "clean";
+        const summary_text = buildAnomalySummary({
+            corpName: record.corp_name,
+            score,
+            verdict,
+            flags: flags.map((f) => f.flag),
+            stats: {
+                disclosures_total: disclosures.length,
+                amendments: amendments.length,
+                amendment_ratio,
+                capital_stress_filings: capitalStress.length,
+                auditor_changes,
+                non_clean_opinions: nonCleanOpinions.length,
+            },
+            bgn_de,
+            end_de,
+            auditors: uniqueAuditors,
+        });
+        return {
+            resolved: record,
+            period: { start: bgn_de, end: end_de },
+            audit_years: years,
+            score,
+            verdict,
+            summary_text,
+            flags,
+            stats: {
+                disclosures_total: disclosures.length,
+                amendments: amendments.length,
+                amendment_ratio: Number(amendment_ratio.toFixed(3)),
+                capital_stress_filings: capitalStress.length,
+                auditor_changes,
+                unique_auditors: uniqueAuditors,
+            },
+            audit_timeline: auditTimeline,
+            note: "verdict 는 휴리스틱. 실제 투자 판단은 원문(download_document) 확인 필수.",
+        };
+    },
+});
+function buildAnomalySummary(p) {
+    const verdictKo = {
+        red_flag: "🚨 적색경보",
+        warning: "⚠️ 경고",
+        watch: "👀 관찰",
+        clean: "✅ 이상 없음",
+    };
+    const head = `${p.corpName} (${p.bgn_de}~${p.end_de}): ${verdictKo[p.verdict] ?? p.verdict}, 점수 ${p.score}/100.`;
+    const parts = [];
+    if (p.stats.amendments > 0) {
+        parts.push(`정정공시 ${p.stats.amendments}/${p.stats.disclosures_total}건 (${(p.stats.amendment_ratio * 100).toFixed(1)}%)`);
+    }
+    if (p.stats.auditor_changes > 0) {
+        parts.push(`감사인 ${p.stats.auditor_changes}회 교체 (${p.auditors.join(" → ")})`);
+    }
+    if (p.stats.non_clean_opinions > 0) {
+        parts.push(`비적정 감사의견 ${p.stats.non_clean_opinions}건`);
+    }
+    if (p.stats.capital_stress_filings >= 3) {
+        parts.push(`자본 스트레스 공시 ${p.stats.capital_stress_filings}건`);
+    }
+    const body = parts.length > 0 ? ` 주요 지표: ${parts.join(" · ")}.` : " 모든 지표 정상 범위.";
+    return head + body;
+}

package/build/tools/download-document.d.ts

@@ -0,0 +1,14 @@
+/**
+ * download_document — 공시 원문 XML (document.xml) + 마크다운 변환
+ *
+ * ZIP 으로 반환되는 DART 원문(DART 전용 XML 마크업) 을 해제하여 반환.
+ * format:
+ *   - "markdown" (기본) → 자체 DART XML 파서로 깔끔한 마크다운 (heading/테이블 보존)
+ *   - "raw"              → 원본 XML 문자열
+ *   - "text"             → 태그 제거한 plain text (테이블 구조 사라짐)
+ *
+ * 파일이 크면 변환 후 `truncate_at` 으로 절단 (기본 100k chars).
+ *
+ * 참고: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001&apiId=2019003
+ */
+export declare const downloadDocumentTool: import("./_helpers.js").ToolDef;

package/build/tools/download-document.js

@@ -0,0 +1,89 @@
+/**
+ * download_document — 공시 원문 XML (document.xml) + 마크다운 변환
+ *
+ * ZIP 으로 반환되는 DART 원문(DART 전용 XML 마크업) 을 해제하여 반환.
+ * format:
+ *   - "markdown" (기본) → 자체 DART XML 파서로 깔끔한 마크다운 (heading/테이블 보존)
+ *   - "raw"              → 원본 XML 문자열
+ *   - "text"             → 태그 제거한 plain text (테이블 구조 사라짐)
+ *
+ * 파일이 크면 변환 후 `truncate_at` 으로 절단 (기본 100k chars).
+ *
+ * 참고: https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001&apiId=2019003
+ */
+import { z } from "zod";
+import iconv from "iconv-lite";
+import { defineTool } from "./_helpers.js";
+import { dartXmlToMarkdown } from "../lib/dart-xml.js";
+import { safeUnzipToMemory } from "../utils/safe-zip.js";
+const Input = z.object({
+    rcept_no: z
+        .string()
+        .regex(/^\d{14}$/)
+        .describe("접수번호 14자리 (search_disclosures 의 rcept_no)"),
+    format: z
+        .enum(["markdown", "raw", "text"])
+        .default("markdown")
+        .describe("출력 포맷. markdown=DART XML → 마크다운, raw=원본 XML, text=태그 제거"),
+    truncate_at: z
+        .number()
+        .int()
+        .min(1000)
+        .default(100000)
+        .describe("텍스트 최대 길이 (초과분은 잘림)"),
+});
+export const downloadDocumentTool = defineTool({
+    name: "download_document",
+    description: "공시서류 원문을 마크다운/원본XML/plain text 로 반환합니다. 기본값 markdown — DART 전용 XML 을 자체 파서로 heading·테이블 보존해 변환. " +
+        "대형 사업보고서는 수백 KB 이상이라 기본 10만 자에서 절단. " +
+        "사업보고서·반기보고서·주요사항보고 등 모든 공시 원문에 사용.",
+    input: Input,
+    handler: async (_ctx, args) => {
+        const buf = await _ctx.client.getZip("document.xml", {
+            rcept_no: args.rcept_no,
+        });
+        const files = await extractZipEntries(buf);
+        const xmlFile = files.find((f) => /\.xml$/i.test(f.name));
+        if (!xmlFile) {
+            throw new Error(`원문 XML 을 찾지 못했습니다. 반환된 파일: ${files.map((f) => f.name).join(", ")}`);
+        }
+        // DART 원문은 EUC-KR 로 인코딩된 경우가 많음 → XML 선언에서 인코딩 감지
+        const xml = decodeXml(xmlFile.data);
+        let content;
+        if (args.format === "raw") {
+            content = xml;
+        }
+        else if (args.format === "text") {
+            content = xml
+                .replace(/<[^>]+>/g, " ")
+                .replace(/\s+/g, " ")
+                .trim();
+        }
+        else {
+            content = dartXmlToMarkdown(xml);
+        }
+        const truncated = content.length > args.truncate_at;
+        return {
+            rcept_no: args.rcept_no,
+            file: xmlFile.name,
+            format: args.format,
+            size_bytes: xmlFile.data.length,
+            raw_char_count: xml.length,
+            char_count: content.length,
+            truncated,
+            content: truncated ? content.slice(0, args.truncate_at) : content,
+        };
+    },
+});
+function extractZipEntries(buf) {
+    return safeUnzipToMemory(buf);
+}
+function decodeXml(buf) {
+    // XML 선언의 encoding 속성 확인 (첫 200바이트만)
+    const head = buf.subarray(0, Math.min(200, buf.length)).toString("ascii");
+    const m = /encoding\s*=\s*["']([^"']+)["']/i.exec(head);
+    const enc = (m?.[1] ?? "utf-8").toLowerCase();
+    if (enc === "utf-8" || enc === "utf8")
+        return buf.toString("utf8");
+    return iconv.decode(buf, enc);
+}

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

@@ -0,0 +1,15 @@
+/**
+ * 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" — 지정한 파일을 다운로드·파싱해 마크다운 반환
+ */
+export declare const getAttachmentsTool: import("./_helpers.js").ToolDef;