kiwoom-mcp-server 0.12.0 → 0.14.0

package/README.en.md

@@ -32,11 +32,15 @@ allowance.
 | `get_sector_stocks` | Member stocks of a sector with quotes | ka20002 |
 | `get_ranking` | Top gainers / losers / volume / trading value | ka10027/30/32 |
 | `get_market_movers` | New highs / new lows / upper & lower limit / surges / plunges | ka10016/17/19 |
+| `get_vi_stocks` | Today's volatility-interruption (VI) triggered stocks (trigger price / disparity / times) | ka10054 |
 | `get_investor_trend` | Retail / foreign / institutional net-buy trend (period sum + daily) | ka10059, ka10061 |
+| `get_broker_activity` | Per-stock top-5 buying/selling brokers (member firms) | ka10002 |
 | `get_etf_info` | ETF tracking index / tax type / quote / NAV & disparity | ka40002, ka10001, ka40009 |
 | `get_etf_returns` | ETF period returns (1w/1m/6m/1y) vs a benchmark index | ka40001 |
 | `get_short_selling` | Per-stock daily short-selling trend (short volume / weight / avg price) | ka10014 |
+| `get_stock_lending` | Securities-lending trend (contracted / repaid / change / balance) — per stock or market-wide | ka10068, ka20068 |
 | `get_foreign_holding` | Per-stock foreign holding trend (holdings / holding weight / limit-usage rate) | ka10008 |
+| `get_program_trading` | Today's top program-trading net buys / sells (KOSPI/KOSDAQ) | ka90003 |
 
 **Watchlist** (interest-stock groups saved in the 영웅문 HTS client — read-only):
 

package/README.md

@@ -30,11 +30,15 @@ Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·
 | `get_sector_stocks` | 업종 구성 종목 시세 (현재가·등락률·거래량·고저가) | ka20002 |
 | `get_ranking` | 상승률/하락률/거래량/거래대금 상위 | ka10027/30/32 |
 | `get_market_movers` | 신고가/신저가/상한가/하한가/급등/급락 특이 종목 | ka10016/17/19 |
+| `get_vi_stocks` | 당일 VI(변동성완화장치) 발동 종목 (발동가·괴리율·시각) | ka10054 |
 | `get_investor_trend` | 개인/외국인/기관 순매수 동향 (기간 합계 + 일별) | ka10059, ka10061 |
+| `get_broker_activity` | 종목별 거래원(증권사) 매수/매도 상위 5 | ka10002 |
 | `get_etf_info` | ETF 추적지수·과세유형·시세·NAV/괴리율 | ka40002, ka10001, ka40009 |
 | `get_etf_returns` | ETF 기간별(1주/1개월/6개월/1년) 수익률 vs 대상지수 | ka40001 |
 | `get_short_selling` | 종목별 일자별 공매도 추이 (공매도량·비중·평균가) | ka10014 |
+| `get_stock_lending` | 대차거래 추이 (체결·상환·증감·잔고) — 종목별 또는 시장 전체 | ka10068, ka20068 |
 | `get_foreign_holding` | 종목별 외국인 보유 추이 (보유주식수·보유비중·한도소진률) | ka10008 |
+| `get_program_trading` | 당일 프로그램 매매 순매수/순매도 상위 (코스피/코스닥) | ka90003 |
 
 **관심종목** (영웅문 HTS에 저장한 관심 그룹, 읽기 전용):
 

package/dist/kiwoom/api.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { sleep } from "../utils/sleep.js";
 import { KiwoomApiError } from "./errors.js";
