kiwoom-mcp-server 0.9.0 → 0.14.0

package/README.en.md

@@ -25,15 +25,22 @@ allowance.
 |---|---|---|
 | `search_stock` | Name → code search (KOSPI/KOSDAQ, incl. ETF/ETN) | ka10099 |
 | `get_stock_price` | Current price / change rate / volume / basic metrics | ka10001 |
-| `get_stock_chart` | Daily/weekly/monthly/minute candles (adjusted price) | ka10080~83 |
+| `get_stock_chart` | Daily/weekly/monthly/yearly/minute/tick candles (adjusted price) | ka10079~83, ka10094 |
 | `get_orderbook` | 10-level ask/bid quotes and sizes | ka10004 |
 | `get_market_index` | KOSPI/KOSDAQ composite and sector indices | ka20003 |
+| `get_sector_price` | Sector index detail (breadth / 52-week range / intraday trend) | ka20001 |
+| `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_etf_info` | ETF tracking index / tax type / quote | ka40002, ka10001 |
+| `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

@@ -23,15 +23,22 @@ Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·
 |---|---|---|
 | `search_stock` | 종목명→코드 검색 (코스피/코스닥, ETF/ETN 포함) | ka10099 |
 | `get_stock_price` | 현재가/등락률/거래량/기본지표 | ka10001 |
-| `get_stock_chart` | 일/주/월/분봉 캔들 차트 (수정주가 반영) | ka10080~83 |
+| `get_stock_chart` | 일/주/월/년/분/틱봉 캔들 차트 (수정주가 반영) | ka10079~83, ka10094 |
 | `get_orderbook` | 10단계 매도/매수 호가·잔량 | ka10004 |
 | `get_market_index` | 코스피/코스닥 종합·업종 지수 | ka20003 |
+| `get_sector_price` | 업종 지수 현재가 상세 (등락 구성·52주 고저·시간대별 추이) | ka20001 |
+| `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_etf_info` | ETF 추적지수·과세유형·시세 | ka40002, ka10001 |
+| `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, foreignHoldingResponseSchema, investorDailyItemSchema, investorTotalItemSchema, limitStockItemSchema, minuteChartItemSchema, newHighLowItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, priceJumpItemSchema, realizedPnlResponseSchema, 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];
@@ -136,11 +137,13 @@ const CHART_TRS = {
     day: { apiId: "ka10081", arrayKey: "stk_dt_pole_chart_qry" },
     week: { apiId: "ka10082", arrayKey: "stk_stk_pole_chart_qry" },
     month: { apiId: "ka10083", arrayKey: "stk_mth_pole_chart_qry" },
+    year: { apiId: "ka10094", arrayKey: "stk_yr_pole_chart_qry" },
 };
 /**
- * ka10081/82/83 일·주·월봉 — newest first; first page (240~600 rows) only,
- * which is plenty for LLM consumption and avoids pagination rate-limit cost.
- * upd_stkpc_tp "1" = 수정주가 반영.
+ * ka10081/82/83/94 일·주·월·년봉 — same item shape, array key differs per TR
+ * (년봉 rows carry no pred_pre — schema defaults cover it). Newest first;
+ * first page (년봉 ~30, others 240~600 rows) only, which is plenty for LLM
+ * consumption and avoids pagination rate-limit cost. upd_stkpc_tp "1" = 수정주가 반영.
  */
 export async function fetchDailyChart(client, stockCode, period, baseDate) {
     const { apiId, arrayKey } = CHART_TRS[period];
@@ -160,6 +163,19 @@ export async function fetchMinuteChart(client, stockCode, ticScope) {
     });
     return parseArray(res.json, "stk_min_pole_chart_qry", minuteChartItemSchema);
 }
