kiwoom-mcp-server 0.8.0

package/dist/tools/pending-orders.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchPendingOrders } from "../kiwoom/api.js";
+import { normalizeStockCode } from "../kiwoom/types.js";
+import { formatKRW, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+/** HHmmss → HH:MM:SS; passes through empty/unknown formats unchanged. */
+function formatTime(raw) {
+    const t = raw.trim();
+    if (/^\d{6}$/.test(t))
+        return `${t.slice(0, 2)}:${t.slice(2, 4)}:${t.slice(4, 6)}`;
+    return t || "-";
+}
+export function formatPendingOrders(rows, modeLabel, stockCode) {
+    const scope = stockCode ? `, 종목 ${stockCode}` : "";
+    // stock_code는 서버(ka10075)에서도 걸리지만, 예상과 다를 때를 대비해 한 번 더 필터한다.
+    const filtered = stockCode
+        ? rows.filter((r) => normalizeStockCode(r.stk_cd) === stockCode)
+        : rows;
+    if (filtered.length === 0) {
+        return `[${modeLabel}] 미체결 주문이 없습니다${stockCode ? ` (종목 ${stockCode})` : ""}.`;
+    }
+    const n = parseKiwoomNumber;
+    const lines = [
+        `[${modeLabel}] 미체결 주문 (${filtered.length}건${scope})`,
+        "",
+        "| 주문번호 | 종목 | 구분 | 상태 | 주문수량 | 미체결수량 | 주문가격 | 현재가 | 시간 |",
+        "|---|---|---|---|---:|---:|---:|---:|---|",
+    ];
+    for (const r of filtered) {
+        const code = normalizeStockCode(r.stk_cd);
+        const stock = r.stk_nm ? `${r.stk_nm} (${code})` : code || "-";
+        const cells = [
+            r.ord_no || "-",
+            stock,
+            r.io_tp_nm || r.trde_tp || "-",
+            r.ord_stt || "-",
+            n(r.ord_qty)?.toLocaleString("ko-KR") ?? "-",
+            n(r.oso_qty)?.toLocaleString("ko-KR") ?? "-",
+            formatKRW(parseKiwoomPrice(r.ord_pric)),
+            formatKRW(parseKiwoomPrice(r.cur_prc)),
+            formatTime(r.tm),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    lines.push("", "※ 미체결 = 아직 체결되지 않은 주문(정정·부분체결 포함). 주문가격 0원은 시장가 주문일 수 있습니다.");
+    return lines.join("\n");
+}
+export function registerPendingOrdersTool(server) {
+    server.registerTool("get_pending_orders", {
+        title: "미체결 주문 조회",
+        description: "계좌의 미체결(아직 체결되지 않은) 주문 목록을 조회합니다 — 주문번호, 종목, 매수/매도 구분, " +
+            "주문상태, 주문수량, 미체결수량, 주문가격, 현재가 (키움 ka10075). stock_code로 특정 종목만 " +
+            "필터링할 수 있습니다. 조회 전용이며 주문 실행 기능은 제공하지 않습니다.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 종목코드여야 합니다")
+                .optional()
+                .describe("특정 종목만 조회할 때의 6자리 종목코드"),
+        },
+    }, async ({ stock_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const rows = await fetchPendingOrders(client, stock_code);
+        return textResult(formatPendingOrders(rows, config.modeLabel, stock_code));
+    }));
+}

package/dist/tools/ping.js

@@ -0,0 +1,14 @@
+export function registerPingTool(server) {
+    server.registerTool("ping", {
+        title: "Ping",
+        description: "Health check for the Kiwoom MCP server. Takes no arguments and returns a fixed message. " +
+            "Use this to verify the server is connected.",
+    }, async () => ({
+        content: [
+            {
+                type: "text",
+                text: "pong — kiwoom-mcp-server 연결 정상 (이 tool은 키움 API를 호출하지 않아 앱키 없이도 동작합니다)",
+            },
+        ],
+    }));
+}

package/dist/tools/ranking.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchPriceChangeRanking, fetchValueRanking, fetchVolumeRanking, } from "../kiwoom/api.js";
+import { formatNumber, formatPercent, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_TOP = 20;
+const MAX_TOP = 50;
+const KIND_LABELS = {
+    rise: "상승률 상위",
+    fall: "하락률 상위",
+    volume: "거래량 상위",
+    value: "거래대금 상위",
+};
+const MARKET_LABELS = {
+    all: "전체",
+    kospi: "코스피",
+    kosdaq: "코스닥",
+};
+const row = (cells) => `| ${cells.join(" | ")} |`;
+function commonCells(rank, item) {
+    return [
+        String(rank),
+        item.stk_nm,
+        item.stk_cd,
+        formatNumber(parseKiwoomPrice(item.cur_prc)),
+        formatPercent(parseKiwoomNumber(item.flu_rt)),
+    ];
+}
+export function formatRanking(kind, market, items, top, modeLabel) {
+    const shown = items.slice(0, top);
+    if (shown.length === 0) {
+        return `[${modeLabel}] ${MARKET_LABELS[market]} ${KIND_LABELS[kind]} 데이터가 없습니다.`;
+    }
+    const lines = [`[${modeLabel}] ${MARKET_LABELS[market]} ${KIND_LABELS[kind]} (상위 ${shown.length}종목)`, ""];
+    const withValue = kind === "volume" || kind === "value";
+    lines.push(withValue
+        ? "| 순위 | 종목명 | 코드 | 현재가 | 등락률 | 거래량 | 거래대금(백만원) |"
+        : "| 순위 | 종목명 | 코드 | 현재가 | 등락률 | 거래량 |", withValue ? "|---:|---|---|---:|---:|---:|---:|" : "|---:|---|---|---:|---:|---:|");
+    shown.forEach((item, i) => {
+        const cells = commonCells(i + 1, item);
+        if (kind === "volume") {
+            const v = item;
+            cells.push(formatNumber(parseKiwoomNumber(v.trde_qty)), formatNumber(parseKiwoomNumber(v.trde_amt)));
+        }
+        else if (kind === "value") {
+            const v = item;
+            cells.push(formatNumber(parseKiwoomNumber(v.now_trde_qty)), formatNumber(parseKiwoomNumber(v.trde_prica)));
+        }
+        else {
+            cells.push(formatNumber(parseKiwoomNumber(item.now_trde_qty)));
+        }
+        lines.push(row(cells));
+    });
+    return lines.join("\n");
+}
+export function registerRankingTool(server) {
+    server.registerTool("get_ranking", {
+        title: "시장 순위 조회",
+        description: "당일 시장 순위를 조회합니다 (키움 ka10027/ka10030/ka10032). type: rise(상승률)/" +
+            "fall(하락률)/volume(거래량)/value(거래대금). market: all(전체, 기본)/kospi/kosdaq.",
+        inputSchema: {
+            type: z.enum(["rise", "fall", "volume", "value"]).describe("순위 종류"),
+            market: z.enum(["all", "kospi", "kosdaq"]).optional().describe("시장 구분 (기본값: all)"),
+            top: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_TOP)
+                .optional()
+                .describe(`표시할 종목 수 (기본값 ${DEFAULT_TOP}, 최대 ${MAX_TOP})`),
+        },
+    }, async ({ type, market, top }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const m = market ?? "all";
+        const count = top ?? DEFAULT_TOP;
+        const items = type === "volume"
+            ? await fetchVolumeRanking(client, m)
+            : type === "value"
+                ? await fetchValueRanking(client, m)
+                : await fetchPriceChangeRanking(client, m, type);
+        return textResult(formatRanking(type, m, items, count, config.modeLabel));
+    }));
+}

