kiwoom-mcp-server 0.8.0

package/dist/tools/account-balance.js

@@ -0,0 +1,36 @@
+import { getKiwoomContext } from "../context.js";
+import { fetchAccountEvaluation, fetchDeposit } from "../kiwoom/api.js";
+import { formatKRW, formatPercent, formatSignedKRW, parseKiwoomNumber } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+export function formatBalance(deposit, evaluation, modeLabel) {
+    const n = parseKiwoomNumber;
+    return [
+        `[${modeLabel}] 계좌 잔고 요약`,
+        "",
+        "■ 예수금 (kt00001)",
+        `- 예수금: ${formatKRW(n(deposit.entr))}`,
+        `- D+1 추정예수금: ${formatKRW(n(deposit.d1_entra))} / D+2 추정예수금: ${formatKRW(n(deposit.d2_entra))}`,
+        `- 주문가능금액: ${formatKRW(n(deposit.ord_alow_amt))} / 출금가능금액: ${formatKRW(n(deposit.pymn_alow_amt))}`,
+        "",
+        "■ 평가 현황 (kt00018)",
+        `- 총매입금액: ${formatKRW(n(evaluation.tot_pur_amt))}`,
+        `- 총평가금액: ${formatKRW(n(evaluation.tot_evlt_amt))}`,
+        `- 총평가손익: ${formatSignedKRW(n(evaluation.tot_evlt_pl))} (${formatPercent(n(evaluation.tot_prft_rt))})`,
+        `- 추정예탁자산: ${formatKRW(n(evaluation.prsm_dpst_aset_amt))}`,
+    ].join("\n");
+}
+export function registerAccountBalanceTool(server) {
+    server.registerTool("get_account_balance", {
+        title: "계좌 잔고 조회",
+        description: "계좌의 예수금(주문가능/출금가능 포함)과 총매입금액, 총평가금액, 총평가손익, " +
+            "추정예탁자산을 조회합니다 (키움 kt00001 + kt00018). 인자가 필요 없습니다.",
+    }, async () => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        // Different TRs — the per-TR rate limit allows these in parallel.
+        const [deposit, evaluation] = await Promise.all([
+            fetchDeposit(client),
+            fetchAccountEvaluation(client, "1"),
+        ]);
+        return textResult(formatBalance(deposit, evaluation, config.modeLabel));
+    }));
+}

package/dist/tools/account-holdings.js

@@ -0,0 +1,52 @@
+import { getKiwoomContext } from "../context.js";
+import { fetchAccountEvaluation } from "../kiwoom/api.js";
+import { normalizeStockCode } from "../kiwoom/types.js";
+import { formatKRW, formatPercent, formatSignedKRW, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+export function formatHoldings(evaluation, modeLabel, truncated = false) {
+    const n = parseKiwoomNumber;
+    const holdings = evaluation.acnt_evlt_remn_indv_tot;
+    if (holdings.length === 0) {
+        return `[${modeLabel}] 보유 종목이 없습니다.`;
+    }
+    const header = [
+        `[${modeLabel}] 보유 종목 (${holdings.length}종목, KRX 기준)`,
+        "",
+        "| 종목명 | 코드 | 보유수량 | 평균단가 | 현재가 | 평가금액 | 평가손익 | 수익률 | 비중 |",
+        "|---|---|---:|---:|---:|---:|---:|---:|---:|",
+    ];
+    const rows = holdings.map((h) => {
+        const cells = [
+            h.stk_nm || "-",
+            normalizeStockCode(h.stk_cd) || "-",
+            n(h.rmnd_qty)?.toLocaleString("ko-KR") ?? "-",
+            formatKRW(parseKiwoomPrice(h.pur_pric)),
+            formatKRW(parseKiwoomPrice(h.cur_prc)),
+            formatKRW(n(h.evlt_amt)),
+            formatSignedKRW(n(h.evltv_prft)),
+            formatPercent(n(h.prft_rt)),
+            n(h.poss_rt) === null ? "-" : `${n(h.poss_rt)}%`,
+        ];
+        return `| ${cells.join(" | ")} |`;
+    });
+    const footer = [
+        "",
+        `합계 — 매입 ${formatKRW(n(evaluation.tot_pur_amt))} / 평가 ${formatKRW(n(evaluation.tot_evlt_amt))} / ` +
+            `평가손익 ${formatSignedKRW(n(evaluation.tot_evlt_pl))} (${formatPercent(n(evaluation.tot_prft_rt))})`,
+    ];
+    if (truncated) {
+        footer.push("", "⚠️ 보유 종목이 많아 조회 상한에 도달했습니다 — 일부 종목이 누락되었을 수 있습니다.");
+    }
+    return [...header, ...rows, ...footer].join("\n");
+}
+export function registerAccountHoldingsTool(server) {
+    server.registerTool("get_account_holdings", {
+        title: "보유 종목 조회",
+        description: "계좌의 보유 종목 목록을 조회합니다 — 종목별 수량, 평균단가, 현재가, 평가금액, " +
+            "평가손익, 수익률, 보유비중 (키움 kt00018). 인자가 필요 없습니다.",
+    }, async () => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const evaluation = await fetchAccountEvaluation(client, "2");
+        return textResult(formatHoldings(evaluation, config.modeLabel, evaluation.truncated));
+    }));
+}

