kiwoom-mcp-server 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChunSam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,227 @@
+# kiwoom-mcp-server
+
+[한국어](README.md) · **English**
+
+A **read-only** MCP server that exposes the Kiwoom Securities REST API.
+From Claude Desktop / Claude Code you can query Korean stock quotes, charts,
+order books, indices, rankings, and investor trends in natural language, along
+with your account's balance, holdings, and transaction history. For an ISA
+account it also computes your realized-gain aggregation against the tax-free
+allowance.
+
+> ⚠️ **Security notice**
+>
+> - Run this server **locally only** — never expose it to an external network.
+> - The AppKey/AppSecret in `.env` grant real-account inquiry access. **Never
+>   commit them** (`.env` is already in `.gitignore`).
+> - Order execution (buy/sell/modify/cancel) is **excluded by design**. This
+>   server never changes your account.
+
+## Tools
+
+**Market data** (account-independent — an app key is enough):
+
+| 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 |
+| `get_stock_chart` | Daily/weekly/monthly/minute candles (adjusted price) | ka10080~83 |
+| `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_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 |
+| `get_foreign_holding` | Per-stock foreign holding trend (holdings / holding weight / limit-usage rate) | ka10008 |
+
+**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 |
+
+> The Kiwoom REST API exposes no watchlist **edit** (add/remove) TR — read-only.
+
+**Theme**:
+
+| Tool | Description | Kiwoom TR |
+|---|---|---|
+| `get_theme_groups` | Theme groups (change rate / stock count / period return / lead stocks; find a stock's themes) | ka90001 |
+| `get_theme_stocks` | Member stocks of one theme with quotes (price / change / volume / period return) | ka90002 |
+
+**Account** (scoped to the account bound to the app key):
+
+| Tool | Description | Kiwoom TR |
+|---|---|---|
+| `get_account_balance` | Deposit + total valuation / total P&L / estimated deposit assets | kt00001, kt00018 |
+| `get_account_holdings` | Per-holding quantity / average cost / current price / valuation P&L | kt00018 |
+| `get_transactions` | Transaction history for a period (trade date, unit price, settlement amount) | kt00015 |
+| `get_pending_orders` | Open/unfilled orders (order no., side, status, ordered/unfilled qty, price) | ka10075 |
+| `get_trading_journal` | The day's trading journal (per-stock buy/sell avg price, qty, realized P&L, totals) | ka10170 |
+| `calc_isa_tax_status` | ISA aggregated net gain vs. the tax-free allowance (realized + full-liquidation scenario) | kt00015, ka10074, kt00018 |
+
+Plus `ping` (connectivity check, no app key needed). Every response is prefixed
+with `[모의투자]` (VIRTUAL) / `[실전투자]` (REAL) so you can tell which server
+answered. The first `search_stock` call downloads the stock master (~4,300
+symbols), takes a few seconds, and is then cached for 12 hours.
+
+### Notes on `calc_isa_tax_status`
+
+- Aggregation start date: `ISA_OPENED_ON` (account opening date) in `.env` is the
+  default; override per call with `from_date`.
+- If dividends/distributions are not auto-detected from the transaction history,
+  enter them manually via the `dividends_received` argument.
+- A stock's tax type (taxable vs. domestic-equity) is classified automatically —
+  for ETFs from Kiwoom's own `etftxon_type` (ka40002), otherwise by a name-based
+  heuristic. Correct a wrong classification with
+  `overrides: [{stock_code, tax_type}]`. Results are for reference only — actual
+  taxation follows the broker's settlement.
+
+## Requirements
+
+- **Node.js 20.12 or later** (uses `process.loadEnvFile`)
+- A Kiwoom Securities REST API app key — register an app at the
+  [Kiwoom Open API portal](https://openapi.kiwoom.com) to obtain one.
+  - VIRTUAL (paper trading) and REAL use **separately issued app keys**; the key
+    type must match `KIWOOM_MODE`.
+  - The account is bound to the app key, so no account number is required.
+
+## Install
+
+The package is published to npm, so you can **run it with `npx` — no clone
+required**; just use the npx config in "Connecting Claude Desktop" / "Connecting
+Claude Code" below. In that case you pass your app key via the **client config's
+`env` block** instead of a `.env` file (examples in each connection section).
+
+To build from source or modify the code:
+
+```sh
+git clone <this repo URL>    # or copy the source
+cd kiwoom-mcp-server
+npm install
+cp .env.example .env         # fill in the values per the table below
+npm run build                # produces dist/
+npm test                     # unit tests (no network required)
+```
+
+## Environment variables (`.env`)
+
+| Variable | Required | Description |
+|---|---|---|
+| `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.
+
+`.env` is resolved from the project root first, so the server works even when
+launched from an arbitrary working directory (as Claude Desktop does).
+
+## Connecting Claude Desktop
+
+Config file location:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**npx (published) — no clone; pass your app key via the `env` block:**
+
+```json
+{
+  "mcpServers": {
+    "kiwoom": {
+      "command": "npx",
+      "args": ["-y", "kiwoom-mcp-server"],
+      "env": {
+        "KIWOOM_APP_KEY": "…",
+        "KIWOOM_APP_SECRET": "…",
+        "KIWOOM_MODE": "REAL"
+      }
+    }
+  }
+}
+```
+
+**From source — run `dist/index.js` directly; app key from the project-root `.env`:**
+
+```json
+{
+  "mcpServers": {
+    "kiwoom": {
+      "command": "/opt/homebrew/bin/node",
+      "args": ["/absolute/path/kiwoom-mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+> **Prefer the absolute path to the executable** (find it with `which node` or
+> `which npx`). GUI apps do not inherit your shell `PATH`, so a bare `"node"` /
+> `"npx"` can make the server silently fail to start — the single most common
+> failure.
+
+After saving, fully quit Claude Desktop (⌘Q on macOS) and relaunch to see the
+tools. **After every `npm run build` rebuild you must fully quit and relaunch
+again** for the change to take effect.
+
+## Connecting Claude Code
+
+npx (published) — pass your app key via `-e` flags:
+
+```sh
+claude mcp add kiwoom \
+  -e KIWOOM_APP_KEY=… -e KIWOOM_APP_SECRET=… -e KIWOOM_MODE=REAL \
+  -- npx -y kiwoom-mcp-server
+```
+
+From source — app key from the project-root `.env`:
+
+```sh
+claude mcp add kiwoom -- node /absolute/path/kiwoom-mcp-server/dist/index.js
+```
+
+## Smoke test
+
+You can verify over stdio without an MCP client:
+
+```sh
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{}}}' \
+  | node dist/index.js
+```
+
+`ping` responds without a `.env`. Market-data and account tools need an app key.
+
+## Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| Tools don't appear in Desktop | Is `command` an **absolute** node path? Did you run `npm run build`? Did you fully quit and relaunch Desktop? |
+| `환경설정이 없거나 잘못되었습니다` (config missing/invalid) | Is `.env` in the project root, with the required variables filled in? |
+| `키움 인증에 실패했습니다` (auth failed) | Does the app-key type (paper/live) match `KIWOOM_MODE`? Is the app active on the portal? |
+| `요청 한도를 초과했습니다` (rate limit) | Kiwoom rate limit (~1 req/s per TR). This means it was still exceeded after the server's automatic retry — wait a moment and retry. |
+| Deposit differs from the D+2 estimated deposit | Normal when there are unsettled (D+2) trades. |
+
+## Development
+
+```sh
+npm run dev        # run the source directly with tsx
+npm run typecheck  # tsc --noEmit
+npm test           # vitest
+npm run build      # tsc → dist/
+```
+
+Structure: `src/kiwoom/` (auth / HTTP / TR layer) → `src/tools/` (MCP tools with
+formatters split out) → `src/isa/` (tax-type classification / realized-P&L
+reconstruction / gain aggregation). See `CLAUDE.md` for detailed rules and the
+verified API contract.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -0,0 +1,217 @@
+# kiwoom-mcp-server
+
+**한국어** · [English](README.en.md)
+
+키움증권 REST API를 **조회 전용(read-only)** 으로 노출하는 MCP 서버입니다.
+Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·호가·지수·순위·수급과
+내 계좌의 잔고·보유 종목·거래내역을 조회할 수 있고, ISA 계좌라면 비과세 한도
+대비 손익통산 현황까지 계산해 줍니다.
+
+> ⚠️ **보안 경고**
+>
+> - 이 서버는 **로컬에서만 실행**하고 절대 외부 네트워크에 노출하지 마세요.
+> - `.env`의 AppKey/AppSecret은 실계좌 조회 권한입니다. 절대 커밋하지 마세요
+>   (`.gitignore`에 이미 등록되어 있습니다).
+> - 주문(매수/매도/정정/취소) 기능은 설계상 제외되어 있습니다. 이 서버가 계좌를
+>   변경하는 일은 없습니다.
+
+## 제공 Tool
+
+**시장 데이터** (계좌와 무관, 앱키만 있으면 사용 가능):
+
+| Tool | 설명 | 키움 TR |
+|---|---|---|
+| `search_stock` | 종목명→코드 검색 (코스피/코스닥, ETF/ETN 포함) | ka10099 |
+| `get_stock_price` | 현재가/등락률/거래량/기본지표 | ka10001 |
+| `get_stock_chart` | 일/주/월/분봉 캔들 차트 (수정주가 반영) | ka10080~83 |
+| `get_orderbook` | 10단계 매도/매수 호가·잔량 | ka10004 |
+| `get_market_index` | 코스피/코스닥 종합·업종 지수 | ka20003 |
+| `get_ranking` | 상승률/하락률/거래량/거래대금 상위 | ka10027/30/32 |
+| `get_investor_trend` | 개인/외국인/기관 순매수 동향 (기간 합계 + 일별) | ka10059, ka10061 |
+| `get_etf_info` | ETF 추적지수·과세유형·시세 | ka40002, ka10001 |
+| `get_short_selling` | 종목별 일자별 공매도 추이 (공매도량·비중·평균가) | ka10014 |
+| `get_foreign_holding` | 종목별 외국인 보유 추이 (보유주식수·보유비중·한도소진률) | ka10008 |
+
+**관심종목** (영웅문 HTS에 저장한 관심 그룹, 읽기 전용):
+
+| Tool | 설명 | 키움 TR |
+|---|---|---|
+| `get_watchlist_groups` | HTS 관심종목 그룹 목록 (그룹코드+그룹명) | ka01300 |
+| `get_watchlist` | 그룹 내 종목 목록 (종목명·전일종가·시장 보강) | ka01301, ka10099 |
+
+> 키움 REST API에는 관심종목 **편집(추가/삭제)** TR이 없어 조회만 가능합니다.
+
+**테마**:
+
+| Tool | 설명 | 키움 TR |
+|---|---|---|
+| `get_theme_groups` | 테마 그룹 목록 (등락률·종목수·기간수익률·주요종목; 종목별 편입 테마 검색) | ka90001 |
+| `get_theme_stocks` | 특정 테마의 구성종목과 시세 (현재가·등락률·거래량·기간수익률) | ka90002 |
+
+**계좌** (앱키에 귀속된 계좌 기준):
+
+| Tool | 설명 | 키움 TR |
+|---|---|---|
+| `get_account_balance` | 예수금 + 총평가금액/총평가손익/추정예탁자산 | kt00001, kt00018 |
+| `get_account_holdings` | 보유 종목별 수량/평균단가/현재가/평가손익 | kt00018 |
+| `get_transactions` | 기간별 거래내역 (체결일·단가·정산금액) | kt00015 |
+| `get_pending_orders` | 미체결 주문 (주문번호·구분·상태·주문/미체결수량·주문가격) | ka10075 |
+| `get_trading_journal` | 당일매매일지 (종목별 매수/매도 평균가·수량·실현손익, 총손익) | ka10170 |
+| `calc_isa_tax_status` | ISA 손익통산 순이익의 비과세 한도 대비 현황 (확정 + 전량매도 시나리오) | kt00015, ka10074, kt00018 |
+
+그 외 `ping`(연결 확인, 앱키 불필요). 모든 응답은 `[모의투자]`/`[실전투자]` 접두어로
+어느 서버가 답했는지 표시합니다. `search_stock` 첫 호출은 종목 마스터(~4,300종목)를
+내려받아 몇 초 걸리며 이후 12시간 캐시됩니다.
+
+### `calc_isa_tax_status` 사용 메모
+
+- 집계 시작일: `.env`의 `ISA_OPENED_ON`(계좌 개설일)이 기본값, 호출 시 `from_date`로 오버라이드 가능.
+- 배당·분배금이 거래내역에서 자동 감지되지 않으면 `dividends_received` 인자로 수동 입력.
+- 종목 과세유형(과세대상 vs 국내주식형)은 종목명 기반 자동 분류이며, 틀린 경우
+  `overrides: [{stock_code, tax_type}]`로 수정. 결과는 참고용 — 실제 과세는 증권사 정산 기준.
+
+## 요구 사항
+
+- **Node.js 20.12 이상** (`process.loadEnvFile` 사용)
+- 키움증권 REST API 앱키 — [키움 Open API 포털](https://openapi.kiwoom.com)에서
+  앱 등록 후 발급
+  - 모의투자(VIRTUAL)와 실전투자(REAL)는 **각각 별도로 발급받은 앱키**를 사용하며,
+    발급받은 키 종류와 `KIWOOM_MODE`가 일치해야 합니다.
+  - 계좌는 앱키에 귀속되므로 계좌번호 입력은 필요 없습니다.
+
+## 설치
+
+npm에 배포되어 있으므로 **클론 없이 `npx`로 바로 실행**할 수 있습니다 — 아래
+"Claude Desktop 연결" / "Claude Code 연결"의 npx 설정을 그대로 쓰면 됩니다. 이 경우
+앱키는 `.env` 파일 대신 **클라이언트 설정의 `env` 블록**으로 전달합니다(예제는 각
+연결 섹션 참고).
+
+소스에서 직접 빌드하거나 코드를 수정하려면:
+
+```sh
+git clone <이 저장소 URL>   # 또는 소스 복사
+cd kiwoom-mcp-server
+npm install
+cp .env.example .env        # 아래 표를 참고해 값 입력
+npm run build               # dist/ 생성
+npm test                    # 단위 테스트 (네트워크 불필요)
+```
+
+## 환경 변수 (`.env`)
+
+| 변수 | 필수 | 설명 |
+|---|---|---|
+| `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은 모두 동작합니다.
+
+`.env`는 프로젝트 루트에서 먼저 찾기 때문에 (Claude Desktop처럼) 임의의 작업
+디렉터리에서 실행돼도 동작합니다.
+
+## Claude Desktop 연결
+
+설정 파일 위치:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**npx (배포판) — 클론 없이 실행. 앱키는 `env` 블록으로 전달:**
+
+```json
+{
+  "mcpServers": {
+    "kiwoom": {
+      "command": "npx",
+      "args": ["-y", "kiwoom-mcp-server"],
+      "env": {
+        "KIWOOM_APP_KEY": "…",
+        "KIWOOM_APP_SECRET": "…",
+        "KIWOOM_MODE": "REAL"
+      }
+    }
+  }
+}
+```
+
+**소스 빌드 — `dist/index.js` 직접 실행. 앱키는 프로젝트 루트 `.env` 사용:**
+
+```json
+{
+  "mcpServers": {
+    "kiwoom": {
+      "command": "/opt/homebrew/bin/node",
+      "args": ["/절대/경로/kiwoom-mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+> **`command`에는 실행 파일의 절대 경로**를 쓰는 편이 가장 안전합니다 (`which node`,
+> `which npx`로 확인). GUI 앱은 셸 PATH를 상속받지 않으므로 `"node"`/`"npx"`라고만
+> 쓰면 서버가 조용히 뜨지 않을 수 있습니다 — 가장 흔한 실패 원인입니다.
+
+저장 후 Claude Desktop을 완전히 종료(macOS는 ⌘Q)했다가 다시 실행하면 tool이
+보입니다. `npm run build`로 **다시 빌드한 뒤에도 완전 종료 후 재실행**해야
+변경이 반영됩니다.
+
+## Claude Code 연결
+
+npx (배포판) — 앱키는 `-e` 플래그로 전달:
+
+```sh
+claude mcp add kiwoom \
+  -e KIWOOM_APP_KEY=… -e KIWOOM_APP_SECRET=… -e KIWOOM_MODE=REAL \
+  -- npx -y kiwoom-mcp-server
+```
+
+소스 빌드 — 프로젝트 루트 `.env` 사용:
+
+```sh
+claude mcp add kiwoom -- node /절대/경로/kiwoom-mcp-server/dist/index.js
+```
+
+## 동작 확인
+
+MCP 클라이언트 없이 stdio로 직접 확인할 수 있습니다:
+
+```sh
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{}}}' \
+  | node dist/index.js
+```
+
+`ping`은 `.env` 없이도 응답합니다. 시세·계좌 tool은 앱키가 있어야 합니다.
+
+## 문제 해결
+
+| 증상 | 확인할 것 |
+|---|---|
+| Desktop에 tool이 안 보임 | `command`가 node **절대 경로**인지, `npm run build`를 했는지, Desktop을 완전 종료 후 재실행했는지 |
+| `환경설정이 없거나 잘못되었습니다` | `.env`가 프로젝트 루트에 있는지, 필수 변수가 채워졌는지 |
+| `키움 인증에 실패했습니다` | 앱키 종류(모의/실전)와 `KIWOOM_MODE`가 일치하는지, 포털에서 앱이 활성 상태인지 |
+| `요청 한도를 초과했습니다` | 키움 레이트리밋(TR당 약 1초 1회). 서버가 자동 재시도한 뒤에도 초과한 경우이니 잠시 후 다시 시도 |
+| 예수금과 D+2 추정예수금이 다름 | 미결제(D+2 정산) 매매가 있으면 정상입니다 |
+
+## 개발
+
+```sh
+npm run dev        # tsx로 소스 직접 실행
+npm run typecheck  # tsc --noEmit
+npm test           # vitest
+npm run build      # tsc → dist/
+```
+
+구조: `src/kiwoom/`(인증·HTTP·TR 계층) → `src/tools/`(MCP tool, 포맷터 분리) →
+`src/isa/`(과세유형 분류·실현손익 재구성·손익통산). 상세 규칙과 검증된 API
+계약은 `CLAUDE.md` 참고.
+
+## 라이선스
+
+[MIT](LICENSE)

package/dist/config.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+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"),
+    /** ISA account opening date — default aggregation start for tax-status math. */
+    ISA_OPENED_ON: z
+        .string()
+        .regex(/^\d{4}-?\d{2}-?\d{2}$/)
+        .optional(),
+});
+const BASE_URLS = {
+    VIRTUAL: "https://mockapi.kiwoom.com",
+    REAL: "https://api.kiwoom.com",
+};
+const MODE_LABELS = {
+    VIRTUAL: "모의투자",
+    REAL: "실전투자",
+};
+let cached = null;
+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)), "..");
+    for (const candidate of [path.join(projectRoot, ".env"), path.join(process.cwd(), ".env")]) {
+        try {
+            process.loadEnvFile(candidate);
+            return;
+        }
+        catch {
+            // File missing — try the next candidate; env vars may also be set directly.
+        }
+    }
+}
+export function getConfig() {
+    if (cached)
+        return cached;
+    loadDotEnv();
+    const parsed = envSchema.safeParse(process.env);
+    if (!parsed.success) {
+        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],
+    };
+    return cached;
+}

package/dist/context.js

@@ -0,0 +1,16 @@
+import { getConfig } from "./config.js";
+import { TokenManager } from "./kiwoom/auth.js";
+import { KiwoomClient } from "./kiwoom/client.js";
+let context = null;
+/**
+ * Lazily builds the shared Kiwoom client. Config errors (missing .env) are
+ * thrown here — at tool-call time — so the server still starts and `ping`
+ * works without credentials.
+ */
+export function getKiwoomContext() {
+    if (!context) {
+        const config = getConfig();
+        context = { config, client: new KiwoomClient(config, new TokenManager(config)) };
+    }
+    return context;
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is reserved for MCP protocol frames — every log must go to stderr,
+    // or Claude Desktop/Code will fail to parse the stream.
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio`);
+}
+main().catch((error) => {
+    console.error("Fatal error while starting kiwoom-mcp-server:", error);
+    process.exit(1);
+});

