kiwoom-mcp-server 0.8.0 → 0.9.0

package/README.en.md

@@ -29,6 +29,7 @@ allowance.
 | `get_orderbook` | 10-level ask/bid quotes and sizes | ka10004 |
 | `get_market_index` | KOSPI/KOSDAQ composite and sector indices | ka20003 |
 | `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_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_short_selling` | Per-stock daily short-selling trend (short volume / weight / avg price) | ka10014 |
@@ -112,11 +113,14 @@ npm test                     # unit tests (no network required)
 | `KIWOOM_APP_KEY` | ✅ | Kiwoom REST API app key |
 | `KIWOOM_APP_SECRET` | ✅ | Kiwoom REST API app secret |
 | `KIWOOM_MODE` | | `VIRTUAL` (paper trading, default) or `REAL` (live trading) |
-| `ISA_TYPE` | | `GENERAL` (general, 2,000,000 KRW limit, default) or `SEOMIN` (low-income/farmer-fisher, 4,000,000 KRW) |
-| `ISA_OPENED_ON` | | ISA account opening date `yyyy-MM-dd` — default aggregation start for `calc_isa_tax_status` |
-
-If the account is not an ISA, leave `ISA_TYPE`/`ISA_OPENED_ON` blank — only
-`calc_isa_tax_status` becomes unavailable; every other tool still works.
+| `ISA_ENABLED` | | `true` registers the `calc_isa_tax_status` tool. Default `false` (general-account-first) |
+| `ISA_TYPE` | | `GENERAL` (general, 2,000,000 KRW limit, default) or `SEOMIN` (low-income/farmer-fisher, 4,000,000 KRW). Only used when `ISA_ENABLED=true` |
+| `ISA_OPENED_ON` | | ISA account opening date `yyyy-MM-dd` — default aggregation start for `calc_isa_tax_status`. Only used when `ISA_ENABLED=true` |
+
+The default is **general-account-first**: without extra config, only the market-data
+and account-inquiry tools are exposed. To use the tax-free-limit tool on an ISA
+account, set `ISA_ENABLED=true` and fill in `ISA_TYPE`/`ISA_OPENED_ON`. When off,
+`calc_isa_tax_status` is not registered and every other tool still works.
 
 `.env` is resolved from the project root first, so the server works even when
 launched from an arbitrary working directory (as Claude Desktop does).

package/README.md

@@ -27,6 +27,7 @@ Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·
 | `get_orderbook` | 10단계 매도/매수 호가·잔량 | ka10004 |
 | `get_market_index` | 코스피/코스닥 종합·업종 지수 | ka20003 |
 | `get_ranking` | 상승률/하락률/거래량/거래대금 상위 | ka10027/30/32 |
+| `get_market_movers` | 신고가/신저가/상한가/하한가/급등/급락 특이 종목 | ka10016/17/19 |
 | `get_investor_trend` | 개인/외국인/기관 순매수 동향 (기간 합계 + 일별) | ka10059, ka10061 |
 | `get_etf_info` | ETF 추적지수·과세유형·시세 | ka40002, ka10001 |
 | `get_short_selling` | 종목별 일자별 공매도 추이 (공매도량·비중·평균가) | ka10014 |
@@ -104,11 +105,14 @@ npm test                    # 단위 테스트 (네트워크 불필요)
 | `KIWOOM_APP_KEY` | ✅ | 키움 REST API 앱키 |
 | `KIWOOM_APP_SECRET` | ✅ | 키움 REST API 앱 시크릿 |
 | `KIWOOM_MODE` | | `VIRTUAL`(모의투자, 기본값) 또는 `REAL`(실전투자) |