-import { accountEvaluationResponseSchema, allIndexResponseSchema, dailyChartItemSchema, depositResponseSchema, etfInfoResponseSchema, etfNavItemSchema, etfReturnItemSchema, foreignHoldingResponseSchema, investorDailyItemSchema, investorTotalItemSchema, limitStockItemSchema, minuteChartItemSchema, newHighLowItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, priceJumpItemSchema, realizedPnlResponseSchema, sectorPriceResponseSchema, sectorStocksResponseSchema, shortSellingResponseSchema, stockInfoResponseSchema, stockListResponseSchema, themeGroupsResponseSchema, tradingJournalResponseSchema, themeStocksResponseSchema, transactionsResponseSchema, valueRankItemSchema, volumeRankItemSchema, watchlistGroupDetailResponseSchema, watchlistGroupsResponseSchema, } from "./types.js";
+import { accountEvaluationResponseSchema, allIndexResponseSchema, brokerActivityResponseSchema, dailyChartItemSchema, depositResponseSchema, etfInfoResponseSchema, etfNavItemSchema, etfReturnItemSchema, foreignHoldingResponseSchema, investorDailyItemSchema, investorTotalItemSchema, lendingTrendResponseSchema, limitStockItemSchema, minuteChartItemSchema, newHighLowItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, priceJumpItemSchema, programTradeItemSchema, realizedPnlResponseSchema, sectorPriceResponseSchema, sectorStocksResponseSchema, shortSellingResponseSchema, stockInfoResponseSchema, stockListResponseSchema, themeGroupsResponseSchema, tradingJournalResponseSchema, themeStocksResponseSchema, transactionsResponseSchema, valueRankItemSchema, viStockItemSchema, volumeRankItemSchema, watchlistGroupDetailResponseSchema, watchlistGroupsResponseSchema, } from "./types.js";
 const STOCK_INFO_PATH = "/api/dostk/stkinfo";
 const ACCOUNT_PATH = "/api/dostk/acnt";
 const CHART_PATH = "/api/dostk/chart";
@@ -13,6 +13,7 @@ const WATCHLIST_PATH = "/api/dostk/watchlist";
 const THEME_PATH = "/api/dostk/thme";
 const SHORT_PATH = "/api/dostk/shsa";
 const FOREIGN_PATH = "/api/dostk/frgnistt";
+const SLB_PATH = "/api/dostk/slb";
 /** Pulls an array out of an already-envelope-checked response body. */
 function parseArray(json, key, itemSchema) {
     const value = json[key];
@@ -439,6 +440,88 @@ export async function fetchForeignHolding(client, stockCode) {
     });
     return foreignHoldingResponseSchema.parse(res.json).stk_frgnr;
 }
