kiwoom-mcp-server 0.14.0 → 0.17.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 |
@@ -47,7 +47,7 @@ allowance.
 | 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.
 
@@ -123,6 +123,11 @@ npm test                     # unit tests (no network required)
 | `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` |
+| `MCP_TRANSPORT` | | `stdio` (default) or `http` — see [Remote access](#remote-access-http-mode--claudeai-webmobile) |
+| `MCP_AUTH_TOKEN` | HTTP mode ✅ | Bearer token every `/mcp` request must present in HTTP mode |
+| `MCP_HTTP_PORT` | | HTTP-mode port (default `8000`) |
+| `MCP_HTTP_HOST` | | HTTP-mode bind address (default `127.0.0.1`) |
+| `MCP_HTTP_NO_AUTH` | | `true` allows starting HTTP mode without auth (discouraged — see the security notes below) |
 
 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
@@ -195,6 +200,38 @@ From source — app key from the project-root `.env`:
 claude mcp add kiwoom -- node /absolute/path/kiwoom-mcp-server/dist/index.js
 ```
 
+## Remote access (HTTP mode) — claude.ai web/mobile
+
+claude.ai **custom connectors** (web/mobile) cannot attach to a local stdio server;
+they need a **Streamable HTTP** MCP server reachable over public HTTPS. Start this
+server in HTTP mode with the `--http` flag (or `MCP_TRANSPORT=http`):
+
+```sh
+MCP_AUTH_TOKEN="$(openssl rand -hex 32)" npx -y kiwoom-mcp-server --http --port 8000
+# endpoint: http://127.0.0.1:8000/mcp · health check: /healthz
+```
+
+- **Auth is required by default.** Without `MCP_AUTH_TOKEN` the server refuses to
+  start — every `/mcp` request must carry `Authorization: Bearer <token>`. To run
+  without auth you must pass `--no-auth` explicitly; the account-inquiry tools are
+  then exposed as-is, so do that only on a trusted network or with a paper-trading
+  key (`KIWOOM_MODE=VIRTUAL`).
+- The default bind is `127.0.0.1`, assuming a tunnel in front. To expose directly
+  (container/VPS), opt in with `--host 0.0.0.0`.
+- Get a public HTTPS URL with e.g. [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/):
+  `cloudflared tunnel --url http://localhost:8000` (ephemeral URL — use a named
+  tunnel for anything permanent).
+- Register on claude.ai under **Settings → Connectors → Add custom connector** with
+  `https://<your-domain>/mcp`. The bearer token can be supplied via the connector's
+  request-header settings (beta). A connector added once is available across the
+  web, mobile, and desktop clients.
+- ⚠️ **Kiwoom API calls originate from wherever this server runs.** REAL mode is
+  bound to Kiwoom's designated-terminal (8050) IP registration, so running it
+  outside a registered IP (e.g. in the cloud) can fail auth. Validate remote
+  setups with a VIRTUAL key first.
+
+The stdio behavior (Claude Desktop/Code) is unchanged when run without arguments.
+
 ## Smoke test
 
 You can verify over stdio without an MCP client:

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 |
@@ -45,7 +45,7 @@ Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·
 | Tool | 설명 | 키움 TR |
 |---|---|---|
 | `get_watchlist_groups` | HTS 관심종목 그룹 목록 (그룹코드+그룹명) | ka01300 |
-| `get_watchlist` | 그룹 내 종목 목록 (종목명·전일종가·시장 보강) | ka01301, ka10099 |
+| `get_watchlist` | 그룹 내 종목 목록 (종목명·전일종가·시장·투자유의 보강) | ka01301, ka10099 |
 
 > 키움 REST API에는 관심종목 **편집(추가/삭제)** TR이 없어 조회만 가능합니다.
 
@@ -115,6 +115,11 @@ npm test                    # 단위 테스트 (네트워크 불필요)
 | `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`일 때만 사용 |