+/**
+ * ka10079 틱차트 — tic_scope = 캔들당 틱 수 ("1"|"3"|"5"|"10"|"30"). Row shape는
+ * ka10080 분봉과 동일(cntr_tm 포함; top-level last_tic_cnt는 미소비). Newest first,
+ * first page (900 rows) only.
+ */
+export async function fetchTickChart(client, stockCode, ticScope) {
+    const res = await client.call({
+        path: CHART_PATH,
+        apiId: "ka10079",
+        body: { stk_cd: stockCode, tic_scope: ticScope, upd_stkpc_tp: "1" },
+    });
+    return parseArray(res.json, "stk_tic_chart_qry", minuteChartItemSchema);
+}
 /** ka10004 주식호가 — 10-level orderbook; levels 2-10 live in the loose passthrough. */
 export async function fetchOrderbook(client, stockCode) {
     const res = await client.call({
@@ -178,6 +194,35 @@ export async function fetchAllIndices(client, indsCd) {
     });
     return allIndexResponseSchema.parse(res.json).all_inds_idex;
 }
+/**
+ * ka20001/ka20002의 mrkt_tp는 inds_cd 선행 자리에서 유도한다
+ * (0xx→"0" 코스피, 1xx→"1" 코스닥, 2xx→"2" 코스피200; mock-probed 2026-07-09).
+ * inds_cd 자체는 ka20003의 업종코드 공간을 그대로 쓴다.
+ */
+function sectorMarketType(indsCd) {
+    return indsCd.startsWith("1") ? "1" : indsCd.startsWith("2") ? "2" : "0";
+}
+/** ka20001 업종현재가 — 업종 지수 스냅샷 + 시간대별 추이. */
+export async function fetchSectorPrice(client, indsCd) {
+    const res = await client.call({
+        path: SECTOR_PATH,
+        apiId: "ka20001",
+        body: { mrkt_tp: sectorMarketType(indsCd), inds_cd: indsCd },
+    });
+    return sectorPriceResponseSchema.parse(res.json);
+}
+/**
+ * ka20002 업종별주가 — 업종 구성 종목의 시세. 100행/페이지(종목코드순)이며
+ * 첫 페이지만 가져온다; 남은 페이지가 있으면 truncated로 알린다.
+ */
+export async function fetchSectorStocks(client, indsCd) {
+    const res = await client.call({
+        path: SECTOR_PATH,
+        apiId: "ka20002",
+        body: { mrkt_tp: sectorMarketType(indsCd), inds_cd: indsCd, stex_tp: "1" },
+    });
+    return { items: sectorStocksResponseSchema.parse(res.json).inds_stkpc, truncated: res.hasNext };
+}
 /** amt_qty_tp: "1"=금액(백만원), "2"=수량(주) — 순매수(trde_tp "0") 기준. */
 const INVESTOR_UNIT_CODES = { amount: "1", quantity: "2" };
 /** ka10061 종목별투자자기관종합 — investor net-buy totals over a date range. */
@@ -277,6 +322,45 @@ export async function fetchEtfInfo(client, stockCode) {
     });
     return etfInfoResponseSchema.parse(res.json);
 }
