@mseep/korean-dart-mcp 0.9.3

package/build/server/mcp-server.js

@@ -0,0 +1,40 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { DartClient } from "../lib/dart-client.js";
+import { CorpCodeResolver } from "../lib/corp-code.js";
+import { TOOL_REGISTRY } from "../tools/index.js";
+import { SERVER_NAME, VERSION } from "../version.js";
+export function createServer(opts) {
+    const client = new DartClient({ apiKey: opts.apiKey });
+    const resolver = new CorpCodeResolver({
+        cacheDir: opts.cacheDir,
+        forceRefresh: opts.forceRefresh,
+    });
+    const ctx = { client, resolver };
+    // corp_code 덤프 선적재: 첫 도구 호출 전에 끝나있어야 함.
+    // 실패하면 각 도구가 호출될 때마다 재시도 (init() 은 동일 promise 를 재사용).
+    const initReady = resolver.init(client).catch((err) => {
+        console.error("[korean-dart-mcp] corp_code 초기화 실패:", err);
+        throw err;
+    });
+    const server = new Server({ name: SERVER_NAME, version: VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOL_REGISTRY.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = TOOL_REGISTRY.find((t) => t.name === req.params.name);
+        if (!tool) {
+            throw new Error(`unknown tool: ${req.params.name}`);
+        }
+        await initReady;
+        const result = await tool.handler(req.params.arguments ?? {}, ctx);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    return server;
+}

package/build/setup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 대화형 설치 마법사 — korean-dart-mcp
+ *
+ * `npx korean-dart-mcp setup` 으로 실행.
+ * OpenDART 인증키를 입력받고, 선택한 AI 클라이언트 설정 파일에 MCP 서버를 자동 등록합니다.
+ * Windows / macOS / Linux 공용.
+ */
+export declare function runSetup(): Promise<void>;

package/build/setup.js

@@ -0,0 +1,264 @@
+/**
+ * 대화형 설치 마법사 — korean-dart-mcp
+ *
+ * `npx korean-dart-mcp setup` 으로 실행.
+ * OpenDART 인증키를 입력받고, 선택한 AI 클라이언트 설정 파일에 MCP 서버를 자동 등록합니다.
+ * Windows / macOS / Linux 공용.
+ */
+import { createInterface } from "node:readline/promises";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir, platform } from "node:os";
+import { stdin, stdout } from "node:process";
+function detectClients() {
+    const home = homedir();
+    const os = platform();
+    const clients = [];
+    const claudePaths = {
+        darwin: resolve(home, "Library/Application Support/Claude/claude_desktop_config.json"),
+        win32: resolve(process.env["APPDATA"] ?? resolve(home, "AppData/Roaming"), "Claude/claude_desktop_config.json"),
+        linux: resolve(home, ".config/Claude/claude_desktop_config.json"),
+    };
+    const claudePath = claudePaths[os];
+    if (claudePath) {
+        clients.push({ name: "Claude Desktop", configPath: claudePath, format: "mcpServers" });
+    }
+    clients.push({
+        name: "Claude Code (현재 디렉토리)",
+        configPath: resolve(process.cwd(), ".mcp.json"),
+        format: "mcpServers",
+    });
+    clients.push({
+        name: "Cursor",
+        configPath: resolve(home, ".cursor/mcp.json"),
+        format: "mcpServers",
+    });
+    clients.push({
+        name: "VS Code (현재 디렉토리)",
+        configPath: resolve(process.cwd(), ".vscode/mcp.json"),
+        format: "servers",
+    });
+    clients.push({
+        name: "Windsurf",
+        configPath: resolve(home, ".codeium/windsurf/mcp_config.json"),
+        format: "mcpServers",
+    });
+    clients.push({
+        name: "Gemini CLI",
+        configPath: resolve(home, ".gemini/settings.json"),
+        format: "mcpServers",
+    });
+    const zedPaths = {
+        darwin: resolve(home, ".zed/settings.json"),
+        linux: resolve(home, ".config/zed/settings.json"),
+        win32: resolve(home, ".zed/settings.json"),
+    };
+    const zedPath = zedPaths[os];
+    if (zedPath) {
+        clients.push({ name: "Zed", configPath: zedPath, format: "context_servers" });
+    }
+    clients.push({
+        name: "Antigravity",
+        configPath: resolve(home, ".gemini/antigravity/mcp_config.json"),
+        format: "mcpServers",
+    });
+    return clients;
+}
+async function readJsonFile(path) {
+    if (!existsSync(path))
+        return {};
+    const raw = await readFile(path, "utf-8");
+    return JSON.parse(raw);
+}
+async function writeJsonFile(path, data) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+    }
+    await writeFile(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+/**
+ * Windows 에선 npx → npx.cmd 를 거치며 Claude Desktop 이 .cmd 를 못 찾는 이슈가 있어
+ * `cmd /c` 래핑이 필요하다. README 에도 동일 가이드 있음.
+ */
+function buildServerEntry(apiKey) {
+    const env = {};
+    if (apiKey)
+        env.DART_API_KEY = apiKey;
+    if (platform() === "win32") {
+        return {
+            command: "cmd",
+            args: ["/c", "npx", "-y", "korean-dart-mcp"],
+            env,
+        };
+    }
+    return {
+        command: "npx",
+        args: ["-y", "korean-dart-mcp"],
+        env,
+    };
+}
+function buildZedEntry(apiKey) {
+    const env = {};
+    if (apiKey)
+        env.DART_API_KEY = apiKey;
+    const base = platform() === "win32"
+        ? { path: "cmd", args: ["/c", "npx", "-y", "korean-dart-mcp"], env }
+        : { path: "npx", args: ["-y", "korean-dart-mcp"], env };
+    return { command: base };
+}
+// ─── ANSI ─────────────────────────────────────────────────────────────
+const ESC = "\x1b[";
+const c = {
+    reset: `${ESC}0m`,
+    bold: `${ESC}1m`,
+    dim: `${ESC}2m`,
+    cyan: `${ESC}36m`,
+    green: `${ESC}32m`,
+    yellow: `${ESC}33m`,
+    red: `${ESC}31m`,
+    white: `${ESC}37m`,
+};
+function rgb(r, g, b) {
+    return `${ESC}38;2;${r};${g};${b}m`;
+}
+function sleep(ms) {
+    return new Promise((res) => setTimeout(res, ms));
+}
+async function typewrite(text, delay = 15) {
+    for (const ch of text) {
+        process.stdout.write(ch);
+        await sleep(delay);
+    }
+    console.log();
+}
+async function printBanner() {
+    const gradients = [
+        rgb(0, 220, 180), rgb(0, 200, 200), rgb(0, 180, 220),
+        rgb(30, 150, 240), rgb(60, 120, 250), rgb(100, 100, 255),
+    ];
+    const logo = [
+        "  _  __                            ____             _   ",
+        " | |/ /___  _ __ ___  __ _ _ __   |  _ \\  __ _ _ __| |_ ",
+        " | ' // _ \\| '__/ _ \\/ _` | '_ \\  | | | |/ _` | '__| __|",
+        " | . \\ (_) | | |  __/ (_| | | | | | |_| | (_| | |  | |_ ",
+        " |_|\\_\\___/|_|  \\___|\\__,_|_| |_| |____/ \\__,_|_|   \\__|",
+    ];
+    console.log();
+    for (let i = 0; i < logo.length; i++) {
+        const color = gradients[i % gradients.length];
+        console.log(`${color}${c.bold}${logo[i]}${c.reset}`);
+        await sleep(60);
+    }
+    console.log();
+    await typewrite(`${c.dim}  MCP Server  ━━  OpenDART 83개 API → 15개 도구${c.reset}`, 12);
+    console.log();
+    console.log(`${c.cyan}  ${"━".repeat(52)}${c.reset}`);
+    console.log();
+}
+function stepHeader(step, total, title) {
+    const dots = `${c.dim}${"·".repeat(Math.max(0, 40 - title.length))}${c.reset}`;
+    console.log(`  ${c.cyan}${c.bold}[${step}/${total}]${c.reset} ${c.white}${c.bold}${title}${c.reset} ${dots}`);
+    console.log();
+}
+function successLine(label, detail) {
+    console.log(`  ${c.green}${c.bold}+${c.reset} ${c.white}${label}${c.reset}${c.dim} ${detail}${c.reset}`);
+}
+function failLine(label, detail) {
+    console.log(`  ${c.red}${c.bold}x${c.reset} ${c.white}${label}${c.reset}${c.dim} ${detail}${c.reset}`);
+}
+async function printComplete(apiKey) {
+    console.log();
+    const box = [
+        `  ${c.green}${c.bold}╔${"═".repeat(50)}╗${c.reset}`,
+        `  ${c.green}${c.bold}║${c.reset}${" ".repeat(14)}${c.green}${c.bold}Setup Complete!${c.reset}${" ".repeat(22)}${c.green}${c.bold}║${c.reset}`,
+        `  ${c.green}${c.bold}╚${"═".repeat(50)}╝${c.reset}`,
+    ];
+    for (const line of box) {
+        console.log(line);
+        await sleep(40);
+    }
+    console.log();
+    if (!apiKey) {
+        console.log(`  ${c.yellow}!${c.reset} API 키 미설정 — 환경변수 ${c.bold}DART_API_KEY${c.reset} 또는 설정 파일의 ${c.bold}env.DART_API_KEY${c.reset} 수정`);
+        console.log();
+    }
+    console.log(`  ${c.dim}클라이언트를 재시작하면 'korean-dart' MCP 서버가 활성화됩니다.${c.reset}`);
+    console.log();
+}
+export async function runSetup() {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        await printBanner();
+        stepHeader(1, 3, "OpenDART 인증키");
+        console.log(`  ${c.dim}발급: https://opendart.fss.or.kr/ (가입 → 인증키 신청, 무료/일 20,000건)${c.reset}`);
+        console.log(`  ${c.dim}Enter로 건너뛰기 — 나중에 환경변수로 설정 가능${c.reset}`);
+        console.log();
+        const apiKey = (await rl.question(`  ${c.cyan}>${c.reset} API 키: `)).trim();
+        if (apiKey) {
+            console.log(`  ${c.green}+${c.reset} 키 등록됨`);
+        }
+        else {
+            console.log(`  ${c.yellow}-${c.reset} 건너뜀`);
+        }
+        console.log();
+        stepHeader(2, 3, "MCP 클라이언트 선택");
+        const clients = detectClients();
+        clients.forEach((cl, i) => {
+            const exists = existsSync(cl.configPath);
+            const badge = exists ? `${c.green} [감지됨]${c.reset}` : "";
+            const num = `${c.cyan}${String(i + 1).padStart(2)}${c.reset}`;
+            console.log(`  ${num}) ${c.white}${cl.name}${c.reset}${badge}`);
+        });
+        console.log();
+        const clientInput = (await rl.question(`  ${c.cyan}>${c.reset} 번호 (예: 1,3): `)).trim();
+        if (!clientInput) {
+            console.log(`\n  ${c.yellow}선택 없음${c.reset} — 수동 설정 안내:`);
+            printManualConfig(apiKey);
+            return;
+        }
+        const indices = clientInput
+            .split(",")
+            .map((s) => parseInt(s.trim(), 10) - 1)
+            .filter((i) => i >= 0 && i < clients.length);
+        if (indices.length === 0) {
+            console.log(`\n  ${c.yellow}유효한 선택 없음${c.reset} — 수동 설정 안내:`);
+            printManualConfig(apiKey);
+            return;
+        }
+        console.log();
+        stepHeader(3, 3, "설정 파일 업데이트");
+        const entry = buildServerEntry(apiKey);
+        for (const idx of indices) {
+            const client = clients[idx];
+            await sleep(150);
+            try {
+                const config = await readJsonFile(client.configPath);
+                const key = client.format;
+                const serverEntry = key === "context_servers" ? buildZedEntry(apiKey) : entry;
+                const servers = (config[key] ?? {});
+                servers["korean-dart"] = serverEntry;
+                config[key] = servers;
+                await writeJsonFile(client.configPath, config);
+                successLine(client.name, client.configPath);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                failLine(client.name, msg);
+            }
+        }
+        await printComplete(apiKey);
+    }
+    finally {
+        rl.close();
+    }
+}
+function printManualConfig(apiKey) {
+    const entry = buildServerEntry(apiKey);
+    console.log();
+    console.log(`  ${c.dim}아래 JSON을 설정 파일의 mcpServers에 추가하세요:${c.reset}`);
+    console.log();
+    console.log(`  ${c.cyan}"korean-dart"${c.reset}: ${JSON.stringify(entry, null, 4)}`);
+    console.log();
+}

