kiwoom-mcp-server 0.18.0 → 0.19.1

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, brokerActivityResponseSchema, dailyChartItemSchema, depositResponseSchema, etfInfoResponseSchema, etfNavItemSchema, etfReturnItemSchema, foreignHoldingResponseSchema, investorDailyItemSchema, investorTotalItemSchema, lendingTrendResponseSchema, limitStockItemSchema, minuteChartItemSchema, newHighLowItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, priceJumpItemSchema, programTradeItemSchema, realizedPnlResponseSchema, sectorPriceResponseSchema, sectorStocksResponseSchema, shortSellingResponseSchema, stockInfoResponseSchema, stockListResponseSchema, themeGroupsResponseSchema, tradingJournalResponseSchema, themeStocksResponseSchema, transactionsResponseSchema, valueRankItemSchema, viStockItemSchema, volumeRankItemSchema, watchlistGroupDetailResponseSchema, watchlistGroupsResponseSchema, } from "./types.js";
+import { accountEvaluationResponseSchema, accountPeriodPlResponseSchema, allIndexResponseSchema, brokerActivityResponseSchema, dailyChartItemSchema, depositResponseSchema, etfInfoResponseSchema, etfNavItemSchema, etfReturnItemSchema, foreignHoldingResponseSchema, investorDailyItemSchema, investorTotalItemSchema, lendingTrendResponseSchema, limitStockItemSchema, minuteChartItemSchema, newHighLowItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, priceJumpItemSchema, programTradeItemSchema, realizedPnlResponseSchema, sectorPriceResponseSchema, sectorStocksResponseSchema, shortSellingResponseSchema, stockInfoResponseSchema, stockListResponseSchema, themeGroupsResponseSchema, tradingJournalResponseSchema, themeStocksResponseSchema, transactionsResponseSchema, valueRankItemSchema, viStockItemSchema, volumeRankItemSchema, watchlistGroupDetailResponseSchema, watchlistGroupsResponseSchema, } from "./types.js";
 const STOCK_INFO_PATH = "/api/dostk/stkinfo";
 const ACCOUNT_PATH = "/api/dostk/acnt";
 const CHART_PATH = "/api/dostk/chart";
@@ -72,6 +72,19 @@ export async function fetchAccountEvaluation(client, qryTp) {
     // 남은 페이지가 있는데 상한에서 멈췄으면 데이터가 잘렸다는 뜻.
     return { ...first, acnt_evlt_remn_indv_tot: holdings, truncated: res.hasNext };
 }