package/dist/tools/etf-info.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchEtfInfo, fetchStockInfo } from "../kiwoom/api.js";
+import { formatKRW, formatPercent, formatQuantity, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+export function formatEtfInfo(etf, quote, stockCode, modeLabel) {
+    if (!etf.stk_nm) {
+        return `[${modeLabel}] ${stockCode}의 ETF 정보가 없습니다. ETF 종목코드인지 확인해 주세요.`;
+    }
+    const lines = [
+        `[${modeLabel}] ${etf.stk_nm} (${stockCode}) ETF 정보`,
+        "",
+        `- 추적지수: ${etf.etfobjt_idex_nm || "-"}`,
+        `- 과세유형: ${etf.etftxon_type || "-"}`,
+    ];
+    if (quote) {
+        lines.push(`- 현재가: ${formatKRW(parseKiwoomPrice(quote.cur_prc))} (${formatPercent(parseKiwoomNumber(quote.flu_rt))})`, `- 거래량: ${formatQuantity(parseKiwoomNumber(quote.trde_qty))}`);
+    }
+    lines.push("", "※ 과세유형은 키움 표기 기준입니다. 매매차익 과세 방식(국내주식형 비과세 vs 배당소득 과세)은 " +
+        "계좌 유형에 따라 달라질 수 있습니다.");
+    return lines.join("\n");
+}
+export function registerEtfInfoTool(server) {
+    server.registerTool("get_etf_info", {
+        title: "ETF 정보 조회",
+        description: "ETF의 추적지수, 과세유형, 현재 시세를 조회합니다 (키움 ka40002+ka10001). " +
+            "종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^[0-9A-Z]{6}$/i, "6자리 종목코드여야 합니다")
+                .describe("6자리 ETF 종목코드 (예: 069500)"),
+        },
+    }, async ({ stock_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const code = stock_code.toUpperCase();
+        // Different TRs — parallel is fine; the quote is best-effort garnish.
+        const [etf, quote] = await Promise.all([
+            fetchEtfInfo(client, code),
+            fetchStockInfo(client, code).catch(() => null),
+        ]);
+        return textResult(formatEtfInfo(etf, quote, code, config.modeLabel));
+    }));
+}