package/build/tools/_helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 툴 공용 유틸
+ *  - defineTool: zod 스키마를 JSON Schema 로 자동 변환하며 핸들러에 파싱된 입력을 전달
+ *  - resolveCorp: 회사명·종목코드·corp_code 중 무엇이 와도 단일 CorpRecord 로 해석
+ *  - normalizeDate: YYYY-MM-DD / YYYYMMDD / YYYY.MM.DD → YYYYMMDD
+ */
+import { z } from "zod";
+import type { CorpCodeResolver, CorpRecord } from "../lib/corp-code.js";
+import type { DartClient } from "../lib/dart-client.js";
+export interface ToolCtx {
+    client: DartClient;
+    resolver: CorpCodeResolver;
+}
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: unknown, ctx: ToolCtx) => Promise<unknown>;
+}
+export declare function defineTool<S extends z.ZodType>(spec: {
+    name: string;
+    description: string;
+    input: S;
+    handler: (ctx: ToolCtx, args: z.infer<S>) => Promise<unknown>;
+}): ToolDef;
+export declare function resolveCorp(resolver: CorpCodeResolver, input: string): CorpRecord;
+/** OpenDART 는 YYYYMMDD 포맷만 허용. */
+export declare function normalizeDate(input: string): string;

package/build/tools/_helpers.js