+/**
+ * kt00004 계좌평가현황요청 — consumed only for the 당일/당월/누적 투자손익 block
+ * (기간 손익); the deposit/evaluation scalars and per-stock list duplicate
+ * kt00001/kt00018. qry_tp "0" = 상장폐지 포함 전체 (probe-validated body).
+ */
+export async function fetchAccountPeriodPl(client) {
+    const res = await client.call({
+        path: ACCOUNT_PATH,
+        apiId: "kt00004",
+        body: { qry_tp: "0", dmst_stex_tp: "KRX" },
+    });
+    return accountPeriodPlResponseSchema.parse(res.json);
+}
 /**
  * kt00015 위탁종합거래내역요청 — all transactions in [fromDate, toDate] (yyyyMMdd).
  * NOTE (live-verified): only 매매 rows are returned for this account type; cash

package/dist/kiwoom/types.js

@@ -72,6 +72,21 @@ export const accountEvaluationResponseSchema = z.looseObject({
     prsm_dpst_aset_amt: str(), // 추정예탁자산
     acnt_evlt_remn_indv_tot: z.array(holdingItemSchema).default([]),
 });
+// ── kt00004: 계좌평가현황 (subset — 당일/당월/누적 기간 손익 필드만 소비) ──
+// 예수금/평가액 계열과 종목별 리스트(stk_acnt_evlt_prst)는 kt00001/kt00018과
+// 중복이라 소비하지 않는다. 필드명은 스펙 그대로(lspft 계열 명명이 뒤섞여 있음).
+export const accountPeriodPlResponseSchema = z.looseObject({
+    ...envelope,
+    tdy_lspft_amt: str(), // 당일투자원금
+    invt_bsamt: str(), // 당월투자원금
+    lspft_amt: str(), // 누적투자원금
+    tdy_lspft: str(), // 당일투자손익 (부호 유의미)
+    lspft2: str(), // 당월투자손익 (부호 유의미)
+    lspft: str(), // 누적투자손익 (부호 유의미)
+    tdy_lspft_rt: str(), // 당일손익율(%)
+    lspft_ratio: str(), // 당월손익율(%)
+    lspft_rt: str(), // 누적손익율(%)
+});
 // ── kt00015: 위탁종합거래내역 (subset) ──
 // NOTE: trde_dt is the settlement date (D+2), not the trade date.
 export const transactionRowSchema = z.looseObject({

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

package/dist/tools/account-balance.js

@@ -1,10 +1,10 @@
 import { getKiwoomContext } from "../context.js";
-import { fetchAccountEvaluation, fetchDeposit } from "../kiwoom/api.js";
+import { fetchAccountEvaluation, fetchAccountPeriodPl, fetchDeposit } from "../kiwoom/api.js";
 import { formatKRW, formatPercent, formatSignedKRW, parseKiwoomNumber } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
-export function formatBalance(deposit, evaluation, modeLabel) {
+export function formatBalance(deposit, evaluation, modeLabel, periodPl = null) {
     const n = parseKiwoomNumber;
-    return [
+    const lines = [
         `[${modeLabel}] 계좌 잔고 요약`,
         "",
         "■ 예수금 (kt00001)",
@@ -17,20 +17,47 @@ export function formatBalance(deposit, evaluation, modeLabel) {
         `- 총평가금액: ${formatKRW(n(evaluation.tot_evlt_amt))}`,
         `- 총평가손익: ${formatSignedKRW(n(evaluation.tot_evlt_pl))} (${formatPercent(n(evaluation.tot_prft_rt))})`,
         `- 추정예탁자산: ${formatKRW(n(evaluation.prsm_dpst_aset_amt))}`,
-    ].join("\n");
+    ];
+    // 기간 손익 블록은 best-effort — kt00004 조회 실패 시 조용히 생략된다.
+    // 라벨은 키움 스펙 원문 그대로 (당일/당월/누적 투자손익·투자원금·손익율).
+    if (periodPl) {
+        const values = [
+            periodPl.tdy_lspft_amt, periodPl.invt_bsamt, periodPl.lspft_amt,
+            periodPl.tdy_lspft, periodPl.lspft2, periodPl.lspft,
+            periodPl.tdy_lspft_rt, periodPl.lspft_ratio, periodPl.lspft_rt,
+        ];
+        const allZero = values.every((v) => !(n(v) ?? 0));
+        lines.push("", "■ 기간 손익 (kt00004)");
+        if (allZero) {
+            // REAL 실측(2026-07-13): 보유·이력이 있는 계좌도 9필드 전부 0으로 반환될 수
+            // 있다 (집계 시점/기준 미설정 추정). "손익 0원"으로 단정 표시하면 오해를
+            // 유발하므로, ka40009 NAV 선례처럼 값이 채워질 때만 수치를 렌더한다.
+            lines.push("- 키움이 기간 손익을 모두 0으로 반환했습니다 — 집계 전이거나 수익률 산출 기준이 없는 계좌일 수 있어 실제 손익이 0이라는 뜻은 아닐 수 있습니다.");
+        }
+        else {
+            lines.push(`- 당일투자손익: ${formatSignedKRW(n(periodPl.tdy_lspft))} (${formatPercent(n(periodPl.tdy_lspft_rt))}) / 당일투자원금 ${formatKRW(n(periodPl.tdy_lspft_amt))}`, `- 당월투자손익: ${formatSignedKRW(n(periodPl.lspft2))} (${formatPercent(n(periodPl.lspft_ratio))}) / 당월투자원금 ${formatKRW(n(periodPl.invt_bsamt))}`, `- 누적투자손익: ${formatSignedKRW(n(periodPl.lspft))} (${formatPercent(n(periodPl.lspft_rt))}) / 누적투자원금 ${formatKRW(n(periodPl.lspft_amt))}`);
+        }
+    }
+    return lines.join("\n");
 }
 export function registerAccountBalanceTool(server) {
     server.registerTool("get_account_balance", {
         title: "계좌 잔고 조회",
         description: "계좌의 예수금(주문가능/출금가능 포함)과 총매입금액, 총평가금액, 총평가손익, " +
-            "추정예탁자산을 조회합니다 (키움 kt00001 + kt00018). 인자가 필요 없습니다.",
+            "추정예탁자산, 당일/당월/누적 투자손익을 조회합니다 (키움 kt00001 + kt00018 + kt00004). " +
+            "인자가 필요 없습니다.",
     }, async () => runTool(async () => {
         const { client, config } = getKiwoomContext();
         // Different TRs — the per-TR rate limit allows these in parallel.
-        const [deposit, evaluation] = await Promise.all([
+        // kt00004 is best-effort: on failure only the 기간 손익 block is dropped.
+        const [deposit, evaluation, periodPl] = await Promise.all([
             fetchDeposit(client),
             fetchAccountEvaluation(client, "1"),
+            fetchAccountPeriodPl(client).catch((error) => {
+                console.error("kt00004 계좌평가현황 조회 실패 — 기간 손익 블록 생략:", error);
+                return null;
+            }),
         ]);
-        return textResult(formatBalance(deposit, evaluation, config.modeLabel));
+        return textResult(formatBalance(deposit, evaluation, config.modeLabel, periodPl));
     }));
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "kiwoom-mcp-server",
-  "version": "0.18.0",
+  "version": "0.19.1",
+  "mcpName": "io.github.ChunSam/kiwoom-mcp-server",
   "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",