package/dist/tools/foreign-holding.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchForeignHolding } from "../kiwoom/api.js";
+import { formatDateDashed } from "../utils/date.js";
+import { formatKRW, formatQuantity, formatRatioPercent, formatSigned, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_DISPLAY_DAYS = 15;
+export function formatForeignHolding(rows, stockCode, modeLabel, limit) {
+    if (rows.length === 0) {
+        return `[${modeLabel}] 외국인 보유 추이가 없습니다 (종목 ${stockCode}).`;
+    }
+    const shown = rows.slice(0, limit);
+    const n = parseKiwoomNumber;
+    const lines = [
+        `[${modeLabel}] 외국인 보유 추이 — 종목 ${stockCode} (최근 ${shown.length}일)`,
+        "",
+        "| 일자 | 종가 | 거래량 | 외국인순변동 | 보유주식수 | 보유비중 | 한도소진률 |",
+        "|---|---:|---:|---:|---:|---:|---:|",
+    ];
+    for (const r of shown) {
+        const cells = [
+            formatDateDashed(r.dt),
+            formatKRW(parseKiwoomPrice(r.close_pric)),
+            formatQuantity(n(r.trde_qty)),
+            `${formatSigned(n(r.chg_qty), 0)}주`,
+            formatQuantity(n(r.poss_stkcnt)),
+            formatRatioPercent(n(r.wght)),
+            formatRatioPercent(n(r.limit_exh_rt)),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    if (rows.length > shown.length) {
+        lines.push("", `※ 최근 ${shown.length}일만 표시했습니다 (limit으로 최대 50일까지 조정 가능).`);
+    }
+    lines.push("", "※ 보유비중 = 외국인 보유주식수 / 상장주식수. 한도소진률 = 보유 / 외국인 한도. 종가 부호는 전일 대비 방향.");
+    return lines.join("\n");
+}
+export function registerForeignHoldingTool(server) {
+    server.registerTool("get_foreign_holding", {
+        title: "외국인 보유 추이 조회",
+        description: "특정 종목의 일자별 외국인 보유 동향을 조회합니다 — 종가, 거래량, 외국인 순변동수량, 보유주식수, " +
+            "보유비중, 한도소진률 (키움 ka10008). 최신순으로 기본 15일 표시하며 limit으로 최대 50일까지 조정할 수 있습니다.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 종목코드여야 합니다")
+                .describe("조회할 6자리 종목코드"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("표시할 일수 (기본 15, 최대 50; 최신순)"),
+        },
+    }, async ({ stock_code, limit }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const rows = await fetchForeignHolding(client, stock_code);
+        return textResult(formatForeignHolding(rows, stock_code, config.modeLabel, limit ?? DEFAULT_DISPLAY_DAYS));
+    }));
+}

package/dist/tools/helpers.js

@@ -0,0 +1,19 @@
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * Wraps a tool body so every failure returns a readable MCP error result
+ * (isError: true) instead of a raw protocol exception.
+ */
+export async function runTool(fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            isError: true,
+            content: [{ type: "text", text: `⚠️ ${message}` }],
+        };
+    }
+}

package/dist/tools/investor-trend.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchInvestorDaily, fetchInvestorTotal } from "../kiwoom/api.js";
+import { formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
+import { formatNumber, formatSigned, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_LOOKBACK_DAYS = 30;
+const DAILY_ROWS = 10;
+/** amt_qty_tp cross-checked live: amount mode is 백만원, quantity mode is 주. */
+const UNIT_LABELS = { amount: "백만원", quantity: "주" };
+const ORGN_DETAIL = [
+    { key: "fnnc_invt", label: "금융투자" },
+    { key: "insrnc", label: "보험" },
+    { key: "invtrt", label: "투신" },
+    { key: "bank", label: "은행" },
+    { key: "penfnd_etc", label: "연기금등" },
+    { key: "samo_fund", label: "사모펀드" },
+    { key: "etc_fnnc", label: "기타금융" },
+];
+const s = (raw) => formatSigned(parseKiwoomNumber(raw));
+export function formatInvestorTrend(total, daily, stockCode, fromDate, toDate, unit, modeLabel) {
+    const period = `${formatDateDashed(fromDate)} ~ ${formatDateDashed(toDate)}`;
+    if (!total && daily.length === 0) {
+        return `[${modeLabel}] ${stockCode} 투자자 매매동향 데이터가 없습니다 (${period}). 종목코드를 확인해 주세요.`;
+    }
+    const lines = [
+        `[${modeLabel}] ${stockCode} 투자자별 매매동향 (${period}, 순매수, 단위: ${UNIT_LABELS[unit]})`,
+    ];
+    if (total) {
+        lines.push("", "■ 기간 합계", `- 개인: ${s(total.ind_invsr)} / 외국인: ${s(total.frgnr_invsr)} / 기관계: ${s(total.orgn)}`, `  · 기관 세부: ${ORGN_DETAIL.map((d) => `${d.label} ${s(total[d.key])}`).join(", ")}`, `- 기타법인: ${s(total.etc_corp)} / 내외국인: ${s(total.natfor)} / 국가: ${s(total.natn)}`);
+    }
+    if (daily.length > 0) {
+        lines.push("", `■ 최근 ${Math.min(daily.length, DAILY_ROWS)}거래일`, "| 일자 | 종가 | 전일대비 | 개인 | 외국인 | 기관계 |", "|---|---:|---:|---:|---:|---:|");
+        for (const d of daily.slice(0, DAILY_ROWS)) {
+            lines.push(`| ${formatDateDashed(d.dt)} | ${formatNumber(parseKiwoomPrice(d.cur_prc))} | ${s(d.pred_pre)} | ` +
+                `${s(d.ind_invsr)} | ${s(d.frgnr_invsr)} | ${s(d.orgn)} |`);
+        }
+    }
+    return lines.join("\n");
+}
+export function registerInvestorTrendTool(server) {
+    server.registerTool("get_investor_trend", {
+        title: "투자자별 매매동향 조회",
+        description: "종목의 개인/외국인/기관 순매수 동향을 조회합니다 (키움 ka10059+ka10061). 기간 합계와 " +
+            "최근 거래일별 내역을 함께 보여줍니다. unit: amount(금액, 백만원, 기본)/quantity(수량, 주). " +
+            "종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^[0-9A-Z]{6}$/i, "6자리 종목코드여야 합니다")
+                .describe("6자리 종목코드 (예: 005930)"),
+            from_date: z
+                .string()
+                .regex(/^\d{4}-?\d{2}-?\d{2}$/, "yyyy-MM-dd 또는 yyyyMMdd 형식이어야 합니다")
+                .optional()
+                .describe("합계 기간 시작일 (기본값: 30일 전)"),
+            to_date: z
+                .string()
+                .regex(/^\d{4}-?\d{2}-?\d{2}$/, "yyyy-MM-dd 또는 yyyyMMdd 형식이어야 합니다")
+                .optional()
+                .describe("합계 기간 종료일 (기본값: 오늘)"),
+            unit: z.enum(["amount", "quantity"]).optional().describe("단위 (기본값: amount=백만원)"),
+        },
+    }, async ({ stock_code, from_date, to_date, unit }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const code = stock_code.toUpperCase();
+        const fromDate = (from_date ?? kstDaysAgo(DEFAULT_LOOKBACK_DAYS)).replaceAll("-", "");
+        const toDate = (to_date ?? todayInKst()).replaceAll("-", "");
+        const u = unit ?? "amount";
+        // ka10061 and ka10059 are different TRs — per-TR rate limits allow parallel calls.
+        const [total, daily] = await Promise.all([
+            fetchInvestorTotal(client, code, fromDate, toDate, u),
+            fetchInvestorDaily(client, code, toDate, u),
+        ]);
+        return textResult(formatInvestorTrend(total, daily, code, fromDate, toDate, u, config.modeLabel));
+    }));
+}