@@ -0,0 +1,35 @@
+/**
+ * 툴 공용 유틸
+ *  - defineTool: zod 스키마를 JSON Schema 로 자동 변환하며 핸들러에 파싱된 입력을 전달
+ *  - resolveCorp: 회사명·종목코드·corp_code 중 무엇이 와도 단일 CorpRecord 로 해석
+ *  - normalizeDate: YYYY-MM-DD / YYYYMMDD / YYYY.MM.DD → YYYYMMDD
+ */
+import { z } from "zod";
+export function defineTool(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        // io:"input" → default() 가 있는 필드는 required 에서 제외되어 LLM 가 빈 인자로도 호출 가능
+        inputSchema: z.toJSONSchema(spec.input, { io: "input" }),
+        handler: async (args, ctx) => {
+            const parsed = spec.input.parse(args ?? {});
+            return spec.handler(ctx, parsed);
+        },
+    };
+}
+export function resolveCorp(resolver, input) {
+    const record = resolver.resolve(input);
+    if (!record) {
+        throw new Error(`회사를 찾을 수 없습니다: "${input}". ` +
+            `resolve_corp_code 로 먼저 정확한 이름을 확인하세요.`);
+    }
+    return record;
+}
+/** OpenDART 는 YYYYMMDD 포맷만 허용. */
+export function normalizeDate(input) {
+    const digits = input.replace(/\D/g, "");
+    if (!/^\d{8}$/.test(digits)) {
+        throw new Error(`날짜 형식 오류: "${input}" (YYYY-MM-DD 또는 YYYYMMDD)`);
+    }
+    return digits;
+}