+const VI_DIRECTION_CODES = { all: "0", up: "1", down: "2" };
+const VI_TYPE_CODES = { all: "0", static: "1", dynamic: "2" };
+/**
+ * ka10054 변동성완화장치(VI) 발동종목 — mock-probed 2026-07-10. 필터 12종 중
+ * 거래량/거래대금 필터는 미사용("0"), skip_stk "000000000" = 전종목 포함.
+ * stockCode 지정 시 해당 종목의 당일 발동 내역만 (미발동이면 빈 배열).
+ */
+export async function fetchViStocks(client, market, direction, viType, stockCode) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10054",
+        body: {
+            mrkt_tp: RANKING_MARKET_CODES[market],
+            bf_mkrt_tp: "0",
+            stk_cd: stockCode ?? "",
+            motn_tp: VI_TYPE_CODES[viType],
+            skip_stk: "000000000",
+            trde_qty_tp: "0",
+            min_trde_qty: "0",
+            max_trde_qty: "0",
+            trde_prica_tp: "0",
+            min_trde_prica: "0",
+            max_trde_prica: "0",
+            motn_drc: VI_DIRECTION_CODES[direction],
+            stex_tp: "1",
+        },
+    });
+    return parseArray(res.json, "motn_stk", viStockItemSchema);
+}
+/** ka10002 주식거래원 — 상위 5 매도/매수 거래원 (flat 37 fields, mock-probed 2026-07-10). */
+export async function fetchBrokerActivity(client, stockCode) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10002",
+        body: { stk_cd: stockCode },
+    });
+    return brokerActivityResponseSchema.parse(res.json);
+}
+/**
+ * ka10068(전체)/ka20068(종목별) 대차거래추이 — securities-lending daily trend.
+ * 두 TR은 배열 키(dbrt_trde_trnsn)와 행 구조가 동일하다 (mock-probed 2026-07-10).
+ * stockCode 지정 시 ka20068 (all_tp "0" = 입력종목만), 미지정 시 ka10068 시장 전체
+ * (all_tp "1" = 전체표시). Rows newest-first.
+ */
+export async function fetchLendingTrend(client, stockCode, fromDate, toDate) {
+    const res = await client.call(stockCode
+        ? {
+            path: SLB_PATH,
+            apiId: "ka20068",
+            body: { stk_cd: stockCode, all_tp: "0", strt_dt: fromDate, end_dt: toDate },
+        }
+        : {
+            path: SLB_PATH,
+            apiId: "ka10068",
+            body: { all_tp: "1", strt_dt: fromDate, end_dt: toDate },
+        });
+    return lendingTrendResponseSchema.parse(res.json).dbrt_trde_trnsn;
+}
+/** ka90003만 쓰는 P-접두 시장코드 — 전체(all) 옵션이 없는 TR이다. */
+const PROGRAM_MARKET_CODES = {
+    kospi: "P00101",
+    kosdaq: "P10102",
+};
+/**
+ * ka90003 프로그램순매수상위50 — program-trading net buy/sell top-50 for the day.
+ * trde_upper_tp "1"=순매도, "2"=순매수; amt_qty_tp는 투자자 TR과 동일 코드
+ * (1=금액 백만원, 2=수량 주)이며 prm_* 필드의 단위가 이를 따른다. 장 시작 전에는
+ * rc=0 + 빈 배열이 온다 (mock-probed 2026-07-10 08:30 KST).
+ */
+export async function fetchProgramTrades(client, direction, unit, market) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka90003",
+        body: {
+            trde_upper_tp: direction === "net_sell" ? "1" : "2",
+            amt_qty_tp: INVESTOR_UNIT_CODES[unit],
+            mrkt_tp: PROGRAM_MARKET_CODES[market],
+            stex_tp: "1",
+        },
+    });
+    return parseArray(res.json, "prm_netprps_upper_50", programTradeItemSchema);
+}
 /**
  * ka10170 당일매매일지요청 — the day's trading journal (per-stock realized P&L). Account-scoped.
  * Returns the full response (period totals + return_msg) so callers can surface the

package/dist/kiwoom/types.js

@@ -421,6 +421,80 @@ export const foreignHoldingResponseSchema = z.looseObject({
     ...envelope,
     stk_frgnr: z.array(foreignHoldingItemSchema).default([]),
 });
+// ── ka10068(전체)/ka20068(종목별): 대차거래추이 — /api/dostk/slb ──
+// Both TRs share the array key AND the row shape (mock-probed 2026-07-10).
+// 당일 행은 집계 전이라 전부 "0"으로 올 수 있다.
+export const lendingTrendItemSchema = z.looseObject({
+    dt: str(), // 일자 yyyyMMdd
+    dbrt_trde_cntrcnt: str(), // 대차거래 체결주수 (주)
+    dbrt_trde_rpy: str(), // 대차거래 상환주수 (주)
+    dbrt_trde_irds: str(), // 대차거래 증감 (주, 부호) = 체결 − 상환
+    rmnd: str(), // 잔고주수 (주)
+    remn_amt: str(), // 잔고금액 (백만원)
+});
+export const lendingTrendResponseSchema = z.looseObject({
+    ...envelope,
+    dbrt_trde_trnsn: z.array(lendingTrendItemSchema).default([]),
+});
+// ── ka10054: 변동성완화장치(VI) 발동종목 — /api/dostk/stkinfo ──
+// 정적 VI 행은 dynm_* 필드가 "0"/"0.00"으로 온다; virelis_time "000000" = 미해제.
+export const viStockItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    acc_trde_qty: str(), // 누적거래량 (주)
+    motn_pric: str(), // 발동가격 (원)
+    dynm_dispty_rt: str(), // 동적괴리율(%)
+    trde_cntr_proc_time: str(), // 매매체결처리시각 HHmmss
+    virelis_time: str(), // VI해제시각 HHmmss ("000000" = 미해제)
+    viaplc_tp: str(), // VI적용구분 ("정적"/"동적" 등)
+    dynm_stdpc: str(), // 동적기준가격 (원)
+    static_stdpc: str(), // 정적기준가격 (원)
+    static_dispty_rt: str(), // 정적괴리율(%)
+    open_pric_pre_flu_rt: str(), // 시가대비등락률(%)
+    vimotn_cnt: str(), // VI발동횟수
+});
+// ── ka10002: 주식거래원 — /api/dostk/stkinfo (flat, 상위 5 매도/매수 거래원) ──
+// 수량은 부호 접두 (매도 음수/매수 양수 — 방향 중복이라 표시할 땐 절대값).
+export const brokerActivityResponseSchema = z.looseObject({
+    ...envelope,
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(), // 현재가 (부호 방향)
+    flu_rt: str(), // 등락률(%)
+    sel_trde_ori_nm_1: str(), // 매도거래원명1
+    sel_trde_qty_1: str(), // 매도거래량1 (주, 부호 접두)
+    sel_trde_ori_nm_2: str(),
+    sel_trde_qty_2: str(),
+    sel_trde_ori_nm_3: str(),
+    sel_trde_qty_3: str(),
+    sel_trde_ori_nm_4: str(),
+    sel_trde_qty_4: str(),
+    sel_trde_ori_nm_5: str(),
+    sel_trde_qty_5: str(),
+    buy_trde_ori_nm_1: str(), // 매수거래원명1
+    buy_trde_qty_1: str(), // 매수거래량1 (주, 부호 접두)
+    buy_trde_ori_nm_2: str(),
+    buy_trde_qty_2: str(),
+    buy_trde_ori_nm_3: str(),
+    buy_trde_qty_3: str(),
+    buy_trde_ori_nm_4: str(),
+    buy_trde_qty_4: str(),
+    buy_trde_ori_nm_5: str(),
+    buy_trde_qty_5: str(),
+});
+// ── ka90003: 프로그램순매수상위50 — /api/dostk/stkinfo ──
+// prm_* 필드의 단위는 요청의 amt_qty_tp를 따른다 (1=금액 백만원, 2=수량 주).
+export const programTradeItemSchema = z.looseObject({
+    rank: str(), // 순위
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(), // 현재가 (부호 방향)
+    flu_rt: str(), // 등락률(%)
+    acc_trde_qty: str(), // 누적거래량 (주)
+    prm_sell_amt: str(), // 프로그램 매도
+    prm_buy_amt: str(), // 프로그램 매수
+    prm_netprps_amt: str(), // 프로그램 순매수 (부호)
+});
 // ── ka10170: 당일매매일지 — /api/dostk/acnt (live-verified 2026-07-07) ──
 // NOTE: an empty trading day returns ONE all-blank row (not an empty array) — callers
 // must filter blank rows (empty stk_cd/stk_nm). A base_dt beyond ~2 months returns

package/dist/server.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { isIsaEnabled } from "./config.js";
 import { registerAccountBalanceTool } from "./tools/account-balance.js";
 import { registerAccountHoldingsTool } from "./tools/account-holdings.js";
+import { registerBrokerActivityTool } from "./tools/broker-activity.js";
 import { registerEtfInfoTool } from "./tools/etf-info.js";
 import { registerEtfReturnsTool } from "./tools/etf-returns.js";
 import { registerForeignHoldingTool } from "./tools/foreign-holding.js";
@@ -12,18 +13,21 @@ import { registerMarketMoversTool } from "./tools/market-movers.js";
 import { registerOrderbookTool } from "./tools/orderbook.js";
 import { registerPendingOrdersTool } from "./tools/pending-orders.js";
 import { registerPingTool } from "./tools/ping.js";
+import { registerProgramTradingTool } from "./tools/program-trading.js";
 import { registerRankingTool } from "./tools/ranking.js";
 import { registerSectorPriceTool, registerSectorStocksTool } from "./tools/sector.js";
 import { registerShortSellingTool } from "./tools/short-selling.js";
 import { registerStockChartTool } from "./tools/stock-chart.js";
+import { registerStockLendingTool } from "./tools/stock-lending.js";
 import { registerStockPriceTool } from "./tools/stock-price.js";
 import { registerStockSearchTool } from "./tools/stock-search.js";
 import { registerThemeGroupsTool, registerThemeStocksTool } from "./tools/theme.js";
 import { registerTradingJournalTool } from "./tools/trading-journal.js";
 import { registerTransactionsTool } from "./tools/transactions.js";
+import { registerViStocksTool } from "./tools/vi-stocks.js";
 import { registerWatchlistGroupsTool, registerWatchlistTool } from "./tools/watchlist.js";
 export const SERVER_NAME = "kiwoom-mcp-server";
-export const SERVER_VERSION = "0.12.0";
+export const SERVER_VERSION = "0.14.0";
 export function createServer() {
     const server = new McpServer({
         name: SERVER_NAME,
@@ -40,11 +44,15 @@ export function createServer() {
     registerSectorStocksTool(server);
     registerRankingTool(server);
     registerMarketMoversTool(server);
+    registerViStocksTool(server);
     registerInvestorTrendTool(server);
+    registerBrokerActivityTool(server);
     registerEtfInfoTool(server);
     registerEtfReturnsTool(server);
     registerShortSellingTool(server);
+    registerStockLendingTool(server);
     registerForeignHoldingTool(server);
+    registerProgramTradingTool(server);
     // Watchlist (HTS 저장 관심종목 — read-only; ka01300/ka01301)
     registerWatchlistGroupsTool(server);
     registerWatchlistTool(server);

package/dist/tools/broker-activity.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchBrokerActivity } from "../kiwoom/api.js";
+import { formatKRW, formatNumber, formatPercent, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+export function formatBrokerActivity(data, stockCode, modeLabel) {
+    // (매수명, 매수량, 매도명, 매도량) 순위 1~5 — 이름이 전부 비면 데이터 없음.
+    const slots = [
+        [data.buy_trde_ori_nm_1, data.buy_trde_qty_1, data.sel_trde_ori_nm_1, data.sel_trde_qty_1],
+        [data.buy_trde_ori_nm_2, data.buy_trde_qty_2, data.sel_trde_ori_nm_2, data.sel_trde_qty_2],
+        [data.buy_trde_ori_nm_3, data.buy_trde_qty_3, data.sel_trde_ori_nm_3, data.sel_trde_qty_3],
+        [data.buy_trde_ori_nm_4, data.buy_trde_qty_4, data.sel_trde_ori_nm_4, data.sel_trde_qty_4],
+        [data.buy_trde_ori_nm_5, data.buy_trde_qty_5, data.sel_trde_ori_nm_5, data.sel_trde_qty_5],
+    ];
+    const filled = slots.filter(([buyNm, , selNm]) => buyNm || selNm);
+    if (filled.length === 0) {
+        return `[${modeLabel}] ${stockCode}의 거래원 정보가 없습니다. 종목코드를 확인해 주세요.`;
+    }
+    const n = parseKiwoomNumber;
+    const title = data.stk_nm ? `${data.stk_nm} (${stockCode})` : stockCode;
+    const lines = [
+        `[${modeLabel}] ${title} 거래원 상위 — 현재가 ${formatKRW(parseKiwoomPrice(data.cur_prc))} (${formatPercent(n(data.flu_rt))})`,
+        "",
+        "| 순위 | 매수 거래원 | 매수량(주) | 매도 거래원 | 매도량(주) |",
+        "|---:|---|---:|---|---:|",
+    ];
+    filled.forEach(([buyNm, buyQty, selNm, selQty], i) => {
+        // 수량 부호는 매수/매도 방향 중복이라 절대값으로 표시.
+        const cells = [
+            String(i + 1),
+            buyNm || "-",
+            formatNumber(parseKiwoomPrice(buyQty)),
+            selNm || "-",
+            formatNumber(parseKiwoomPrice(selQty)),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    });
+    lines.push("", "※ 당일 거래원(증권사)별 누적 매수/매도 수량 상위 5개사입니다.");
+    return lines.join("\n");
+}
+export function registerBrokerActivityTool(server) {
+    server.registerTool("get_broker_activity", {
+        title: "거래원 동향 조회",
+        description: "특정 종목의 당일 거래원(증권사)별 매수/매도 상위 5개사를 조회합니다 (키움 ka10002). " +
+            "어느 증권사 창구에서 많이 사고팔았는지 보여줍니다. 종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 종목코드여야 합니다")
+                .describe("조회할 6자리 종목코드"),
+        },
+    }, async ({ stock_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const data = await fetchBrokerActivity(client, stock_code);
+        return textResult(formatBrokerActivity(data, stock_code, config.modeLabel));
+    }));
+}

package/dist/tools/etf-returns.js

@@ -6,6 +6,19 @@ import { runTool, textResult } from "./helpers.js";
 import { sectorLabel } from "./sector.js";
 /** ka40001의 etfobjt_idex_cd는 필수 — 지정이 없으면 KOSPI200(201)을 기본 벤치마크로 쓴다. */
 const DEFAULT_BENCHMARK = "201";