-| `ISA_TYPE` | | `GENERAL`(일반형, 한도 200만원, 기본값) 또는 `SEOMIN`(서민형/농어민형, 400만원) |
-| `ISA_OPENED_ON` | | ISA 계좌 개설일 `yyyy-MM-dd` — `calc_isa_tax_status` 집계 시작일 기본값 |
-
-ISA 계좌가 아니라면 `ISA_TYPE`/`ISA_OPENED_ON`은 비워 두면 됩니다 —
-`calc_isa_tax_status`만 사용할 수 없고 나머지 tool은 모두 동작합니다.
+| `ISA_ENABLED` | | `true`면 `calc_isa_tax_status` tool 활성화. 기본값 `false`(일반 계좌 기준) |
+| `ISA_TYPE` | | `GENERAL`(일반형, 한도 200만원, 기본값) 또는 `SEOMIN`(서민형/농어민형, 400만원). `ISA_ENABLED=true`일 때만 사용 |
+| `ISA_OPENED_ON` | | ISA 계좌 개설일 `yyyy-MM-dd` — `calc_isa_tax_status` 집계 시작일 기본값. `ISA_ENABLED=true`일 때만 사용 |
+
+기본값은 **일반(비-ISA) 계좌 기준**입니다 — 별도 설정이 없으면 시장·계좌 조회 tool만
+노출됩니다. ISA 계좌를 연결해 비과세 한도 tool을 쓰려면 `ISA_ENABLED=true`로 켜고
+`ISA_TYPE`/`ISA_OPENED_ON`을 채우세요. 끄면 `calc_isa_tax_status`가 등록되지 않고
+나머지 tool은 모두 그대로 동작합니다.
 
 `.env`는 프로젝트 루트에서 먼저 찾기 때문에 (Claude Desktop처럼) 임의의 작업
 디렉터리에서 실행돼도 동작합니다.

package/dist/config.js

@@ -1,16 +1,36 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+/**
+ * Treat an empty / whitespace-only env value the same as "unset", so a blank
+ * line in `.env` (e.g. the shipped `.env.example`'s `ISA_OPENED_ON=`, or a
+ * mock/general account that never uses ISA) falls back to the field's default /
+ * optional instead of failing validation. Without this, one stray empty value
+ * would throw at config load and break every tool, not just the ISA one.
+ */
+const emptyToUndefined = (v) => typeof v === "string" && v.trim() === "" ? undefined : v;
+/**
+ * Parse a boolean-ish env string. Only an explicit truthy token
+ * ("true"/"1"/"yes"/"on", case-insensitive) is true — so unset, blank, and
+ * "false" all mean disabled. Keeps ISA opt-in unambiguous.
+ */
+export const parseBool = (v) => typeof v === "string" && ["true", "1", "yes", "on"].includes(v.trim().toLowerCase());
 const envSchema = z.object({
     KIWOOM_APP_KEY: z.string().min(1),
     KIWOOM_APP_SECRET: z.string().min(1),
-    KIWOOM_MODE: z.enum(["VIRTUAL", "REAL"]).default("VIRTUAL"),
-    ISA_TYPE: z.enum(["GENERAL", "SEOMIN"]).default("GENERAL"),
+    KIWOOM_MODE: z.preprocess(emptyToUndefined, z.enum(["VIRTUAL", "REAL"]).default("VIRTUAL")),
+    /**
+     * Opt-in switch for the ISA tax tool. Off by default so the server is
+     * general-account-first; ISA users set ISA_ENABLED=true (+ the two fields
+     * below). ISA_TYPE / ISA_OPENED_ON are only consulted when this is true.
+     */
+    ISA_ENABLED: z.preprocess((v) => parseBool(v), z.boolean()),
+    ISA_TYPE: z.preprocess(emptyToUndefined, z.enum(["GENERAL", "SEOMIN"]).default("GENERAL")),
     /** ISA account opening date — default aggregation start for tax-status math. */
-    ISA_OPENED_ON: z
+    ISA_OPENED_ON: z.preprocess(emptyToUndefined, z
         .string()
         .regex(/^\d{4}-?\d{2}-?\d{2}$/)
-        .optional(),
+        .optional()),
 });
 const BASE_URLS = {
     VIRTUAL: "https://mockapi.kiwoom.com",
@@ -35,27 +55,40 @@ function loadDotEnv() {
         }
     }
 }