package/build/tools/buffett-quality-snapshot.d.ts

@@ -0,0 +1,10 @@
+/**
+ * buffett_quality_snapshot — 버핏·그레이엄 식 퀄리티 체크리스트
+ *
+ * 기업 1개 → N년 시계열 + 체크리스트 + CAGR
+ * 기업 2+ → 기업별 스냅샷 + 지표별 랭킹 (기존 quality_compare 통합)
+ *
+ * DART 주요계정(fnlttSinglAcnt) 를 base year 3년 간격으로 호출해 요율 절약.
+ * 여러 기업은 기업별 병렬 실행.
+ */
+export declare const buffettQualitySnapshotTool: import("./_helpers.js").ToolDef;

package/build/tools/buffett-quality-snapshot.js

@@ -0,0 +1,261 @@
+/**
+ * buffett_quality_snapshot — 버핏·그레이엄 식 퀄리티 체크리스트
+ *
+ * 기업 1개 → N년 시계열 + 체크리스트 + CAGR
+ * 기업 2+ → 기업별 스냅샷 + 지표별 랭킹 (기존 quality_compare 통합)
+ *
+ * DART 주요계정(fnlttSinglAcnt) 를 base year 3년 간격으로 호출해 요율 절약.
+ * 여러 기업은 기업별 병렬 실행.
+ */
+import { z } from "zod";
+import { defineTool, resolveCorp } from "./_helpers.js";
+const Input = z.object({
+    corps: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(10)
+        .describe("회사 1~10개. 1개면 시계열+체크리스트, 2+면 비교+랭킹 추가"),
+    years: z.number().int().min(3).max(15).default(10).describe("과거 N년 (기본 10)"),
+    end_year: z.number().int().min(2016).optional().describe("기준연도 (미지정=작년)"),
+    prefer_consolidated: z.boolean().default(true).describe("연결재무제표 우선"),
+});
+function parseAmount(v) {
+    if (!v)
+        return null;
+    const cleaned = v.replace(/[,\s]/g, "");
+    if (cleaned === "" || cleaned === "-")
+        return null;
+    const n = Number(cleaned);
+    return Number.isFinite(n) ? n : null;
+}
+const ACCOUNT_MATCHERS = {
+    revenue: [/^(매출액|영업수익|수익\(매출액\))$/, /^수익$/, /매출/],
+    operating_income: [/^영업이익(\([손실]*\))?$/, /영업이익/],
+    net_income: [/^당기순이익(\([손실]*\))?$/, /당기순이익/],
+    assets: [/^자산총계$/],
+    liabilities: [/^부채총계$/],
+    equity: [/^자본총계$/],
+};
+function pickAccount(items, key, period) {
+    for (const pat of ACCOUNT_MATCHERS[key]) {
+        const hit = items.find((it) => pat.test(it.account_nm ?? ""));
+        if (hit) {
+            const field = `${period}_amount`;
+            return parseAmount(hit[field]);
+        }
+    }
+    return null;
+}
+function computeRatios(m) {
+    if (m.net_income != null && m.equity && m.equity !== 0) {
+        m.roe_pct = Number(((m.net_income / m.equity) * 100).toFixed(2));
+    }
+    if (m.operating_income != null && m.revenue && m.revenue !== 0) {
+        m.op_margin_pct = Number(((m.operating_income / m.revenue) * 100).toFixed(2));
+    }
+    if (m.liabilities != null && m.equity && m.equity !== 0) {
+        m.debt_to_equity_pct = Number(((m.liabilities / m.equity) * 100).toFixed(2));
+    }
+    return m;
+}
+function filterFsDiv(items, preferConsolidated) {
+    const primary = preferConsolidated ? "CFS" : "OFS";
+    const secondary = preferConsolidated ? "OFS" : "CFS";
+    const hitPrimary = items.filter((i) => i.fs_div === primary);
+    if (hitPrimary.length)
+        return hitPrimary;
+    const hitSecondary = items.filter((i) => i.fs_div === secondary);
+    if (hitSecondary.length)
+        return hitSecondary;
+    return items;
+}
+function cagr(first, last, periods) {
+    if (first == null || last == null || first <= 0 || last <= 0 || periods < 1)
+        return null;
+    return Number(((Math.pow(last / first, 1 / periods) - 1) * 100).toFixed(2));
+}
+function stddev(nums) {
+    if (nums.length < 2)
+        return 0;
+    const mean = nums.reduce((a, b) => a + b, 0) / nums.length;
+    const variance = nums.reduce((s, n) => s + (n - mean) ** 2, 0) / nums.length;
+    return Math.sqrt(variance);
+}
+async function computeSnapshot(ctx, corp, years, endYearArg, preferConsolidated) {
+    const record = resolveCorp(ctx.resolver, corp);
+    const endYear = endYearArg ?? new Date().getFullYear() - 1;
+    const startYear = endYear - years + 1;
+    const baseYears = [];
+    for (let y = endYear; y >= startYear; y -= 3)
+        baseYears.push(y);
+    const responses = await Promise.all(baseYears.map(async (year) => {
+        try {
+            const raw = await ctx.client.getJson("fnlttSinglAcnt.json", {
+                corp_code: record.corp_code,
+                bsns_year: String(year),
+                reprt_code: "11011",
+            });
+            return { base_year: year, items: raw.status === "000" ? raw.list ?? [] : [] };
+        }
+        catch {
+            return { base_year: year, items: [] };
+        }
+    }));
+    const byYear = new Map();
+    for (const r of responses.sort((a, b) => a.base_year - b.base_year)) {
+        if (!r.items.length)
+            continue;
+        const filtered = filterFsDiv(r.items, preferConsolidated);
+        const periods = [
+            ["thstrm", r.base_year],
+            ["frmtrm", r.base_year - 1],
+            ["bfefrmtrm", r.base_year - 2],
+        ];
+        for (const [period, y] of periods) {
+            if (y < startYear || y > endYear)
+                continue;
+            const m = {
+                year: y,
+                source_base_year: r.base_year,
+                source_period: period,
+                revenue: pickAccount(filtered, "revenue", period),
+                operating_income: pickAccount(filtered, "operating_income", period),
+                net_income: pickAccount(filtered, "net_income", period),
+                assets: pickAccount(filtered, "assets", period),
+                liabilities: pickAccount(filtered, "liabilities", period),
+                equity: pickAccount(filtered, "equity", period),
+                roe_pct: null,
+                op_margin_pct: null,
+                debt_to_equity_pct: null,
+            };
+            computeRatios(m);
+            byYear.set(y, m);
+        }
+    }
+    const series = Array.from(byYear.values()).sort((a, b) => a.year - b.year);
+    const roes = series.map((s) => s.roe_pct).filter((v) => v != null);
+    const debtRatios = series
+        .map((s) => s.debt_to_equity_pct)
+        .filter((v) => v != null);
+    const first = series[0];
+    const last = series[series.length - 1];
+    const periodsLen = series.length > 1 ? last.year - first.year : 0;
+    const revenue_cagr = first && last ? cagr(first.revenue, last.revenue, periodsLen) : null;
+    const net_income_cagr = first && last ? cagr(first.net_income, last.net_income, periodsLen) : null;
+    const avg_roe = roes.length ? Number((roes.reduce((a, b) => a + b, 0) / roes.length).toFixed(2)) : null;
+    const latest_debt = last?.debt_to_equity_pct ?? null;
+    const checklist = {
+        consistent_high_roe: {
+            pass: roes.length >= 3 && roes.every((r) => r >= 15),
+            rule: "모든 연도 ROE ≥ 15%",
+            evidence: { roes, years_observed: roes.length },
+        },
+        low_debt: {
+            pass: latest_debt != null && latest_debt <= 100,
+            rule: "최근 부채비율 ≤ 100%",
+            evidence: { latest_debt_to_equity_pct: latest_debt },
+        },
+        growing_revenue: {
+            pass: revenue_cagr != null && revenue_cagr >= 5,
+            rule: "매출 CAGR ≥ 5%",
+            evidence: { revenue_cagr_pct: revenue_cagr, periods: periodsLen },
+        },
+        growing_earnings: {
+            pass: net_income_cagr != null && net_income_cagr >= 5,
+            rule: "순이익 CAGR ≥ 5%",
+            evidence: { net_income_cagr_pct: net_income_cagr, periods: periodsLen },
+        },
+    };
+    const passed = Object.values(checklist).filter((c) => c.pass).length;
+    return {
+        resolved: record,
+        window: { start_year: startYear, end_year: endYear, years },
+        fs_preference: preferConsolidated ? "CFS>OFS" : "OFS>CFS",
+        api_calls: baseYears.length,
+        series,
+        ratios: {
+            avg_roe_pct: avg_roe,
+            min_roe_pct: roes.length ? Math.min(...roes) : null,
+            max_roe_pct: roes.length ? Math.max(...roes) : null,
+            roe_stddev: Number(stddev(roes).toFixed(2)),
+            latest_debt_to_equity_pct: latest_debt,
+            avg_debt_to_equity_pct: debtRatios.length
+                ? Number((debtRatios.reduce((a, b) => a + b, 0) / debtRatios.length).toFixed(2))
+                : null,
+            revenue_cagr_pct: revenue_cagr,
+            net_income_cagr_pct: net_income_cagr,
+        },
+        checklist,
+        overall_score: `${passed}/4`,
+    };
+}
+function rankBy(rows, key, dir) {
+    const withValue = rows
+        .map((r) => ({ r, v: r[key] }))
+        .filter((x) => typeof x.v === "number" && Number.isFinite(x.v));
+    withValue.sort((a, b) => (dir === "desc" ? b.v - a.v : a.v - b.v));
+    return withValue.map((x) => `${x.r.corp_name}(${x.v})`);
+}
+export const buffettQualitySnapshotTool = defineTool({
+    name: "buffett_quality_snapshot",
+    description: "버핏 퀄리티 체크리스트. corps 1개 → N년 ROE/부채/CAGR 시계열 + 체크 4종. " +
+        "corps 2~10개 → 각 기업 스냅샷 + 5지표별 랭킹 (기존 quality_compare 통합). 기업별 병렬 실행.",
+    input: Input,
+    handler: async (ctx, args) => {
+        const snapshots = await Promise.all(args.corps.map(async (corp) => {
+            try {
+                const snap = await computeSnapshot(ctx, corp, args.years, args.end_year, args.prefer_consolidated);
+                return { corp_input: corp, snap, error: null };
+            }
+            catch (e) {
+                return {
+                    corp_input: corp,
+                    snap: null,
+                    error: e instanceof Error ? e.message : String(e),
+                };
+            }
+        }));
+        if (args.corps.length === 1) {
+            const r = snapshots[0];
+            if (!r.snap)
+                throw new Error(`snapshot 실패 [${r.corp_input}]: ${r.error}`);
+            return { mode: "single", ...r.snap };
+        }
+        const successful = snapshots.filter((s) => s.snap !== null);
+        const rows = successful.map((s) => ({
+            corp_name: s.snap.resolved.corp_name,
+            corp_code: s.snap.resolved.corp_code,
+            window: s.snap.window,
+            avg_roe_pct: s.snap.ratios.avg_roe_pct,
+            roe_stddev: s.snap.ratios.roe_stddev,
+            latest_debt_to_equity_pct: s.snap.ratios.latest_debt_to_equity_pct,
+            revenue_cagr_pct: s.snap.ratios.revenue_cagr_pct,
+            net_income_cagr_pct: s.snap.ratios.net_income_cagr_pct,
+            overall_score: s.snap.overall_score,
+            checklist_pass: Object.entries(s.snap.checklist)
+                .filter(([, v]) => v.pass)
+                .map(([k]) => k),
+        }));
+        const errors = snapshots.filter((s) => s.error).map((s) => ({
+            corp_input: s.corp_input,
+            error: s.error,
+        }));
+        return {
+            mode: "compare",
+            inputs: args.corps,
+            years: args.years,
+            end_year: args.end_year ?? new Date().getFullYear() - 1,
+            rows,
+            rankings: {
+                by_avg_roe_desc: rankBy(rows, "avg_roe_pct", "desc"),
+                by_debt_ratio_asc: rankBy(rows, "latest_debt_to_equity_pct", "asc"),
+                by_revenue_cagr_desc: rankBy(rows, "revenue_cagr_pct", "desc"),
+                by_net_income_cagr_desc: rankBy(rows, "net_income_cagr_pct", "desc"),
+                by_roe_stability_asc: rankBy(rows, "roe_stddev", "asc"),
+            },
+            individuals: successful.map((s) => ({ corp_input: s.corp_input, snapshot: s.snap })),
+            errors,
+            note: "체크리스트는 휴리스틱. 업종·경기 고려 필수. insider_signal·disclosure_anomaly 로 질적 시그널 보완.",
+        };
+    },
+});

package/build/tools/disclosure-anomaly.d.ts

@@ -0,0 +1,14 @@
+/**
+ * disclosure_anomaly — 공시·회계 이상 징후 탐지 (킬러 포인트)
+ *
+ * 공시 이력과 감사인·감사의견 이력을 교차해 회계·거버넌스 위험 신호를 점수화.
+ *
+ * 시그널:
+ *   1. 정정공시 비율 — report_nm 에 "[기재정정]"/"[첨부정정]" 포함 비율
+ *   2. 감사인 교체 — 지정 연도 범위의 감사인 이름이 바뀌면 +
+ *   3. 감사의견 비적정 — "적정" 이외 의견(한정/부적정/의견거절)
+ *   4. 자본 스트레스 — 유상증자·CB·자사주 처분 공시 빈도
+ *
+ * 점수 0-100. 해석은 LLM 에게 위임하되, 핵심 flag 와 evidence 를 구조화해서 제공.
+ */
+export declare const disclosureAnomalyTool: import("./_helpers.js").ToolDef;