+/**
+ * 비ETF 가드 안내 (2026-07-10 GUI 테스트 발견 대응): ka40001은 일반 종목 코드에도
+ * 수익률을 돌려주므로 ka40002로 선별한다 — 비ETF는 stk_nm은 있지만 추적지수명이
+ * 빈값, 존재하지 않는 코드는 둘 다 빈값 (mock-probed 2026-07-10).
+ */
+export function formatNonEtfNotice(stockName, stockCode, modeLabel) {
+    if (stockName) {
+        return (`[${modeLabel}] ${stockName} (${stockCode})은(는) ETF가 아니어서 ETF 기간 수익률을 제공하지 않습니다. ` +
+            `일반 종목 시세는 get_stock_price / get_stock_chart를 이용하세요.`);
+    }
+    return (`[${modeLabel}] ${stockCode}의 ETF 정보를 찾을 수 없습니다. ` +
+        `ETF 종목코드인지 확인해 주세요 (search_stock으로 검색 가능).`);
+}
 export function formatEtfReturns(rows, etfName, stockCode, benchmarkCode, modeLabel) {
     const n = parseKiwoomNumber;
     if (rows.every((r) => r === null || n(r.etfprft_rt) === null)) {
@@ -50,11 +63,14 @@ export function registerEtfReturnsTool(server) {
         const { client, config } = getKiwoomContext();
         const code = stock_code.toUpperCase();
         const benchmark = benchmark_index_code ?? DEFAULT_BENCHMARK;
-        // 4-period loop (~3.3s, same-TR rate limit) + name garnish in parallel.
-        const [rows, etf] = await Promise.all([
-            fetchEtfReturns(client, code, benchmark),
-            fetchEtfInfo(client, code).catch(() => null),
-        ]);
+        // Non-ETF guard BEFORE the 4-call loop — best-effort: a flaky ka40002
+        // lookup must not block a real ETF, so only a successful blank-index
+        // response refuses (and it also saves the 4 wasted ka40001 calls).
+        const etf = await fetchEtfInfo(client, code).catch(() => null);
+        if (etf && !etf.etfobjt_idex_nm) {
+            return textResult(formatNonEtfNotice(etf.stk_nm, code, config.modeLabel));
+        }
+        const rows = await fetchEtfReturns(client, code, benchmark);
         return textResult(formatEtfReturns(rows, etf?.stk_nm || null, code, benchmark, config.modeLabel));
     }));
 }