+| `MCP_TRANSPORT` | | `stdio`(기본값) 또는 `http` — [원격 연결](#원격-연결-http-모드--claudeai-웹모바일) 참조 |
+| `MCP_AUTH_TOKEN` | HTTP 모드 ✅ | HTTP 모드에서 모든 `/mcp` 요청이 제시해야 하는 Bearer 토큰 |
+| `MCP_HTTP_PORT` | | HTTP 모드 포트 (기본값 `8000`) |
+| `MCP_HTTP_HOST` | | HTTP 모드 바인드 주소 (기본값 `127.0.0.1`) |
+| `MCP_HTTP_NO_AUTH` | | `true`면 인증 없이 HTTP 모드 기동 허용 (비권장 — 아래 보안 주의 참조) |
 
 기본값은 **일반(비-ISA) 계좌 기준**입니다 — 별도 설정이 없으면 시장·계좌 조회 tool만
 노출됩니다. ISA 계좌를 연결해 비과세 한도 tool을 쓰려면 `ISA_ENABLED=true`로 켜고
@@ -186,6 +191,34 @@ claude mcp add kiwoom \
 claude mcp add kiwoom -- node /절대/경로/kiwoom-mcp-server/dist/index.js
 ```
 
+## 원격 연결 (HTTP 모드) — claude.ai 웹/모바일
+
+claude.ai(웹/모바일)의 **커스텀 커넥터**는 로컬 stdio 서버에 직접 붙을 수 없고, 공개
+HTTPS로 접근 가능한 **Streamable HTTP** MCP 서버가 필요합니다. `--http` 플래그(또는
+`MCP_TRANSPORT=http`)로 이 서버를 HTTP 모드로 띄울 수 있습니다:
+
+```sh
+MCP_AUTH_TOKEN="$(openssl rand -hex 32)" npx -y kiwoom-mcp-server --http --port 8000
+# 엔드포인트: http://127.0.0.1:8000/mcp · 헬스체크: /healthz
+```
+
+- **인증이 기본 필수입니다.** `MCP_AUTH_TOKEN`이 없으면 기동을 거부합니다 — 모든 `/mcp`
+  요청에 `Authorization: Bearer <토큰>` 헤더가 있어야 합니다. 인증 없이 열려면
+  `--no-auth`를 명시해야 하며, 계좌 조회 도구가 그대로 노출되므로 신뢰할 수 있는
+  네트워크나 모의투자(`KIWOOM_MODE=VIRTUAL`)에서만 사용하세요.
+- 기본 바인드는 `127.0.0.1`입니다 — 터널을 앞에 두는 구성을 전제합니다. 컨테이너/서버에
+  직접 노출하려면 `--host 0.0.0.0`을 명시하세요.
+- 공개 HTTPS URL은 [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) 등으로 만듭니다:
+  `cloudflared tunnel --url http://localhost:8000` (임시 URL — 상시 운영은 named tunnel 권장).
+- claude.ai 등록: **Settings → Connectors → Add custom connector**에
+  `https://<도메인>/mcp`를 입력합니다. Bearer 토큰은 Advanced settings의 요청 헤더
+  설정(베타)으로 전달할 수 있습니다. 등록한 커넥터는 웹/모바일/데스크톱에서 공용입니다.
+- ⚠️ **키움 API 호출은 이 서버가 실행되는 곳에서 나갑니다.** REAL 모드는 키움 지정단말기
+  인증(8050)이 IP에 묶이므로, 등록된 IP가 아닌 곳(클라우드 등)에서 실행하면 인증 오류가
+  날 수 있습니다. 원격 노출은 모의투자로 먼저 검증하세요.
+
+기존 stdio 동작(Claude Desktop/Code 연결)은 인자 없이 실행하면 그대로입니다.
+
 ## 동작 확인
 
 MCP 클라이언트 없이 stdio로 직접 확인할 수 있습니다:

package/dist/config.js

@@ -41,7 +41,7 @@ const MODE_LABELS = {
     REAL: "실전투자",
 };
 let cached = null;
-function loadDotEnv() {
+export function loadDotEnv() {
     // Claude Desktop launches this server with an arbitrary cwd, so resolve .env
     // relative to the project root (parent of dist/ or src/) first.
     const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");

package/dist/http.js

@@ -0,0 +1,135 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import http from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+const DEFAULT_PORT = 8000;
+const DEFAULT_HOST = "127.0.0.1";
+const MCP_PATH = "/mcp";
+const HEALTH_PATH = "/healthz";
+/**
+ * Decides the transport from CLI args + env. Pure (unit-testable): pass
+ * process.argv.slice(2) and process.env. Defaults to stdio so existing
+ * Claude Desktop/Code installs are untouched; HTTP is strictly opt-in.
+ *
+ * The auth token is env-only (MCP_AUTH_TOKEN) — a CLI flag would leak the
+ * secret to `ps`. HTTP mode refuses to start without a token unless the
+ * operator explicitly passes --no-auth: this server fronts a brokerage
+ * account, so an unauthenticated public endpoint must be a deliberate act.
+ */
+export function chooseTransport(argv, env) {
+    const flags = new Set();
+    const values = new Map();
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--port" || arg === "--host") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error(`${arg} 옵션에 값이 없습니다 (예: ${arg === "--port" ? "--port 8000" : "--host 127.0.0.1"}).`);
+            }
+            values.set(arg, value);
+            i += 1;
+        }
+        else if (arg === "--http" || arg === "--stdio" || arg === "--no-auth") {
+            flags.add(arg);
+        }
+        else {
+            throw new Error(`알 수 없는 옵션입니다: ${arg} (지원: --http, --stdio, --port <n>, --host <addr>, --no-auth)`);
+        }
+    }
+    const envTransport = env.MCP_TRANSPORT?.trim().toLowerCase();
+    if (envTransport !== undefined && envTransport !== "" && envTransport !== "stdio" && envTransport !== "http") {
+        throw new Error(`MCP_TRANSPORT 값이 잘못되었습니다: "${env.MCP_TRANSPORT}" (stdio 또는 http).`);
+    }
+    const wantsHttp = flags.has("--http") || (!flags.has("--stdio") && envTransport === "http");
+    if (!wantsHttp)
+        return { mode: "stdio" };
+    const portRaw = values.get("--port") ?? env.MCP_HTTP_PORT?.trim();
+    let port = DEFAULT_PORT;
+    if (portRaw !== undefined && portRaw !== "") {
+        port = Number(portRaw);
+        if (!Number.isInteger(port) || port < 0 || port > 65535) {
+            throw new Error(`포트가 잘못되었습니다: "${portRaw}" (0~65535 정수).`);
+        }
+    }
+    const host = values.get("--host") ?? (env.MCP_HTTP_HOST?.trim() || DEFAULT_HOST);
+    const allowNoAuth = flags.has("--no-auth") || env.MCP_HTTP_NO_AUTH?.trim().toLowerCase() === "true";
+    const authToken = env.MCP_AUTH_TOKEN?.trim() || undefined;
+    if (!authToken && !allowNoAuth) {
+        throw new Error("HTTP 모드에는 MCP_AUTH_TOKEN 환경변수가 필요합니다 (모든 /mcp 요청의 Bearer 토큰). " +
+            "인증 없이 열려면 --no-auth를 명시하세요 — 계좌 조회 도구가 인터넷에 그대로 노출되므로 " +
+            "신뢰할 수 있는 네트워크/모의투자(VIRTUAL) 환경에서만 권장합니다.");
+    }
+    return { mode: "http", options: { port, host, authToken, allowNoAuth } };
+}
+/** Timing-safe bearer-token check (hash first so lengths never short-circuit). */
+export function isAuthorized(authorizationHeader, token) {
+    if (!authorizationHeader)
+        return false;
+    const match = /^Bearer\s+(.+)$/i.exec(authorizationHeader.trim());
+    if (!match)
+        return false;
+    const presented = createHash("sha256").update(match[1]).digest();
+    const expected = createHash("sha256").update(token).digest();
+    return timingSafeEqual(presented, expected);
+}
+function deny(res, status, message) {
+    res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: -32000, message },
+        id: null,
+    }));
+}
+/**
+ * Streamable HTTP endpoint for remote MCP clients (claude.ai custom
+ * connectors, Claude Desktop/mobile via the account-brokered connector).
+ * Stateless per the MCP spec: each request gets a fresh McpServer+transport
+ * pair; the expensive state (Kiwoom token cache, ka10099 master-list cache)
+ * lives at module level and is shared across requests.
+ */
+export function createHttpServer(options) {
+    return http.createServer((req, res) => {
+        void handleRequest(req, res, options).catch((error) => {
+            console.error("HTTP request handling failed:", error);
+            if (!res.headersSent)
+                deny(res, 500, "internal server error");
+        });
+    });
+}
+async function handleRequest(req, res, options) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    if (url.pathname === HEALTH_PATH) {
+        res.writeHead(200, { "Content-Type": "text/plain" }).end("ok");
+        return;
+    }
+    if (url.pathname !== MCP_PATH) {
+        deny(res, 404, `not found — MCP endpoint is ${MCP_PATH}`);
+        return;
+    }
+    if (options.authToken && !isAuthorized(req.headers.authorization, options.authToken)) {
+        deny(res, 401, "unauthorized — Authorization: Bearer <MCP_AUTH_TOKEN> 헤더가 필요합니다");
+        return;
+    }
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+        void transport.close();
+        void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res);
+}
+export async function startHttpServer(options) {
+    const server = createHttpServer(options);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, resolve);
+    });
+    const address = server.address();
+    const boundPort = typeof address === "object" && address ? address.port : options.port;
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} listening on http://${options.host}:${boundPort}${MCP_PATH} ` +
+        `(auth: ${options.authToken ? "bearer token" : "NONE — --no-auth"})`);
+    if (!options.authToken) {
+        console.error("⚠️  인증 없이 실행 중입니다. 이 서버는 계좌 조회 도구를 노출하므로 공개 네트워크에 직접 연결하지 마세요.");
+    }
+    return server;
+}