-export function getConfig() {
-    if (cached)
-        return cached;
-    loadDotEnv();
-    const parsed = envSchema.safeParse(process.env);
+/** Pure env → config mapping (no file I/O), so it is unit-testable. */
+export function buildConfig(env) {
+    const parsed = envSchema.safeParse(env);
     if (!parsed.success) {
-        const problems = parsed.error.issues
-            .map((issue) => issue.path.join("."))
-            .join(", ");
+        const problems = parsed.error.issues.map((issue) => issue.path.join(".")).join(", ");
         throw new Error(`환경설정이 없거나 잘못되었습니다: ${problems}. ` +
             `프로젝트 루트의 .env.example을 .env로 복사한 뒤 키움 REST API 앱키를 입력해 주세요.`);
     }
-    const env = parsed.data;
-    cached = {
-        appKey: env.KIWOOM_APP_KEY,
-        appSecret: env.KIWOOM_APP_SECRET,
-        mode: env.KIWOOM_MODE,
-        modeLabel: MODE_LABELS[env.KIWOOM_MODE],
-        isaType: env.ISA_TYPE,
-        isaOpenedOn: env.ISA_OPENED_ON?.replaceAll("-", ""),
-        baseUrl: BASE_URLS[env.KIWOOM_MODE],
+    const e = parsed.data;
+    return {
+        appKey: e.KIWOOM_APP_KEY,
+        appSecret: e.KIWOOM_APP_SECRET,
+        mode: e.KIWOOM_MODE,
+        modeLabel: MODE_LABELS[e.KIWOOM_MODE],
+        isaEnabled: e.ISA_ENABLED,
+        isaType: e.ISA_TYPE,
+        isaOpenedOn: e.ISA_OPENED_ON?.replaceAll("-", ""),
+        baseUrl: BASE_URLS[e.KIWOOM_MODE],
     };
+}
+export function getConfig() {
+    if (cached)
+        return cached;
+    loadDotEnv();
+    cached = buildConfig(process.env);
     return cached;
 }
+/**
+ * Lightweight startup check used to decide whether to register the optional ISA
+ * tax tool. Loads `.env` if present and reads only the opt-in flag — it does NOT
+ * validate credentials, so the server still starts (and `ping` works) without a
+ * full config. Defaults to false → general-account-first.
+ */
+export function isIsaEnabled() {
+    loadDotEnv();
+    return parseBool(process.env.ISA_ENABLED);
+}

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, minuteChartItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, realizedPnlResponseSchema, shortSellingResponseSchema, stockInfoResponseSchema, stockListResponseSchema, themeGroupsResponseSchema, tradingJournalResponseSchema, themeStocksResponseSchema, transactionsResponseSchema, valueRankItemSchema, volumeRankItemSchema, watchlistGroupDetailResponseSchema, watchlistGroupsResponseSchema, } from "./types.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";
 const STOCK_INFO_PATH = "/api/dostk/stkinfo";
 const ACCOUNT_PATH = "/api/dostk/acnt";
 const CHART_PATH = "/api/dostk/chart";
@@ -370,3 +370,73 @@ export async function fetchTradingJournal(client, baseDate) {
     });
     return tradingJournalResponseSchema.parse(res.json);
 }