package/dist/tools/program-trading.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchProgramTrades } from "../kiwoom/api.js";
+import { formatNumber, formatPercent, formatSigned, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_TOP = 20;
+const MAX_TOP = 50;
+const DIRECTION_LABELS = {
+    net_buy: "프로그램 순매수 상위",
+    net_sell: "프로그램 순매도 상위",
+};
+const MARKET_LABELS = {
+    kospi: "코스피",
+    kosdaq: "코스닥",
+};
+const UNIT_LABELS = {
+    amount: "백만원",
+    quantity: "주",
+};
+export function formatProgramTrades(items, direction, unit, market, top, modeLabel) {
+    const title = `${MARKET_LABELS[market]} ${DIRECTION_LABELS[direction]}`;
+    const shown = items.slice(0, top);
+    if (shown.length === 0) {
+        return `[${modeLabel}] ${title} 데이터가 없습니다 (장 시작 전이거나 당일 집계 전일 수 있습니다).`;
+    }
+    const n = parseKiwoomNumber;
+    const lines = [
+        `[${modeLabel}] ${title} (상위 ${shown.length}종목, 단위: ${UNIT_LABELS[unit]})`,
+        "",
+        "| 순위 | 종목명 | 코드 | 현재가 | 등락률 | 프로그램 매수 | 프로그램 매도 | 순매수 |",
+        "|---:|---|---|---:|---:|---:|---:|---:|",
+    ];
+    shown.forEach((item, i) => {
+        const cells = [
+            String(i + 1),
+            item.stk_nm,
+            item.stk_cd,
+            formatNumber(parseKiwoomPrice(item.cur_prc)),
+            formatPercent(n(item.flu_rt)),
+            formatNumber(n(item.prm_buy_amt)),
+            formatNumber(n(item.prm_sell_amt)),
+            formatSigned(n(item.prm_netprps_amt), 0),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    });
+    return lines.join("\n");
+}
+export function registerProgramTradingTool(server) {
+    server.registerTool("get_program_trading", {
+        title: "프로그램 매매 상위 조회",
+        description: "당일 프로그램 매매 순매수/순매도 상위 종목을 조회합니다 (키움 ka90003). " +
+            "direction: net_buy(순매수, 기본)/net_sell(순매도). unit: amount(금액 백만원, 기본)/" +
+            "quantity(수량 주). market: kospi(기본)/kosdaq — 이 TR에는 전체(all) 옵션이 없습니다.",
+        inputSchema: {
+            direction: z.enum(["net_buy", "net_sell"]).optional().describe("순매수/순매도 (기본값: net_buy)"),
+            unit: z.enum(["amount", "quantity"]).optional().describe("금액/수량 기준 (기본값: amount)"),
+            market: z.enum(["kospi", "kosdaq"]).optional().describe("시장 구분 (기본값: kospi)"),
+            top: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_TOP)
+                .optional()
+                .describe(`표시할 종목 수 (기본값 ${DEFAULT_TOP}, 최대 ${MAX_TOP})`),
+        },
+    }, async ({ direction, unit, market, top }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const d = direction ?? "net_buy";
+        const u = unit ?? "amount";
+        const m = market ?? "kospi";
+        const items = await fetchProgramTrades(client, d, u, m);
+        return textResult(formatProgramTrades(items, d, u, m, top ?? DEFAULT_TOP, config.modeLabel));
+    }));
+}