package/dist/tools/isa-tax-status.js

@@ -0,0 +1,245 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { classifyInstrument } from "../isa/classify.js";
+import { classifyInstruments } from "../isa/classify-etf.js";
+import { reconstructRealizedPnl } from "../isa/realized.js";
+import { computeIsaTaxStatus, ISA_LIMITS } from "../isa/tax.js";
+import { fetchAccountEvaluation, fetchRealizedPnlSummary, fetchTransactions } from "../kiwoom/api.js";
+import { loadMasterList } from "../kiwoom/master-list.js";
+import { normalizeStockCode } from "../kiwoom/types.js";
+import { formatDateDashed, todayInKst } from "../utils/date.js";
+import { formatKRW, formatSignedKRW, parseKiwoomNumber } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DIVIDEND_PATTERN = /배당|분배|이자/;
+export function scanDividends(rows) {
+    const scan = { total: 0, rows: [], otherNonTradeRows: 0 };
+    for (const row of rows) {
+        if (row.trde_kind_nm === "매매")
+            continue;
+        const label = `${row.trde_kind_nm} ${row.rmrk_nm}`.trim();
+        if (DIVIDEND_PATTERN.test(label)) {
+            const amount = parseKiwoomNumber(row.exct_amt) ?? parseKiwoomNumber(row.trde_amt) ?? 0;
+            scan.total += amount;
+            scan.rows.push({ date: row.trde_dt, label, amount });
+        }
+        else {
+            scan.otherNonTradeRows += 1;
+        }
+    }
+    return scan;
+}
+export function toTradeEvents(rows) {
+    const events = [];
+    const skipped = [];
+    rows.forEach((row, index) => {
+        if (row.trde_kind_nm !== "매매")
+            return;
+        const side = row.io_tp_nm.includes("매수") ? "BUY" : row.io_tp_nm.includes("매도") ? "SELL" : null;
+        const quantity = parseKiwoomNumber(row.trde_qty_jwa_cnt);
+        const netAmount = parseKiwoomNumber(row.exct_amt);
+        if (!side || quantity === null || netAmount === null) {
+            skipped.push(`${row.trde_dt} ${row.stk_nm} (${row.io_tp_nm || "구분 불명"})`);
+            return;
+        }
+        events.push({
+            code: normalizeStockCode(row.stk_cd),
+            name: row.stk_nm,
+            side,
+            quantity,
+            netAmount,
+            date: row.trde_dt,
+            seq: parseKiwoomNumber(row.trde_no) ?? index,
+        });
+    });
+    return { events, skipped };
+}
+function entryLines(entries) {
+    return entries.map((e) => `  · ${e.name} (${e.code}): ${formatSignedKRW(Math.round(e.amount))}` +
+        `${e.incomplete ? " ⚠️이력 불완전" : ""}${e.confident ? "" : " ※분류 추정"}`);
+}
+export function formatTaxReport(report) {
+    const s = report.status;
+    const round = Math.round;
+    const usedPct = s.limit > 0 ? Math.max(0, s.confirmedNet) / s.limit : 0;
+    const lines = [
+        `[${report.modeLabel}] ISA 비과세 한도 현황 — ${report.isaTypeLabel} (한도 ${formatKRW(s.limit)})`,
+        `집계 기간: ${formatDateDashed(report.fromDate)} ~ ${formatDateDashed(report.toDate)}`,
+        "",
+        "■ 확정 손익통산 (실현 기준)",
+        `- 과세대상 실현손익: ${formatSignedKRW(round(s.taxableRealized))}`,
+        ...entryLines(report.realizedEntries.filter((e) => e.taxType === "TAXABLE")),
+        `- 국내주식형 실현손익: ${formatSignedKRW(round(s.domesticRealizedNet))} → ` +
+            (s.domesticLossDeduction < 0
+                ? `순손실 ${formatKRW(round(-s.domesticLossDeduction))} 통산 차감`
+                : "이익은 비과세라 통산 제외 (차감 0원)"),
+        ...entryLines(report.realizedEntries.filter((e) => e.taxType === "DOMESTIC_EQUITY")),
+        `- 배당·분배금·이자: ${formatKRW(round(s.dividends))}` +
+            ` (자동 감지 ${report.dividendScan.rows.length}건` +
+            `${report.manualDividends !== undefined ? ` + 수동 입력 ${formatKRW(report.manualDividends)}` : ""})`,
+        ...report.dividendScan.rows.map((d) => `  · ${formatDateDashed(d.date)} ${d.label}: ${formatKRW(round(d.amount))}`),
+        `= 통산 순이익(확정): ${formatSignedKRW(round(s.confirmedNet))}`,
+        "",
+        "■ 비과세 한도",
+    ];
+    if (s.confirmedNet < 0) {
+        lines.push(`- 현재 순손실 상태 — 한도 ${formatKRW(s.limit)} 전액 잔여. ` +
+            `손실 ${formatKRW(round(-s.confirmedNet))}은 만기까지 발생하는 이익과 상계됩니다.`);
+    }
+    else {
+        lines.push(`- 사용: ${formatKRW(round(s.confirmedNet))} / ${formatKRW(s.limit)} (${(usedPct * 100).toFixed(1)}%)`, `- 잔여: ${formatKRW(round(s.remainingAllowance))}`, `- 한도 초과분 예상 세금(9.9%): ${formatKRW(round(s.estimatedTaxNow))}`);
+    }
+    lines.push("", "■ 시나리오: 현재 보유분 전량 매도 가정 (미실현 포함)", `- 과세대상 미실현: ${formatSignedKRW(round(s.taxableUnrealized))}`, ...entryLines(report.unrealizedEntries.filter((e) => e.taxType === "TAXABLE")), `- 국내주식형 미실현: ${formatSignedKRW(round(s.domesticUnrealizedNet))}` +
+        (Math.min(0, s.domesticUnrealizedNet) < 0 ? " (순손실만 차감 반영)" : " (이익은 비과세 — 미반영)"), ...entryLines(report.unrealizedEntries.filter((e) => e.taxType === "DOMESTIC_EQUITY")), `= 시나리오 통산 순이익: ${formatSignedKRW(round(s.scenarioNet))}`, `- 시나리오 잔여 한도: ${formatKRW(round(s.scenarioRemaining))} / 예상 세금: ${formatKRW(round(s.scenarioEstimatedTax))}`);
+    const kiwoom = report.kiwoomRealizedTotal;
+    if (kiwoom !== null) {
+        const diff = round(report.reconstructedTotal - kiwoom);
+        const tolerance = Math.max(1_000, Math.abs(kiwoom) * 0.01);
+        lines.push("", `※ 검증: 자체 재구성 실현손익 합계 ${formatSignedKRW(round(report.reconstructedTotal))} vs ` +
+            `키움 실현손익 TR 합계 ${formatSignedKRW(round(kiwoom))} (차이 ${formatSignedKRW(diff)}` +
+            `${Math.abs(diff) > tolerance ? " — ⚠️ 허용 오차 초과, 결과 신뢰도 주의" : " — 정상 범위"})`);
+    }
+    for (const warning of report.warnings) {
+        lines.push(`⚠️ ${warning}`);
+    }
+    lines.push("", "※ 이 계산은 참고용입니다. 배당 자동 감지는 아직 실데이터로 검증되지 않았고(미수령), " +
+        "과세유형 분류는 ETF는 키움 과세유형 기준이고 그 외(개별주식 등)는 종목명 기반 추정이며, " +
+        "손익통산 세부 규정(국내주식형 손실 차감 방식 등)은 " +
+        "증권사 정산과 다를 수 있습니다. 실제 과세는 만기·해지 시점에 확정되므로 정확한 금액은 " +
+        "증권사 안내를 기준으로 하세요.");
+    return lines.join("\n");
+}
+const ISA_TYPE_LABELS = { GENERAL: "일반형", SEOMIN: "서민형" };
+/**
+ * ka10099 마스터리스트에서 ETF(`marketName == "ETF"`)로 표시된 코드 집합을 만든다.
+ * 브랜드 접두어가 없는 ETF도 ka40002 확정 분류를 받게 하기 위한 게이트. 마스터리스트
+ * 조회가 실패하면 빈 집합을 반환해 종목명 휴리스틱으로 폴백한다(계산은 계속 진행).
+ */
+async function loadEtfCodeSet(client) {
+    try {
+        const master = await loadMasterList(client);
+        return new Set(master.filter((s) => s.marketName === "ETF").map((s) => s.code));
+    }
+    catch {
+        return new Set();
+    }
+}
+export function registerIsaTaxStatusTool(server) {
+    server.registerTool("calc_isa_tax_status", {
+        title: "ISA 비과세 한도 현황 계산",
+        description: "ISA 계좌의 손익통산 순이익을 계산해 비과세 한도(일반형 200만원/서민형 400만원) 대비 " +
+            "사용량·잔여량을 보여줍니다. 실현손익(거래내역 재구성)과 배당을 확정분으로, 보유 종목 " +
+            "미실현 손익을 '전량 매도 가정' 시나리오로 함께 제공합니다. 집계 시작일은 ISA_OPENED_ON " +
+            "환경변수(계좌 개설일) 또는 from_date 인자로 지정합니다. 배당 수령액이 거래내역에서 " +
+            "감지되지 않으면 dividends_received로 수동 입력하세요.",
+        inputSchema: {
+            from_date: z
+                .string()
+                .regex(/^\d{4}-?\d{2}-?\d{2}$/, "yyyy-MM-dd 또는 yyyyMMdd 형식이어야 합니다")
+                .optional()
+                .describe("집계 시작일 (기본값: ISA_OPENED_ON 환경변수 = 계좌 개설일)"),
+            dividends_received: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("집계 기간 중 수령한 배당·분배금·이자 총액(원) — 자동 감지분에 더해짐"),
+            overrides: z
+                .array(z.object({
+                stock_code: z.string().describe("6자리 종목코드"),
+                tax_type: z
+                    .enum(["TAXABLE", "DOMESTIC_EQUITY"])
+                    .describe("TAXABLE=과세대상(해외/채권형 등), DOMESTIC_EQUITY=국내주식형(매매차익 비과세)"),
+            }))
+                .optional()
+                .describe("자동 과세유형 분류가 틀린 종목의 수동 지정"),
+        },
+    }, async ({ from_date, dividends_received, overrides }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const fromDate = (from_date ?? config.isaOpenedOn)?.replaceAll("-", "");
+        if (!fromDate) {
+            throw new Error("집계 시작일이 없습니다. .env에 ISA_OPENED_ON=yyyy-MM-dd(계좌 개설일)를 설정하거나 " +
+                "from_date 인자를 전달해 주세요.");
+        }
+        const toDate = todayInKst();
+        const overrideMap = new Map((overrides ?? []).map((o) => [o.stock_code, o.tax_type]));
+        // Distinct TRs — per-TR rate limits allow parallel calls. loadEtfCodeSet
+        // (ka10099) is best-effort and never rejects, so Promise.all is safe.
+        const [transactions, evaluation, realizedSummary, etfCodes] = await Promise.all([
+            fetchTransactions(client, fromDate, toDate),
+            fetchAccountEvaluation(client, "2"),
+            fetchRealizedPnlSummary(client, fromDate, toDate),
+            loadEtfCodeSet(client),
+        ]);
+        const { events, skipped } = toTradeEvents(transactions.rows);
+        const reconstruction = reconstructRealizedPnl(events);
+        const dividendScan = scanDividends(transactions.rows);
+        const holdingCodes = evaluation.acnt_evlt_remn_indv_tot.map((h) => ({
+            code: normalizeStockCode(h.stk_cd),
+            name: h.stk_nm,
+        }));
+        // 실현·미실현 종목을 한 번에 dedup 분류: ETF는 ka40002 과세유형으로 확정,
+        // 그 외는 종목명 휴리스틱으로 폴백한다.
+        const classifications = await classifyInstruments(client, [...reconstruction.perStock.map((r) => ({ code: r.code, name: r.name })), ...holdingCodes], overrideMap, etfCodes);
+        const classifyOf = (code, name) => classifications.get(code) ?? classifyInstrument(code, name, overrideMap);
+        const realizedEntries = reconstruction.perStock.map((r) => {
+            const c = classifyOf(r.code, r.name);
+            return {
+                code: r.code,
+                name: r.name,
+                amount: r.realized,
+                taxType: c.taxType,
+                confident: c.confident,
+                reason: c.reason,
+                incomplete: r.incompleteHistory,
+            };
+        });
+        const unrealizedEntries = evaluation.acnt_evlt_remn_indv_tot.map((h) => {
+            const code = normalizeStockCode(h.stk_cd);
+            const c = classifyOf(code, h.stk_nm);
+            return {
+                code,
+                name: h.stk_nm,
+                amount: parseKiwoomNumber(h.evltv_prft) ?? 0,
+                taxType: c.taxType,
+                confident: c.confident,
+                reason: c.reason,
+            };
+        });
+        const dividends = dividendScan.total + (dividends_received ?? 0);
+        const status = computeIsaTaxStatus({
+            limit: ISA_LIMITS[config.isaType],
+            dividends,
+            realized: realizedEntries,
+            unrealized: unrealizedEntries,
+        });
+        const warnings = [...reconstruction.warnings];
+        if (transactions.truncated) {
+            warnings.push("거래내역이 조회 상한에 도달해 일부 오래된 거래가 누락되었을 수 있습니다 — " +
+                "집계 시작일(from_date)을 좁혀 재확인하세요. 실현손익·배당 집계가 불완전할 수 있습니다.");
+        }
+        if (evaluation.truncated) {
+            warnings.push("보유 종목이 조회 상한에 도달해 일부가 누락되었을 수 있습니다 — 미실현 시나리오가 불완전할 수 있습니다.");
+        }
+        if (skipped.length > 0) {
+            warnings.push(`매수/매도로 분류하지 못해 제외한 거래 ${skipped.length}건: ${skipped.join(", ")}`);
+        }
+        if (dividendScan.otherNonTradeRows > 0) {
+            warnings.push(`배당으로 분류되지 않은 비매매 거래 ${dividendScan.otherNonTradeRows}건이 있습니다. ` +
+                `필요 시 거래내역을 직접 확인하세요.`);
+        }
+        const report = {
+            modeLabel: config.modeLabel,
+            isaTypeLabel: ISA_TYPE_LABELS[config.isaType],
+            fromDate,
+            toDate,
+            status,
+            realizedEntries,
+            unrealizedEntries,
+            dividendScan,
+            manualDividends: dividends_received,
+            kiwoomRealizedTotal: parseKiwoomNumber(realizedSummary.rlzt_pl),
+            reconstructedTotal: reconstruction.total,
+            warnings,
+        };
+        return textResult(formatTaxReport(report));
+    }));
+}