+/**
+ * ka10016 신고저가요청 — stocks marking a new period high/low (mock-verified
+ * 2026-07-08; REAL not yet probed). ntl_tp "1"=신고가, "2"=신저가; dt = lookback
+ * days (5/10/20/60/250); array key `ntl_pric`. Filter params fixed to "all".
+ */
+export async function fetchNewHighLow(client, market, direction, days) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10016",
+        body: {
+            mrkt_tp: RANKING_MARKET_CODES[market],
+            ntl_tp: direction === "high" ? "1" : "2",
+            high_low_close_tp: "1",
+            stk_cnd: "0",
+            trde_qty_tp: "00000",
+            crd_cnd: "0",
+            updown_incls: "0",
+            dt: days,
+            stex_tp: "1",
+        },
+    });
+    return parseArray(res.json, "ntl_pric", newHighLowItemSchema);
+}
+/**
+ * ka10017 상하한가요청 — stocks at the daily upper/lower price limit
+ * (mock-verified 2026-07-08; REAL not yet probed). updown_tp "1"=상한, "4"=하한;
+ * sort_tp "3"=등락률순; array key `updown_pric`. `cnt` = 연속 도달 횟수.
+ */
+export async function fetchLimitStocks(client, market, direction) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10017",
+        body: {
+            mrkt_tp: RANKING_MARKET_CODES[market],
+            updown_tp: direction === "upper" ? "1" : "4",
+            sort_tp: "3",
+            stk_cnd: "0",
+            trde_qty_tp: "00000",
+            crd_cnd: "0",
+            trde_gold_tp: "0",
+            stex_tp: "1",
+        },
+    });
+    return parseArray(res.json, "updown_pric", limitStockItemSchema);
+}
+/**
+ * ka10019 가격급등락요청 — sharp movers vs the previous day (mock-verified
+ * 2026-07-08; REAL not yet probed). flu_tp "1"=급등, "2"=급락; tm_tp "2"/tm "1"
+ * fixes the baseline to 1 trading day ago; array key `pric_jmpflu`.
+ * `jmp_rt` = 기준가(base_pric) 대비 급등/급락률.
+ */
+export async function fetchPriceJumps(client, market, direction) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10019",
+        body: {
+            mrkt_tp: RANKING_MARKET_CODES[market],
+            flu_tp: direction === "surge" ? "1" : "2",
+            tm_tp: "2",
+            tm: "1",
+            trde_qty_tp: "00000",
+            stk_cnd: "0",
+            crd_cnd: "0",
+            pric_cnd: "0",
+            updown_incls: "1",
+            stex_tp: "1",
+        },
+    });
+    return parseArray(res.json, "pric_jmpflu", priceJumpItemSchema);
+}

package/dist/kiwoom/types.js

@@ -379,6 +379,35 @@ export const tradingJournalResponseSchema = z.looseObject({
     tot_prft_rt: str(), // 총수익률(%)
     tdy_trde_diary: z.array(tradingJournalItemSchema).default([]),
 });