package/dist/index.js

@@ -1,7 +1,17 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadDotEnv } from "./config.js";
+import { chooseTransport, startHttpServer } from "./http.js";
 import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
 async function main() {
+    // Load .env before reading MCP_* transport vars (credential validation stays
+    // lazy in getConfig). Real environment variables win over the file.
+    loadDotEnv();
+    const choice = chooseTransport(process.argv.slice(2), process.env);
+    if (choice.mode === "http") {
+        await startHttpServer(choice.options);
+        return;
+    }
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);

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,

package/dist/server.js

@@ -27,7 +27,7 @@ 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.14.0";
+export const SERVER_VERSION = "0.17.0";
 export function createServer() {
     const server = new McpServer({
         name: SERVER_NAME,

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

@@ -10,10 +10,11 @@ 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) {
+export function formatNonEtfNotice(stockName, stockCode, modeLabel, featurePhrase = "ETF 기간 수익률을") {
     if (stockName) {
-        return (`[${modeLabel}] ${stockName} (${stockCode})은(는) ETF가 아니어서 ETF 기간 수익률을 제공하지 않습니다. ` +
+        return (`[${modeLabel}] ${stockName} (${stockCode})은(는) ETF가 아니어서 ${featurePhrase} 제공하지 않습니다. ` +
             `일반 종목 시세는 get_stock_price / get_stock_chart를 이용하세요.`);
     }
     return (`[${modeLabel}] ${stockCode}의 ETF 정보를 찾을 수 없습니다. ` +

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/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.14.0",
+  "version": "0.17.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",