package/dist/tools/stock-lending.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchLendingTrend } from "../kiwoom/api.js";
+import { assertDateRange, formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
+import { formatNumber, formatSigned, parseKiwoomNumber } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_LOOKBACK_DAYS = 30;
+export function formatLendingTrend(rows, query, modeLabel) {
+    const scope = query.stockCode ? `종목 ${query.stockCode}` : "시장 전체";
+    const period = `${formatDateDashed(query.fromDate)} ~ ${formatDateDashed(query.toDate)}`;
+    if (rows.length === 0) {
+        return `[${modeLabel}] 대차거래 추이가 없습니다 (${scope}, ${period}).`;
+    }
+    const n = parseKiwoomNumber;
+    const lines = [
+        `[${modeLabel}] 대차거래 추이 — ${scope} (${period}, ${rows.length}일)`,
+        "",
+        "| 일자 | 체결(주) | 상환(주) | 증감(주) | 잔고(주) | 잔고금액(백만원) |",
+        "|---|---:|---:|---:|---:|---:|",
+    ];
+    for (const r of rows) {
+        const cells = [
+            formatDateDashed(r.dt),
+            formatNumber(n(r.dbrt_trde_cntrcnt)),
+            formatNumber(n(r.dbrt_trde_rpy)),
+            formatSigned(n(r.dbrt_trde_irds), 0),
+            formatNumber(n(r.rmnd)),
+            formatNumber(n(r.remn_amt)),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    lines.push("", "※ 증감 = 체결 − 상환. 당일 행은 집계 확정 전이라 0으로 표시될 수 있습니다.");
+    return lines.join("\n");
+}
+export function registerStockLendingTool(server) {
+    server.registerTool("get_stock_lending", {
+        title: "대차거래 추이 조회",
+        description: "일자별 대차거래(주식 대여) 추이를 조회합니다 — 체결·상환·증감 주수와 대차잔고, 잔고금액 " +
+            "(키움 ka10068/ka20068). stock_code를 지정하면 해당 종목, 생략하면 시장 전체 집계입니다. " +
+            "기본 조회 기간은 최근 30일이며 from_date/to_date로 변경할 수 있습니다. " +
+            "공매도 흐름과 함께 보려면 get_short_selling을 참고하세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 종목코드여야 합니다")
+                .optional()
+                .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("-", ""),
+        };
+        assertDateRange(query.fromDate, query.toDate);
+        const rows = await fetchLendingTrend(client, query.stockCode, query.fromDate, query.toDate);
+        return textResult(formatLendingTrend(rows, query, config.modeLabel));
+    }));
+}