package/dist/tools/market-index.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchAllIndices } from "../kiwoom/api.js";
+import { formatNumber, formatPercent, formatSigned, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const MARKET_LABELS = { kospi: "코스피", kosdaq: "코스닥" };
+export function formatIndices(items, market, modeLabel) {
+    if (items.length === 0) {
+        return `[${modeLabel}] ${MARKET_LABELS[market]} 지수 데이터가 없습니다.`;
+    }
+    const lines = [
+        `[${modeLabel}] ${MARKET_LABELS[market]} 업종 지수 (${items.length}개)`,
+        "",
+        "| 지수 | 현재 | 전일대비 | 등락률 | 상승/보합/하락 |",
+        "|---|---:|---:|---:|---:|",
+    ];
+    for (const item of items) {
+        lines.push(`| ${item.stk_nm} | ${formatNumber(parseKiwoomPrice(item.cur_prc))} | ` +
+            `${formatSigned(parseKiwoomNumber(item.pred_pre))} | ${formatPercent(parseKiwoomNumber(item.flu_rt))} | ` +
+            `${parseKiwoomNumber(item.rising) ?? "-"}/${parseKiwoomNumber(item.stdns) ?? "-"}/${parseKiwoomNumber(item.fall) ?? "-"} |`);
+    }
+    return lines.join("\n");
+}
+export function registerMarketIndexTool(server) {
+    server.registerTool("get_market_index", {
+        title: "시장 지수 조회",
+        description: "코스피/코스닥 종합지수와 업종별 지수를 조회합니다 (키움 ka20003). " +
+            "첫 행이 시장 종합지수, 이후는 업종 지수입니다.",
+        inputSchema: {
+            market: z
+                .enum(["kospi", "kosdaq"])
+                .optional()
+                .describe("시장 구분 (기본값: kospi)"),
+        },
+    }, async ({ market }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const m = market ?? "kospi";
+        const items = await fetchAllIndices(client, m === "kospi" ? "001" : "101");
+        return textResult(formatIndices(items, m, config.modeLabel));
+    }));
+}