package/dist/tools/short-selling.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchShortSelling } from "../kiwoom/api.js";
+import { formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
+import { formatKRW, formatPercent, formatQuantity, formatRatioPercent, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_LOOKBACK_DAYS = 30;
+export function formatShortSelling(rows, query, modeLabel) {
+    const period = `${formatDateDashed(query.fromDate)} ~ ${formatDateDashed(query.toDate)}`;
+    if (rows.length === 0) {
+        return `[${modeLabel}] 공매도 추이가 없습니다 (종목 ${query.stockCode}, ${period}).`;
+    }
+    const n = parseKiwoomNumber;
+    const lines = [
+        `[${modeLabel}] 공매도 추이 — 종목 ${query.stockCode} (${period}, ${rows.length}일)`,
+        "",
+        "| 일자 | 종가 | 등락률 | 거래량 | 공매도량 | 공매도비중 | 공매도평균가 |",
+        "|---|---:|---:|---:|---:|---:|---:|",
+    ];
+    for (const r of rows) {
+        const cells = [
+            formatDateDashed(r.dt),
+            formatKRW(parseKiwoomPrice(r.close_pric)),
+            formatPercent(n(r.flu_rt)),
+            formatQuantity(n(r.trde_qty)),
+            formatQuantity(n(r.shrts_qty)),
+            formatRatioPercent(n(r.trde_wght)),
+            formatKRW(parseKiwoomPrice(r.shrts_avg_pric)),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    lines.push("", "※ 공매도비중 = 공매도량 / 거래량. 종가·등락률의 부호는 전일 대비 방향입니다.");
+    return lines.join("\n");
+}
+export function registerShortSellingTool(server) {
+    server.registerTool("get_short_selling", {
+        title: "공매도 추이 조회",
+        description: "특정 종목의 일자별 공매도 추이를 조회합니다 — 종가, 등락률, 거래량, 공매도량, 공매도비중, " +
+            "공매도평균가 (키움 ka10014). 기본 조회 기간은 최근 30일이며 from_date/to_date로 변경할 수 있습니다.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 종목코드여야 합니다")
+                .describe("조회할 6자리 종목코드"),
+            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("조회 종료일 (기본값: 오늘)"),
+        },
+    }, async ({ stock_code, from_date, to_date }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const query = {
+            stockCode: stock_code,
+            fromDate: (from_date ?? kstDaysAgo(DEFAULT_LOOKBACK_DAYS)).replaceAll("-", ""),
+            toDate: (to_date ?? todayInKst()).replaceAll("-", ""),
+        };
+        const rows = await fetchShortSelling(client, query.stockCode, query.fromDate, query.toDate);
+        return textResult(formatShortSelling(rows, query, config.modeLabel));
+    }));
+}

package/dist/tools/stock-chart.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchDailyChart, fetchMinuteChart } from "../kiwoom/api.js";
+import { formatDateDashed, todayInKst } from "../utils/date.js";
+import { formatNumber, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_COUNT = 30;
+const MAX_COUNT = 200;
+const PERIOD_LABELS = {
+    day: "일봉",
+    week: "주봉",
+    month: "월봉",
+    minute: "분봉",
+};
+/** "20260703153000" → "2026-07-03 15:30" */
+function formatMinuteTime(cntrTm) {
+    if (cntrTm.length < 12)
+        return cntrTm;
+    return `${formatDateDashed(cntrTm)} ${cntrTm.slice(8, 10)}:${cntrTm.slice(10, 12)}`;
+}
+function candleRow(time, item, volume) {
+    const p = (raw) => formatNumber(parseKiwoomPrice(raw));
+    return `| ${time} | ${p(item.open_pric)} | ${p(item.high_pric)} | ${p(item.low_pric)} | ${p(item.cur_prc)} | ${volume} |`;
+}
+export function formatDailyChart(items, stockCode, period, count, modeLabel) {
+    if (items.length === 0) {
+        return `[${modeLabel}] ${stockCode} ${PERIOD_LABELS[period]} 데이터가 없습니다. 종목코드를 확인해 주세요.`;
+    }
+    // API answers newest-first; display oldest→newest for trend reading.
+    const shown = items.slice(0, count).reverse();
+    const lines = [
+        `[${modeLabel}] ${stockCode} ${PERIOD_LABELS[period]} 차트 (최근 ${shown.length}개, 수정주가 반영)`,
+        "",
+        "| 일자 | 시가 | 고가 | 저가 | 종가 | 거래량 |",
+        "|---|---:|---:|---:|---:|---:|",
+        ...shown.map((i) => candleRow(formatDateDashed(i.dt), i, formatNumber(parseKiwoomNumber(i.trde_qty)))),
+    ];
+    return lines.join("\n");
+}
+export function formatMinuteChart(items, stockCode, ticScope, count, modeLabel) {
+    if (items.length === 0) {
+        return `[${modeLabel}] ${stockCode} 분봉 데이터가 없습니다. 종목코드를 확인해 주세요.`;
+    }
+    const shown = items.slice(0, count).reverse();
+    const lines = [
+        `[${modeLabel}] ${stockCode} ${ticScope}분봉 차트 (최근 ${shown.length}개, 수정주가 반영)`,
+        "",
+        "| 시각 | 시가 | 고가 | 저가 | 종가 | 거래량 |",
+        "|---|---:|---:|---:|---:|---:|",
+        ...shown.map((i) => candleRow(formatMinuteTime(i.cntr_tm), i, formatNumber(parseKiwoomNumber(i.trde_qty)))),
+    ];
+    return lines.join("\n");
+}
+export function registerStockChartTool(server) {
+    server.registerTool("get_stock_chart", {
+        title: "주식 차트 조회 (일/주/월/분봉)",
+        description: "종목의 캔들 차트 데이터를 조회합니다 (키움 ka10080~ka10083, 수정주가 반영). " +
+            "period: day(일봉, 기본)/week(주봉)/month(월봉)/minute(분봉). 분봉은 minute_scope로 " +
+            "분 단위를 지정합니다. 종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^[0-9A-Z]{6}$/i, "6자리 종목코드여야 합니다")
+                .describe("6자리 종목코드 (예: 005930)"),
+            period: z
+                .enum(["day", "week", "month", "minute"])
+                .optional()
+                .describe("봉 주기 (기본값: day)"),
+            count: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_COUNT)
+                .optional()
+                .describe(`캔들 개수 (기본값 ${DEFAULT_COUNT}, 최대 ${MAX_COUNT})`),
+            minute_scope: z
+                .enum(["1", "3", "5", "10", "15", "30", "45", "60"])
+                .optional()
+                .describe("period=minute일 때 분 단위 (기본값: 5)"),
+        },
+    }, async ({ stock_code, period, count, minute_scope }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const code = stock_code.toUpperCase();
+        const n = count ?? DEFAULT_COUNT;
+        if (period === "minute") {
+            const scope = minute_scope ?? "5";
+            const items = await fetchMinuteChart(client, code, scope);
+            return textResult(formatMinuteChart(items, code, scope, n, config.modeLabel));
+        }
+        const p = period ?? "day";
+        const items = await fetchDailyChart(client, code, p, todayInKst());
+        return textResult(formatDailyChart(items, code, p, n, config.modeLabel));
+    }));
+}