+/** ka40001의 dt(기간) 코드 — 조회 순서대로 4행 테이블을 만든다. */
+export const ETF_RETURN_PERIODS = [
+    { dt: "0", label: "1주" },
+    { dt: "1", label: "1개월" },
+    { dt: "2", label: "6개월" },
+    { dt: "3", label: "1년" },
+];
+/**
+ * ka40001 ETF수익율 — 기간(dt)별 ETF 수익률 + 대상지수 수익률. mock-probed
+ * 2026-07-09: etfobjt_idex_cd는 필수(빈값 → 1511 오류)지만 ETF와 대조 검증되지
+ * 않는 "벤치마크 지수 선택자"다 — cntr_prft_rt가 그 지수의 기간 수익률로 채워진다.
+ * 4개 dt를 순차 호출(같은 TR — 레이트리밋 1.1s 간격)해 기간 순서대로 돌려준다.
+ */
+export async function fetchEtfReturns(client, stockCode, benchmarkIndexCode) {
+    const rows = [];
+    for (const [i, period] of ETF_RETURN_PERIODS.entries()) {
+        if (i > 0)
+            await sleep(PAGE_INTERVAL_MS);
+        const res = await client.call({
+            path: ETF_PATH,
+            apiId: "ka40001",
+            body: { stk_cd: stockCode, etfobjt_idex_cd: benchmarkIndexCode, dt: period.dt },
+        });
+        rows.push(parseArray(res.json, "etfprft_rt_lst", etfReturnItemSchema)[0] ?? null);
+    }
+    return rows;
+}
+/**
+ * ka40009 ETF NAV 추이 — 최신순 배열(etfnavarray)이지만 행에 시각 필드가 없다.
+ * mock에서는 NAV 관련 필드가 전부 빈 문자열 — 호출부는 빈값을 허용해야 한다.
+ */
+export async function fetchEtfNav(client, stockCode) {
+    const res = await client.call({
+        path: ETF_PATH,
+        apiId: "ka40009",
+        body: { stk_cd: stockCode },
+    });
+    return parseArray(res.json, "etfnavarray", etfNavItemSchema);
+}
 /**
  * ka01300 관심종목 그룹 리스트 조회 — HTS에 저장된 관심종목 그룹 목록 (읽기 전용).
  * 응답 배열 키는 nofi. 편집(추가/삭제) TR은 키움 REST에 존재하지 않는다.
@@ -356,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

@@ -195,6 +195,57 @@ export const allIndexResponseSchema = z.looseObject({
     ...envelope,
     all_inds_idex: z.array(indexItemSchema).default([]),
 });
+// ── ka20001: 업종현재가 (subset) ──
+/** 시간대별 행 (`*_n` suffix). tm_n "999999"/"888888"은 장마감 집계 센티널 — 표시 시 필터. */
+export const sectorTimeRowSchema = z.looseObject({
+    tm_n: str(),
+    cur_prc_n: str(),
+    pred_pre_n: str(),
+    flu_rt_n: str(),
+    acc_trde_qty_n: str(), // 누적 거래량 (천주)
+});
+export const sectorPriceResponseSchema = z.looseObject({
+    ...envelope,
+    cur_prc: str(), // 지수 (소수점, 부호 접두)
+    pred_pre: str(),
+    flu_rt: str(),
+    trde_qty: str(), // 천주 (ka20003과 동일 단위)
+    trde_prica: str(), // 백만원
+    trde_frmatn_stk_num: str(), // 거래형성 종목수
+    trde_frmatn_rt: str(), // 거래형성 비율(%), 부호 접두
+    open_pric: str(),
+    high_pric: str(),
+    low_pric: str(),
+    upl: str(), // 상한 종목수
+    rising: str(),
+    stdns: str(), // 보합
+    fall: str(),
+    lst: str(), // 하한 종목수
+    "52wk_hgst_pric": str(),
+    "52wk_hgst_pric_dt": str(), // yyyyMMdd
+    "52wk_hgst_pric_pre_rt": str(), // 현재가의 52주 최고 대비 등락률
+    "52wk_lwst_pric": str(),
+    "52wk_lwst_pric_dt": str(),
+    "52wk_lwst_pric_pre_rt": str(),
+    inds_cur_prc_tm: z.array(sectorTimeRowSchema).default([]),
+});
+// ── ka20002: 업종별주가 (subset) ──
+export const sectorStockItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(),
+    pred_pre_sig: str(),
+    pred_pre: str(),
+    flu_rt: str(),
+    now_trde_qty: str(),
+    open_pric: str(),
+    high_pric: str(),
+    low_pric: str(),
+});
+export const sectorStocksResponseSchema = z.looseObject({
+    ...envelope,
+    inds_stkpc: z.array(sectorStockItemSchema).default([]),
+});
 // ── ka10059/ka10061: 종목별 투자자·기관 (13-field investor breakdown) ──
 // amt_qty_tp "1"=금액(백만원), "2"=수량(주) — cross-checked live against volume.
 const investorFields = {
@@ -259,6 +310,26 @@ export const etfInfoResponseSchema = z.looseObject({
     etftxon_type: str(), // ETF 과세유형 ("비과세" 등)
     etntxon_type: str(),
 });
+// ── ka40001: ETF수익율 (array key etfprft_rt_lst; mock-probed 2026-07-09) ──
+// NOTE: cntr_prft_rt is the period return of the index selected by the
+// etfobjt_idex_cd REQUEST field (not validated against the ETF) — probed:
+// same code → same value regardless of stk_cd; bogus code → "0.00".
+export const etfReturnItemSchema = z.looseObject({
+    etfprft_rt: str(), // ETF 기간 수익률(%)
+    cntr_prft_rt: str(), // 대상지수(etfobjt_idex_cd) 기간 수익률(%)
+    for_netprps_qty: str(), // 외인 순매수량
+    orgn_netprps_qty: str(), // 기관 순매수량 (mock: blank)
+});
+// ── ka40009: ETF NAV 추이 (array key etfnavarray, newest first, no time field) ──
+// Rows carry NO timestamp; NAV/괴리율/추적오차 fields arrive blank on mock —
+// only stkcnt/base_pric are populated there. Callers must tolerate blanks.
+export const etfNavItemSchema = z.looseObject({
+    nav: str(),
+    navpred_pre: str(), // NAV 전일대비
+    navflu_rt: str(), // NAV 등락률(%)
+    trace_eor_rt: str(), // 추적오차율(%)
+    dispty_rt: str(), // 괴리율(%)
+});
 // ── ka01300/ka01301: 관심종목 그룹 (HTS 저장 그룹, live-verified 2026-07-06) ──
 // NOTE: array keys are nofi(그룹)/nofj(종목); item fields are terse (gcod/name,
 // cod2/bgb) and differ from the usual snake_case TRs. The response also carries
@@ -350,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,7 +2,9 @@ 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";
 import { registerInvestorTrendTool } from "./tools/investor-trend.js";
 import { registerIsaTaxStatusTool } from "./tools/isa-tax-status.js";
@@ -11,17 +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.9.0";
+export const SERVER_VERSION = "0.14.0";
 export function createServer() {
     const server = new McpServer({
         name: SERVER_NAME,
@@ -34,12 +40,19 @@ export function createServer() {
     registerStockChartTool(server);
     registerOrderbookTool(server);
     registerMarketIndexTool(server);
+    registerSectorPriceTool(server);
+    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-info.js

@@ -1,9 +1,9 @@
 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 { fetchEtfInfo, fetchEtfNav, fetchStockInfo } from "../kiwoom/api.js";
+import { formatKRW, formatPercent, formatQuantity, formatRatioPercent, formatSigned, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
-export function formatEtfInfo(etf, quote, stockCode, modeLabel) {
+export function formatEtfInfo(etf, quote, nav, stockCode, modeLabel) {
     if (!etf.stk_nm) {
         return `[${modeLabel}] ${stockCode}의 ETF 정보가 없습니다. ETF 종목코드인지 확인해 주세요.`;
     }
@@ -16,14 +16,21 @@ export function formatEtfInfo(etf, quote, stockCode, modeLabel) {
     if (quote) {
         lines.push(`- 현재가: ${formatKRW(parseKiwoomPrice(quote.cur_prc))} (${formatPercent(parseKiwoomNumber(quote.flu_rt))})`, `- 거래량: ${formatQuantity(parseKiwoomNumber(quote.trde_qty))}`);
     }
+    // ka40009 NAV — 필드가 빈값으로 오는 환경(mock 확인)이 있어 값이 있을 때만 표시.
+    const navValue = parseKiwoomPrice(nav?.nav);
+    if (nav && navValue !== null) {
+        lines.push(`- NAV: ${formatKRW(navValue)} (전일대비 ${formatSigned(parseKiwoomNumber(nav.navpred_pre))}, ` +
+            `${formatPercent(parseKiwoomNumber(nav.navflu_rt))})`, `- 괴리율: ${formatPercent(parseKiwoomNumber(nav.dispty_rt))} · ` +
+            `추적오차율: ${formatRatioPercent(parseKiwoomNumber(nav.trace_eor_rt))}`);
+    }
     lines.push("", "※ 과세유형은 키움 표기 기준입니다. 매매차익 과세 방식(국내주식형 비과세 vs 배당소득 과세)은 " +
-        "계좌 유형에 따라 달라질 수 있습니다.");
+        "계좌 유형에 따라 달라질 수 있습니다.", "※ 기간별(1주/1개월/6개월/1년) 수익률은 get_etf_returns로 조회할 수 있습니다.");
     return lines.join("\n");
 }
 export function registerEtfInfoTool(server) {
     server.registerTool("get_etf_info", {
         title: "ETF 정보 조회",
-        description: "ETF의 추적지수, 과세유형, 현재 시세를 조회합니다 (키움 ka40002+ka10001). " +
+        description: "ETF의 추적지수, 과세유형, 현재 시세, NAV·괴리율을 조회합니다 (키움 ka40002+ka10001+ka40009). " +
             "종목코드를 모르면 search_stock으로 먼저 찾으세요.",
         inputSchema: {
             stock_code: z
@@ -34,11 +41,12 @@ export function registerEtfInfoTool(server) {
     }, 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([
+        // Different TRs — parallel is fine; quote and NAV are best-effort garnish.
+        const [etf, quote, navRows] = await Promise.all([
             fetchEtfInfo(client, code),
             fetchStockInfo(client, code).catch(() => null),
+            fetchEtfNav(client, code).catch(() => null),
         ]);
-        return textResult(formatEtfInfo(etf, quote, code, config.modeLabel));
+        return textResult(formatEtfInfo(etf, quote, navRows?.[0] ?? null, code, config.modeLabel));
     }));
 }

package/dist/tools/etf-returns.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { ETF_RETURN_PERIODS, fetchEtfInfo, fetchEtfReturns } from "../kiwoom/api.js";
+import { formatPercent, formatSigned, parseKiwoomNumber } from "../utils/num.js";
+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)) {
+        return (`[${modeLabel}] ${stockCode}의 ETF 수익률 데이터가 없습니다. ` +
+            `ETF 종목코드인지 확인해 주세요 (search_stock으로 검색 가능).`);
+    }
+    const title = etfName ? `${etfName} (${stockCode})` : stockCode;
+    const lines = [
+        `[${modeLabel}] ${title} ETF 기간 수익률`,
+        "",
+        "| 기간 | ETF 수익률 | 대상지수 수익률 | 외인 순매수량 | 기관 순매수량 |",
+        "|---|---:|---:|---:|---:|",
+    ];
+    for (const [i, period] of ETF_RETURN_PERIODS.entries()) {
+        const row = rows[i] ?? null;
+        lines.push(`| ${period.label} | ${formatPercent(n(row?.etfprft_rt))} | ${formatPercent(n(row?.cntr_prft_rt))} | ` +
+            `${formatSigned(n(row?.for_netprps_qty), 0)} | ${formatSigned(n(row?.orgn_netprps_qty), 0)} |`);
+    }
+    lines.push("", `※ 대상지수: ${benchmarkCode} (${sectorLabel(benchmarkCode)}) — benchmark_index_code로 변경할 수 ` +
+        `있습니다 (get_market_index의 '코드' 값).`);
+    return lines.join("\n");
+}
+export function registerEtfReturnsTool(server) {
+    server.registerTool("get_etf_returns", {
+        title: "ETF 기간 수익률 조회",
+        description: "ETF의 기간별(1주/1개월/6개월/1년) 수익률을 대상지수 수익률과 나란히 조회합니다 (키움 ka40001). " +
+            `대상지수는 benchmark_index_code로 지정하며 기본값은 ${DEFAULT_BENCHMARK}(KOSPI200)입니다 — ` +
+            "코드는 get_market_index의 '코드' 값을 사용하세요 (001 코스피 종합, 101 코스닥 종합 등). " +
+            "종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^[0-9A-Z]{6}$/i, "6자리 종목코드여야 합니다")
+                .describe("6자리 ETF 종목코드 (예: 069500)"),
+            benchmark_index_code: z
+                .string()
+                .regex(/^\d{3}$/)
+                .optional()
+                .describe(`비교할 지수 코드 3자리 (기본값 ${DEFAULT_BENCHMARK} KOSPI200 — get_market_index의 '코드' 값)`),
+        },
+    }, async ({ stock_code, benchmark_index_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const code = stock_code.toUpperCase();
+        const benchmark = benchmark_index_code ?? DEFAULT_BENCHMARK;
+        // 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/market-index.js

@@ -11,21 +11,23 @@ export function formatIndices(items, market, modeLabel) {
     const lines = [
         `[${modeLabel}] ${MARKET_LABELS[market]} 업종 지수 (${items.length}개)`,
         "",
-        "| 지수 | 현재 | 전일대비 | 등락률 | 상승/보합/하락 |",
-        "|---|---:|---:|---:|---:|",
+        "| 지수 | 코드 | 현재 | 전일대비 | 등락률 | 상승/보합/하락 |",
+        "|---|---|---:|---:|---:|---:|",
     ];
     for (const item of items) {
-        lines.push(`| ${item.stk_nm} | ${formatNumber(parseKiwoomPrice(item.cur_prc))} | ` +
+        lines.push(`| ${item.stk_nm} | ${item.stk_cd || "-"} | ${formatNumber(parseKiwoomPrice(item.cur_prc))} | ` +
             `${formatSigned(parseKiwoomNumber(item.pred_pre))} | ${formatPercent(parseKiwoomNumber(item.flu_rt))} | ` +
             `${parseKiwoomNumber(item.rising) ?? "-"}/${parseKiwoomNumber(item.stdns) ?? "-"}/${parseKiwoomNumber(item.fall) ?? "-"} |`);
     }
+    lines.push("", "※ 업종 상세·구성종목은 get_sector_price / get_sector_stocks에 '코드' 값을 넣어 조회하세요.");
     return lines.join("\n");
 }
 export function registerMarketIndexTool(server) {
     server.registerTool("get_market_index", {
         title: "시장 지수 조회",
         description: "코스피/코스닥 종합지수와 업종별 지수를 조회합니다 (키움 ka20003). " +
-            "첫 행이 시장 종합지수, 이후는 업종 지수입니다.",
+            "첫 행이 시장 종합지수, 이후는 업종 지수입니다. 각 행의 '코드'는 " +
+            "get_sector_price / get_sector_stocks의 sector_code로 사용할 수 있습니다.",
         inputSchema: {
             market: z
                 .enum(["kospi", "kosdaq"])

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/sector.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchSectorPrice, fetchSectorStocks } from "../kiwoom/api.js";
+import { formatDateDashed } from "../utils/date.js";
+import { formatNumber, formatPercent, formatRatioPercent, formatSigned, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_STOCK_LIMIT = 30;
+const MAX_STOCK_LIMIT = 100;
+const TIME_ROWS_SHOWN = 10;
+/** 잘 알려진 업종 코드 라벨 — 전체 코드 목록은 get_market_index로 조회. */
+const SECTOR_LABELS = {
+    "001": "코스피 종합",
+    "002": "코스피 대형주",
+    "101": "코스닥 종합",
+    "201": "KOSPI200",
+};
+export const sectorLabel = (code) => SECTOR_LABELS[code] ?? `업종 ${code}`;
+/** "153220" → "15:32:20"; 시각이 아닌 값(장마감 센티널 999999/888888 등)은 null. */
+function formatSectorTime(tm) {
+    if (!/^\d{6}$/.test(tm) || Number(tm.slice(0, 2)) > 23)
+        return null;
+    return `${tm.slice(0, 2)}:${tm.slice(2, 4)}:${tm.slice(4, 6)}`;
+}
+const dashedOr = (yyyymmdd) => /^\d{8}$/.test(yyyymmdd) ? formatDateDashed(yyyymmdd) : "-";
+export function formatSectorPrice(res, sectorCode, modeLabel) {
+    const n = parseKiwoomNumber;
+    const p = parseKiwoomPrice;
+    const index = p(res.cur_prc);
+    if (index === null) {
+        return (`[${modeLabel}] 업종 ${sectorCode}의 시세 데이터가 없습니다. ` +
+            `업종 코드를 확인하세요 (get_market_index의 '코드' 값).`);
+    }
+    const lines = [
+        `[${modeLabel}] 업종 현재가 — ${sectorLabel(sectorCode)} (${sectorCode})`,
+        "",
+        `지수 ${formatNumber(index)} (전일대비 ${formatSigned(n(res.pred_pre))}, ${formatPercent(n(res.flu_rt))})`,
+        `시가 ${formatNumber(p(res.open_pric))} · 고가 ${formatNumber(p(res.high_pric))} · 저가 ${formatNumber(p(res.low_pric))}`,
+        `거래량 ${formatNumber(n(res.trde_qty), 0)}천주 · 거래대금 ${formatNumber(n(res.trde_prica), 0)}백만원`,
+        `등락 구성: 상한 ${n(res.upl) ?? "-"} · 상승 ${n(res.rising) ?? "-"} · 보합 ${n(res.stdns) ?? "-"} · ` +
+            `하락 ${n(res.fall) ?? "-"} · 하한 ${n(res.lst) ?? "-"} ` +
+            `(거래형성 ${formatNumber(n(res.trde_frmatn_stk_num), 0)}종목, ${formatRatioPercent(p(res.trde_frmatn_rt))})`,
+        `52주 최고 ${formatNumber(p(res["52wk_hgst_pric"]))} (${dashedOr(res["52wk_hgst_pric_dt"])}, ` +
+            `현재 대비 ${formatPercent(n(res["52wk_hgst_pric_pre_rt"]))}) · ` +
+            `최저 ${formatNumber(p(res["52wk_lwst_pric"]))} (${dashedOr(res["52wk_lwst_pric_dt"])}, ` +
+            `현재 대비 ${formatPercent(n(res["52wk_lwst_pric_pre_rt"]))})`,
+    ];
+    const timeRows = [];
+    for (const row of res.inds_cur_prc_tm) {
+        const time = formatSectorTime(row.tm_n);
+        if (time)
+            timeRows.push({ time, row });
+        if (timeRows.length >= TIME_ROWS_SHOWN)
+            break;
+    }
+    if (timeRows.length > 0) {
+        lines.push("", `시간대별 추이 (최근 ${timeRows.length}건)`, "", "| 시각 | 지수 | 전일대비 | 등락률 | 누적거래량(천주) |", "|---|---:|---:|---:|---:|");
+        for (const { time, row } of timeRows) {
+            lines.push(`| ${time} | ${formatNumber(p(row.cur_prc_n))} | ${formatSigned(n(row.pred_pre_n))} | ` +
+                `${formatPercent(n(row.flu_rt_n))} | ${formatNumber(n(row.acc_trde_qty_n), 0)} |`);
+        }
+    }
+    lines.push("", "※ 구성 종목별 시세는 get_sector_stocks에 같은 업종 코드를 넣어 조회하세요.");
+    return lines.join("\n");
+}
+export function formatSectorStocks(items, truncated, sectorCode, limit, modeLabel) {
+    if (items.length === 0) {
+        return (`[${modeLabel}] ${sectorLabel(sectorCode)} (${sectorCode})의 구성 종목이 없습니다. ` +
+            `업종 코드를 확인하세요 (get_market_index의 '코드' 값).`);
+    }
+    const n = parseKiwoomNumber;
+    const p = parseKiwoomPrice;
+    const shown = items.slice(0, limit);
+    const lines = [
+        `[${modeLabel}] 업종별 주가 — ${sectorLabel(sectorCode)} (${sectorCode}), ${shown.length}종목 (종목코드순)`,
+        "",
+        "| 종목명 | 코드 | 현재가 | 전일대비 | 등락률 | 거래량 | 고가 | 저가 |",
+        "|---|---|---:|---:|---:|---:|---:|---:|",
+    ];
+    for (const item of shown) {
+        lines.push(`| ${item.stk_nm || "-"} | ${item.stk_cd || "-"} | ${formatNumber(p(item.cur_prc), 0)} | ` +
+            `${formatSigned(n(item.pred_pre), 0)} | ${formatPercent(n(item.flu_rt))} | ` +
+            `${formatNumber(n(item.now_trde_qty), 0)} | ${formatNumber(p(item.high_pric), 0)} | ` +
+            `${formatNumber(p(item.low_pric), 0)} |`);
+    }
+    const notes = [];
+    if (items.length > shown.length) {
+        notes.push(`※ 첫 ${shown.length}종목만 표시했습니다 (limit으로 최대 ${MAX_STOCK_LIMIT}개까지 조정 가능).`);
+    }
+    if (truncated) {
+        notes.push("※ 구성 종목이 더 있습니다 — 이 조회는 첫 페이지(종목코드순 100종목)만 가져옵니다.");
+    }
+    if (notes.length > 0)
+        lines.push("", ...notes);
+    return lines.join("\n");
+}
+const sectorCodeSchema = z
+    .string()
+    .regex(/^\d{3}$/)
+    .describe("업종 코드 3자리 (예: 001 코스피 종합, 101 코스닥 종합 — get_market_index의 '코드' 값)");
+export function registerSectorPriceTool(server) {
+    server.registerTool("get_sector_price", {
+        title: "업종 현재가 조회",
+        description: "업종(섹터) 지수의 현재가 상세를 조회합니다 (키움 ka20001) — 지수·시/고/저가·거래량·" +
+            "상승/하락 종목수·52주 고저·시간대별 추이. sector_code는 get_market_index가 보여주는 " +
+            "업종 코드입니다 (001 코스피 종합, 002 코스피 대형주, 101 코스닥 종합, 201 KOSPI200 등).",
+        inputSchema: {
+            sector_code: sectorCodeSchema,
+        },
+    }, async ({ sector_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const res = await fetchSectorPrice(client, sector_code);
+        return textResult(formatSectorPrice(res, sector_code, config.modeLabel));
+    }));
+}
+export function registerSectorStocksTool(server) {
+    server.registerTool("get_sector_stocks", {
+        title: "업종별 종목 시세 조회",
+        description: "특정 업종에 속한 종목들의 시세를 조회합니다 (키움 ka20002). 종목코드순 정렬이며 " +
+            "첫 페이지(최대 100종목)만 가져옵니다. sector_code는 get_market_index의 업종 코드입니다.",
+        inputSchema: {
+            sector_code: sectorCodeSchema,
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_STOCK_LIMIT)
+                .optional()
+                .describe(`표시할 종목 수 (기본값 ${DEFAULT_STOCK_LIMIT}, 최대 ${MAX_STOCK_LIMIT})`),
+        },
+    }, async ({ sector_code, limit }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const { items, truncated } = await fetchSectorStocks(client, sector_code);
+        return textResult(formatSectorStocks(items, truncated, sector_code, limit ?? DEFAULT_STOCK_LIMIT, config.modeLabel));
+    }));
+}

package/dist/tools/stock-chart.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
-import { fetchDailyChart, fetchMinuteChart } from "../kiwoom/api.js";
+import { fetchDailyChart, fetchMinuteChart, fetchTickChart } 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";
@@ -10,7 +10,7 @@ const PERIOD_LABELS = {
     day: "일봉",
     week: "주봉",
     month: "월봉",
-    minute: "분봉",
+    year: "년봉",
 };
 /** "20260703153000" → "2026-07-03 15:30" */
 function formatMinuteTime(cntrTm) {
@@ -37,13 +37,14 @@ export function formatDailyChart(items, stockCode, period, count, modeLabel) {
     ];
     return lines.join("\n");
 }
-export function formatMinuteChart(items, stockCode, ticScope, count, modeLabel) {
+/** 분봉과 틱봉이 같은 행 구조(cntr_tm)를 공유 — scopeLabel은 "5분"/"30틱" 형태. */
+export function formatMinuteChart(items, stockCode, scopeLabel, count, modeLabel) {
     if (items.length === 0) {
-        return `[${modeLabel}] ${stockCode} 분봉 데이터가 없습니다. 종목코드를 확인해 주세요.`;
+        return `[${modeLabel}] ${stockCode} ${scopeLabel}봉 데이터가 없습니다. 종목코드를 확인해 주세요.`;
     }
     const shown = items.slice(0, count).reverse();
     const lines = [
-        `[${modeLabel}] ${stockCode} ${ticScope}분봉 차트 (최근 ${shown.length}개, 수정주가 반영)`,
+        `[${modeLabel}] ${stockCode} ${scopeLabel}봉 차트 (최근 ${shown.length}개, 수정주가 반영)`,
         "",
         "| 시각 | 시가 | 고가 | 저가 | 종가 | 거래량 |",
         "|---|---:|---:|---:|---:|---:|",
@@ -53,17 +54,18 @@ export function formatMinuteChart(items, stockCode, ticScope, count, modeLabel)
 }
 export function registerStockChartTool(server) {
     server.registerTool("get_stock_chart", {
-        title: "주식 차트 조회 (일/주/월/분봉)",
-        description: "종목의 캔들 차트 데이터를 조회합니다 (키움 ka10080~ka10083, 수정주가 반영). " +
-            "period: day(일봉, 기본)/week(주봉)/month(월봉)/minute(분봉). 분봉은 minute_scope로 " +
-            "분 단위를 지정합니다. 종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        title: "주식 차트 조회 (일/주/월/년/분/틱봉)",
+        description: "종목의 캔들 차트 데이터를 조회합니다 (키움 ka10079~ka10083/ka10094, 수정주가 반영). " +
+            "period: day(일봉, 기본)/week(주봉)/month(월봉)/year(년봉)/minute(분봉)/tick(틱봉). " +
+            "분봉은 minute_scope로 분 단위를, 틱봉은 tick_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"])
+                .enum(["day", "week", "month", "year", "minute", "tick"])
                 .optional()
                 .describe("봉 주기 (기본값: day)"),
             count: z
@@ -77,15 +79,22 @@ export function registerStockChartTool(server) {
                 .enum(["1", "3", "5", "10", "15", "30", "45", "60"])
                 .optional()
                 .describe("period=minute일 때 분 단위 (기본값: 5)"),
+            tick_scope: z
+                .enum(["1", "3", "5", "10", "30"])
+                .optional()
+                .describe("period=tick일 때 캔들당 틱 수 (기본값: 30)"),
         },
-    }, async ({ stock_code, period, count, minute_scope }) => runTool(async () => {
+    }, async ({ stock_code, period, count, minute_scope, tick_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));
+        if (period === "minute" || period === "tick") {
+            const isTick = period === "tick";
+            const scope = isTick ? (tick_scope ?? "30") : (minute_scope ?? "5");
+            const items = isTick
+                ? await fetchTickChart(client, code, scope)
+                : await fetchMinuteChart(client, code, scope);
+            return textResult(formatMinuteChart(items, code, `${scope}${isTick ? "틱" : "분"}`, n, config.modeLabel));
         }
         const p = period ?? "day";
         const items = await fetchDailyChart(client, code, p, todayInKst());

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.9.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",