kiwoom-mcp-server 0.12.0 → 0.16.0

package/README.en.md

@@ -23,8 +23,8 @@ allowance.
 
 | Tool | Description | Kiwoom TR |
 |---|---|---|
-| `search_stock` | Name → code search (KOSPI/KOSDAQ, incl. ETF/ETN) | ka10099 |
-| `get_stock_price` | Current price / change rate / volume / basic metrics | ka10001 |
+| `search_stock` | Name → code search (KOSPI/KOSDAQ, incl. ETF/ETN) + trading-caution flags | ka10099 |
+| `get_stock_price` | Current price / change rate / volume / basic metrics + sector, listing date, caution flags | ka10001, ka10099 |
 | `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 |
@@ -32,18 +32,22 @@ 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):
 
 | Tool | Description | Kiwoom TR |
 |---|---|---|
 | `get_watchlist_groups` | List of saved watchlist groups (code + name) | ka01300 |
-| `get_watchlist` | Stocks in a group (enriched with name / prev close / market) | ka01301, ka10099 |
+| `get_watchlist` | Stocks in a group (enriched with name / prev close / market / caution flags) | ka01301, ka10099 |
 
 > The Kiwoom REST API exposes no watchlist **edit** (add/remove) TR — read-only.
 

package/README.md

@@ -21,8 +21,8 @@ Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·
 
 | Tool | 설명 | 키움 TR |
 |---|---|---|
-| `search_stock` | 종목명→코드 검색 (코스피/코스닥, ETF/ETN 포함) | ka10099 |
-| `get_stock_price` | 현재가/등락률/거래량/기본지표 | ka10001 |
+| `search_stock` | 종목명→코드 검색 (코스피/코스닥, ETF/ETN 포함) + 투자유의 표시 | ka10099 |
+| `get_stock_price` | 현재가/등락률/거래량/기본지표 + 업종·상장일·투자유의 | ka10001, ka10099 |
 | `get_stock_chart` | 일/주/월/년/분/틱봉 캔들 차트 (수정주가 반영) | ka10079~83, ka10094 |
 | `get_orderbook` | 10단계 매도/매수 호가·잔량 | ka10004 |
 | `get_market_index` | 코스피/코스닥 종합·업종 지수 | ka20003 |
@@ -30,18 +30,22 @@ 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에 저장한 관심 그룹, 읽기 전용):
 
 | Tool | 설명 | 키움 TR |
 |---|---|---|
 | `get_watchlist_groups` | HTS 관심종목 그룹 목록 (그룹코드+그룹명) | ka01300 |
-| `get_watchlist` | 그룹 내 종목 목록 (종목명·전일종가·시장 보강) | ka01301, ka10099 |
+| `get_watchlist` | 그룹 내 종목 목록 (종목명·전일종가·시장·투자유의 보강) | ka01301, ka10099 |
 
 > 키움 REST API에는 관심종목 **편집(추가/삭제)** TR이 없어 조회만 가능합니다.
 

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/master-list.js

@@ -23,3 +23,30 @@ export async function loadMasterList(client) {
 export function clearMasterListCache() {
     cache = null;
 }
+/**
+ * ka10099 orderWarning(투자유의종목여부) codes. "5" arrives on rows whose
+ * auditInfo is 투자경고 (mock-probed 2026-07-11), so the openapi description's
+ * "투자경과" is read as a typo for 투자경고. "1" is ETF-only.
+ */
+const ORDER_WARNING_LABELS = {
+    "1": "ETF투자주의요망",
+    "2": "정리매매",
+    "3": "단기과열",
+    "4": "투자위험",
+    "5": "투자경고",
+};
+/**
+ * Abnormal-status labels for a master-list row — 감리구분(auditInfo)이 "정상"이
+ * 아니면 그 값을, orderWarning이 "0"이 아니면 라벨을 모은다. 둘이 같은 상태를
+ * 가리키는 경우(예: auditInfo "단기과열" + orderWarning "3")는 한 번만 담는다.
+ * 정상 종목은 빈 배열.
+ */
+export function masterItemWarnings(item) {
+    const warnings = [];
+    if (item.auditInfo && item.auditInfo !== "정상")
+        warnings.push(item.auditInfo);
+    const orderLabel = ORDER_WARNING_LABELS[item.orderWarning];
+    if (orderLabel && !warnings.includes(orderLabel))
+        warnings.push(orderLabel);
+    return warnings;
+}

package/dist/kiwoom/types.js

@@ -134,10 +134,12 @@ export const stockListItemSchema = z.looseObject({
     lastPrice: str(), // 전일종가, zero-padded
     marketName: str(), // "거래소" | "코스닥" | "ETF" | ...
     upName: str(), // 업종명 (ETF/ETN은 빈 값)
-    upSizeName: str(), // 대형주/중형주/소형주
+    upSizeName: str(), // 대형주/중형주/소형주 (우선주/ETF 등은 빈 값)
     state: str(), // "증거금20%|담보대출|신용가능"
-    auditInfo: str(), // "정상" 등
-    orderWarning: str(), // "0"=정상
+    auditInfo: str(), // "정상"/"거래정지"/"관리종목"/"투자주의환기종목"/"단기과열"/"투자경고" 등
+    orderWarning: str(), // 투자유의: "0"=해당없음, 나머지는 master-list.ts ORDER_WARNING_LABELS
+    regDay: str(), // 상장일 yyyyMMdd
+    companyClassName: str(), // 코스닥 전용 기업분류: 벤처기업/우량기업/스팩 등 (그 외 빈 값)
 });
 export const stockListResponseSchema = z.looseObject({
     ...envelope,
@@ -421,6 +423,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.16.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-info.js

@@ -2,10 +2,14 @@ import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
 import { fetchEtfInfo, fetchEtfNav, fetchStockInfo } from "../kiwoom/api.js";
 import { formatKRW, formatPercent, formatQuantity, formatRatioPercent, formatSigned, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
+import { formatNonEtfNotice } from "./etf-returns.js";
 import { runTool, textResult } from "./helpers.js";
 export function formatEtfInfo(etf, quote, nav, stockCode, modeLabel) {
-    if (!etf.stk_nm) {
-        return `[${modeLabel}] ${stockCode}의 ETF 정보가 없습니다. ETF 종목코드인지 확인해 주세요.`;
+    // 비ETF/미존재 코드 가드 — get_etf_returns와 동일한 ka40002 판별자
+    // (비ETF는 stk_nm만 채워지고 추적지수명이 빈값, 없는 코드는 둘 다 빈값).
+    // 이전에는 비ETF에 "-"투성이 카드가 나갔다 (2026-07-10 GUI 테스트 watch item).
+    if (!etf.stk_nm || !etf.etfobjt_idex_nm) {
+        return formatNonEtfNotice(etf.stk_nm, stockCode, modeLabel, "ETF 정보를");
     }
     const lines = [
         `[${modeLabel}] ${etf.stk_nm} (${stockCode}) ETF 정보`,

package/dist/tools/etf-returns.js

@@ -6,6 +6,20 @@ 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).
+ * get_etf_info도 같은 판별자를 쓴다 — featurePhrase는 조사까지 포함한 목적어구.
+ */
+export function formatNonEtfNotice(stockName, stockCode, modeLabel, featurePhrase = "ETF 기간 수익률을") {
+    if (stockName) {
+        return (`[${modeLabel}] ${stockName} (${stockCode})은(는) ETF가 아니어서 ${featurePhrase} 제공하지 않습니다. ` +
+            `일반 종목 시세는 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 +64,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/stock-price.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
 import { fetchStockInfo } from "../kiwoom/api.js";