package/dist/tools/stock-price.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchStockInfo } from "../kiwoom/api.js";
+import { formatKRW, formatPercent, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const PRE_SIG_LABELS = {
+    "1": "상한",
+    "2": "상승",
+    "3": "보합",
+    "4": "하한",
+    "5": "하락",
+};
+export function formatStockInfo(info, modeLabel) {
+    const cur = parseKiwoomPrice(info.cur_prc);
+    const change = parseKiwoomNumber(info.pred_pre);
+    const fluRt = parseKiwoomNumber(info.flu_rt);
+    const volume = parseKiwoomNumber(info.trde_qty);
+    const sigLabel = PRE_SIG_LABELS[info.pre_sig] ?? "";
+    const changeText = change === null
+        ? "-"
+        : `${sigLabel ? `${sigLabel} ` : ""}${formatKRW(Math.abs(change))} (${formatPercent(fluRt)})`.trim();
+    const lines = [
+        `[${modeLabel}] ${info.stk_nm} (${info.stk_cd}) 시세`,
+        "",
+        `- 현재가: ${formatKRW(cur)}`,
+        `- 전일대비: ${changeText}`,
+        `- 기준가(전일종가): ${formatKRW(parseKiwoomPrice(info.base_pric))}`,
+        `- 시가/고가/저가: ${formatKRW(parseKiwoomPrice(info.open_pric))} / ${formatKRW(parseKiwoomPrice(info.high_pric))} / ${formatKRW(parseKiwoomPrice(info.low_pric))}`,
+        `- 거래량: ${volume === null ? "-" : `${volume.toLocaleString("ko-KR")}주`}`,
+        `- 250일 최고/최저: ${formatKRW(parseKiwoomPrice(info["250hgst"]))} / ${formatKRW(parseKiwoomPrice(info["250lwst"]))}`,
+    ];
+    const per = parseKiwoomNumber(info.per);
+    const eps = parseKiwoomNumber(info.eps);
+    const pbr = parseKiwoomNumber(info.pbr);
+    const mac = parseKiwoomNumber(info.mac);
+    const fundamentals = [];
+    if (per !== null)
+        fundamentals.push(`PER ${per}`);
+    if (eps !== null)
+        fundamentals.push(`EPS ${formatKRW(eps)}`);
+    if (pbr !== null)
+        fundamentals.push(`PBR ${pbr}`);
+    if (mac !== null)
+        fundamentals.push(`시가총액 ${mac.toLocaleString("ko-KR")}억원`);
+    if (fundamentals.length > 0) {
+        lines.push(`- ${fundamentals.join(" / ")}`);
+    }
+    return lines.join("\n");
+}
+export function registerStockPriceTool(server) {
+    server.registerTool("get_stock_price", {
+        title: "종목 현재가 조회",
+        description: "6자리 종목코드로 국내 주식/ETF의 현재가, 등락률, 거래량, 기본 지표를 조회합니다 (키움 ka10001). " +
+            "종목명만 알고 있다면 search_stock으로 먼저 코드를 찾으세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 숫자 종목코드여야 합니다 (예: 005930)")
+                .describe("6자리 종목코드 (예: 삼성전자 005930, KODEX 200 069500)"),
+        },
+    }, async ({ stock_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const info = await fetchStockInfo(client, stock_code);
+        return textResult(formatStockInfo(info, config.modeLabel));
+    }));
+}