+// ── ka10016/ka10017/ka10019: 신고저가/상하한가/가격급등락 (mock-verified 2026-07-08) ──
+export const newHighLowItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(), // 부호 포함
+    pred_pre: str(), // 전일대비 (부호)
+    flu_rt: str(), // 등락률 (부호)
+    trde_qty: str(), // 거래량
+    high_pric: str(), // 기간 고가
+    low_pric: str(), // 기간 저가
+});
+export const limitStockItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(),
+    pred_pre: str(),
+    flu_rt: str(),
+    trde_qty: str(),
+    cnt: str(), // 연속 횟수
+});
+export const priceJumpItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(),
+    flu_rt: str(), // 전일 대비 등락률 (부호)
+    base_pric: str(), // 기준가 (급등락 산정 기준시점 가격)
+    jmp_rt: str(), // 기준 대비 급등/급락률 (부호)
+    trde_qty: str(),
+});
 /** Strips Kiwoom's asset-class prefix (e.g. "A005930" → "005930"). */
 export function normalizeStockCode(code) {
     return code.replace(/^[A-Z]/, "");

package/dist/server.js

@@ -1,4 +1,5 @@
 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 { registerEtfInfoTool } from "./tools/etf-info.js";
@@ -6,6 +7,7 @@ import { registerForeignHoldingTool } from "./tools/foreign-holding.js";
 import { registerInvestorTrendTool } from "./tools/investor-trend.js";
 import { registerIsaTaxStatusTool } from "./tools/isa-tax-status.js";
 import { registerMarketIndexTool } from "./tools/market-index.js";
+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";
@@ -19,7 +21,7 @@ import { registerTradingJournalTool } from "./tools/trading-journal.js";
 import { registerTransactionsTool } from "./tools/transactions.js";
 import { registerWatchlistGroupsTool, registerWatchlistTool } from "./tools/watchlist.js";
 export const SERVER_NAME = "kiwoom-mcp-server";
-export const SERVER_VERSION = "0.8.0";
+export const SERVER_VERSION = "0.9.0";
 export function createServer() {
     const server = new McpServer({
         name: SERVER_NAME,
@@ -33,6 +35,7 @@ export function createServer() {
     registerOrderbookTool(server);
     registerMarketIndexTool(server);
     registerRankingTool(server);
+    registerMarketMoversTool(server);
     registerInvestorTrendTool(server);
     registerEtfInfoTool(server);
     registerShortSellingTool(server);
@@ -49,6 +52,10 @@ export function createServer() {
     registerTransactionsTool(server);
     registerPendingOrdersTool(server);
     registerTradingJournalTool(server);
-    registerIsaTaxStatusTool(server);
+    // ISA tax tool — opt-in, general-account-first. Enable with ISA_ENABLED=true
+    // (see .env.example). A non-ISA / general account simply won't see this tool.
+    if (isIsaEnabled()) {
+        registerIsaTaxStatusTool(server);
+    }
     return server;
 }

package/dist/tools/investor-trend.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
 import { fetchInvestorDaily, fetchInvestorTotal } from "../kiwoom/api.js";
-import { formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
+import { assertDateRange, formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
 import { formatNumber, formatSigned, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
 const DEFAULT_LOOKBACK_DAYS = 30;
@@ -66,6 +66,7 @@ export function registerInvestorTrendTool(server) {
         const code = stock_code.toUpperCase();
         const fromDate = (from_date ?? kstDaysAgo(DEFAULT_LOOKBACK_DAYS)).replaceAll("-", "");
         const toDate = (to_date ?? todayInKst()).replaceAll("-", "");
+        assertDateRange(fromDate, toDate);
         const u = unit ?? "amount";
         // ka10061 and ka10059 are different TRs — per-TR rate limits allow parallel calls.
         const [total, daily] = await Promise.all([

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

@@ -7,7 +7,7 @@ import { computeIsaTaxStatus, ISA_LIMITS } from "../isa/tax.js";
 import { fetchAccountEvaluation, fetchRealizedPnlSummary, fetchTransactions } from "../kiwoom/api.js";
 import { loadMasterList } from "../kiwoom/master-list.js";
 import { normalizeStockCode } from "../kiwoom/types.js";
-import { formatDateDashed, todayInKst } from "../utils/date.js";
+import { assertDateRange, formatDateDashed, todayInKst } from "../utils/date.js";
 import { formatKRW, formatSignedKRW, parseKiwoomNumber } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
 const DIVIDEND_PATTERN = /배당|분배|이자/;
@@ -144,7 +144,10 @@ export function registerIsaTaxStatusTool(server) {
                 .describe("집계 기간 중 수령한 배당·분배금·이자 총액(원) — 자동 감지분에 더해짐"),
             overrides: z
                 .array(z.object({
-                stock_code: z.string().describe("6자리 종목코드"),
+                stock_code: z
+                    .string()
+                    .regex(/^\d{6}$/, "6자리 숫자 종목코드여야 합니다")
+                    .describe("6자리 종목코드"),
                 tax_type: z
                     .enum(["TAXABLE", "DOMESTIC_EQUITY"])
                     .describe("TAXABLE=과세대상(해외/채권형 등), DOMESTIC_EQUITY=국내주식형(매매차익 비과세)"),
@@ -160,6 +163,7 @@ export function registerIsaTaxStatusTool(server) {
                 "from_date 인자를 전달해 주세요.");
         }
         const toDate = todayInKst();
+        assertDateRange(fromDate, toDate);
         const overrideMap = new Map((overrides ?? []).map((o) => [o.stock_code, o.tax_type]));
         // Distinct TRs — per-TR rate limits allow parallel calls. loadEtfCodeSet
         // (ka10099) is best-effort and never rejects, so Promise.all is safe.
@@ -212,6 +216,17 @@ export function registerIsaTaxStatusTool(server) {
             unrealized: unrealizedEntries,
         });
         const warnings = [...reconstruction.warnings];
+        // 존재 검증: 실현·보유 어디에도 없는 종목의 override는 조용히 무시되므로
+        // (오타 가능성) 경고로 표면화한다.
+        const knownCodes = new Set([
+            ...realizedEntries.map((e) => e.code),
+            ...unrealizedEntries.map((e) => e.code),
+        ]);
+        const unusedOverrides = [...overrideMap.keys()].filter((code) => !knownCodes.has(code));
+        if (unusedOverrides.length > 0) {
+            warnings.push(`overrides에 지정한 종목 ${unusedOverrides.join(", ")}이(가) 집계 기간의 실현손익·보유 ` +
+                `내역에 없어 반영되지 않았습니다 — 종목코드를 확인해 주세요.`);
+        }
         if (transactions.truncated) {
             warnings.push("거래내역이 조회 상한에 도달해 일부 오래된 거래가 누락되었을 수 있습니다 — " +
                 "집계 시작일(from_date)을 좁혀 재확인하세요. 실현손익·배당 집계가 불완전할 수 있습니다.");

package/dist/tools/market-movers.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchLimitStocks, fetchNewHighLow, fetchPriceJumps, } 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 DEFAULT_DAYS = "5";
+const DAYS_VALUES = ["5", "10", "20", "60", "250"];
+const SIGNAL_LABELS = {
+    new_high: "신고가",
+    new_low: "신저가",
+    upper_limit: "상한가",
+    lower_limit: "하한가",
+    surge: "급등",
+    plunge: "급락",
+};
+const MARKET_LABELS = {
+    all: "전체",
+    kospi: "코스피",
+    kosdaq: "코스닥",
+};
+const row = (cells) => `| ${cells.join(" | ")} |`;
+function commonCells(rank, item) {
+    return [
+        String(rank),
+        item.stk_nm,
+        item.stk_cd,
+        formatNumber(parseKiwoomPrice(item.cur_prc)),
+        formatPercent(parseKiwoomNumber(item.flu_rt)),
+    ];
+}
+export function formatMarketMovers(signal, market, items, top, modeLabel, days) {
+    const shown = items.slice(0, top);
+    const daysSuffix = signal === "new_high" || signal === "new_low" ? ` (${days ?? DEFAULT_DAYS}일 기준)` : "";
+    const title = `${MARKET_LABELS[market]} ${SIGNAL_LABELS[signal]} 종목${daysSuffix}`;
+    if (shown.length === 0) {
+        return `[${modeLabel}] ${title} — 해당 종목이 없습니다.`;
+    }
+    const lines = [`[${modeLabel}] ${title} (${shown.length}종목)`, ""];
+    if (signal === "new_high" || signal === "new_low") {
+        lines.push("| 순위 | 종목명 | 코드 | 현재가 | 등락률 | 거래량 | 기간고가 | 기간저가 |", "|---:|---|---|---:|---:|---:|---:|---:|");
+        shown.forEach((item, i) => {
+            lines.push(row([
+                ...commonCells(i + 1, item),
+                formatNumber(parseKiwoomNumber(item.trde_qty)),
+                formatNumber(parseKiwoomPrice(item.high_pric)),
+                formatNumber(parseKiwoomPrice(item.low_pric)),
+            ]));
+        });
+    }
+    else if (signal === "upper_limit" || signal === "lower_limit") {
+        lines.push("| 순위 | 종목명 | 코드 | 현재가 | 등락률 | 거래량 | 연속 |", "|---:|---|---|---:|---:|---:|---:|");
+        shown.forEach((item, i) => {
+            lines.push(row([
+                ...commonCells(i + 1, item),
+                formatNumber(parseKiwoomNumber(item.trde_qty)),
+                `${parseKiwoomNumber(item.cnt) ?? "-"}회`,
+            ]));
+        });
+    }
+    else {
+        lines.push("| 순위 | 종목명 | 코드 | 현재가 | 등락률 | 급등락률(기준가 대비) | 거래량 |", "|---:|---|---|---:|---:|---:|---:|");
+        shown.forEach((item, i) => {
+            lines.push(row([
+                ...commonCells(i + 1, item),
+                formatPercent(parseKiwoomNumber(item.jmp_rt)),
+                formatNumber(parseKiwoomNumber(item.trde_qty)),
+            ]));
+        });
+    }
+    return lines.join("\n");
+}
+export function registerMarketMoversTool(server) {
+    server.registerTool("get_market_movers", {
+        title: "시장 특이 종목 조회",
+        description: "시장 특이 종목을 조회합니다 (키움 ka10016/ka10017/ka10019). signal: " +
+            "new_high(신고가)/new_low(신저가)/upper_limit(상한가)/lower_limit(하한가)/" +
+            "surge(급등)/plunge(급락). market: all(전체, 기본)/kospi/kosdaq. " +
+            "신고/신저는 days(5/10/20/60/250일, 기본 5일) 기준, 급등/급락은 전일 대비입니다.",
+        inputSchema: {
+            signal: z.enum(["new_high", "new_low", "upper_limit", "lower_limit", "surge", "plunge"]).describe("특이 신호 종류"),
+            market: z.enum(["all", "kospi", "kosdaq"]).optional().describe("시장 구분 (기본값: all)"),
+            days: z
+                .enum(DAYS_VALUES)
+                .optional()
+                .describe(`신고/신저 기준 기간(일) — new_high/new_low에서만 사용 (기본값 ${DEFAULT_DAYS})`),
+            top: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_TOP)
+                .optional()
+                .describe(`표시할 종목 수 (기본값 ${DEFAULT_TOP}, 최대 ${MAX_TOP})`),
+        },
+    }, async ({ signal, market, days, top }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const m = market ?? "all";
+        const count = top ?? DEFAULT_TOP;
+        const d = days ?? DEFAULT_DAYS;
+        const items = signal === "new_high" || signal === "new_low"
+            ? await fetchNewHighLow(client, m, signal === "new_high" ? "high" : "low", d)
+            : signal === "upper_limit" || signal === "lower_limit"
+                ? await fetchLimitStocks(client, m, signal === "upper_limit" ? "upper" : "lower")
+                : await fetchPriceJumps(client, m, signal);
+        return textResult(formatMarketMovers(signal, m, items, count, config.modeLabel, d));
+    }));
+}

package/dist/tools/short-selling.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
 import { fetchShortSelling } from "../kiwoom/api.js";
-import { formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
+import { assertDateRange, formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
 import { formatKRW, formatPercent, formatQuantity, formatRatioPercent, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
 const DEFAULT_LOOKBACK_DAYS = 30;
@@ -60,6 +60,7 @@ export function registerShortSellingTool(server) {
             fromDate: (from_date ?? kstDaysAgo(DEFAULT_LOOKBACK_DAYS)).replaceAll("-", ""),
             toDate: (to_date ?? todayInKst()).replaceAll("-", ""),
         };
+        assertDateRange(query.fromDate, query.toDate);
         const rows = await fetchShortSelling(client, query.stockCode, query.fromDate, query.toDate);
         return textResult(formatShortSelling(rows, query, config.modeLabel));
     }));

package/dist/tools/transactions.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
 import { fetchTransactions } from "../kiwoom/api.js";
 import { normalizeStockCode } from "../kiwoom/types.js";
-import { formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
+import { assertDateRange, formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
 import { formatKRW, parseKiwoomNumber } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
 const DEFAULT_LOOKBACK_DAYS = 30;
@@ -74,6 +74,7 @@ export function registerTransactionsTool(server) {
             toDate: (to_date ?? todayInKst()).replaceAll("-", ""),
             stockCode: stock_code,
         };
+        assertDateRange(query.fromDate, query.toDate);
         const { rows, truncated } = await fetchTransactions(client, query.fromDate, query.toDate);
         return textResult(formatTransactions(rows, query, config.modeLabel, truncated));
     }));

package/dist/utils/date.js

@@ -13,3 +13,14 @@ export function kstDaysAgo(days) {
 export function formatDateDashed(yyyymmdd) {
     return `${yyyymmdd.slice(0, 4)}-${yyyymmdd.slice(4, 6)}-${yyyymmdd.slice(6, 8)}`;
 }
+/**
+ * Sanity-check a date range (both yyyyMMdd, so string order == date order).
+ * Kiwoom returns confusing empty results for an inverted range — fail early
+ * with a readable Korean error instead.
+ */
+export function assertDateRange(fromDate, toDate) {
+    if (fromDate > toDate) {
+        throw new Error(`조회 기간이 잘못되었습니다: 시작일(${formatDateDashed(fromDate)})이 ` +
+            `종료일(${formatDateDashed(toDate)})보다 늦습니다. from_date/to_date를 확인해 주세요.`);
+    }
+}

package/package.json

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