+import { loadMasterList, masterItemWarnings } from "../kiwoom/master-list.js";
+import { formatDateDashed } from "../utils/date.js";
 import { formatKRW, formatPercent, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
 const PRE_SIG_LABELS = {
@@ -10,7 +12,7 @@ const PRE_SIG_LABELS = {
     "4": "하한",
     "5": "하락",
 };
-export function formatStockInfo(info, modeLabel) {
+export function formatStockInfo(info, modeLabel, master) {
     const cur = parseKiwoomPrice(info.cur_prc);
     const change = parseKiwoomNumber(info.pred_pre);
     const fluRt = parseKiwoomNumber(info.flu_rt);
@@ -45,12 +47,28 @@ export function formatStockInfo(info, modeLabel) {
     if (fundamentals.length > 0) {
         lines.push(`- ${fundamentals.join(" / ")}`);
     }
+    // ka10099 마스터 캐시에서 얻는 부가 정보 — 조회 실패 시 이 블록만 조용히 빠진다.
+    if (master) {
+        const marketParts = [master.marketName, master.upName].filter(Boolean).join(" · ");
+        const sizeClass = [master.upSizeName, master.companyClassName].filter(Boolean).join(", ");
+        if (marketParts) {
+            lines.push(`- 시장/업종: ${marketParts}${sizeClass ? ` (${sizeClass})` : ""}`);
+        }
+        if (/^\d{8}$/.test(master.regDay)) {
+            lines.push(`- 상장일: ${formatDateDashed(master.regDay)}`);
+        }
+        const warnings = masterItemWarnings(master);
+        if (warnings.length > 0) {
+            lines.push(`- ⚠️ 투자유의: ${warnings.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
@@ -60,7 +78,14 @@ export function registerStockPriceTool(server) {
         },
     }, async ({ stock_code }) => runTool(async () => {
         const { client, config } = getKiwoomContext();
-        const info = await fetchStockInfo(client, stock_code);
-        return textResult(formatStockInfo(info, config.modeLabel));
+        // 마스터 조회는 best-effort 부가정보 — 실패해도 시세 응답은 그대로 나간다.
+        // 캐시가 따뜻하면 추가 API 콜 없음(12h TTL), 콜드면 ka10099 2콜이 병렬로 얹힌다.
+        const [info, master] = await Promise.all([
+            fetchStockInfo(client, stock_code),
+            loadMasterList(client)
+                .then((items) => items.find((i) => i.code === stock_code))
+                .catch(() => undefined),
+        ]);
+        return textResult(formatStockInfo(info, config.modeLabel, master));
     }));
 }

package/dist/tools/stock-search.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
-import { loadMasterList } from "../kiwoom/master-list.js";
+import { loadMasterList, masterItemWarnings } from "../kiwoom/master-list.js";
 import { formatKRW, parseKiwoomPrice } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
 const MAX_RESULTS = 10;
@@ -38,11 +38,12 @@ export function formatSearchResults(results, query, modeLabel) {
     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 || "-"} |`);
+        const warnings = masterItemWarnings(r);
+        lines.push(`| ${r.code} | ${r.name} | ${r.marketName || "-"} | ${formatKRW(parseKiwoomPrice(r.lastPrice))} | ${r.upName || "-"} | ${warnings.join("·") || "-"} |`);
     }
     return lines.join("\n");
 }
@@ -51,6 +52,7 @@ export function registerStockSearchTool(server) {
         title: "종목 검색 (이름→코드)",
         description: "종목명(부분 일치)이나 6자리 코드로 코스피/코스닥 상장 종목(ETF/ETN 포함)을 검색해 " +
             "종목코드를 찾습니다 (키움 ka10099). 다른 tool에 넘길 종목코드를 모를 때 먼저 사용하세요. " +
+            "거래정지·관리종목·투자경고 같은 투자유의 상태는 비고 컬럼에 표시됩니다. " +
             "첫 호출은 종목 마스터를 내려받아 몇 초 걸리고, 이후 12시간 동안 캐시됩니다.",
         inputSchema: {
             query: z.string().min(1).describe("종목명 일부(예: '삼성전자', 'KODEX 미국') 또는 6자리 종목코드"),

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/dist/tools/watchlist.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
 import { fetchWatchlistGroupDetail, fetchWatchlistGroups } from "../kiwoom/api.js";
 import { KiwoomApiError } from "../kiwoom/errors.js";
-import { loadMasterList } from "../kiwoom/master-list.js";
+import { loadMasterList, masterItemWarnings } from "../kiwoom/master-list.js";
 import { normalizeStockCode, } from "../kiwoom/types.js";
 import { formatKRW, parseKiwoomPrice } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
@@ -39,7 +39,7 @@ export function formatWatchlist(group, stocks, nameIndex, modeLabel) {
     if (stocks.length === 0) {
         return `${title}\n\n(이 그룹에 등록된 종목이 없습니다.)`;
     }
-    const lines = [title, "", "| 코드 | 종목명 | 시장 | 전일종가 |", "|---|---|---|---:|"];
+    const lines = [title, "", "| 코드 | 종목명 | 시장 | 전일종가 | 비고 |", "|---|---|---|---:|---|"];
     let missing = 0;
     for (const s of stocks) {
         const code = normalizeStockCode(s.cod2);
@@ -50,7 +50,8 @@ export function formatWatchlist(group, stocks, nameIndex, modeLabel) {
         const name = `${bookmark}${info?.name || "-"}`;
         const market = info?.marketName || "-";
         const price = info ? formatKRW(parseKiwoomPrice(info.lastPrice)) : "-";
-        lines.push(`| ${code} | ${name} | ${market} | ${price} |`);
+        const flags = info ? masterItemWarnings(info).join("·") : "";
+        lines.push(`| ${code} | ${name} | ${market} | ${price} | ${flags || "-"} |`);
     }
     if (nameIndex.size === 0) {
         lines.push("", "※ 종목 마스터를 불러오지 못해 코드만 표시했습니다.");
@@ -91,7 +92,7 @@ export function registerWatchlistTool(server) {
         title: "관심종목 그룹 상세",
         description: "관심종목 그룹에 담긴 종목 목록을 조회합니다 (키움 ka01301, 읽기 전용). " +
             "그룹코드(예: '000') 또는 그룹명(예: 'etf')을 넘기세요. 그룹을 모르면 get_watchlist_groups로 먼저 확인하세요. " +
-            "종목명·전일종가·시장은 종목 마스터에서 보강해 함께 표시합니다.",
+            "종목명·전일종가·시장과 거래정지/관리종목 같은 투자유의 상태를 종목 마스터에서 보강해 함께 표시합니다.",
         inputSchema: {
             group: z
                 .string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiwoom-mcp-server",
-  "version": "0.12.0",
+  "version": "0.16.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",