package/dist/tools/stock-search.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { loadMasterList } from "../kiwoom/master-list.js";
+import { formatKRW, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const MAX_RESULTS = 10;
+/** Test hook — clears the shared master-list cache. */
+export { clearMasterListCache as clearStockListCache } from "../kiwoom/master-list.js";
+const normalize = (s) => s.replaceAll(/\s+/g, "").toLowerCase();
+export function searchStockItems(items, query, limit = MAX_RESULTS) {
+    const q = normalize(query);
+    if (q === "")
+        return [];
+    if (/^[0-9a-z]{6}$/.test(q)) {
+        const byCode = items.filter((i) => i.code.toLowerCase() === q);
+        if (byCode.length > 0)
+            return byCode.slice(0, limit);
+    }
+    const exact = [];
+    const prefix = [];
+    const partial = [];
+    for (const item of items) {
+        const name = normalize(item.name);
+        if (name === q)
+            exact.push(item);
+        else if (name.startsWith(q))
+            prefix.push(item);
+        else if (name.includes(q))
+            partial.push(item);
+    }
+    return [...exact, ...prefix, ...partial].slice(0, limit);
+}
+export function formatSearchResults(results, query, modeLabel) {
+    if (results.length === 0) {
+        return (`[${modeLabel}] "${query}"에 해당하는 종목을 찾지 못했습니다. ` +
+            `다른 키워드나 정확한 종목명으로 다시 검색해 보세요.`);
+    }
+    const lines = [
+        `[${modeLabel}] 종목 검색: "${query}" (${results.length}건${results.length >= MAX_RESULTS ? ", 상위만 표시" : ""})`,
+        "",
+        "| 코드 | 종목명 | 시장 | 전일종가 | 업종 |",
+        "|---|---|---|---:|---|",
+    ];
+    for (const r of results) {
+        lines.push(`| ${r.code} | ${r.name} | ${r.marketName || "-"} | ${formatKRW(parseKiwoomPrice(r.lastPrice))} | ${r.upName || "-"} |`);
+    }
+    return lines.join("\n");
+}
+export function registerStockSearchTool(server) {
+    server.registerTool("search_stock", {
+        title: "종목 검색 (이름→코드)",
+        description: "종목명(부분 일치)이나 6자리 코드로 코스피/코스닥 상장 종목(ETF/ETN 포함)을 검색해 " +
+            "종목코드를 찾습니다 (키움 ka10099). 다른 tool에 넘길 종목코드를 모를 때 먼저 사용하세요. " +
+            "첫 호출은 종목 마스터를 내려받아 몇 초 걸리고, 이후 12시간 동안 캐시됩니다.",
+        inputSchema: {
+            query: z.string().min(1).describe("종목명 일부(예: '삼성전자', 'KODEX 미국') 또는 6자리 종목코드"),
+        },
+    }, async ({ query }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const items = await loadMasterList(client);
+        return textResult(formatSearchResults(searchStockItems(items, query), query, config.modeLabel));
+    }));
+}