package/dist/tools/orderbook.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchOrderbook } from "../kiwoom/api.js";
+import { formatNumber, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+/** Levels 2-10 sit in the loose passthrough under sel_/buy_{n}th_pre_* keys. */
+function passthroughField(book, key) {
+    const value = book[key];
+    return typeof value === "string" ? value : null;
+}
+export function formatOrderbook(book, stockCode, modeLabel) {
+    const price = (raw) => formatNumber(parseKiwoomPrice(raw));
+    const qty = (raw) => formatNumber(parseKiwoomNumber(raw));
+    const baseTm = book.bid_req_base_tm;
+    const baseTmLabel = baseTm.length === 6 ? `${baseTm.slice(0, 2)}:${baseTm.slice(2, 4)}:${baseTm.slice(4, 6)}` : baseTm;
+    const lines = [
+        `[${modeLabel}] ${stockCode} 호가 (기준시각 ${baseTmLabel})`,
+        "",
+        "| 구분 | 호가 | 잔량 |",
+        "|---|---:|---:|",
+    ];
+    for (let level = 10; level >= 2; level--) {
+        lines.push(`| 매도${level} | ${price(passthroughField(book, `sel_${level}th_pre_bid`))} | ${qty(passthroughField(book, `sel_${level}th_pre_req`))} |`);
+    }
+    lines.push(`| 매도1 | ${price(book.sel_fpr_bid)} | ${qty(book.sel_fpr_req)} |`);
+    lines.push(`| 매수1 | ${price(book.buy_fpr_bid)} | ${qty(book.buy_fpr_req)} |`);
+    for (let level = 2; level <= 10; level++) {
+        lines.push(`| 매수${level} | ${price(passthroughField(book, `buy_${level}th_pre_bid`))} | ${qty(passthroughField(book, `buy_${level}th_pre_req`))} |`);
+    }
+    lines.push("", `총잔량 — 매도 ${qty(book.tot_sel_req)} / 매수 ${qty(book.tot_buy_req)}`);
+    return lines.join("\n");
+}
+export function registerOrderbookTool(server) {
+    server.registerTool("get_orderbook", {
+        title: "호가 조회",
+        description: "종목의 10단계 매도/매수 호가와 잔량을 조회합니다 (키움 ka10004). " +
+            "종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^[0-9A-Z]{6}$/i, "6자리 종목코드여야 합니다")
+                .describe("6자리 종목코드 (예: 005930)"),
+        },
+    }, async ({ stock_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const code = stock_code.toUpperCase();
+        const book = await fetchOrderbook(client, code);
+        return textResult(formatOrderbook(book, code, config.modeLabel));
+    }));
+}