kiwoom-mcp-server 0.8.0

package/dist/kiwoom/auth.js

@@ -0,0 +1,89 @@
+import { redactSecrets } from "../utils/redact.js";
+import { KiwoomAuthError } from "./errors.js";
+import { tokenResponseSchema } from "./types.js";
+/** Refresh this long before the reported expiry to avoid using a token mid-expiration. */
+const EXPIRY_MARGIN_MS = 60_000;
+const TOKEN_TIMEOUT_MS = 10_000;
+/**
+ * Parses Kiwoom's expires_dt ("yyyyMMddHHmmss", KST) into a unix epoch (ms).
+ * Returns null when the format is unrecognized.
+ */
+export function parseExpiresDt(expiresDt) {
+    const match = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(expiresDt.trim());
+    if (!match)
+        return null;
+    const [, y, mo, d, h, mi, s] = match;
+    // KST is UTC+9 with no DST; subtract 9h to convert to UTC.
+    return Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h) - 9, Number(mi), Number(s));
+}
+export class TokenManager {
+    config;
+    token = null;
+    expiresAt = 0;
+    inflight = null;
+    constructor(config) {
+        this.config = config;
+    }
+    async getToken() {
+        if (this.token && Date.now() < this.expiresAt - EXPIRY_MARGIN_MS) {
+            return this.token;
+        }
+        // Concurrent tool calls share a single issuance request.
+        this.inflight ??= this.issueToken().finally(() => {
+            this.inflight = null;
+        });
+        return this.inflight;
+    }
+    /** Drops the cached token, forcing re-issuance on the next call (e.g. after a 401). */
+    invalidate() {
+        this.token = null;
+        this.expiresAt = 0;
+    }
+    async issueToken() {
+        let response;
+        try {
+            response = await fetch(`${this.config.baseUrl}/oauth2/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json;charset=UTF-8" },
+                body: JSON.stringify({
+                    grant_type: "client_credentials",
+                    appkey: this.config.appKey,
+                    secretkey: this.config.appSecret,
+                }),
+                signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw new KiwoomAuthError(`키움 토큰 발급 요청이 실패했습니다 (네트워크 오류 또는 시간 초과): ${this.describe(error)}`);
+        }
+        const rawBody = await response.text();
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(rawBody);
+        }
+        catch {
+            throw new KiwoomAuthError(`키움 토큰 발급 응답을 해석할 수 없습니다 (HTTP ${response.status}): ${this.snippet(rawBody)}`);
+        }
+        const body = tokenResponseSchema.parse(parsedJson);
+        const returnCode = Number(body.return_code ?? (response.ok ? 0 : -1));
+        if (!response.ok || returnCode !== 0 || !body.token) {
+            const reason = body.return_msg?.trim() || `HTTP ${response.status}`;
+            throw new KiwoomAuthError(`키움 인증에 실패했습니다: ${reason}. .env의 KIWOOM_APP_KEY/KIWOOM_APP_SECRET과 ` +
+                `KIWOOM_MODE(현재 ${this.config.mode})가 앱 등록 정보와 일치하는지 확인해 주세요.`);
+        }
+        this.token = body.token;
+        this.expiresAt = body.expires_dt ? (parseExpiresDt(body.expires_dt) ?? this.fallbackExpiry()) : this.fallbackExpiry();
+        return this.token;
+    }
+    /** Conservative fallback when expires_dt is missing or malformed. */
+    fallbackExpiry() {
+        return Date.now() + 10 * 60_000;
+    }
+    describe(error) {
+        const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+        return redactSecrets(text, [this.config.appKey, this.config.appSecret, this.token]);
+    }
+    snippet(rawBody) {
+        return redactSecrets(rawBody.slice(0, 200), [this.config.appKey, this.config.appSecret, this.token]);
+    }
+}

package/dist/kiwoom/client.js

@@ -0,0 +1,104 @@
+import { redactSecrets } from "../utils/redact.js";
+import { sleep } from "../utils/sleep.js";
+import { KiwoomApiError } from "./errors.js";
+const REQUEST_TIMEOUT_MS = 10_000;
+/** Kiwoom enforces ~1 req/s per TR (burst 2); 429 backoff must exceed 1s. */
+const RETRY_429_BASE_MS = 1_300;
+const RETRY_5XX_BASE_MS = 800;
+const MAX_RETRIES = 2;
+export class KiwoomClient {
+    config;
+    tokens;
+    constructor(config, tokens) {
+        this.config = config;
+        this.tokens = tokens;
+    }
+    /**
+     * Calls one Kiwoom REST TR. All TRs this server uses are read-only queries,
+     * so retrying on transient failures (network, 429, 5xx) is safe.
+     */
+    async call(request) {
+        let tokenRetryUsed = false;
+        let retries = 0;
+        while (true) {
+            const token = await this.tokens.getToken();
+            let response;
+            try {
+                response = await fetch(`${this.config.baseUrl}${request.path}`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json;charset=UTF-8",
+                        authorization: `Bearer ${token}`,
+                        "api-id": request.apiId,
+                        ...(request.contYn ? { "cont-yn": request.contYn, "next-key": request.nextKey ?? "" } : {}),
+                    },
+                    body: JSON.stringify(request.body),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+            }
+            catch (error) {
+                if (retries < 1) {
+                    retries += 1;
+                    await sleep(RETRY_5XX_BASE_MS);
+                    continue;
+                }
+                throw new KiwoomApiError(`키움 API 요청이 실패했습니다 (네트워크 오류 또는 시간 초과, ${request.apiId}): ${this.describe(error, token)}`, { apiId: request.apiId });
+            }
+            if (response.status === 401 && !tokenRetryUsed) {
+                tokenRetryUsed = true;
+                this.tokens.invalidate();
+                continue;
+            }
+            if ((response.status === 429 || response.status >= 500) && retries < MAX_RETRIES) {
+                retries += 1;
+                const base = response.status === 429 ? RETRY_429_BASE_MS : RETRY_5XX_BASE_MS;
+                await sleep(base * retries);
+                continue;
+            }
+            if (!response.ok) {
+                throw new KiwoomApiError(this.httpErrorMessage(response.status, request.apiId), {
+                    httpStatus: response.status,
+                    apiId: request.apiId,
+                });
+            }
+            const rawBody = await response.text();
+            let json;
+            try {
+                json = JSON.parse(rawBody);
+            }
+            catch {
+                throw new KiwoomApiError(`키움 API 응답을 해석할 수 없습니다 (${request.apiId}): ${redactSecrets(rawBody.slice(0, 200), [token])}`, { apiId: request.apiId });
+            }
+            const envelope = json;
+            const returnCode = Number(envelope.return_code ?? 0);
+            if (returnCode !== 0) {
+                const reason = envelope.return_msg?.trim() || "원인 미상";
+                throw new KiwoomApiError(`키움 API 오류 (${request.apiId}, code ${returnCode}): ${reason}`, {
+                    returnCode,
+                    apiId: request.apiId,
+                });
+            }
+            return {
+                json,
+                hasNext: response.headers.get("cont-yn") === "Y",
+                nextKey: response.headers.get("next-key") ?? "",
+            };
+        }
+    }
+    httpErrorMessage(status, apiId) {
+        if (status === 401 || status === 403) {
+            return `키움 API 인증이 거부되었습니다 (${apiId}, HTTP ${status}). 앱키 상태와 KIWOOM_MODE를 확인해 주세요.`;
+        }
+        if (status === 429) {
+            return `키움 API 요청 한도를 초과했습니다 (${apiId}). 잠시 후 다시 시도해 주세요.`;
+        }
+        if (status >= 500) {
+            return `키움 서버 오류입니다 (${apiId}, HTTP ${status}). 잠시 후 다시 시도해 주세요.`;
+        }
+        return `키움 API 요청이 거부되었습니다 (${apiId}, HTTP ${status}).`;
+    }
+    describe(error, token) {
+        const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+        return redactSecrets(text, [this.config.appKey, this.config.appSecret, token]);
+    }
+}

package/dist/kiwoom/errors.js

@@ -0,0 +1,15 @@
+/** Error from the Kiwoom REST API, already translated to a human-readable message. */
+export class KiwoomApiError extends Error {
+    details;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = "KiwoomApiError";
+        this.details = details;
+    }
+}
+export class KiwoomAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KiwoomAuthError";
+    }
+}

package/dist/kiwoom/master-list.js

@@ -0,0 +1,25 @@
+import { sleep } from "../utils/sleep.js";
+import { fetchStockList } from "./api.js";
+/**
+ * Shared in-process cache of the ka10099 종목 마스터 list (KOSPI + KOSDAQ,
+ * ETF/ETN included). Both `search_stock` and the watchlist tools read it to
+ * resolve a bare 종목코드 to a name/전일종가 without extra per-stock API calls.
+ * The list changes at most daily (listings/delistings), so a 12h TTL is ample.
+ */
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+/** ka10099 is one TR — space the two market calls to respect the ~1 req/s limit. */
+const MARKET_FETCH_GAP_MS = 1_100;
+let cache = null;
+export async function loadMasterList(client) {
+    if (cache && Date.now() - cache.fetchedAt < CACHE_TTL_MS)
+        return cache.items;
+    const kospi = await fetchStockList(client, "0");
+    await sleep(MARKET_FETCH_GAP_MS);
+    const kosdaq = await fetchStockList(client, "10");
+    cache = { fetchedAt: Date.now(), items: [...kospi, ...kosdaq] };
+    return cache.items;
+}
+/** Test hook — clears the module-level master-list cache. */
+export function clearMasterListCache() {
+    cache = null;
+}

package/dist/kiwoom/types.js

@@ -0,0 +1,385 @@
+import { z } from "zod";
+/**
+ * Field names follow the Kiwoom REST API spec verbatim (snake_case, Korean
+ * abbreviations). Only fields this server consumes are declared; every schema
+ * is loose so unknown fields pass through untouched.
+ */
+const envelope = {
+    return_code: z.union([z.string(), z.number()]).optional(),
+    return_msg: z.string().optional(),
+};
+const str = () => z.string().default("");
+// ── au10001: 접근토큰 발급 ──
+export const tokenResponseSchema = z.looseObject({
+    ...envelope,
+    token: z.string().optional(),
+    token_type: z.string().optional(),
+    /** yyyyMMddHHmmss, KST */
+    expires_dt: z.string().optional(),
+});
+// ── ka10001: 주식기본정보 (subset) ──
+export const stockInfoResponseSchema = z.looseObject({
+    ...envelope,
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(), // 현재가 (부호 접두 가능)
+    pred_pre: str(), // 전일대비
+    pre_sig: str(), // 대비기호 1상한 2상승 3보합 4하한 5하락
+    flu_rt: str(), // 등락률(%)
+    trde_qty: str(), // 거래량
+    open_pric: str(),
+    high_pric: str(),
+    low_pric: str(),
+    base_pric: str(), // 기준가(전일종가)
+    "250hgst": str(), // 250일 최고
+    "250lwst": str(), // 250일 최저
+    per: str(),
+    eps: str(),
+    pbr: str(),
+    bps: str(),
+    mac: str(), // 시가총액(억원)
+});
+// ── kt00001: 예수금상세현황 (subset) ──
+export const depositResponseSchema = z.looseObject({
+    ...envelope,
+    entr: str(), // 예수금
+    d1_entra: str(), // D+1 추정예수금
+    d2_entra: str(), // D+2 추정예수금
+    ord_alow_amt: str(), // 주문가능금액
+    pymn_alow_amt: str(), // 출금가능금액
+});
+// ── kt00018: 계좌평가잔고내역 ──
+export const holdingItemSchema = z.looseObject({
+    stk_cd: str(), // 종목코드 — "A005930"처럼 A 접두가 붙어 올 수 있음
+    stk_nm: str(),
+    rmnd_qty: str(), // 보유수량
+    trde_able_qty: str(), // 매매가능수량
+    pur_pric: str(), // 매입가(평균단가)
+    cur_prc: str(), // 현재가
+    pur_amt: str(), // 매입금액
+    evlt_amt: str(), // 평가금액
+    evltv_prft: str(), // 평가손익 (부호 유의미)
+    prft_rt: str(), // 수익률(%)
+    poss_rt: str(), // 보유비중(%)
+    pred_close_pric: str(), // 전일종가
+});
+export const accountEvaluationResponseSchema = z.looseObject({
+    ...envelope,
+    tot_pur_amt: str(), // 총매입금액
+    tot_evlt_amt: str(), // 총평가금액
+    tot_evlt_pl: str(), // 총평가손익 (부호 유의미)
+    tot_prft_rt: str(), // 총수익률(%)
+    prsm_dpst_aset_amt: str(), // 추정예탁자산
+    acnt_evlt_remn_indv_tot: z.array(holdingItemSchema).default([]),
+});
+// ── kt00015: 위탁종합거래내역 (subset) ──
+// NOTE: trde_dt is the settlement date (D+2), not the trade date.
+export const transactionRowSchema = z.looseObject({
+    trde_dt: str(), // 거래일자(결제 기준, yyyyMMdd)
+    cntr_dt: str(), // 체결일자(실제 매매일, yyyyMMdd) — live-verified 2026-07
+    trde_unit: str(), // 단가 — 쉼표 포함 포맷("20,190")으로 옴
+    trde_no: str(),
+    trde_kind_nm: str(), // 거래종류명 — "매매" 등
+    rmrk_nm: str(), // 적요명 — "장내매수"/"장내매도" 등
+    io_tp_nm: str(), // 입출구분명 — "매수"/"매도" 등
+    stk_cd: str(),
+    stk_nm: str(),
+    trde_qty_jwa_cnt: str(), // 거래수량(좌수)
+    trde_amt: str(), // 거래금액
+    exct_amt: str(), // 정산금액 (수수료 반영된 실제 입출금액)
+    cmsn: str(), // 수수료
+});
+export const transactionsResponseSchema = z.looseObject({
+    ...envelope,
+    trst_ovrl_trde_prps_array: z.array(transactionRowSchema).default([]),
+});
+// ── ka10074: 일자별실현손익 (subset — summary only) ──
+export const realizedPnlResponseSchema = z.looseObject({
+    ...envelope,
+    tot_buy_amt: str(),
+    tot_sell_amt: str(),
+    rlzt_pl: str(), // 기간 실현손익 합계 (수수료·세금 반영)
+    trde_cmsn: str(),
+    trde_tax: str(),
+});
+// ── ka10075: 미체결 주문 (미체결요청) ──
+// The array key `oso` is live-verified (2026-07-07 — an empty array, since the
+// verification account had no open orders). The item fields are wrapper-sourced
+// (dongbin300 KiwoomRestApi.Net model) and NOT live-verified, because no pending
+// order existed to observe — treat the item shape as provisional, like dividends.
+// Only the consumed subset is declared. `cur_prc`/`ord_pric` encode direction in
+// their sign → read magnitude via parseKiwoomPrice.
+export const pendingOrderItemSchema = z.looseObject({
+    ord_no: str(), // 주문번호
+    stk_cd: str(), // 종목코드 ("A005930"처럼 접두 가능)
+    stk_nm: str(), // 종목명
+    ord_stt: str(), // 주문상태 ("접수"/"확인" 등)
+    io_tp_nm: str(), // 주문구분 ("매수"/"매도"/"정정" 등)
+    ord_qty: str(), // 주문수량
+    ord_pric: str(), // 주문가격
+    oso_qty: str(), // 미체결수량
+    cntr_qty: str(), // 체결량
+    cur_prc: str(), // 현재가 (부호 유의미)
+    tm: str(), // 시간 (HHmmss)
+    trde_tp: str(), // 매매구분
+});
+export const pendingOrdersResponseSchema = z.looseObject({
+    ...envelope,
+    oso: z.array(pendingOrderItemSchema).default([]),
+});
+// ── ka10099: 종목정보요약 — NOTE: this TR answers in camelCase (live-verified) ──
+export const stockListItemSchema = z.looseObject({
+    code: str(),
+    name: str(),
+    lastPrice: str(), // 전일종가, zero-padded
+    marketName: str(), // "거래소" | "코스닥" | "ETF" | ...
+    upName: str(), // 업종명 (ETF/ETN은 빈 값)
+    upSizeName: str(), // 대형주/중형주/소형주
+    state: str(), // "증거금20%|담보대출|신용가능"
+    auditInfo: str(), // "정상" 등
+    orderWarning: str(), // "0"=정상
+});
+export const stockListResponseSchema = z.looseObject({
+    ...envelope,
+    list: z.array(stockListItemSchema).default([]),
+});
+// ── ka10081/ka10082/ka10083: 일/주/월봉 차트 (same item shape, different array key) ──
+export const dailyChartItemSchema = z.looseObject({
+    dt: str(), // yyyyMMdd
+    open_pric: str(),
+    high_pric: str(),
+    low_pric: str(),
+    cur_prc: str(), // 종가
+    trde_qty: str(),
+    trde_prica: str(), // 거래대금(백만원)
+    pred_pre: str(),
+    pred_pre_sig: str(),
+});
+// ── ka10080: 분봉 차트 ──
+export const minuteChartItemSchema = z.looseObject({
+    cntr_tm: str(), // yyyyMMddHHmmss
+    open_pric: str(),
+    high_pric: str(),
+    low_pric: str(),
+    cur_prc: str(),
+    trde_qty: str(), // 해당 분봉 거래량
+    acc_trde_qty: str(),
+});
+// ── ka10004: 주식호가 — level 1 uses *_fpr_* keys, levels 2-10 use sel_/buy_Nth_pre_* ──
+// (live-verified key shapes; levels 2-10 are read via the loose passthrough)
+export const orderbookResponseSchema = z.looseObject({
+    ...envelope,
+    bid_req_base_tm: str(), // 호가 기준시각 HHmmss
+    sel_fpr_bid: str(), // 매도최우선호가
+    sel_fpr_req: str(), // 매도최우선잔량
+    buy_fpr_bid: str(),
+    buy_fpr_req: str(),
+    tot_sel_req: str(),
+    tot_buy_req: str(),
+});
+// ── ka20003: 전업종지수 (inds_cd 001=코스피 그룹, 101=코스닥 그룹) ──
+export const indexItemSchema = z.looseObject({
+    stk_cd: str(), // 업종코드 ("001" 종합 등)
+    stk_nm: str(),
+    cur_prc: str(), // 지수 (소수점 포함)
+    pre_sig: str(),
+    pred_pre: str(),
+    flu_rt: str(),
+    trde_qty: str(), // 천주
+    trde_prica: str(), // 백만원
+    rising: str(),
+    stdns: str(), // 보합
+    fall: str(),
+});
+export const allIndexResponseSchema = z.looseObject({
+    ...envelope,
+    all_inds_idex: z.array(indexItemSchema).default([]),
+});
+// ── ka10059/ka10061: 종목별 투자자·기관 (13-field investor breakdown) ──
+// amt_qty_tp "1"=금액(백만원), "2"=수량(주) — cross-checked live against volume.
+const investorFields = {
+    ind_invsr: str(), // 개인
+    frgnr_invsr: str(), // 외국인
+    orgn: str(), // 기관계
+    fnnc_invt: str(), // 금융투자
+    insrnc: str(), // 보험
+    invtrt: str(), // 투신
+    etc_fnnc: str(), // 기타금융
+    bank: str(),
+    penfnd_etc: str(), // 연기금등
+    samo_fund: str(), // 사모펀드
+    natn: str(), // 국가
+    etc_corp: str(), // 기타법인
+    natfor: str(), // 내외국인
+};
+export const investorTotalItemSchema = z.looseObject(investorFields);
+export const investorDailyItemSchema = z.looseObject({
+    dt: str(),
+    cur_prc: str(),
+    pre_sig: str(),
+    pred_pre: str(),
+    acc_trde_qty: str(),
+    ...investorFields,
+});
+// ── ka10027/ka10030/ka10032: 순위 TR item shapes ──
+export const priceChangeRankItemSchema = 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(),
+});
+export const volumeRankItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(),
+    pred_pre_sig: str(),
+    pred_pre: str(),
+    flu_rt: str(),
+    trde_qty: str(), // NOTE: Kiwoom caps this at uint32 max (4294967295) — live-observed
+    trde_amt: str(), // 백만원
+});
+export const valueRankItemSchema = 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(),
+    trde_prica: str(), // 백만원
+});
+// ── ka40002: ETF종목정보 (flat) ──
+export const etfInfoResponseSchema = z.looseObject({
+    ...envelope,
+    stk_nm: str(),
+    etfobjt_idex_nm: str(), // 추적지수명
+    etftxon_type: str(), // ETF 과세유형 ("비과세" 등)
+    etntxon_type: 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
+// a legacy `rtcd:"S"` flag alongside the standard return_code envelope.
+export const watchlistGroupItemSchema = z.looseObject({
+    gcod: str(), // 그룹코드 (예: "000")
+    name: str(), // 그룹명
+});
+export const watchlistGroupsResponseSchema = z.looseObject({
+    ...envelope,
+    nofi: z.array(watchlistGroupItemSchema).default([]),
+});
+export const watchlistStockItemSchema = z.looseObject({
+    cod2: str(), // 종목코드
+    bgb: str(), // 북마크 구분 ("0"=없음)
+    bgb_clr: str(), // 북마크 컬러
+});
+export const watchlistGroupDetailResponseSchema = z.looseObject({
+    ...envelope,
+    nofj: z.array(watchlistStockItemSchema).default([]),
+});
+// ── ka90001/ka90002: 테마 (테마그룹별 / 테마구성종목) — /api/dostk/thme ──
+// All fields live-verified 2026-07-07 on REAL. ka90001 paginates (100/page,
+// sorted by flu_pl_amt_tp); this server reads page 1 only. flu_rt/dt_prft_rt are
+// sign-prefixed percentages; cur_prc/pred_pre sign-encode direction. Counts
+// (stk_num/rising/fall) arrive as plain numeric strings.
+export const themeGroupItemSchema = z.looseObject({
+    thema_grp_cd: str(), // 테마그룹코드
+    thema_nm: str(), // 테마명
+    stk_num: str(), // 종목수
+    flu_sig: str(), // 등락기호 (1상한 2상승 3보합 4하한 5하락)
+    flu_rt: str(), // 등락률(%)
+    rising_stk_num: str(), // 상승종목수
+    fall_stk_num: str(), // 하락종목수
+    dt_prft_rt: str(), // 기간수익률(%) — date_tp 일수 기준
+    main_stk: str(), // 주요종목 (쉼표 구분)
+});
+export const themeGroupsResponseSchema = z.looseObject({
+    ...envelope,
+    thema_grp: z.array(themeGroupItemSchema).default([]),
+});
+export const themeStockItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(), // 현재가 (부호 유의미)
+    flu_sig: str(),
+    pred_pre: str(), // 전일대비 (부호 유의미)
+    flu_rt: str(), // 등락률(%)
+    acc_trde_qty: str(), // 누적거래량
+    dt_prft_rt_n: str(), // 기간수익률(%)
+});
+export const themeStocksResponseSchema = z.looseObject({
+    ...envelope,
+    flu_rt: str(), // 테마 전체 등락률(%)
+    dt_prft_rt: str(), // 테마 전체 기간수익률(%)
+    thema_comp_stk: z.array(themeStockItemSchema).default([]),
+});
+// ── ka10014: 공매도추이 — /api/dostk/shsa (all fields live-verified 2026-07-07) ──
+export const shortSellingItemSchema = z.looseObject({
+    dt: str(), // 일자 yyyyMMdd
+    close_pric: str(), // 종가 (부호 방향)
+    pred_pre: str(), // 전일대비 (부호 유의미)
+    flu_rt: str(), // 등락률(%)
+    trde_qty: str(), // 거래량
+    shrts_qty: str(), // 공매도량
+    ovr_shrts_qty: str(), // 누적공매도량
+    trde_wght: str(), // 공매도 비중(%) — 비방향성 비율
+    shrts_trde_prica: str(), // 공매도 거래대금
+    shrts_avg_pric: str(), // 공매도 평균가
+});
+export const shortSellingResponseSchema = z.looseObject({
+    ...envelope,
+    shrts_trnsn: z.array(shortSellingItemSchema).default([]),
+});
+// ── ka10008: 주식외국인 종목별 매매동향 — /api/dostk/frgnistt (live-verified) ──
+export const foreignHoldingItemSchema = z.looseObject({
+    dt: str(), // 일자 yyyyMMdd
+    close_pric: str(), // 종가 (부호)
+    pred_pre: str(), // 전일대비 (부호)
+    trde_qty: str(), // 거래량
+    chg_qty: str(), // 외국인 변동수량 (부호)
+    poss_stkcnt: str(), // 외국인 보유주식수
+    wght: str(), // 외국인 보유비중(%) — 비방향성 비율
+    gain_pos_stkcnt: str(), // 취득가능주식수
+    frgnr_limit: str(), // 외국인 한도
+    limit_exh_rt: str(), // 한도소진률(%) — 비방향성 비율
+});
+export const foreignHoldingResponseSchema = z.looseObject({
+    ...envelope,
+    stk_frgnr: z.array(foreignHoldingItemSchema).default([]),
+});
+// ── 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
+// return_code 0 with a "최근 2개월 이내" notice in return_msg and blank data. Item field
+// NAMES are live-confirmed (blank-row keys + dongbin300 .NET model); non-empty item VALUES
+// were NOT observable (no day-trade on this account), so treat them as provisional.
+export const tradingJournalItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    buy_avg_pric: str(), // 매수평균가
+    buy_qty: str(), // 매수수량
+    sel_avg_pric: str(), // 매도평균가
+    sell_qty: str(), // 매도수량
+    cmsn_alm_tax: str(), // 수수료+제세금
+    pl_amt: str(), // 손익금액 (부호)
+    sell_amt: str(), // 매도금액
+    buy_amt: str(), // 매수금액
+    prft_rt: str(), // 수익률(%)
+});
+export const tradingJournalResponseSchema = z.looseObject({
+    ...envelope,
+    tot_sell_amt: str(), // 총매도금액
+    tot_buy_amt: str(), // 총매수금액
+    tot_cmsn_tax: str(), // 총수수료+세금
+    tot_exct_amt: str(), // 총정산금액
+    tot_pl_amt: str(), // 총손익금액 (부호)
+    tot_prft_rt: str(), // 총수익률(%)
+    tdy_trde_diary: z.array(tradingJournalItemSchema).default([]),
+});
+/** Strips Kiwoom's asset-class prefix (e.g. "A005930" → "005930"). */
+export function normalizeStockCode(code) {
+    return code.replace(/^[A-Z]/, "");
+}

package/dist/server.js

@@ -0,0 +1,54 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerAccountBalanceTool } from "./tools/account-balance.js";
+import { registerAccountHoldingsTool } from "./tools/account-holdings.js";
+import { registerEtfInfoTool } from "./tools/etf-info.js";
+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 { registerOrderbookTool } from "./tools/orderbook.js";
+import { registerPendingOrdersTool } from "./tools/pending-orders.js";
+import { registerPingTool } from "./tools/ping.js";
+import { registerRankingTool } from "./tools/ranking.js";
+import { registerShortSellingTool } from "./tools/short-selling.js";
+import { registerStockChartTool } from "./tools/stock-chart.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 { registerWatchlistGroupsTool, registerWatchlistTool } from "./tools/watchlist.js";
+export const SERVER_NAME = "kiwoom-mcp-server";
+export const SERVER_VERSION = "0.8.0";
+export function createServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    registerPingTool(server);
+    // Market data (account-independent)
+    registerStockSearchTool(server);
+    registerStockPriceTool(server);
+    registerStockChartTool(server);
+    registerOrderbookTool(server);
+    registerMarketIndexTool(server);
+    registerRankingTool(server);
+    registerInvestorTrendTool(server);
+    registerEtfInfoTool(server);
+    registerShortSellingTool(server);
+    registerForeignHoldingTool(server);
+    // Watchlist (HTS 저장 관심종목 — read-only; ka01300/ka01301)
+    registerWatchlistGroupsTool(server);
+    registerWatchlistTool(server);
+    // Theme (테마 그룹 + 구성종목; ka90001/ka90002)
+    registerThemeGroupsTool(server);
+    registerThemeStocksTool(server);
+    // Account (bound to the app key)
+    registerAccountBalanceTool(server);
+    registerAccountHoldingsTool(server);
+    registerTransactionsTool(server);
+    registerPendingOrdersTool(server);
+    registerTradingJournalTool(server);
+    registerIsaTaxStatusTool(server);
+    return server;
+}