-
-
+
+
+ {([['ALL', '전체'], ['KR', '국내'], ['US', '미국']] as const).map(([value, label]) => (
+
+ ))}
+
+
+
{/* [Left Column] 보유 종목 */}
-
+
{
{/* [Center Column] 차트 & 트레이딩 정보 */}
-
+
{/* 차트 섹션 */}
+
{/* [Right Column] 분석 종목 & 매매일지 */}
-
+
{
/>
diff --git a/frontend/src/pages/Login.tsx b/frontend/src/pages/Login.tsx
new file mode 100644
index 0000000..ea1070f
--- /dev/null
+++ b/frontend/src/pages/Login.tsx
@@ -0,0 +1,128 @@
+/**
+ * Login.tsx — 로그인 페이지 컴포넌트
+ *
+ * 역할:
+ * - API 키(SECRET_KEY) 입력을 통한 사용자 인증 처리
+ * - 백엔드 portfolio API로 키 유효성 검증 후 App 컴포넌트에 인증 콜백 전달
+ * - 인증 실패 시 에러 메시지 표시 (401/403 또는 네트워크 오류)
+ *
+ * Props:
+ * - onLogin: 인증 성공 시 API 키를 전달받는 콜백 (App에서 localStorage 저장)
+ */
+import { useState, FormEvent } from 'react'
+import { Activity } from 'lucide-react'
+
+/** Login 컴포넌트 Props 정의 */
+interface LoginProps {
+ /** 인증 성공 시 호출되는 콜백 — API 키 문자열 전달 */
+ onLogin: (apiKey: string) => void
+}
+
+/**
+ * Login — API 키 인증 폼 컴포넌트
+ *
+ * 상태(State):
+ * - apiKey: 사용자 입력 API 키
+ * - error: 인증 실패 에러 메시지
+ * - loading: 검증 요청 진행 중 여부 (버튼 비활성화)
+ */
+const Login = ({ onLogin }: LoginProps) => {
+ const [apiKey, setApiKey] = useState('')
+ const [error, setError] = useState('')
+ const [loading, setLoading] = useState(false)
+
+ /**
+ * 폼 제출 핸들러 — API 키 유효성 검증
+ *
+ * 검증 흐름:
+ * 1. 빈 입력 체크
+ * 2. /api/v1/portfolio/combined 엔드포인트로 API 키 검증 요청
+ * 3. 401/403 응답 시 에러 표시, 성공 시 onLogin 콜백 호출
+ */
+ const handleSubmit = async (e: FormEvent) => {
+ e.preventDefault()
+ if (!apiKey.trim()) {
+ setError('API 키를 입력하세요.')
+ return
+ }
+
+ setLoading(true)
+ setError('')
+
+ try {
+ // API 키 검증: portfolio 엔드포인트로 테스트
+ const res = await fetch('/api/v1/portfolio/combined', {
+ headers: { 'X-API-Key': apiKey.trim() },
+ })
+
+ if (res.status === 401 || res.status === 403) {
+ setError('유효하지 않은 API 키입니다.')
+ setLoading(false)
+ return
+ }
+
+ if (!res.ok) {
+ setError(`서버 오류가 발생했습니다. (HTTP ${res.status})`)
+ setLoading(false)
+ return
+ }
+
+ // 검증 성공 — 상위 컴포넌트에 API 키 전달
+ onLogin(apiKey.trim())
+ } catch {
+ setError('서버 연결에 실패했습니다.')
+ } finally {
+ setLoading(false)
+ }
+ }
+
+ return (
+ (data.length);
+ let sum = 0;
for (let i = 0; i < data.length; i++) {
+ sum += data[i];
if (i < period - 1) {
- result.push(NaN);
+ result[i] = NaN;
} else {
- const sum = data.slice(i - period + 1, i + 1).reduce((a, b) => a + b, 0);
- result.push(sum / period);
+ if (i >= period) sum -= data[i - period];
+ result[i] = sum / period;
}
}
return result;
};
/**
- * 지수이동평균 (Exponential Moving Average)
- * @param data 가격 데이터 배열
- * @param period EMA 기간
- * @returns EMA 값 배열
+ * 지수이동평균 (Exponential Moving Average) — O(n)
+ *
+ * 가중 계수 k = 2 / (period + 1)
+ * EMA[i] = data[i] * k + EMA[i-1] * (1 - k)
+ *
+ * @param data - 종가 배열
+ * @param period - EMA 기간 (예: 12, 26, 9)
+ * @returns EMA 배열 (첫 값은 data[0]으로 초기화)
*/
export const calculateEMA = (data: number[], period: number): number[] => {
- const k = 2 / (period + 1);
- const ema: number[] = [];
-
- for (let i = 0; i < data.length; i++) {
- if (i === 0) {
- ema.push(data[i]);
- } else {
- ema.push(data[i] * k + ema[i - 1] * (1 - k));
- }
+ const k = 2 / (period + 1); // 가중 계수 (smoothing factor)
+ const ema = new Array(data.length);
+ ema[0] = data[0]; // 첫 값은 종가 그대로 사용
+ for (let i = 1; i < data.length; i++) {
+ ema[i] = data[i] * k + ema[i - 1] * (1 - k);
}
-
return ema;
};
/**
- * 볼린저 밴드 (Bollinger Bands)
- * @param closes 종가 배열
- * @param period 기간 (기본값: 20)
- * @returns 상단, 중간(SMA), 하단 밴드 배열
+ * 볼린저 밴드 (Bollinger Bands) — O(n) 슬라이딩 윈도우
+ *
+ * 상단 = SMA(20) + 2 * 표준편차
+ * 중앙 = SMA(20)
+ * 하단 = SMA(20) - 2 * 표준편차
+ *
+ * 표준편차 계산: 슬라이딩 윈도우로 sum과 sumOfSquares를 관리하여 O(n) 달성
+ * 분산 = sumSq/period - mean^2 (Welford 대안 — 수치 안정성은 약간 낮음)
+ *
+ * @param closes - 종가 배열
+ * @param period - 기간 (기본 20)
+ * @returns { upper, middle, lower } 배열
*/
export const calculateBollingerBands = (closes: number[], period: number = 20) => {
const sma = calculateSMA(closes, period);
- const upper: number[] = [];
- const lower: number[] = [];
+ const upper = new Array(closes.length);
+ const lower = new Array(closes.length);
+ // 슬라이딩 윈도우로 sum-of-squares 관리 (O(n) 표준편차 계산)
+ let sumSq = 0;
+ let sum = 0;
for (let i = 0; i < closes.length; i++) {
+ sum += closes[i];
+ sumSq += closes[i] * closes[i];
+ if (i >= period) {
+ sum -= closes[i - period];
+ sumSq -= closes[i - period] * closes[i - period];
+ }
if (i < period - 1) {
- upper.push(NaN);
- lower.push(NaN);
+ upper[i] = NaN;
+ lower[i] = NaN;
} else {
- const slice = closes.slice(i - period + 1, i + 1);
const mean = sma[i];
- const variance = slice.reduce((sum, val) => sum + Math.pow(val - mean, 2), 0) / period;
- const stdDev = Math.sqrt(variance);
- upper.push(mean + 2 * stdDev);
- lower.push(mean - 2 * stdDev);
+ const variance = sumSq / period - mean * mean;
+ const stdDev = Math.sqrt(Math.max(0, variance));
+ upper[i] = mean + 2 * stdDev;
+ lower[i] = mean - 2 * stdDev;
}
}
@@ -70,47 +100,81 @@ export const calculateBollingerBands = (closes: number[], period: number = 20) =
};
/**
- * RSI (Relative Strength Index)
- * @param closes 종가 배열
- * @param period RSI 기간 (기본값: 14)
- * @returns RSI 값 배열
+ * RSI (Relative Strength Index) — O(n) Wilder 스무딩
+ *
+ * RSI = 100 - (100 / (1 + RS))
+ * RS = 평균 상승폭 / 평균 하락폭
+ *
+ * 계산 방식:
+ * 1. 첫 period 구간: 단순 평균으로 avgGain, avgLoss 초기화
+ * 2. 이후: Wilder 스무딩 적용
+ * avgGain = (avgGain * (period-1) + 현재 상승폭) / period
+ * avgLoss = (avgLoss * (period-1) + 현재 하락폭) / period
+ *
+ * @param closes - 종가 배열
+ * @param period - RSI 기간 (기본 14)
+ * @returns RSI 배열 (period 이하 구간은 NaN)
*/
export const calculateRSI = (closes: number[], period: number = 14): number[] => {
- const rsi: number[] = [];
- const gains: number[] = [];
- const losses: number[] = [];
+ const rsi = new Array(closes.length);
- for (let i = 1; i < closes.length; i++) {
+ let avgGain = 0;
+ let avgLoss = 0;
+
+ // 첫 period 구간: 단순 평균
+ for (let i = 1; i <= period; i++) {
const change = closes[i] - closes[i - 1];
- gains.push(change > 0 ? change : 0);
- losses.push(change < 0 ? -change : 0);
+ if (change > 0) avgGain += change;
+ else avgLoss -= change;
}
+ avgGain /= period;
+ avgLoss /= period;
for (let i = 0; i < closes.length; i++) {
- if (i < period) {
- rsi.push(NaN);
- } else {
- const avgGain = gains.slice(i - period, i).reduce((a, b) => a + b, 0) / period;
- const avgLoss = losses.slice(i - period, i).reduce((a, b) => a + b, 0) / period;
- const rs = avgLoss === 0 ? 100 : avgGain / avgLoss;
- rsi.push(100 - (100 / (1 + rs)));
+ if (i <= period) {
+ rsi[i] = NaN;
+ continue;
}
+ // Wilder smoothing
+ const change = closes[i] - closes[i - 1];
+ avgGain = (avgGain * (period - 1) + (change > 0 ? change : 0)) / period;
+ avgLoss = (avgLoss * (period - 1) + (change < 0 ? -change : 0)) / period;
+ const rs = avgLoss === 0 ? 100 : avgGain / avgLoss;
+ rsi[i] = 100 - (100 / (1 + rs));
+ }
+
+ // period 인덱스에 값 설정 (첫 RSI)
+ if (closes.length > period) {
+ const firstAvgGain = (() => { let s = 0; for (let i = 1; i <= period; i++) { const c = closes[i] - closes[i-1]; if (c > 0) s += c; } return s / period; })();
+ const firstAvgLoss = (() => { let s = 0; for (let i = 1; i <= period; i++) { const c = closes[i] - closes[i-1]; if (c < 0) s -= c; } return s / period; })();
+ const rs = firstAvgLoss === 0 ? 100 : firstAvgGain / firstAvgLoss;
+ rsi[period] = 100 - (100 / (1 + rs));
}
return rsi;
};
/**
- * MACD (Moving Average Convergence Divergence)
- * @param closes 종가 배열
- * @returns MACD, Signal, Histogram 배열
+ * MACD (Moving Average Convergence Divergence) — O(n)
+ *
+ * MACD Line = EMA(12) - EMA(26)
+ * Signal Line = EMA(9) of MACD
+ * Histogram = MACD - Signal
+ *
+ * @param closes - 종가 배열
+ * @returns { macd, signal, histogram } 배열
*/
export const calculateMACD = (closes: number[]) => {
const ema12 = calculateEMA(closes, 12);
const ema26 = calculateEMA(closes, 26);
- const macd = ema12.map((val, i) => val - ema26[i]);
+ const macd = new Array(closes.length);
+ for (let i = 0; i < closes.length; i++) {
+ macd[i] = ema12[i] - ema26[i];
+ }
const signal = calculateEMA(macd, 9);
- const histogram = macd.map((val, i) => val - signal[i]);
-
+ const histogram = new Array(closes.length);
+ for (let i = 0; i < closes.length; i++) {
+ histogram[i] = macd[i] - signal[i];
+ }
return { macd, signal, histogram };
};
diff --git a/mcp-server/auto_trade_claude.py b/mcp-server/auto_trade_claude.py
index cc43e4c..7205849 100644
--- a/mcp-server/auto_trade_claude.py
+++ b/mcp-server/auto_trade_claude.py
@@ -1,3 +1,19 @@
+"""Claude AI 응답 기반 자동매매 실행 모듈 (auto_trade_claude.py)
+
+Claude 응답 텍스트에서 종목코드/진입가/손절가/목표가를 정규식으로 추출하고,
+리스크 검증(risk_validator) 통과 후 KIS API를 통해 매수 주문을 실행한다.
+
+주요 흐름:
+ 1. parse_claude_response() — 정규식 파싱
+ 2. get_account_balance() — 계좌 잔고 조회
+ 3. get_stock_info() — 현재가 및 종목명 조회
+ 4. validate_and_log_order() — 종합 리스크 검증 (CLAUDE.md 섹션 5)
+ 5. place_order() — KIS API 지정가 매수 주문
+ 6. save_active_trade() — 체결 정보 JSON 파일 저장
+
+활성 거래 저장: active_trades.json (asyncio.Lock + to_thread로 동시 접근 방지)
+"""
+
import re
import asyncio
import json
@@ -7,27 +23,40 @@ import logging
from datetime import datetime, timezone
from decimal import Decimal
-# Backend imports for risk validation
+# 백엔드 모듈 임포트를 위한 경로 추가
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../backend')))
from app.services.korea_investment_api import korea_investment_api
-from app.core.database import AsyncSessionLocal
-# Risk validator
+# 리스크 검증 모듈
from risk_validator import validate_and_log_order
-# Logging setup
+# 로깅 설정
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logger = logging.getLogger(__name__)
-# Claude 응답에서 종목/가격 추출
-CLAUDE_FORMAT = r"종목[:\s]+(\d+)" # 종목코드
-ENTRY_FORMAT = r"진입가[:\s]+([\d,]+)" # 진입가
+# ── Claude 응답 파싱용 정규식 패턴 ──────────────────────────────────────────────
+CLAUDE_FORMAT = r"종목[:\s]+(\d+)" # 종목코드 (6자리 숫자)
+ENTRY_FORMAT = r"진입가[:\s]+([\d,]+)" # 진입가 (콤마 포함 숫자)
STOP_FORMAT = r"손절가[:\s]+([\d,]+)" # 손절가
TARGET_FORMAT = r"목표가[:\s]+([\d,]+)" # 목표가
+# 활성 거래 정보를 저장하는 JSON 파일 경로
ACTIVE_TRADES_FILE = os.path.join(os.path.dirname(__file__), 'active_trades.json')
+# active_trades.json 동시 접근 방지용 asyncio Lock
+_trades_file_lock = asyncio.Lock()
+
+
def parse_claude_response(text):
+ """Claude 응답 텍스트에서 종목코드, 진입가, 손절가, 목표가를 정규식으로 추출한다.
+
+ Args:
+ text: Claude AI 응답 텍스트
+
+ Returns:
+ dict: {"stock_code", "entry_price", "stop_loss", "take_profit"}
+ 각 값이 없으면 None
+ """
code = re.search(CLAUDE_FORMAT, text)
entry = re.search(ENTRY_FORMAT, text)
stop = re.search(STOP_FORMAT, text)
@@ -39,41 +68,53 @@ def parse_claude_response(text):
'take_profit': int(target.group(1).replace(',', '')) if target else None,
}
-def save_active_trade(trade_info):
- """활성화된 거래를 JSON 파일에 저장합니다."""
- trades = []
- if os.path.exists(ACTIVE_TRADES_FILE):
- with open(ACTIVE_TRADES_FILE, 'r', encoding='utf-8') as f:
- try:
- trades = json.load(f)
- except json.JSONDecodeError:
- print(f"경고: {ACTIVE_TRADES_FILE} 파일이 비어있거나 잘못된 형식입니다. 새 파일을 생성합니다.")
-
- trades.append(trade_info)
-
+
+def _read_trades_sync() -> list:
+ """동기 방식으로 active_trades.json 읽기 (asyncio.to_thread 내부 전용)."""
+ if not os.path.exists(ACTIVE_TRADES_FILE):
+ return []
+ with open(ACTIVE_TRADES_FILE, 'r', encoding='utf-8') as f:
+ try:
+ return json.load(f)
+ except json.JSONDecodeError:
+ logger.warning(f"경고: {ACTIVE_TRADES_FILE} 파일이 비어있거나 잘못된 형식입니다. 새 파일을 생성합니다.")
+ return []
+
+
+def _write_trades_sync(trades: list) -> None:
+ """동기 방식으로 active_trades.json 쓰기 (asyncio.to_thread 내부 전용)."""
with open(ACTIVE_TRADES_FILE, 'w', encoding='utf-8') as f:
json.dump(trades, f, indent=4, ensure_ascii=False)
- print(f"✅ 거래 정보 저장 완료: {trade_info['stock_code']}")
+
+
+async def save_active_trade(trade_info: dict) -> None:
+ """활성화된 거래를 JSON 파일에 저장합니다. (Lock + to_thread로 race condition 방지)"""
+ async with _trades_file_lock:
+ trades = await asyncio.to_thread(_read_trades_sync)
+ trades.append(trade_info)
+ await asyncio.to_thread(_write_trades_sync, trades)
+ logger.info(f"거래 정보 저장 완료: {trade_info['stock_code']}")
+
async def get_account_balance() -> float:
- """Fetch current account balance from KIS API"""
+ """Fetch current account balance from KIS API via public get_balance() method.
+
+ [수정 1] _make_request() 직접 호출 제거 → get_balance() 공개 메서드 사용.
+ get_balance() 응답: output2[0].tot_evalu_mony (총평가금액)
+ output2[0].dnca_tot_amt (예수금총금액) 폴백
+ """
try:
- balance_info, _ = await korea_investment_api._make_request(
- "GET",
- "/uapi/domestic-stock/v1/trading/inquire-account",
- "TTTC8434R",
- params={}
- )
+ balance_info = await korea_investment_api.get_balance()
if balance_info and balance_info.get('rt_cd') == '0':
- output = balance_info.get('output', {})
- # Try multiple possible field names for balance
- balance = float(
- output.get('tot_evalu_amt') or
- output.get('tot_assets') or
- output.get('dnca_tot_amt') or
- 0
- )
- return balance
+ output2 = balance_info.get('output2', [])
+ if output2:
+ summary = output2[0]
+ balance = float(
+ summary.get('tot_evalu_mony') or
+ summary.get('dnca_tot_amt') or
+ 0
+ )
+ return balance
return 0
except Exception as e:
logger.error(f"Failed to fetch account balance: {e}")
@@ -81,14 +122,12 @@ async def get_account_balance() -> float:
async def get_stock_info(stock_code: str) -> tuple:
- """Fetch stock name and current price"""
+ """Fetch stock name and current price via public get_current_price() method.
+
+ [수정 1] _make_request() 직접 호출 제거 → get_current_price() 공개 메서드 사용.
+ """
try:
- price_info, _ = await korea_investment_api._make_request(
- "GET",
- "/uapi/domestic-stock/v1/quotations/inquire-price",
- "FHKST01010100",
- params={"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": stock_code}
- )
+ price_info = await korea_investment_api.get_current_price(stock_code)
if price_info and price_info.get('rt_cd') == '0':
output = price_info.get('output', {})
stock_name = output.get('hts_kor_isnm', 'Unknown')
@@ -184,7 +223,7 @@ async def auto_trade_from_claude(text, quantity=1):
'timestamp': datetime.now(timezone.utc).isoformat(),
'validation_details': validation_details # Store validation context
}
- save_active_trade(trade_details)
+ await save_active_trade(trade_details)
else:
error_message = result.get('msg1', '알 수 없는 오류')
logger.error(f"❌ Order placement failed: {error_message}")
@@ -196,7 +235,6 @@ async def auto_trade_from_claude(text, quantity=1):
if __name__ == "__main__":
# 예시: Claude 응답 텍스트를 받아 자동매매 실행
- import sys
if len(sys.argv) > 1:
text = sys.argv[1]
asyncio.run(auto_trade_from_claude(text))
diff --git a/mcp-server/claude_client.py b/mcp-server/claude_client.py
index 70ee7c3..2fd42f7 100644
--- a/mcp-server/claude_client.py
+++ b/mcp-server/claude_client.py
@@ -1,3 +1,21 @@
+"""Claude AI 클라이언트 모듈 (claude_client.py)
+
+Anthropic Claude API를 사용하여 주식 분석, 리스크 평가, 매매일지 생성 등을 수행.
+
+주요 기능:
+ - analyze(): 범용 Claude 분석 (캐싱 컨텍스트 지원)
+ - validate_trading_rule(): 트레이딩 규칙 검증
+ - analyze_market(): 시장 분석 (추세/심리/추천)
+ - calculate_fair_price(): AI 기반 적정가 산출
+ - assess_risk(): 리스크 평가 (토큰 최소화)
+ - optimize_trading_rules(): 전략 파라미터 최적화
+ - generate_trade_journal(): 매매일지 자동 생성
+
+캐싱 전략:
+ - _CACHED_CONTEXT를 system 프롬프트의 첫 블록으로 전송 (cache_control: ephemeral)
+ - 반복 호출 시 Anthropic 서버 측에서 캐시 히트로 입력 토큰 절약
+"""
+
from anthropic import AsyncAnthropic
from config import settings
from utils import _dumps
@@ -36,7 +54,8 @@ class ClaudeClient:
self,
system_prompt: str,
user_message: str,
- tools: List[Dict[str, Any]] = None
+ tools: List[Dict[str, Any]] = None,
+ max_tokens: int = None,
) -> Dict[str, Any]:
"""Claude를 통한 분석 실행.
@@ -51,7 +70,7 @@ class ClaudeClient:
params = {
"model": self.model,
- "max_tokens": settings.MAX_TOKENS,
+ "max_tokens": max_tokens or settings.MAX_TOKENS,
"temperature": settings.TEMPERATURE,
"system": [
{
@@ -109,6 +128,32 @@ class ClaudeClient:
logger.error(f"Claude analysis error: {e}")
raise
+ def _parse_json_response(self, response: Dict[str, Any], fallback: Dict[str, Any]) -> Dict[str, Any]:
+ """응답 텍스트에서 JSON 파싱 (공통 헬퍼).
+
+ GeminiClient._parse_json_response()와 동일한 로직.
+ 1) 응답 content에서 text 블록을 찾아 JSON 파싱 시도
+ 2) 순수 json.loads 실패 시 텍스트 내 첫 '{' ~ 마지막 '}' 범위를 추출하여 재시도
+ 3) 모두 실패하면 fallback에 analysis 필드를 추가하여 반환
+ """
+ for content in response["content"]:
+ if content["type"] == "text":
+ text = content["text"]
+ try:
+ return json.loads(text)
+ except json.JSONDecodeError:
+ pass
+ # JSON이 마크다운 코드블록 등으로 감싸진 경우 추출 시도
+ try:
+ json_start = text.find('{')
+ json_end = text.rfind('}') + 1
+ if json_start != -1 and json_end > json_start:
+ return json.loads(text[json_start:json_end])
+ except (json.JSONDecodeError, Exception):
+ pass
+ return {**fallback, "analysis": content["text"]}
+ return fallback
+
async def validate_trading_rule(
self,
rule: Dict[str, Any],
@@ -124,28 +169,12 @@ class ClaudeClient:
if news_data:
user_message += f"\n뉴스:{_dumps(news_data)}"
-
+
response = await self.analyze(system_prompt, user_message)
-
- # 텍스트 응답 파싱
- for content in response["content"]:
- if content["type"] == "text":
- try:
- # JSON 응답 파싱 시도
- return json.loads(content["text"])
- except json.JSONDecodeError:
- # JSON이 아닌 경우 기본 구조로 반환
- return {
- "decision": "HOLD",
- "confidence": 0.5,
- "analysis": content["text"]
- }
-
- return {
- "decision": "HOLD",
- "confidence": 0.0,
- "analysis": "분석 실패"
- }
+ return self._parse_json_response(
+ response,
+ {"decision": "HOLD", "confidence": 0.0, "analysis": "분석 실패"}
+ )
async def analyze_market(
self,
@@ -167,26 +196,10 @@ class ClaudeClient:
user_message = f"종목:{stock_code}\n시장:{_dumps(market_data)}{news_text}"
response = await self.analyze(system_prompt, user_message)
-
- for content in response["content"]:
- if content["type"] == "text":
- try:
- return json.loads(content["text"])
- except json.JSONDecodeError:
- return {
- "trend": "SIDEWAYS",
- "sentiment": "NEUTRAL",
- "recommendation": "HOLD",
- "confidence": 0.5,
- "analysis": content["text"]
- }
-
- return {
- "trend": "UNKNOWN",
- "sentiment": "NEUTRAL",
- "recommendation": "HOLD",
- "confidence": 0.0
- }
+ return self._parse_json_response(
+ response,
+ {"trend": "UNKNOWN", "sentiment": "NEUTRAL", "recommendation": "HOLD", "confidence": 0.0}
+ )
async def calculate_fair_price(
self,
@@ -201,51 +214,28 @@ class ClaudeClient:
user_message = f"종목:{stock_code} 현재가:{market_data.get('current_price')} 고가:{market_data.get('high_price')} 저가:{market_data.get('low_price')} 거래량:{market_data.get('volume')} 지표:{_dumps(market_data.get('indicators', {}))}"
response = await self.analyze(system_prompt, user_message)
-
- for content in response["content"]:
- if content["type"] == "text":
- try:
- return json.loads(content["text"])
- except json.JSONDecodeError:
- return {
- "buy_prices": {"neutral": market_data.get('current_price', 0)},
- "sell_prices": {"target1": market_data.get('current_price', 0) * 1.05},
- "stop_loss": market_data.get('current_price', 0) * 0.97,
- "strategy": content["text"],
- "confidence": 0.5
- }
-
- return {
- "error": "분석 실패",
- "confidence": 0.0
- }
+ return self._parse_json_response(
+ response,
+ {"error": "분석 실패", "confidence": 0.0}
+ )
async def assess_risk(
self,
portfolio: Dict[str, Any],
trade_plan: Dict[str, Any]
) -> Dict[str, Any]:
- """리스크 평가"""
- system_prompt = """투자 리스크 관리 전문가. JSON으로 응답.
-필수 필드: risk_level(LOW/MEDIUM/HIGH/CRITICAL), risk_factors, approval(APPROVED/REJECTED), recommendation."""
+ """리스크 평가 (토큰 최소화 — max_tokens=RISK_MAX_TOKENS)"""
+ system_prompt = """리스크 평가. JSON만 출력.
+필수: risk_level(LOW/MEDIUM/HIGH), approval(APPROVED/REJECTED), reason(한줄)."""
- user_message = f"포트폴리오:{_dumps(portfolio)}\n거래계획:{_dumps(trade_plan)}"
-
- response = await self.analyze(system_prompt, user_message)
-
- for content in response["content"]:
- if content["type"] == "text":
- try:
- return json.loads(content["text"])
- except json.JSONDecodeError:
- return {
- "risk_level": "MEDIUM",
- "approval": "HOLD",
- "confidence": 0.5,
- "analysis": content["text"]
- }
-
- return {"error": "Failed to assess risk"}
+ slim_portfolio = {k: portfolio[k] for k in ("strategy", "position_count", "mdd") if k in portfolio}
+ user_message = f"포트:{_dumps(slim_portfolio)} 계획:{_dumps(trade_plan)}"
+
+ response = await self.analyze(system_prompt, user_message, max_tokens=settings.RISK_MAX_TOKENS)
+ return self._parse_json_response(
+ response,
+ {"error": "Failed to assess risk"}
+ )
async def optimize_trading_rules(
self,
@@ -264,20 +254,10 @@ class ClaudeClient:
user_message += f"\n뉴스:{_dumps(news_data)}"
response = await self.analyze(system_prompt, user_message)
-
- # 텍스트 응답 파싱
- for content in response["content"]:
- if content["type"] == "text":
- try:
- text = content["text"]
- json_start = text.find('{')
- json_end = text.rfind('}') + 1
- if json_start != -1 and json_end != -1:
- return json.loads(text[json_start:json_end])
- except Exception as e:
- logger.error(f"Failed to parse optimization result: {e}")
-
- return {"error": "Failed to generate optimized rules"}
+ return self._parse_json_response(
+ response,
+ {"error": "Failed to generate optimized rules"}
+ )
async def generate_trade_journal(
self,
@@ -292,19 +272,10 @@ class ClaudeClient:
user_message = f"거래:{_dumps(trade_info)}\n시장:{_dumps(market_data)}"
response = await self.analyze(system_prompt, user_message)
-
- for content in response["content"]:
- if content["type"] == "text":
- try:
- text = content["text"]
- json_start = text.find('{')
- json_end = text.rfind('}') + 1
- if json_start != -1 and json_end != -1:
- return json.loads(text[json_start:json_end])
- except Exception as e:
- logger.error(f"Failed to parse journal result: {e}")
-
- return {"error": "Failed to generate journal"}
+ return self._parse_json_response(
+ response,
+ {"error": "Failed to generate journal"}
+ )
claude_client = ClaudeClient()
diff --git a/mcp-server/config.py b/mcp-server/config.py
index 1bceed8..fc6faec 100644
--- a/mcp-server/config.py
+++ b/mcp-server/config.py
@@ -1,10 +1,25 @@
+"""MCP 서버 설정 모듈 (config.py)
+
+환경변수 기반 설정을 관리하는 Settings 클래스.
+모듈 하단에서 settings = Settings() 싱글톤 인스턴스를 생성한다.
+
+주의: 이 모듈은 백엔드의 app.core.config.settings와 별도 인스턴스이다.
+ MCP 서버 전용 설정(MCP_SERVER_HOST, MCP_API_KEY 등)을 관리한다.
+"""
+
import os
from dotenv import load_dotenv
-load_dotenv(override=True) # 컨테이너 빈 env var보다 .env 파일 우선
+# Docker 환경변수 우선, .env 파일은 폴백으로 사용
+load_dotenv(override=False)
class Settings:
+ """MCP 서버 전역 설정.
+
+ AI_PROVIDER에 따라 MAX_TOKENS, TEMPERATURE를 동적으로 설정한다.
+ 클래스 변수는 import 시점에 평가되고, __init__에서 인스턴스 속성으로 재설정된다.
+ """
# API Keys
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY", "")
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "")
@@ -16,6 +31,9 @@ class Settings:
MCP_SERVER_HOST = os.getenv("MCP_SERVER_HOST", "0.0.0.0")
MCP_SERVER_PORT = int(os.getenv("MCP_SERVER_PORT", "8001"))
+ # MCP API Key Authentication (backend -> MCP 서버 인증)
+ MCP_API_KEY = os.getenv("MCP_API_KEY", "")
+
# Database
DATABASE_URL = os.getenv("DATABASE_URL", "")
REDIS_URL = os.getenv("REDIS_URL", "")
@@ -29,21 +47,30 @@ class Settings:
# Gemini Settings
GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-2.0-flash")
- # Common AI Settings (AI_PROVIDER에 따라 자동 선택)
- MAX_TOKENS = int(os.getenv(
- "GEMINI_MAX_TOKENS" if AI_PROVIDER == "gemini" else "CLAUDE_MAX_TOKENS",
- "1024"
- ))
- TEMPERATURE = float(os.getenv(
- "GEMINI_TEMPERATURE" if AI_PROVIDER == "gemini" else "CLAUDE_TEMPERATURE",
- "0.3"
- ))
+ # Common AI Settings — __init__에서 AI_PROVIDER 값을 읽어 동적으로 설정한다.
+ # [수정 2] 클래스 변수 평가 시점 문제: AI_PROVIDER가 클래스 변수로 먼저 정의되어 있어도
+ # 아래 두 줄은 클래스 정의 시점(import 시)에 한 번만 평가되므로, 환경변수가 변경돼도
+ # 올바른 분기가 보장되지 않는다. __init__에서 재설정한다.
+ MAX_TOKENS: int = 1024 # 임시 기본값 — __init__에서 덮어씀
+ TEMPERATURE: float = 0.3 # 임시 기본값 — __init__에서 덮어씀
- # Token Optimization Settings
- TOKEN_SAVE_MODE = os.getenv("TOKEN_SAVE_MODE", "false").lower() == "true"
- NEWS_LIMIT = int(os.getenv("NEWS_LIMIT", "5"))
- CHART_DAYS = int(os.getenv("CHART_DAYS", "100"))
- JSON_COMPACT = os.getenv("JSON_COMPACT", "false").lower() == "true"
+ def __init__(self):
+ # AI_PROVIDER를 인스턴스 속성으로 다시 읽어 올바른 env 키를 선택한다.
+ self.AI_PROVIDER = os.getenv("AI_PROVIDER", "gemini")
+ if self.AI_PROVIDER == "gemini":
+ self.MAX_TOKENS = int(os.getenv("GEMINI_MAX_TOKENS", "1024"))
+ self.TEMPERATURE = float(os.getenv("GEMINI_TEMPERATURE", "0.3"))
+ else:
+ self.MAX_TOKENS = int(os.getenv("CLAUDE_MAX_TOKENS", "1024"))
+ self.TEMPERATURE = float(os.getenv("CLAUDE_TEMPERATURE", "0.3"))
+
+ # Token Optimization Settings (기본값을 절약 모드로 설정)
+ TOKEN_SAVE_MODE = os.getenv("TOKEN_SAVE_MODE", "true").lower() == "true"
+ NEWS_LIMIT = int(os.getenv("NEWS_LIMIT", "3"))
+ CHART_DAYS = int(os.getenv("CHART_DAYS", "30"))
+ JSON_COMPACT = os.getenv("JSON_COMPACT", "true").lower() == "true"
+ # RISK_ASSESSMENT 전용 max_tokens (단순 approve/reject — 256 충분)
+ RISK_MAX_TOKENS = int(os.getenv("RISK_MAX_TOKENS", "256"))
# CORS (이슈 5)
# 서버-서버 통신용: 브라우저 credentials 불필요.
diff --git a/mcp-server/gemini_client.py b/mcp-server/gemini_client.py
index 399ecc7..ad46506 100644
--- a/mcp-server/gemini_client.py
+++ b/mcp-server/gemini_client.py
@@ -1,3 +1,21 @@
+"""Gemini AI 클라이언트 모듈 (gemini_client.py)
+
+Google Gemini API를 사용하여 주식 분석, 리스크 평가, 매매일지 생성 등을 수행.
+Claude 클라이언트와 동일한 인터페이스를 제공하여 AI_PROVIDER 설정으로 전환 가능.
+
+주요 기능:
+ - analyze(): 범용 Gemini 분석
+ - validate_trading_rule(): 트레이딩 규칙 검증
+ - analyze_market(): 시장 분석
+ - calculate_fair_price(): 적정가 산출
+ - assess_risk(): 리스크 평가
+ - optimize_trading_rules(): 전략 최적화
+ - generate_trade_journal(): 매매일지 생성
+
+공통 헬퍼:
+ - _parse_json_response(): AI 응답에서 JSON 추출 (Claude 클라이언트에도 동일 로직 존재)
+"""
+
from google import genai
from google.genai import types
from config import settings
@@ -30,15 +48,14 @@ class GeminiClient:
self,
system_prompt: str,
user_message: str,
- tools: List[Dict[str, Any]] = None
+ tools: List[Dict[str, Any]] = None,
+ max_tokens: int = None,
) -> Dict[str, Any]:
"""Gemini를 통한 분석 실행"""
try:
- # 최신 SDK에서는 별도의 모델 객체 생성 없이 client.models.generate_content를 사용합니다.
- # system_instruction을 config에 포함시켜 보냅니다.
config_with_system = types.GenerateContentConfig(
system_instruction=system_prompt,
- max_output_tokens=self.config.max_output_tokens,
+ max_output_tokens=max_tokens or self.config.max_output_tokens,
temperature=self.config.temperature,
)
@@ -149,13 +166,14 @@ class GeminiClient:
portfolio: Dict[str, Any],
trade_plan: Dict[str, Any]
) -> Dict[str, Any]:
- """리스크 평가"""
- system_prompt = """투자 리스크 관리 전문가. JSON으로만 응답.
-필수 필드: risk_level(LOW/MEDIUM/HIGH/CRITICAL), risk_factors, approval(APPROVED/REJECTED), recommendation. JSON 외 텍스트 금지."""
+ """리스크 평가 (토큰 최소화)"""
+ system_prompt = """리스크 평가. JSON만 출력.
+필수: risk_level(LOW/MEDIUM/HIGH), approval(APPROVED/REJECTED), reason(한줄). JSON 외 금지."""
- user_message = f"포트폴리오:{_dumps(portfolio)}\n거래계획:{_dumps(trade_plan)}"
+ slim_portfolio = {k: portfolio[k] for k in ("strategy", "position_count", "mdd") if k in portfolio}
+ user_message = f"포트:{_dumps(slim_portfolio)} 계획:{_dumps(trade_plan)}"
- response = await self.analyze(system_prompt, user_message)
+ response = await self.analyze(system_prompt, user_message, max_tokens=settings.RISK_MAX_TOKENS)
return self._parse_json_response(
response,
{"error": "Failed to assess risk"}
diff --git a/mcp-server/main.py b/mcp-server/main.py
index 0ba1091..b1bf35e 100644
--- a/mcp-server/main.py
+++ b/mcp-server/main.py
@@ -1,8 +1,31 @@
-from fastapi import FastAPI, HTTPException
+"""MCP 서버 메인 모듈 (main.py)
+
+Model Context Protocol(MCP) 서버 — AI 기반 주식 매매를 위한 REST API 제공.
+백엔드(FastAPI)에서 이 서버를 호출하여 AI 분석 및 도구 실행을 요청한다.
+
+엔드포인트:
+ GET / — 서버 상태 확인
+ GET /health — 헬스 체크 (AI 프로바이더 설정 확인)
+ GET /tools — 사용 가능한 MCP 도구 목록
+ POST /tools/call — MCP 도구 호출 (시장 데이터, 지표 계산, 뉴스 조회 등)
+ POST /analyze — AI 분석 실행 (규칙 검증, 시장 분석, 리스크 평가 등)
+
+보안:
+ - MCP_API_KEY가 설정된 경우 X-API-Key 헤더 검증 (constant-time 비교)
+ - CORS: MCP_CORS_ORIGINS로 origin 제한
+
+AI 프로바이더:
+ - AI_PROVIDER=gemini 이면 GeminiClient, 아니면 ClaudeClient 사용
+"""
+
+from fastapi import FastAPI, HTTPException, Request
from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
from pydantic import BaseModel
from typing import Dict, Any, List
+import hmac
import logging
+import os
from config import settings
from claude_client import claude_client
@@ -44,10 +67,33 @@ app.add_middleware(
allow_origins=_allowed_origins,
allow_credentials=False, # 서버-서버 통신; 브라우저 세션 쿠키 불필요
allow_methods=["GET", "POST"],
- allow_headers=["Content-Type", "Authorization"],
+ allow_headers=["Content-Type", "Authorization", "X-API-Key"],
)
+# ─── API Key 인증 미들웨어 ──────────────────────────────────────────────
+# MCP_API_KEY가 설정되어 있으면 모든 요청에 X-API-Key 헤더 검증 (health/root 제외)
+_MCP_API_KEY = settings.MCP_API_KEY
+_PUBLIC_PATHS = {"/", "/health"}
+
+
+@app.middleware("http")
+async def verify_api_key(request: Request, call_next):
+ """X-API-Key 헤더를 constant-time 비교로 검증.
+
+ MCP_API_KEY가 빈 문자열이면 인증을 비활성화 (개발 환경 호환).
+ """
+ if _MCP_API_KEY and request.url.path not in _PUBLIC_PATHS:
+ api_key = request.headers.get("X-API-Key", "")
+ if not api_key or not hmac.compare_digest(api_key.encode(), _MCP_API_KEY.encode()):
+ logger.warning(f"[MCP Security] API 키 검증 실패 — path={request.url.path}")
+ return JSONResponse(
+ status_code=401,
+ content={"detail": "유효한 X-API-Key 헤더가 필요합니다."},
+ )
+ return await call_next(request)
+
+
class ToolCallRequest(BaseModel):
tool_name: str
parameters: Dict[str, Any]
@@ -112,6 +158,12 @@ async def analyze(request: AnalysisRequest):
detail="rule and market_data are required"
)
stock_code = market_data.get("stock_code")
+ # TOKEN_SAVE_MODE: OHLCV 배열 제거, 핵심 지표만 유지
+ if settings.TOKEN_SAVE_MODE:
+ _keep = {"stock_code", "current_price", "change_rate", "volume",
+ "rsi", "atr", "adx", "bollinger_upper", "bollinger_lower",
+ "bollinger_middle", "ma5", "ma20", "ma60", "signals", "score"}
+ market_data = {k: v for k, v in market_data.items() if k in _keep}
news_data = []
if stock_code:
try:
@@ -132,6 +184,12 @@ async def analyze(request: AnalysisRequest):
status_code=400,
detail="stock_code and market_data are required"
)
+ # TOKEN_SAVE_MODE: OHLCV 배열 제거
+ if settings.TOKEN_SAVE_MODE and isinstance(market_data, dict):
+ market_data = {k: v for k, v in market_data.items() if k != "data"}
+ # 뉴스 제목만 유지
+ if settings.TOKEN_SAVE_MODE and news:
+ news = [{"title": n.get("title", "")} for n in news[:settings.NEWS_LIMIT]]
result = await ai_client.analyze_market(stock_code, market_data, news)
return {"analysis_type": analysis_type, "result": result}
@@ -145,6 +203,9 @@ async def analyze(request: AnalysisRequest):
status_code=400,
detail="trade_plan is required"
)
+ # signals를 trade_plan에 병합하여 AI에 전달
+ if signals:
+ trade_plan["signals"] = signals
result = await ai_client.assess_risk(portfolio, trade_plan)
return {"analysis_type": analysis_type, "result": result}
@@ -206,9 +267,12 @@ async def analyze(request: AnalysisRequest):
if __name__ == "__main__":
import uvicorn
+ # [수정 5] reload=True는 운영 환경에서 성능 저하 및 다중 프로세스 부작용을 유발한다.
+ # 개발 환경에서는 MCP_DEV_RELOAD=true 환경변수로 활성화할 수 있다.
+ _dev_reload = os.getenv("MCP_DEV_RELOAD", "false").lower() == "true"
uvicorn.run(
"main:app",
host=settings.MCP_SERVER_HOST,
port=settings.MCP_SERVER_PORT,
- reload=True
+ reload=_dev_reload,
)
diff --git a/mcp-server/mcp_tools.py b/mcp-server/mcp_tools.py
index c5db1cc..a58c5bd 100644
--- a/mcp-server/mcp_tools.py
+++ b/mcp-server/mcp_tools.py
@@ -1,3 +1,22 @@
+"""MCP 도구 레지스트리 모듈 (mcp_tools.py)
+
+MCP 서버가 제공하는 도구(Tool)들을 등록하고 실행하는 모듈.
+Claude/Gemini AI가 function calling으로 이 도구들을 호출할 수 있다.
+
+등록된 도구:
+ - get_market_data: 국내/해외 주식 시장 데이터 조회 (KIS API)
+ - calculate_indicators: 기술적 지표 계산 (RSI, MACD, BB, SMA, EMA)
+ - check_portfolio: 포트폴리오 보유 현황 조회
+ - validate_rules: 트레이딩 규칙 검증 (RSI 조건 등)
+ - execute_order: 주문 실행 (차단됨 - 백엔드 API 경유 필수)
+ - get_news: 네이버 금융 뉴스 크롤링
+
+아키텍처 주의사항:
+ - korea_investment_api는 None (MCP 서버에서 KIS API 직접 호출 불가)
+ - execute_order()는 리스크 검증 우회 방지를 위해 항상 차단 응답 반환
+ - 주문은 반드시 백엔드 /api/trades 엔드포인트를 통해 실행해야 함
+"""
+
from typing import Dict, Any, Callable
import logging
import pandas as pd
@@ -9,11 +28,25 @@ import httpx
from bs4 import BeautifulSoup
from config import settings
-# Optional: KIS API dependency (not currently available in MCP server directly)
+# KIS API 인스턴스 — MCP 서버에서는 직접 사용 불가 (None)
+# 주문은 백엔드 API를 통해서만 실행해야 한다 (리스크 검증 파이프라인 우회 방지)
korea_investment_api = None
logger = logging.getLogger(__name__)
+# Major US stock exchange mapping
+_EXCHANGE_MAP = {
+ # NYSE stocks
+ "JPM": "NYSE", "V": "NYSE", "JNJ": "NYSE", "WMT": "NYSE", "PG": "NYSE",
+ "UNH": "NYSE", "HD": "NYSE", "BAC": "NYSE", "XOM": "NYSE", "CVX": "NYSE",
+ "KO": "NYSE", "DIS": "NYSE", "MCD": "NYSE", "NKE": "NYSE", "BA": "NYSE",
+ # AMEX (mostly ETFs)
+ "SPY": "AMEX", "QQQ": "AMEX", "IWM": "AMEX", "XLF": "AMEX",
+}
+
+def _detect_exchange(ticker: str) -> str:
+ return _EXCHANGE_MAP.get(ticker.upper(), "NAS") # Default to NAS
+
class MCPTools:
"""MCP Tools Registry"""
@@ -22,8 +55,6 @@ class MCPTools:
def __init__(self):
self.tools: Dict[str, Callable] = {}
self._register_tools()
- # Initialize KIS API if available
- self.korea_investment_api = None
def _register_tools(self):
"""도구 등록"""
@@ -201,9 +232,8 @@ class MCPTools:
"data": formatted_data
}
else:
- # 해외 주식 logic (기본 NASD 가정)
- exchange = "NASD"
- # TODO: 거래소 판별 로직 고도화 필요 (현재는 NASD 고정)
+ # 해외 주식 logic (거래소 자동 판별)
+ exchange = _detect_exchange(stock_code)
current_price_data = await korea_investment_api.get_overseas_price(stock_code, exchange)
chart_data = await korea_investment_api.get_overseas_daily_chart(stock_code, exchange, period)
@@ -364,38 +394,28 @@ class MCPTools:
quantity: int,
price: float = None
) -> Dict[str, Any]:
- """주문 실행 (실제로는 backend API 호출)"""
- if not korea_investment_api:
- return {"error": "Korea Investment API not available"}
+ """주문 실행.
- try:
- # 국내/해외 구분
- is_domestic = stock_code.isdigit() and len(stock_code) == 6
-
- if is_domestic:
- result = await korea_investment_api.place_order(
- stock_code=stock_code,
- order_type=order_type,
- quantity=quantity,
- price=int(price) if price else None
- )
- else:
- # 해외 주문 (지정가 필수)
- if price is None:
- return {"error": "Overseas orders require a limit price."}
-
- result = await korea_investment_api.place_overseas_order(
- symbol=stock_code,
- order_type=order_type,
- quantity=quantity,
- price=price,
- exchange_code="NASD" # 기본값
- )
-
- return result
- except Exception as e:
- logger.error(f"Failed to place order: {e}")
- raise
+ [수정 3] MCP 서버에서 KIS API를 직접 호출하는 것은 리스크 검증 파이프라인을 우회하므로
+ 허용하지 않는다. 주문은 반드시 백엔드 API(/api/trades)를 통해 실행해야 한다.
+
+ MCP 서버 내부에서 korea_investment_api 인스턴스가 None인지 여부와 무관하게
+ 이 함수는 항상 에러를 반환한다. 실제 주문은 auto_trade_claude.py의
+ auto_trade_from_claude() 함수(리스크 검증 포함)를 사용하거나
+ 백엔드 /api/trades 엔드포인트를 호출해야 한다.
+ """
+ logger.warning(
+ "[execute_order] MCP 서버에서 직접 주문 호출 차단 — "
+ "백엔드 /api/trades 엔드포인트를 통해 주문하십시오. "
+ f"요청 정보: stock_code={stock_code}, order_type={order_type}, qty={quantity}, price={price}"
+ )
+ return {
+ "error": (
+ "MCP 서버에서 KIS API 직접 주문은 리스크 검증 우회 위험으로 차단되었습니다. "
+ "백엔드 API(/api/trades)를 통해 주문하십시오."
+ ),
+ "blocked": True,
+ }
async def get_news(self, stock_code: str = None, limit: int = 5) -> Dict[str, Any]:
"""네이버 금융 뉴스 크롤링"""
@@ -424,7 +444,9 @@ class MCPTools:
continue
title = title_tag.get_text(strip=True)
- link = "https://finance.naver.com" + title_tag['href']
+ # [수정 6] href 속성이 없는 경우 KeyError 방지
+ href = title_tag.get('href', '')
+ link = ("https://finance.naver.com" + href) if href else ''
date_tag = row.select_one('.date')
date = date_tag.get_text(strip=True) if date_tag else ""
source_tag = row.select_one('.info')
diff --git a/mcp-server/risk_validator.py b/mcp-server/risk_validator.py
index f65d1cf..ef5c11a 100644
--- a/mcp-server/risk_validator.py
+++ b/mcp-server/risk_validator.py
@@ -1,16 +1,22 @@
-"""
-🔒 Risk Validation Module for Auto Trading (MCP Server)
+"""리스크 검증 모듈 (risk_validator.py) — MCP 서버용
-This module validates all trades BEFORE execution against CLAUDE.md Section 5 risk rules:
-- Position sizing: max 3-4% per stock, max 20-25 holdings
-- Price filter: > 5,000 KRW (domestic)
-- MDD state check: -10% pauses new entries, -20% forces reduction
-- Leverage ETF limit: max 20% of capital
+모든 매매 주문을 실행 전에 CLAUDE.md 섹션 5 리스크 규칙으로 검증한다.
-CLAUDE.md Compliance:
-- All DB reads use AsyncSessionLocal from backend
-- No breaking changes to existing function signatures
-- All rejections are logged with clear reasons
+검증 항목:
+ 1. 가격 필터: 국내 5,000원 초과 (ETF/리츠 예외)
+ 2. 포지션 사이징: 종목당 총자본 4% 이내
+ 3. 최대 보유 종목: 20개 이내
+ 4. MDD 상태: -10% 신규 진입 중단, -20% 강제 축소
+ 5. 레버리지 ETF 한도: 총자본 20% 이내
+
+아키텍처:
+ - DB 읽기: AsyncSessionLocal 직접 사용 (SELECT only)
+ - DB 쓰기: 없음 (검증만 수행)
+ - 싱글톤: risk_validator 인스턴스, asyncio.Lock으로 동시성 보호
+ - 공개 API: validate_and_log_order() — 종합 검증 + 로깅
+
+[주의] 이 모듈은 자체 DB 엔진을 생성한다 (백엔드 database.py와 별도).
+ MCP 서버가 백엔드와 다른 프로세스에서 실행되기 때문.
"""
import asyncio
@@ -39,8 +45,8 @@ engine = create_async_engine(settings.DATABASE_URL, echo=False)
AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
# Risk limits from CLAUDE.md Section 5
-MAX_POSITION_SIZE_PCT = 0.04 # 3-4% per stock (using 4% as upper bound)
-MAX_HOLDINGS_COUNT = 25 # max 20-25 holdings
+MAX_POSITION_SIZE_PCT = settings.MAX_POSITION_SIZE # config.py와 동기화 (백테스트 검증 완료: 0.06)
+MAX_HOLDINGS_COUNT = 20 # CLAUDE.md 5.1: max 20 holdings
MIN_DOMESTIC_PRICE = 5000 # KRW
MAX_LEVERAGE_ETF_PCT = 0.20 # max 20% of capital for leverage/inverse ETF
@@ -68,7 +74,11 @@ class RiskValidator:
self._lock = asyncio.Lock()
async def _get_session(self) -> AsyncSession:
- """Get or create DB session"""
+ """Get or create DB session.
+
+ DEPRECATED: 새 코드에서는 _session_ctx()를 사용하세요.
+ 기존 시그니처 유지를 위해 남겨두되, 내부적으로 새 세션을 생성합니다.
+ """
if self.db_session is None:
self.db_session = AsyncSessionLocal()
return self.db_session
@@ -76,9 +86,21 @@ class RiskValidator:
async def _close_session(self):
"""Close DB session"""
if self.db_session is not None:
- await self.db_session.close()
+ try:
+ await self.db_session.close()
+ except Exception:
+ pass
self.db_session = None
+ def _session_ctx(self):
+ """컨텍스트 매니저로 세션을 안전하게 관리.
+
+ 사용법:
+ async with self._session_ctx() as session:
+ result = await session.execute(...)
+ """
+ return AsyncSessionLocal()
+
async def validate_price_filter(self, stock_code: str, market: str = "KRX") -> RiskValidationResult:
"""
Check price filter: min 5,000 KRW for domestic stocks
@@ -96,22 +118,17 @@ class RiskValidator:
logger.info(f"[{stock_code}] Price filter skipped (overseas market: {market})")
return RiskValidationResult(allowed=True)
- # Get current price from KIS API
- price_info, _ = await korea_investment_api._make_request(
- "GET",
- "/uapi/domestic-stock/v1/quotations/inquire-price",
- "FHKST01010100",
- params={"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": stock_code}
- )
+ # Get current price from KIS API (공개 메서드 사용)
+ # get_current_price()는 dict를 반환: {"output": {"stck_prpr": "50000", ...}}
+ price_info = await korea_investment_api.get_current_price(stock_code)
+ current_price = int(price_info.get('output', {}).get('stck_prpr', 0))
- if not price_info or price_info.get('rt_cd') != '0':
+ if not current_price or current_price <= 0:
return RiskValidationResult(
allowed=False,
reason=f"Failed to fetch current price for {stock_code}"
)
- current_price = int(price_info.get('output', {}).get('stck_prpr', 0))
-
if current_price < MIN_DOMESTIC_PRICE:
return RiskValidationResult(
allowed=False,
@@ -179,27 +196,26 @@ class RiskValidator:
RiskValidationResult
"""
try:
- db = await self._get_session()
-
- # Count active holdings (quantity > 0)
- result = await db.execute(
- select(Portfolio).where(Portfolio.quantity > 0)
- )
- active_holdings = result.scalars().all()
- holdings_count = len(active_holdings)
-
- if holdings_count >= MAX_HOLDINGS_COUNT:
- return RiskValidationResult(
- allowed=False,
- reason=f"Max holdings limit reached: {holdings_count} >= {MAX_HOLDINGS_COUNT}",
- details={"current_holdings": holdings_count, "max_allowed": MAX_HOLDINGS_COUNT}
+ async with self._session_ctx() as db:
+ # Count active holdings (quantity > 0)
+ result = await db.execute(
+ select(Portfolio).where(Portfolio.quantity > 0)
)
+ active_holdings = result.scalars().all()
+ holdings_count = len(active_holdings)
- logger.info(f"Max holdings check passed: {holdings_count}/{MAX_HOLDINGS_COUNT}")
- return RiskValidationResult(
- allowed=True,
- details={"current_holdings": holdings_count, "available_slots": MAX_HOLDINGS_COUNT - holdings_count}
- )
+ if holdings_count >= MAX_HOLDINGS_COUNT:
+ return RiskValidationResult(
+ allowed=False,
+ reason=f"Max holdings limit reached: {holdings_count} >= {MAX_HOLDINGS_COUNT}",
+ details={"current_holdings": holdings_count, "max_allowed": MAX_HOLDINGS_COUNT}
+ )
+
+ logger.info(f"Max holdings check passed: {holdings_count}/{MAX_HOLDINGS_COUNT}")
+ return RiskValidationResult(
+ allowed=True,
+ details={"current_holdings": holdings_count, "available_slots": MAX_HOLDINGS_COUNT - holdings_count}
+ )
except Exception as e:
logger.error(f"Max holdings check error: {e}")
@@ -274,9 +290,9 @@ class RiskValidator:
return RiskValidationResult(allowed=True)
# Calculate total leverage ETF position
- db = await self._get_session()
- result = await db.execute(select(Portfolio))
- all_holdings = result.scalars().all()
+ async with self._session_ctx() as db:
+ result = await db.execute(select(Portfolio))
+ all_holdings = result.scalars().all()
leverage_etf_value = 0
for holding in all_holdings:
+
+ )
+}
+
+export default Login
diff --git a/frontend/src/types/trading.ts b/frontend/src/types/trading.ts
index 3c222c7..fdb1b6d 100644
--- a/frontend/src/types/trading.ts
+++ b/frontend/src/types/trading.ts
@@ -1,8 +1,27 @@
/**
- * Shared type definitions for trading application
+ * trading.ts — 트레이딩 애플리케이션 공유 타입 정의
+ *
+ * 역할:
+ * - 프론트엔드 전체에서 사용되는 TypeScript 인터페이스 정의
+ * - 백엔드 API 응답 구조와 1:1 매핑
+ *
+ * 타입 카테고리:
+ * - 시장 데이터: CandleData, MarketData
+ * - 포트폴리오: Position, PortfolioSummary, PortfolioCombined
+ * - 매매: Trade, TradeHistory
+ * - 추천: RecommendedStock, Recommendation, RecommendationsData
+ * - 매매일지: Journal
+ * - 호가: Orderbook, OrderbookLevel
+ * - 차트: ProcessedChartData
+ * - WebSocket: MarketUpdateMessage, ChartDataMessage, WebSocketMessage
+ * - AI 분석: AiAnalysisResult
*/
-// Market Data Types
+// ──────────────────────────────────────────────────
+// 시장 데이터 타입 (Market Data Types)
+// ──────────────────────────────────────────────────
+
+/** 캔들 차트 데이터 (OHLCV) — 일/주/월봉 공통 */
export interface CandleData {
date: string | Date;
open: number;
@@ -12,6 +31,7 @@ export interface CandleData {
volume: number;
}
+/** 시장 데이터 — AI 분석 API 응답 구조 */
export interface MarketData {
stock_code: string;
stock_name: string;
@@ -34,7 +54,11 @@ export interface MarketData {
ai_analysis?: string;
}
-// Portfolio Types
+// ──────────────────────────────────────────────────
+// 포트폴리오 타입 (Portfolio Types)
+// ──────────────────────────────────────────────────
+
+/** 보유 종목 포지션 — /portfolio/combined API의 holdings 항목 */
export interface Position {
stock_code: string;
stock_name: string;
@@ -42,9 +66,21 @@ export interface Position {
average_price: number;
current_price: number;
profit_loss_rate: number;
- [key: string]: string | number;
+ market?: string;
+ exchange_code?: string;
+ currency_code?: string;
+ strategy_type?: string;
+ [key: string]: string | number | undefined;
}
+/** 환율 정보 (미국 주식 원화 환산용) */
+export interface ExchangeRate {
+ currency_pair: string; // "USD/KRW"
+ rate: number;
+ recorded_at: string;
+}
+
+/** 포트폴리오 요약 — /portfolio/combined API의 summary */
export interface PortfolioSummary {
total_assets: number;
bfdy_total_assets: number;
@@ -55,6 +91,11 @@ export interface PortfolioSummary {
total_investment?: number;
total_profit_loss?: number;
total_profit_loss_rate?: number;
+ available_cash?: number;
+ cumulative_realized_pl?: number;
+ overseas_value_usd?: number;
+ overseas_value_krw?: number;
+ exchange_rate?: number;
[key: string]: string | number | undefined;
}
@@ -63,7 +104,11 @@ export interface PortfolioCombined {
summary: PortfolioSummary;
}
-// Trade Types
+// ──────────────────────────────────────────────────
+// 매매 타입 (Trade Types)
+// ──────────────────────────────────────────────────
+
+/** 매매 기본 구조 */
export interface Trade {
id: number;
stock_code: string;
@@ -75,11 +120,16 @@ export interface Trade {
[key: string]: string | number;
}
+/** 매매 이력 — Trade 확장 (추가 필드는 any로 허용) */
export interface TradeHistory extends Trade {
[key: string]: any;
}
-// Recommendation Types
+// ──────────────────────────────────────────────────
+// 추천 종목 타입 (Recommendation Types)
+// ──────────────────────────────────────────────────
+
+/** 분석 종목 — 배치 분석 결과의 개별 종목 */
export interface RecommendedStock {
stock_code: string;
stock_name: string;
@@ -110,15 +160,28 @@ export interface RecommendationsData {
[key: string]: any;
}
-// Journal Types
+// ──────────────────────────────────────────────────
+// 매매일지 타입 (Journal Types)
+// ──────────────────────────────────────────────────
+
+/** 매매일지 항목 — 장 마감 후 AI 자동 생성 */
export interface Journal {
id: number;
stock_code: string;
stock_name: string;
- [key: string]: string | number;
+ journal_date?: string;
+ created_at?: string;
+ mood?: string;
+ content?: string;
+ tags?: string[];
+ [key: string]: string | number | string[] | undefined;
}
-// Orderbook Types
+// ──────────────────────────────────────────────────
+// 호가 타입 (Orderbook Types)
+// ──────────────────────────────────────────────────
+
+/** 호가 단계 (가격 + 잔량) */
export interface OrderbookLevel {
price: number;
volume: number;
@@ -132,7 +195,11 @@ export interface Orderbook {
bids: OrderbookLevel[];
}
-// Chart Data Types
+// ──────────────────────────────────────────────────
+// 차트 데이터 타입 (Chart Data Types)
+// ──────────────────────────────────────────────────
+
+/** 가공된 차트 데이터 — TradingChart 컴포넌트용 (기술적 지표 포함) */
export interface ProcessedChartData {
candles: Array<{ time: string | number; open: number; high: number; low: number; close: number }>;
volumes: Array<{ time: string | number; value: number; color: string }>;
@@ -156,7 +223,11 @@ export interface ProcessedChartData {
};
}
-// WebSocket Message Types
+// ──────────────────────────────────────────────────
+// WebSocket 메시지 타입
+// ──────────────────────────────────────────────────
+
+/** 시장 업데이트 메시지 (tick: 체결가, quote: 호가) */
export interface MarketUpdateMessage {
_type: 'tick' | 'quote';
stock_code?: string;
@@ -176,7 +247,11 @@ export interface WebSocketMessage {
[key: string]: any;
}
-// AI Analysis Types
+// ──────────────────────────────────────────────────
+// AI 분석 타입
+// ──────────────────────────────────────────────────
+
+/** AI 분석 결과 — 포맷된 텍스트 + 원시 데이터 */
export interface AiAnalysisResult {
analysis: string;
data: MarketData | null;
diff --git a/frontend/src/utils/formatUtils.ts b/frontend/src/utils/formatUtils.ts
new file mode 100644
index 0000000..445b04d
--- /dev/null
+++ b/frontend/src/utils/formatUtils.ts
@@ -0,0 +1,16 @@
+/**
+ * formatUtils.ts — 포맷 관련 유틸리티 함수
+ *
+ * 날짜/시간 등 공통 포맷 함수를 모아둔 모듈입니다.
+ */
+
+/**
+ * ISO 날짜 문자열을 한국 시간 형식(HH:MM:SS)으로 변환
+ * @param isoStr - ISO 형식 날짜 문자열 (예: "2026-03-26T10:30:00")
+ * @returns 한국 시간 문자열 또는 null (입력값 없을 때)
+ */
+export const formatTime = (isoStr?: string): string | null => {
+ if (!isoStr) return null
+ const d = new Date(isoStr)
+ return d.toLocaleTimeString('ko-KR', { hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false, timeZone: 'Asia/Seoul' })
+}
diff --git a/frontend/src/utils/stockUtils.ts b/frontend/src/utils/stockUtils.ts
new file mode 100644
index 0000000..f1db390
--- /dev/null
+++ b/frontend/src/utils/stockUtils.ts
@@ -0,0 +1,12 @@
+/**
+ * stockUtils.ts — 주식 관련 유틸리티 함수
+ *
+ * 공통으로 사용되는 주식 판별 함수를 모아둔 모듈입니다.
+ */
+
+/**
+ * 미국 주식 여부 판별
+ * @param code - 종목 코드
+ * @returns 6자리 숫자가 아니면 미국 주식으로 판별
+ */
+export const isUsStock = (code: string): boolean => !/^\d{6}$/.test(code)
diff --git a/frontend/src/utils/technicalIndicators.ts b/frontend/src/utils/technicalIndicators.ts
index 5ef38db..fa2fa66 100644
--- a/frontend/src/utils/technicalIndicators.ts
+++ b/frontend/src/utils/technicalIndicators.ts
@@ -1,68 +1,98 @@
-// 기술적 지표 계산 유틸리티
-// 기존 TradingChart.tsx에서 검증된 로직을 재사용
+/**
+ * technicalIndicators.ts — 기술적 지표 계산 유틸리티
+ *
+ * 역할:
+ * - TradingChart 컴포넌트에서 사용하는 기술적 지표 계산 함수 모음
+ * - 모든 함수는 O(n) 시간 복잡도로 최적화 (슬라이딩 윈도우 또는 누적 평균)
+ *
+ * 포함 지표:
+ * - SMA (단순이동평균): 5일, 20일, 60일선
+ * - EMA (지수이동평균): MACD 계산용
+ * - 볼린저 밴드: 20일 기준, 표준편차 2배
+ * - RSI (상대강도지수): 14일 기준, Wilder 스무딩
+ * - MACD: EMA(12) - EMA(26), Signal: EMA(9)
+ */
/**
- * 단순이동평균 (Simple Moving Average)
- * @param data 가격 데이터 배열
- * @param period 이동평균 기간
- * @returns SMA 값 배열
+ * 단순이동평균 (Simple Moving Average) — O(n) 슬라이딩 윈도우
+ *
+ * @param data - 종가 배열
+ * @param period - 이동평균 기간 (예: 5, 20, 60)
+ * @returns 이동평균 배열 (period 미만 구간은 NaN)
*/
export const calculateSMA = (data: number[], period: number): number[] => {
- const result: number[] = [];
+ const result = new Array
+
+
+
+
+
+
+
+
+
+
+ + AutoStock +
+GEN 3 ALGO
++ .env 파일의 SECRET_KEY 값을 입력하세요 +
+