kiwoom-mcp-server 0.17.0 → 0.19.0

package/README.en.md

@@ -222,9 +222,15 @@ MCP_AUTH_TOKEN="$(openssl rand -hex 32)" npx -y kiwoom-mcp-server --http --port
   `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.
+  `https://<your-domain>/mcp` (leave the OAuth fields in Advanced settings empty).
+  On connect, a browser **consent page** opens — enter your `MCP_AUTH_TOKEN` as the
+  access password and you are done: the server implements the MCP authorization spec
+  (OAuth 2.0 + PKCE with dynamic client registration), so no header configuration is
+  needed. A connector added once is available across the web, mobile, and desktop
+  clients. Header-capable clients (e.g. Claude Code `--header`) can still use the
+  static `Authorization: Bearer <MCP_AUTH_TOKEN>` path. OAuth tokens are persisted
+  to `.oauth-state.json` (0600) in the working directory, so restarts don't drop
+  the connection.
 - ⚠️ **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

package/README.md

@@ -211,8 +211,14 @@ MCP_AUTH_TOKEN="$(openssl rand -hex 32)" npx -y kiwoom-mcp-server --http --port
 - 공개 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의 요청 헤더
-  설정(베타)으로 전달할 수 있습니다. 등록한 커넥터는 웹/모바일/데스크톱에서 공용입니다.
+  `https://<도메인>/mcp`를 입력합니다 (고급 설정의 OAuth 필드는 비워둡니다). 연결 시
+  브라우저에 **승인 페이지**가 뜨고, `MCP_AUTH_TOKEN` 값을 접속 암호로 입력하면
+  완료됩니다 — 서버가 MCP 인증 스펙(OAuth 2.0 + PKCE, 동적 클라이언트 등록)을 내장하고
+  있어 별도 헤더 설정이 필요 없습니다. 등록한 커넥터는 웹/모바일/데스크톱에서 공용입니다.
+  헤더를 지정할 수 있는 클라이언트(예: Claude Code `--header`)는 기존처럼
+  `Authorization: Bearer <MCP_AUTH_TOKEN>` 정적 헤더로도 접속할 수 있습니다.
+  OAuth 토큰은 작업 디렉터리의 `.oauth-state.json`(0600)에 저장되어 서버를 재시작해도
+  연결이 유지됩니다.
 - ⚠️ **키움 API 호출은 이 서버가 실행되는 곳에서 나갑니다.** REAL 모드는 키움 지정단말기
   인증(8050)이 IP에 묶이므로, 등록된 IP가 아닌 곳(클라우드 등)에서 실행하면 인증 오류가
   날 수 있습니다. 원격 노출은 모의투자로 먼저 검증하세요.

package/dist/http.js

@@ -1,6 +1,7 @@
-import { createHash, timingSafeEqual } from "node:crypto";
 import http from "node:http";
+import path from "node:path";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { handleOAuthRequest, OAuthProvider, requestBaseUrl, timingSafeStringEqual, } from "./oauth.js";
 import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
 const DEFAULT_PORT = 8000;
 const DEFAULT_HOST = "127.0.0.1";
@@ -59,18 +60,20 @@ export function chooseTransport(argv, env) {
             "인증 없이 열려면 --no-auth를 명시하세요 — 계좌 조회 도구가 인터넷에 그대로 노출되므로 " +
             "신뢰할 수 있는 네트워크/모의투자(VIRTUAL) 환경에서만 권장합니다.");
     }
-    return { mode: "http", options: { port, host, authToken, allowNoAuth } };
+    const publicUrl = env.MCP_PUBLIC_URL?.trim() || undefined;
+    return { mode: "http", options: { port, host, authToken, allowNoAuth, publicUrl } };
 }