package/dist/tools/vi-stocks.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchViStocks } 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 MARKET_LABELS = {
+    all: "전체",
+    kospi: "코스피",
+    kosdaq: "코스닥",
+};
+const DIRECTION_LABELS = {
+    all: "",
+    up: "상승 ",
+    down: "하락 ",
+};
+const TYPE_LABELS = {
+    all: "",
+    static: "정적 ",
+    dynamic: "동적 ",
+};
+/** "133301" → "13:33:01"; "000000"(미해제)과 그 외 비정상 값은 "-". */
+function formatHms(hms) {
+    if (hms.length !== 6 || hms === "000000")
+        return "-";
+    return `${hms.slice(0, 2)}:${hms.slice(2, 4)}:${hms.slice(4, 6)}`;
+}
+export function formatViStocks(items, market, direction, viType, stockCode, top, modeLabel) {
+    const scope = stockCode
+        ? `종목 ${stockCode}`
+        : `${MARKET_LABELS[market]} ${DIRECTION_LABELS[direction]}${TYPE_LABELS[viType]}`.trimEnd();
+    const shown = items.slice(0, top);
+    if (shown.length === 0) {
+        return `[${modeLabel}] ${scope} VI 발동 내역이 없습니다 (당일 기준).`;
+    }
+    const n = parseKiwoomNumber;
+    const lines = [
+        `[${modeLabel}] ${scope} VI 발동 종목 (${shown.length}건)`,
+        "",
+        "| 종목명 | 코드 | 구분 | 발동가 | 괴리율 | 시가대비 | 발동시각 | 해제시각 | 횟수 |",
+        "|---|---|---|---:|---:|---:|---|---|---:|",
+    ];
+    for (const item of shown) {
+        // 정적 VI 행은 dynm_* 필드가 "0"으로 오므로 적용구분에 맞는 괴리율을 고른다.
+        const dispty = item.viaplc_tp.includes("동적") ? item.dynm_dispty_rt : item.static_dispty_rt;
+        const cells = [
+            item.stk_nm,
+            item.stk_cd,
+            item.viaplc_tp || "-",
+            formatNumber(parseKiwoomPrice(item.motn_pric)),
+            formatPercent(n(dispty)),
+            formatPercent(n(item.open_pric_pre_flu_rt)),
+            formatHms(item.trde_cntr_proc_time),
+            formatHms(item.virelis_time),
+            formatNumber(n(item.vimotn_cnt)),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    lines.push("", "※ VI(변동성완화장치) = 급등락 시 단일가 매매로 전환되는 안전장치. 해제시각 '-'는 아직 해제되지 않았거나 기록이 없는 경우입니다.");
+    return lines.join("\n");
+}
+export function registerViStocksTool(server) {
+    server.registerTool("get_vi_stocks", {
+        title: "VI 발동 종목 조회",
+        description: "당일 변동성완화장치(VI)가 발동된 종목을 조회합니다 — 발동가격·괴리율·시가대비등락률·발동/해제 " +
+            "시각·발동횟수 (키움 ka10054). market: all(기본)/kospi/kosdaq, direction: all(기본)/up(상승)/" +
+            "down(하락), vi_type: all(기본)/static(정적)/dynamic(동적). stock_code를 지정하면 해당 종목의 " +
+            "당일 발동 내역만 조회합니다.",
+        inputSchema: {
+            market: z.enum(["all", "kospi", "kosdaq"]).optional().describe("시장 구분 (기본값: all)"),
+            direction: z.enum(["all", "up", "down"]).optional().describe("발동 방향 (기본값: all)"),
+            vi_type: z.enum(["all", "static", "dynamic"]).optional().describe("VI 유형 (기본값: all)"),
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 종목코드여야 합니다")
+                .optional()
+                .describe("특정 종목의 발동 내역만 조회 (생략 시 전체)"),
+            top: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_TOP)
+                .optional()
+                .describe(`표시할 건수 (기본값 ${DEFAULT_TOP}, 최대 ${MAX_TOP})`),
+        },
+    }, async ({ market, direction, vi_type, stock_code, top }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const m = market ?? "all";
+        const d = direction ?? "all";
+        const t = vi_type ?? "all";
+        const items = await fetchViStocks(client, m, d, t, stock_code);
+        return textResult(formatViStocks(items, m, d, t, stock_code, top ?? DEFAULT_TOP, config.modeLabel));
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiwoom-mcp-server",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Read-only MCP server exposing the Kiwoom Securities REST API (market data, account inquiry, ISA tax-allowance calculator) to Claude Desktop / Claude Code.",
   "private": false,
   "type": "module",