package/dist/isa/classify-etf.js

@@ -0,0 +1,84 @@
+/**
+ * ka40002(ETF종목정보)의 `etftxon_type`을 사용한 권위 있는 과세유형 분류.
+ *
+ * ETF는 키움이 직접 제공하는 과세유형으로 확정하고, 개별주식·브랜드 미매칭·API
+ * 실패 시에는 `classifyInstrument`의 종목명 휴리스틱으로 폴백한다. 수동 지정
+ * (`overrides`)은 항상 최우선이며 이 경우 API를 호출하지 않는다.
+ *
+ * ka40002는 동일 TR 기준 ~1 req/s 제한이 있으므로 ETF 코드만 순차 호출하고,
+ * 과세유형은 사실상 불변이라 프로세스 내에서 길게 캐시한다.
+ */
+import { fetchEtfInfo } from "../kiwoom/api.js";
+import { sleep } from "../utils/sleep.js";
+import { classifyInstrument, isLikelyEtf, mapEtfTaxonType, } from "./classify.js";
+/** 과세유형은 상장 폐지 전까지 바뀌지 않으므로 길게 캐시해도 안전하다. */
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+/** ka40002는 동일 TR 1 req/s — 캐시 미스로 연속 호출할 때만 간격을 둔다. */
+const ETF_FETCH_GAP_MS = 1_100;
+let cache = new Map();
+/** 테스트 훅 — 모듈 레벨 ka40002 과세유형 캐시를 비운다. */
+export function clearEtfTaxonCache() {
+    cache = new Map();
+}
+function freshEntry(code) {
+    const hit = cache.get(code);
+    if (hit && Date.now() - hit.fetchedAt < CACHE_TTL_MS)
+        return hit;
+    return undefined;
+}
+/** ka40002 1회 호출; 성공(빈 값 포함)은 캐시하고, 실패는 캐시하지 않는다. */
+async function fetchTaxonType(client, code) {
+    try {
+        const etf = await fetchEtfInfo(client, code);
+        // stk_nm이 비면 ETF가 아님(비-ETF 코드) → null로 확정 캐시.
+        const taxonType = etf.stk_nm ? etf.etftxon_type.trim() || null : null;
+        cache.set(code, { fetchedAt: Date.now(), taxonType });
+        return taxonType;
+    }
+    catch {
+        return null; // API 실패 → 휴리스틱 폴백 (다음 호출에서 재시도되도록 캐시하지 않음)
+    }
+}
+/**
+ * 종목 목록을 코드 기준으로 dedup 하여 과세유형을 분류한다. ETF는 ka40002로
+ * 확정하고 나머지는 휴리스틱으로 폴백한 `Map<code, Classification>`을 반환한다.
+ *
+ * @param etfCodes ka10099 마스터리스트에서 `marketName == "ETF"`로 확인된 코드 집합.
+ *   브랜드 접두어가 없어 이름만으로는 ETF로 안 보이는 종목도 여기 있으면 ka40002
+ *   확정 분류 대상에 포함한다(전달하지 않으면 종목명 브랜드 휴리스틱만 사용).
+ */
+export async function classifyInstruments(client, instruments, overrides, etfCodes) {
+    const unique = new Map();
+    for (const { code, name } of instruments) {
+        if (!unique.has(code))
+            unique.set(code, name);
+    }
+    const result = new Map();
+    let priorFetch = false;
+    for (const [code, name] of unique) {
+        // 브랜드 접두어(이름) 또는 마스터리스트 ETF 표시 중 하나라도 맞으면 ETF로 취급.
+        const isEtf = isLikelyEtf(name) || (etfCodes?.has(code) ?? false);
+        const heuristic = classifyInstrument(code, name, overrides, isEtf);
+        // 수동 지정은 최우선, ETF가 아닌 종목은 조회할 것이 없다.
+        if (overrides?.get(code) || !isEtf) {
+            result.set(code, heuristic);
+            continue;
+        }
+        const cached = freshEntry(code);
+        let taxonType;
+        if (cached) {
+            taxonType = cached.taxonType;
+        }
+        else {
+            if (priorFetch)
+                await sleep(ETF_FETCH_GAP_MS);
+            priorFetch = true;
+            taxonType = await fetchTaxonType(client, code);
+        }
+        const mapped = taxonType ? mapEtfTaxonType(taxonType) : null;
+        result.set(code, mapped
+            ? { taxType: mapped, confident: true, reason: `키움 과세유형: ${taxonType.trim()}` }
+            : heuristic);
+    }
+    return result;
+}