-/** Timing-safe bearer-token check (hash first so lengths never short-circuit). */
-export function isAuthorized(authorizationHeader, token) {
+/** Extracts the bearer credential from an Authorization header, if any. */
+export function bearerToken(authorizationHeader) {
     if (!authorizationHeader)
-        return false;
+        return undefined;
     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);
+    return match?.[1];
+}
+/** Timing-safe static bearer-token check. */
+export function isAuthorized(authorizationHeader, token) {
+    const presented = bearerToken(authorizationHeader);
+    return presented !== undefined && timingSafeStringEqual(presented, token);
 }
 function deny(res, status, message) {
     res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify({
@@ -87,27 +90,47 @@ function deny(res, status, message) {
  * lives at module level and is shared across requests.
  */
 export function createHttpServer(options) {
+    // OAuth rides on the same consent secret as the static bearer: no token → no
+    // OAuth endpoints (that is the explicit --no-auth everything-open mode).
+    const oauth = options.authToken
+        ? new OAuthProvider({
+            consentToken: options.authToken,
+            statePath: options.oauthStatePath ?? path.join(process.cwd(), ".oauth-state.json"),
+        })
+        : null;
     return http.createServer((req, res) => {
-        void handleRequest(req, res, options).catch((error) => {
+        void handleRequest(req, res, options, oauth).catch((error) => {
             console.error("HTTP request handling failed:", error);
             if (!res.headersSent)
                 deny(res, 500, "internal server error");
         });
     });
 }
-async function handleRequest(req, res, options) {
+async function handleRequest(req, res, options, oauth) {
     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 (oauth && (await handleOAuthRequest(req, res, oauth, options.publicUrl))) {
+        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;
+    if (options.authToken) {
+        const presented = bearerToken(req.headers.authorization);
+        const ok = presented !== undefined &&
+            (timingSafeStringEqual(presented, options.authToken) ||
+                (oauth?.validateAccessToken(presented) ?? false));
+        if (!ok) {
+            // RFC 9728: point 401s at the protected-resource metadata so MCP
+            // clients (claude.ai connectors) can discover the OAuth flow.
+            res.setHeader("WWW-Authenticate", `Bearer realm="${SERVER_NAME}", resource_metadata="${requestBaseUrl(req, options.publicUrl)}/.well-known/oauth-protected-resource"`);
+            deny(res, 401, "unauthorized — OAuth 승인 또는 Authorization: Bearer <MCP_AUTH_TOKEN> 헤더가 필요합니다");
+            return;
+        }
     }
     const server = createServer();
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });

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/oauth.js

@@ -0,0 +1,427 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+/**
+ * Minimal built-in OAuth 2.0 authorization server for the HTTP transport,
+ * implementing what the MCP authorization spec expects from a remote server
+ * (claude.ai custom connectors drive this flow):
+ *
+ *   401 + WWW-Authenticate → RFC 9728 protected-resource metadata
+ *   → RFC 8414 authorization-server metadata → RFC 7591 dynamic client
+ *   registration → authorization-code + PKCE(S256) → opaque bearer tokens.
+ *
+ * Consent model: this server fronts ONE owner's brokerage account, so the
+ * /authorize page asks for the pre-shared MCP_AUTH_TOKEN as an access
+ * password instead of a user login. One secret serves both auth paths
+ * (static bearer for header-capable clients, OAuth consent for claude.ai).
+ */
+const CODE_TTL_MS = 5 * 60 * 1000;
+const ACCESS_TOKEN_TTL_MS = 60 * 60 * 1000;
+/** Consent brute-force guard: max failures per window, shared across IPs. */
+const MAX_CONSENT_FAILURES = 10;
+const CONSENT_FAILURE_WINDOW_MS = 10 * 60 * 1000;
+const MAX_BODY_BYTES = 64 * 1024;
+const token = (bytes = 32) => randomBytes(bytes).toString("hex");
+const sha256base64url = (value) => createHash("sha256").update(value).digest("base64url");
+/** Timing-safe string comparison (hash first so lengths never short-circuit). */
+export function timingSafeStringEqual(a, b) {
+    return timingSafeEqual(createHash("sha256").update(a).digest(), createHash("sha256").update(b).digest());
+}
+/** PKCE S256: does sha256(verifier) match the stored challenge? */
+export function verifyPkce(codeVerifier, codeChallenge) {
+    return timingSafeStringEqual(sha256base64url(codeVerifier), codeChallenge);
+}
+const escapeHtml = (s) => s
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+/** https-only redirect URIs, except loopback for local development. */
+export function isAllowedRedirectUri(uri) {
+    let url;
+    try {
+        url = new URL(uri);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol === "https:")
+        return true;
+    return url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+}
+export class OAuthProvider {
+    consentToken;
+    statePath;
+    clients = new Map();
+    codes = new Map();
+    tokens = new Map(); // keyed by accessToken
+    refresh = new Map(); // keyed by refreshToken
+    consentFailures = 0;
+    consentWindowStart = 0;
+    constructor(options) {
+        this.consentToken = options.consentToken;
+        this.statePath = options.statePath;
+        this.load();
+    }
+    load() {
+        if (!this.statePath || !existsSync(this.statePath))
+            return;
+        try {
+            const state = JSON.parse(readFileSync(this.statePath, "utf8"));
+            for (const c of state.clients ?? [])
+                this.clients.set(c.clientId, c);
+            for (const t of state.tokens ?? []) {
+                this.tokens.set(t.accessToken, t);
+                this.refresh.set(t.refreshToken, t);
+            }
+        }
+        catch (error) {
+            // A corrupt state file only means connectors must re-authorize.
+            console.error("OAuth state file unreadable — starting empty:", error);
+        }
+    }
+    save() {
+        if (!this.statePath)
+            return;
+        const state = {
+            clients: [...this.clients.values()],
+            tokens: [...this.refresh.values()],
+        };
+        try {
+            writeFileSync(this.statePath, JSON.stringify(state, null, 2), { mode: 0o600 });
+        }
+        catch (error) {
+            console.error("Failed to persist OAuth state:", error);
+        }
+    }
+    registerClient(meta) {
+        const uris = Array.isArray(meta.redirect_uris)
+            ? meta.redirect_uris.filter((u) => typeof u === "string")
+            : [];
+        if (uris.length === 0 || !uris.every(isAllowedRedirectUri)) {
+            return { error: "redirect_uris must be https URLs (or http loopback)" };
+        }
+        const client = {
+            clientId: token(16),
+            redirectUris: uris,
+            clientName: typeof meta.client_name === "string" ? meta.client_name.slice(0, 200) : "",
+            createdAt: Date.now(),
+        };
+        this.clients.set(client.clientId, client);
+        this.save();
+        return client;
+    }
+    getClient(clientId) {
+        return this.clients.get(clientId);
+    }
+    consentRateLimited() {
+        if (Date.now() - this.consentWindowStart > CONSENT_FAILURE_WINDOW_MS)
+            return false;
+        return this.consentFailures >= MAX_CONSENT_FAILURES;
+    }
+    /** Validates the consent password; counts failures for the rate limit. */
+    checkConsent(password) {
+        if (timingSafeStringEqual(password, this.consentToken))
+            return true;
+        if (Date.now() - this.consentWindowStart > CONSENT_FAILURE_WINDOW_MS) {
+            this.consentWindowStart = Date.now();
+            this.consentFailures = 0;
+        }
+        this.consentFailures += 1;
+        return false;
+    }
+    createCode(clientId, redirectUri, codeChallenge) {
+        const code = {
+            code: token(24),
+            clientId,
+            redirectUri,
+            codeChallenge,
+            expiresAt: Date.now() + CODE_TTL_MS,
+        };
+        this.codes.set(code.code, code);
+        return code.code;
+    }
+    exchangeCode(params) {
+        const record = this.codes.get(params.code);
+        this.codes.delete(params.code); // single-use, even on failure
+        if (!record || record.expiresAt < Date.now())
+            return { error: "invalid_grant" };
+        if (record.clientId !== params.clientId || record.redirectUri !== params.redirectUri) {
+            return { error: "invalid_grant" };
+        }
+        if (!verifyPkce(params.codeVerifier, record.codeChallenge))
+            return { error: "invalid_grant" };
+        return this.issueTokens(record.clientId);
+    }
+    refreshTokens(refreshToken, clientId) {
+        const record = this.refresh.get(refreshToken);
+        if (!record || record.clientId !== clientId)
+            return { error: "invalid_grant" };
+        // Rotate: the presented refresh token is spent either way.
+        this.refresh.delete(refreshToken);
+        this.tokens.delete(record.accessToken);
+        return this.issueTokens(clientId);
+    }
+    issueTokens(clientId) {
+        const record = {
+            accessToken: token(32),
+            refreshToken: token(32),
+            clientId,
+            accessExpiresAt: Date.now() + ACCESS_TOKEN_TTL_MS,
+            createdAt: Date.now(),
+        };
+        this.tokens.set(record.accessToken, record);
+        this.refresh.set(record.refreshToken, record);
+        this.save();
+        return record;
+    }
+    validateAccessToken(accessToken) {
+        const record = this.tokens.get(accessToken);
+        return record !== undefined && record.accessExpiresAt > Date.now();
+    }
+}
+/** Base URL for metadata/issuer: explicit override, else the request's own host. */
+export function requestBaseUrl(req, publicUrl) {
+    if (publicUrl)
+        return publicUrl.replace(/\/+$/, "");
+    const forwardedProto = req.headers["x-forwarded-proto"];
+    const proto = (Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto)?.split(",")[0]?.trim() ||
+        "http";
+    return `${proto}://${req.headers.host ?? "localhost"}`;
+}
+export function buildProtectedResourceMetadata(base) {
+    return {
+        resource: `${base}/mcp`,
+        authorization_servers: [base],
+        bearer_methods_supported: ["header"],
+    };
+}
+export function buildAuthServerMetadata(base) {
+    return {
+        issuer: base,
+        authorization_endpoint: `${base}/authorize`,
+        token_endpoint: `${base}/token`,
+        registration_endpoint: `${base}/register`,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["none"],
+        scopes_supported: [],
+    };
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error("body too large");
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function parseBodyParams(raw, contentType) {
+    if (contentType?.includes("application/json")) {
+        const parsed = JSON.parse(raw);
+        const out = {};
+        if (parsed && typeof parsed === "object") {
+            for (const [k, v] of Object.entries(parsed))
+                if (typeof v === "string")
+                    out[k] = v;
+        }
+        return out;
+    }
+    return Object.fromEntries(new URLSearchParams(raw));
+}
+function sendJson(res, status, body) {
+    res
+        .writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" })
+        .end(JSON.stringify(body));
+}
+function sendHtml(res, status, body) {
+    res
+        .writeHead(status, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+        "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
+    })
+        .end(body);
+}
+function consentPage(fields, clientName, error) {
+    const hidden = Object.entries(fields)
+        .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`)
+        .join("\n      ");
+    return `<!doctype html>
+<html lang="ko"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>kiwoom-mcp-server 연결 승인</title>
+<style>
+  body { font-family: -apple-system, sans-serif; max-width: 26rem; margin: 4rem auto; padding: 0 1rem; }
+  input[type=password] { width: 100%; padding: .6rem; font-size: 1rem; margin: .8rem 0; box-sizing: border-box; }
+  button { padding: .6rem 1.4rem; font-size: 1rem; }
+  .err { color: #c0392b; }
+  .meta { color: #666; font-size: .85rem; }
+</style></head>
+<body>
+  <h2>kiwoom-mcp-server 연결 승인</h2>
+  <p>클라이언트${clientName ? ` <strong>${escapeHtml(clientName)}</strong>` : ""}가 이 서버의
+  주식 조회 도구(읽기 전용)에 접근하려고 합니다.</p>
+  <p class="meta">승인하려면 서버의 <code>MCP_AUTH_TOKEN</code> 값을 입력하세요.</p>
+  ${error ? `<p class="err">${escapeHtml(error)}</p>` : ""}
+  <form method="post" action="/authorize">
+      ${hidden}
+      <input type="password" name="password" placeholder="접속 암호 (MCP_AUTH_TOKEN)" autofocus required>
+      <button type="submit">승인</button>
+  </form>
+</body></html>`;
+}
+/** Shared /authorize validation for GET (render) and POST (approve). */
+function validateAuthorizeParams(provider, q, res) {
+    const client = q.client_id ? provider.getClient(q.client_id) : undefined;
+    if (!client) {
+        sendHtml(res, 400, consentPage({}, "", "알 수 없는 client_id입니다. 커넥터를 다시 등록해 주세요."));
+        return null;
+    }
+    const redirectUri = q.redirect_uri ?? "";
+    if (!client.redirectUris.includes(redirectUri)) {
+        sendHtml(res, 400, consentPage({}, client.clientName, "redirect_uri가 등록된 값과 다릅니다."));
+        return null;
+    }
+    // From here on the redirect target is trusted — protocol errors go back via redirect.
+    const redirectError = (error) => {
+        const url = new URL(redirectUri);
+        url.searchParams.set("error", error);
+        if (q.state)
+            url.searchParams.set("state", q.state);
+        res.writeHead(302, { Location: url.toString() }).end();
+        return null;
+    };
+    if (q.response_type !== "code")
+        return redirectError("unsupported_response_type");
+    if (!q.code_challenge || (q.code_challenge_method ?? "S256") !== "S256") {
+        return redirectError("invalid_request");
+    }
+    return { client, redirectUri, codeChallenge: q.code_challenge, state: q.state ?? "" };
+}
+/**
+ * Handles OAuth endpoints. Returns true when the request was consumed.
+ * Wire this BEFORE the /mcp route; call only when auth is enabled.
+ */
+export async function handleOAuthRequest(req, res, provider, publicUrl) {
+    const base = requestBaseUrl(req, publicUrl);
+    const url = new URL(req.url ?? "/", base);
+    if (url.pathname === "/.well-known/oauth-protected-resource") {
+        sendJson(res, 200, buildProtectedResourceMetadata(base));
+        return true;
+    }
+    if (url.pathname === "/.well-known/oauth-authorization-server") {
+        sendJson(res, 200, buildAuthServerMetadata(base));
+        return true;
+    }
+    if (url.pathname === "/register" && req.method === "POST") {
+        let meta;
+        try {
+            meta = JSON.parse(await readBody(req));
+        }
+        catch {
+            sendJson(res, 400, { error: "invalid_client_metadata" });
+            return true;
+        }
+        const client = provider.registerClient(meta);
+        if ("error" in client) {
+            sendJson(res, 400, { error: "invalid_redirect_uri", error_description: client.error });
+            return true;
+        }
+        sendJson(res, 201, {
+            client_id: client.clientId,
+            client_id_issued_at: Math.floor(client.createdAt / 1000),
+            redirect_uris: client.redirectUris,
+            client_name: client.clientName || undefined,
+            token_endpoint_auth_method: "none",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+        });
+        return true;
+    }
+    if (url.pathname === "/authorize" && req.method === "GET") {
+        const q = Object.fromEntries(url.searchParams);
+        const params = validateAuthorizeParams(provider, q, res);
+        if (!params)
+            return true;
+        sendHtml(res, 200, consentPage({
+            client_id: params.client.clientId,
+            redirect_uri: params.redirectUri,
+            state: params.state,
+            code_challenge: params.codeChallenge,
+            code_challenge_method: "S256",
+            response_type: "code",
+        }, params.client.clientName));
+        return true;
+    }
+    if (url.pathname === "/authorize" && req.method === "POST") {
+        let form;
+        try {
+            form = parseBodyParams(await readBody(req), req.headers["content-type"]);
+        }
+        catch {
+            sendHtml(res, 400, consentPage({}, "", "요청을 읽지 못했습니다. 다시 시도해 주세요."));
+            return true;
+        }
+        const params = validateAuthorizeParams(provider, form, res);
+        if (!params)
+            return true;
+        if (provider.consentRateLimited()) {
+            sendHtml(res, 429, consentPage({}, params.client.clientName, "시도 횟수를 초과했습니다. 10분 후 다시 시도해 주세요."));
+            return true;
+        }
+        if (!provider.checkConsent(form.password ?? "")) {
+            const { password: _password, ...fields } = form;
+            sendHtml(res, 401, consentPage(fields, params.client.clientName, "접속 암호가 일치하지 않습니다."));
+            return true;
+        }
+        const code = provider.createCode(params.client.clientId, params.redirectUri, params.codeChallenge);
+        const target = new URL(params.redirectUri);
+        target.searchParams.set("code", code);
+        if (params.state)
+            target.searchParams.set("state", params.state);
+        res.writeHead(302, { Location: target.toString() }).end();
+        return true;
+    }
+    if (url.pathname === "/token" && req.method === "POST") {
+        let form;
+        try {
+            form = parseBodyParams(await readBody(req), req.headers["content-type"]);
+        }
+        catch {
+            sendJson(res, 400, { error: "invalid_request" });
+            return true;
+        }
+        let result;
+        if (form.grant_type === "authorization_code") {
+            result = provider.exchangeCode({
+                code: form.code ?? "",
+                codeVerifier: form.code_verifier ?? "",
+                clientId: form.client_id ?? "",
+                redirectUri: form.redirect_uri ?? "",
+            });
+        }
+        else if (form.grant_type === "refresh_token") {
+            result = provider.refreshTokens(form.refresh_token ?? "", form.client_id ?? "");
+        }
+        else {
+            sendJson(res, 400, { error: "unsupported_grant_type" });
+            return true;
+        }
+        if ("error" in result) {
+            sendJson(res, 400, { error: result.error });
+            return true;
+        }
+        sendJson(res, 200, {
+            access_token: result.accessToken,
+            token_type: "Bearer",
+            expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+            refresh_token: result.refreshToken,
+        });
+        return true;
+    }
+    return false;
+}

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.17.0";
+export const SERVER_VERSION = "0.19.0";
 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,6 @@
 {
   "name": "kiwoom-mcp-server",
-  "version": "0.17.0",
+  "version": "0.19.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",