package/dist/tools/theme.js

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchThemeGroups, fetchThemeStocks } from "../kiwoom/api.js";
+import { normalizeStockCode } from "../kiwoom/types.js";
+import { formatKRW, formatPercent, formatQuantity, formatSignedKRW, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_GROUP_LIMIT = 30;
+export function formatThemeGroups(groups, modeLabel, opts) {
+    if (groups.length === 0) {
+        return opts.stockCode
+            ? `[${modeLabel}] 종목 ${opts.stockCode}이(가) 편입된 테마가 없습니다.`
+            : `[${modeLabel}] 테마 그룹을 찾을 수 없습니다.`;
+    }
+    // 종목 검색(qry_tp 2)은 결과가 적어 전부, 전체 목록은 등락률 상위 limit개만 표시.
+    const shown = opts.stockCode ? groups : groups.slice(0, opts.limit);
+    const n = parseKiwoomNumber;
+    const heading = opts.stockCode
+        ? `[${modeLabel}] 종목 ${opts.stockCode} 편입 테마 (${groups.length}개)`
+        : `[${modeLabel}] 테마 그룹 — 등락률 상위 ${shown.length}개 (기간수익률 10일 기준)`;
+    const lines = [
+        heading,
+        "",
+        "| 테마 | 코드 | 종목수 | 등락률 | 상승/하락 | 기간수익률 | 주요종목 |",
+        "|---|---|---:|---:|---:|---:|---|",
+    ];
+    for (const g of shown) {
+        const cells = [
+            g.thema_nm || "-",
+            g.thema_grp_cd || "-",
+            n(g.stk_num)?.toLocaleString("ko-KR") ?? "-",
+            formatPercent(n(g.flu_rt)),
+            `${n(g.rising_stk_num) ?? "-"}/${n(g.fall_stk_num) ?? "-"}`,
+            formatPercent(n(g.dt_prft_rt)),
+            g.main_stk || "-",
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    if (!opts.stockCode && groups.length > shown.length) {
+        lines.push("", `※ 등락률 상위 ${shown.length}개만 표시했습니다 (limit으로 최대 100개까지 조정 가능).`);
+    }
+    lines.push("", "※ 특정 테마의 구성종목은 get_theme_stocks에 '코드' 값을 넣어 조회하세요.");
+    return lines.join("\n");
+}
+export function formatThemeStocks(response, themeCode, modeLabel) {
+    const stocks = response.thema_comp_stk;
+    if (stocks.length === 0) {
+        return `[${modeLabel}] 테마 ${themeCode}의 구성종목이 없습니다 (테마 코드를 확인하세요).`;
+    }
+    const n = parseKiwoomNumber;
+    const themeRt = n(response.flu_rt);
+    const themePrft = n(response.dt_prft_rt);
+    const aggregate = themeRt !== null || themePrft !== null
+        ? ` — 테마 등락률 ${formatPercent(themeRt)} · 기간수익률 ${formatPercent(themePrft)}`
+        : "";
+    const lines = [
+        `[${modeLabel}] 테마 구성종목 (코드 ${themeCode}, ${stocks.length}종목)${aggregate}`,
+        "",
+        "| 종목 | 현재가 | 전일대비 | 등락률 | 거래량 | 기간수익률 |",
+        "|---|---:|---:|---:|---:|---:|",
+    ];
+    for (const s of stocks) {
+        const code = normalizeStockCode(s.stk_cd);
+        const cells = [
+            s.stk_nm ? `${s.stk_nm} (${code})` : code || "-",
+            formatKRW(parseKiwoomPrice(s.cur_prc)),
+            formatSignedKRW(n(s.pred_pre)),
+            formatPercent(n(s.flu_rt)),
+            formatQuantity(n(s.acc_trde_qty)),
+            formatPercent(n(s.dt_prft_rt_n)),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    return lines.join("\n");
+}
+export function registerThemeGroupsTool(server) {
+    server.registerTool("get_theme_groups", {
+        title: "테마 그룹 조회",
+        description: "키움 테마 그룹 목록을 조회합니다 — 테마명, 종목수, 등락률, 상승/하락 종목수, 기간수익률(10일), " +
+            "주요종목 (키움 ka90001). 기본은 등락률 상위 테마를 보여주며, stock_code를 주면 해당 종목이 " +
+            "편입된 테마를 검색합니다. 특정 테마의 구성종목은 get_theme_stocks로 조회하세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 종목코드여야 합니다")
+                .optional()
+                .describe("특정 종목이 편입된 테마만 검색할 6자리 종목코드"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("표시할 테마 개수 (기본 30, 최대 100; 등락률 상위순). 종목 검색 시에는 무시됩니다."),
+        },
+    }, async ({ stock_code, limit }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const groups = await fetchThemeGroups(client, stock_code);
+        return textResult(formatThemeGroups(groups, config.modeLabel, {
+            stockCode: stock_code,
+            limit: limit ?? DEFAULT_GROUP_LIMIT,
+        }));
+    }));
+}
+export function registerThemeStocksTool(server) {
+    server.registerTool("get_theme_stocks", {
+        title: "테마 구성종목 조회",
+        description: "특정 테마 그룹의 구성종목과 시세를 조회합니다 — 종목별 현재가, 전일대비, 등락률, 거래량, " +
+            "기간수익률 (키움 ka90002). theme_code는 get_theme_groups가 돌려주는 '코드' 값입니다.",
+        inputSchema: {
+            theme_code: z
+                .string()
+                .regex(/^\d{1,6}$/, "테마 코드는 숫자여야 합니다")
+                .describe("테마 그룹 코드 (get_theme_groups의 '코드' 열 값)"),
+        },
+    }, async ({ theme_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const response = await fetchThemeStocks(client, theme_code);
+        return textResult(formatThemeStocks(response, theme_code, config.modeLabel));
+    }));
+}

package/dist/tools/trading-journal.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchTradingJournal } from "../kiwoom/api.js";
+import { normalizeStockCode } from "../kiwoom/types.js";
+import { formatDateDashed, todayInKst } from "../utils/date.js";
+import { formatKRW, formatPercent, formatSignedKRW, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+export function formatTradingJournal(response, baseDate, modeLabel) {
+    // 매매 없는 날은 전 필드가 빈 placeholder 1행을 돌려주므로 실제 종목행만 남긴다.
+    const rows = response.tdy_trde_diary.filter((r) => r.stk_cd.trim() !== "" || r.stk_nm.trim() !== "");
+    // 2개월 초과 조회는 return_code 0 + return_msg 안내 + 빈 데이터로 온다.
+    const notice = (response.return_msg ?? "").includes("2개월") ? `\n⚠️ ${response.return_msg?.trim()}` : "";
+    const dateLabel = formatDateDashed(baseDate);
+    if (rows.length === 0) {
+        return `[${modeLabel}] ${dateLabel} 당일 매매 내역이 없습니다.${notice}`;
+    }
+    const n = parseKiwoomNumber;
+    const lines = [
+        `[${modeLabel}] 당일매매일지 — ${dateLabel} (${rows.length}종목)`,
+        `합계 — 매도 ${formatKRW(n(response.tot_sell_amt))} / 매수 ${formatKRW(n(response.tot_buy_amt))} / ` +
+            `손익 ${formatSignedKRW(n(response.tot_pl_amt))} (${formatPercent(n(response.tot_prft_rt))}) · ` +
+            `수수료·세금 ${formatKRW(n(response.tot_cmsn_tax))}`,
+        "",
+        "| 종목 | 매수평균가 | 매수수량 | 매도평균가 | 매도수량 | 손익금액 | 수익률 |",
+        "|---|---:|---:|---:|---:|---:|---:|",
+    ];
+    for (const r of rows) {
+        const code = normalizeStockCode(r.stk_cd);
+        const cells = [
+            r.stk_nm ? `${r.stk_nm} (${code})` : code || "-",
+            formatKRW(parseKiwoomPrice(r.buy_avg_pric)),
+            n(r.buy_qty)?.toLocaleString("ko-KR") ?? "-",
+            formatKRW(parseKiwoomPrice(r.sel_avg_pric)),
+            n(r.sell_qty)?.toLocaleString("ko-KR") ?? "-",
+            formatSignedKRW(n(r.pl_amt)),
+            formatPercent(n(r.prft_rt)),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    lines.push("", "※ 당일 매수·매도가 모두 있는 종목의 실현손익입니다 (수수료·세금 반영).");
+    return lines.join("\n") + notice;
+}
+export function registerTradingJournalTool(server) {
+    server.registerTool("get_trading_journal", {
+        title: "당일매매일지 조회",
+        description: "특정일의 당일매매일지를 조회합니다 — 종목별 매수/매도 평균가·수량, 손익금액, 수익률과 총손익·총수익률 " +
+            "(키움 ka10170). base_date를 생략하면 오늘 기준이며, 최근 2개월 이내 날짜만 조회할 수 있습니다.",
+        inputSchema: {
+            base_date: z
+                .string()
+                .regex(/^\d{4}-?\d{2}-?\d{2}$/, "yyyy-MM-dd 또는 yyyyMMdd 형식이어야 합니다")
+                .optional()
+                .describe("조회 기준일 (기본값: 오늘, 최근 2개월 이내)"),
+        },
+    }, async ({ base_date }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const baseDate = (base_date ?? todayInKst()).replaceAll("-", "");
+        const response = await fetchTradingJournal(client, baseDate);
+        return textResult(formatTradingJournal(response, baseDate, config.modeLabel));
+    }));
+}