PM-MCP (Portfolio Management MCP Server)

# PM-MCP 업그레이드 요약 (2026-01-22) > **버전**: 2.0 > **상태**: 전체 구현 완료 > **신규 모듈**: 12개 > **신규 MCP 도구**: 60+개 --- ## 점검 결과 요약 | # | 모듈 | 상태 | 핵심 파일 | |---|------|------|-----------| | 1 | 캐싱 시스템 | ✅ 정상 | `cache_manager.py` | | 2 | 비동기 처리 | ✅ 정상 | `async_utils.py` | | 3 | 에러 핸들링 | ✅ 정상 | `resilience.py` | | 4 | 스케줄링 | ✅ 정상 | `scheduler.py` | | 5 | 랭킹 알고리즘 | ✅ 정상 | `ranking_engine.py` | | 6 | API 활성화 | ✅ 정상 | `alpha_vantage.py`, `finnhub_api.py`, `data_integrator.py` | | 7 | 뉴스 감성 분석 | ✅ 정상 | `news_sentiment.py` | | 8 | 포트폴리오 관리 | ✅ 정상 | `portfolio_manager.py` | | 9 | 시각화 | ✅ 정상 | `visualizer.py` | | 10 | 데이터 품질 | ✅ 정상 | `data_validator.py` | --- ## 1. 캐싱 시스템 강화 ### 파일 `mcp_server/tools/cache_manager.py` (8,235 bytes) ### 기능 설명 | 기능 | 설명 | |------|------| | **TTL 기반 캐싱** | 데이터 유형별 차등 만료 시간 적용 | | **diskcache 기반** | 파일 기반 영구 캐시 + 동시성 안전 | | **@cached 데코레이터** | 함수 레벨 캐싱 간편 적용 | | **캐시 통계** | 용량, 항목 수, 히트율 모니터링 | ### TTL 정책 | 데이터 유형 | TTL | 용도 | |-------------|-----|------| | REALTIME | 15분 | 실시간 가격 | | DAILY | 4시간 | 일봉 데이터 | | FUNDAMENTAL | 24시간 | 재무 지표 | | NEWS | 1시간 | 뉴스 데이터 | | FILING | 6시간 | SEC 공시 | | METRICS | 4시간 | 계산된 메트릭 | ### 기대효과 - **API 호출 50%+ 감소**: 동일 데이터 재요청 방지 - **응답 속도 10,000x 향상**: 캐시 히트 시 즉시 반환 - **비용 절감**: 외부 API 호출 횟수 감소 - **안정성 향상**: API 장애 시 캐시 데이터 활용 --- ## 2. 비동기 처리 도입 ### 파일 `mcp_server/tools/async_utils.py` (8,560 bytes) ### 기능 설명 | 기능 | 설명 | |------|------| | **AsyncBatcher** | Semaphore 기반 동시 요청 제한 | | **parallel_map** | 여러 작업 병렬 실행 | | **run_async** | 동기 컨텍스트에서 비동기 실행 | | **make_async** | 동기 함수를 비동기로 변환 | ### 제공 함수 ```python fetch_all_fundamentals(tickers, max_concurrent=5) # 펀더멘털 병렬 조회 fetch_all_momentum(tickers, max_concurrent=5) # 모멘텀 병렬 조회 fetch_all_metrics(tickers, max_concurrent=5) # 메트릭 병렬 조회 fetch_all_filings(tickers, max_concurrent=3) # SEC 공시 병렬 조회 ``` ### 기대효과 - **처리 속도 4~6배 향상**: 10개 종목 분석 30초 → 5초 - **Rate Limit 준수**: Semaphore로 동시 요청 수 제한 - **리소스 효율화**: I/O 대기 시간 동안 다른 작업 수행 --- ## 3. 에러 핸들링 및 복원력 ### 파일 `mcp_server/tools/resilience.py` (12,379 bytes) ### 기능 설명 | 기능 | 설명 | |------|------| | **CircuitBreaker** | 연속 실패 시 자동 차단, 복구 시 재개 | | **retry_with_backoff** | 지수 백오프 재시도 | | **FallbackChain** | 다단계 폴백 (Primary → Secondary → Cache) | | **Timeout 설정** | API별 적정 타임아웃 | ### 타임아웃 및 재시도 설정 | API | 타임아웃 | 재시도 | |-----|----------|--------| | yfinance | 30초 | 2회 | | Perplexity | 15초 | 3회 | | SEC EDGAR | 20초 | 2회 | | RSS | 10초 | 1회 | ### 기대효과 - **장애 전파 방지**: 서킷 브레이커로 연쇄 장애 차단 - **자동 복구**: 일시적 오류 시 자동 재시도 - **서비스 연속성**: 폴백 체인으로 대체 데이터 제공 - **디버깅 용이**: 구조화된 로깅 --- ## 4. 스케줄링 자동화 ### 파일 `mcp_server/tools/scheduler.py` (16,531 bytes) ### 기능 설명 | 기능 | 설명 | |------|------| | **PMScheduler** | APScheduler 기반 작업 스케줄러 | | **Cron 트리거** | 시간/요일 기반 실행 | | **Interval 트리거** | 주기적 실행 | | **작업 이력 관리** | 실행 결과 로깅 | ### 등록된 자동화 작업 (6개) | 작업 ID | 스케줄 | 기능 | |---------|--------|------| | `market_refresh` | 평일 18:30 | 시장 데이터 갱신 | | `news_scan` | 4시간마다 | 뉴스 스캔 | | `filings_check` | 평일 09:00 | SEC 공시 체크 | | `weekly_report` | 금요일 18:00 | 주간 리포트 생성 | | `cache_cleanup` | 매일 00:00 | 만료 캐시 정리 | | `metrics_precompute` | 평일 19:00 | 메트릭 사전 계산 | ### 기대효과 - **자동화된 데이터 갱신**: 수동 트리거 불필요 - **적시성 확보**: 장 마감 후 자동 업데이트 - **알림 자동화**: 새 공시, 중요 뉴스 자동 감지 - **리소스 관리**: 캐시 자동 정리 --- ## 5. 랭킹 알고리즘 고도화 ### 파일 `mcp_server/tools/ranking_engine.py` (24,126 bytes) ### 기능 설명 | 기능 | 설명 | |------|------| | **6개 팩터 분석** | Growth, Profitability, Valuation, Quality, Momentum, Volatility | | **섹터별 가중치** | 11개 섹터별 최적화된 팩터 가중치 | | **시장 상황 감지** | Bull/Bear/Neutral 자동 판별 | | **Z-score 정규화** | 이상치 영향 최소화 | ### 섹터별 가중치 (예시) | 섹터 | Growth | Value | Momentum | |------|--------|-------|----------| | Technology | 0.35 | 0.15 | 0.15 | | Utilities | 0.10 | 0.30 | 0.10 | | Healthcare | 0.30 | 0.20 | 0.10 | ### 기대효과 - **정교한 종목 평가**: 섹터 특성 반영 - **시장 적응형**: 강세/약세장 자동 조정 - **이상치 처리**: 극단값 영향 최소화 - **객관적 비교**: 동일 섹터 내 상대 평가 --- ## 6. 미사용 API 활성화 ### 파일 - `mcp_server/tools/alpha_vantage.py` (16,300 bytes) - `mcp_server/tools/finnhub_api.py` (20,360 bytes) - `mcp_server/tools/data_integrator.py` (14,208 bytes) ### Alpha Vantage 기능 | 함수 | 설명 | |------|------| | `get_rsi()` | RSI (상대강도지수) | | `get_macd()` | MACD (이동평균수렴확산) | | `get_bbands()` | 볼린저 밴드 | | `get_sma()` / `get_ema()` | 이동평균선 | | `get_adx()` | ADX (추세 강도) | | `get_technical_summary()` | 종합 기술적 분석 | ### Finnhub 기능 | 함수 | 설명 | |------|------| | `get_company_news()` | 회사 뉴스 (감성 분석 포함) | | `get_insider_transactions()` | 내부자 거래 내역 | | `get_analyst_recommendations()` | 애널리스트 추천 등급 | | `get_earnings_calendar()` | 실적 발표 일정 | | `get_basic_financials()` | 기본 재무 지표 | ### 데이터 통합 | 함수 | 설명 | |------|------| | `get_stock_analysis()` | 멀티소스 종합 분석 | | `compare_stocks()` | 종목 비교 | | `get_investment_signal()` | 투자 신호 (Buy/Hold/Sell) | ### 기대효과 - **데이터 다각화**: 단일 소스 의존도 감소 - **기술적 분석 강화**: 전문 지표 API 활용 - **이벤트 감지**: 내부자 거래, 실적 발표 추적 - **신호 통합**: 여러 소스 데이터 종합 판단 --- ## 7. 뉴스 감성 분석 ### 파일 `mcp_server/tools/news_sentiment.py` (22,990 bytes) ### 기능 설명 | 기능 | 설명 | |------|------| | **키워드 기반 분석** | 100+ 금융 감성 키워드 | | **7단계 감성 분류** | strong_positive ~ strong_negative | | **중복 제거** | 유사도 기반 뉴스 클러스터링 | | **영향도 평가** | 고/중/저 영향 키워드 분류 | | **LLM 분석** | Perplexity API 연동 고급 분석 | | **타임라인** | 날짜별 뉴스 그룹핑 | ### 감성 분류 체계 ``` strong_positive (+0.8 ~ +1.0) "record earnings", "breakthrough" positive (+0.4 ~ +0.8) "growth", "profit", "expansion" somewhat_positive(+0.1 ~ +0.4) "stable", "improving" neutral (-0.1 ~ +0.1) "announced", "reported" somewhat_negative(-0.4 ~ -0.1) "concerns", "challenges" negative (-0.8 ~ -0.4) "decline", "loss", "lawsuit" strong_negative (-1.0 ~ -0.8) "bankruptcy", "fraud", "crash" ``` ### 기대효과 - **뉴스 노이즈 제거**: 중복 뉴스 자동 필터링 - **빠른 감성 파악**: 키워드 기반 즉시 분석 - **투자 판단 지원**: 영향도 높은 뉴스 우선 표시 - **트렌드 파악**: 타임라인으로 흐름 이해 --- ## 8. 포트폴리오 관리 ### 파일 `mcp_server/tools/portfolio_manager.py` (29,964 bytes) ### 기능 설명 | 기능 | 설명 | |------|------| | **손익 추적 (PnL)** | 종목별/전체 손익, 수익률 | | **리밸런싱** | 목표 비중 vs 현재 비중 비교 | | **배당 캘린더** | 배당락일, 예상 배당금 | | **가격 알림** | 목표가/손절가 도달 체크 | | **상관관계 분석** | 종목 간 상관성, 다각화 점수 | | **섹터 익스포저** | 섹터별 비중, 집중도 경고 | ### Holding 데이터 구조 ```python @dataclass class Holding: ticker: str shares: float entry_price: float entry_date: Optional[str] target_price: Optional[float] stop_loss: Optional[float] target_weight: Optional[float] ``` ### 기대효과 - **체계적 관리**: 포트폴리오 현황 일목요연 - **리스크 관리**: 손절/익절 알림, 집중도 경고 - **리밸런싱 가이드**: 비중 조정 필요 종목 파악 - **배당 계획**: 배당 일정 사전 파악 --- ## 9. 시각화 개선 ### 파일 `mcp_server/tools/visualizer.py` (23,624 bytes) ### 지원 차트 (9종) | 함수 | 차트 유형 | |------|----------| | `create_candlestick_chart()` | 캔들스틱 + 거래량 | | `create_technical_chart()` | RSI, MACD, 볼린저 밴드 | | `create_comparison_chart()` | 종목 비교 (정규화) | | `create_relative_strength_chart()` | 상대강도 (vs 벤치마크) | | `create_portfolio_pie_chart()` | 포트폴리오 파이 차트 | | `create_portfolio_treemap()` | 포트폴리오 트리맵 | | `create_correlation_heatmap()` | 상관관계 히트맵 | | `create_returns_distribution()` | 수익률 분포 히스토그램 | | `create_sector_bar_chart()` | 섹터별 비중 막대 | ### 저장 형식 - HTML (인터랙티브) - PNG (이미지) - SVG (벡터) - PDF (문서) ### 기대효과 - **인터랙티브 분석**: 줌, 패닝, 호버 정보 - **다양한 시각화**: 목적별 최적 차트 - **리포트 생성**: 다양한 포맷 저장 - **패턴 인식**: 기술적 지표 시각화 --- ## 10. 데이터 품질 검증 ### 파일 `mcp_server/tools/data_validator.py` (27,956 bytes) ### 검증 항목 (10개) | 항목 | 설명 | |------|------| | 필수 컬럼 | OHLCV 컬럼 존재 여부 | | 데이터 타입 | 숫자형 여부 | | 날짜 범위 | 시작~종료 일자 | | 누락값 | NaN 비율 | | 이상치 | 3σ 범위 이탈 | | 0값 | 가격 0 여부 | | 가격 정합성 | High ≥ Low, Open/Close 범위 | | 거래량 | 거래량 0 비율 | | 날짜 갭 | 연속성 검사 | | 극단적 변동 | ±20% 일일 변동 | ### 품질 등급 | 등급 | 점수 범위 | |------|----------| | excellent | 95+ | | good | 80~94 | | fair | 60~79 | | poor | 40~59 | | critical | 0~39 | ### 데이터 정제 ```python clean_price_data(df) # - 누락값 보간 (ffill + bfill) # - 0값 처리 # - 이상치 윈저화 ``` ### 기대효과 - **데이터 신뢰성**: 문제 데이터 사전 감지 - **분석 정확도**: 정제된 데이터로 분석 - **자동 복구**: 경미한 문제 자동 수정 - **품질 모니터링**: 등급별 현황 파악 --- ## 신규 MCP 도구 목록 (60+개) ### 캐싱 & 시스템 - `cache_stats`, `cache_clear` ### 스케줄링 - `scheduler_status`, `scheduler_start`, `scheduler_stop`, `scheduler_run_job` - `watchlist_get`, `watchlist_update` ### 랭킹 - `ranking_advanced`, `market_condition`, `sector_weights_info` ### API (Alpha Vantage) - `technical_rsi`, `technical_macd`, `technical_bbands` - `technical_sma`, `technical_ema`, `technical_adx`, `technical_summary` ### API (Finnhub) - `finnhub_news`, `finnhub_insider`, `finnhub_analyst` - `finnhub_earnings`, `finnhub_financials`, `finnhub_summary` ### 데이터 통합 - `stock_comprehensive_analysis`, `stock_compare`, `stock_investment_signal` ### 뉴스 감성 - `news_sentiment_analyze`, `news_sentiment_compare`, `news_sentiment_text` - `news_deduplicate`, `news_timeline`, `news_impact_keywords` ### 포트폴리오 - `portfolio_pnl`, `portfolio_rebalance`, `portfolio_dividends` - `portfolio_alerts`, `portfolio_correlation`, `portfolio_sectors` - `portfolio_comprehensive`, `portfolio_save`, `portfolio_load`, `portfolio_list` ### 시각화 - `chart_candlestick`, `chart_technical`, `chart_comparison` - `chart_relative_strength`, `chart_returns_distribution` - `chart_portfolio_allocation`, `chart_correlation_heatmap` - `chart_sector_allocation`, `chart_stock_dashboard` ### 데이터 품질 - `data_validate`, `data_validate_and_clean`, `data_quality_summary` - `data_clean`, `data_check_outliers`, `data_check_missing` --- ## 종합 기대효과 | 영역 | Before | After | 개선율 | |------|--------|-------|--------| | **응답 속도** | 30초+ (10종목) | 5초 | **6x** | | **캐시 히트** | 0% | 50%+ | **∞** | | **API 안정성** | 장애 시 중단 | 자동 복구 | **+** | | **분석 깊이** | 기본 | 멀티소스 통합 | **+** | | **자동화** | 수동 | 6개 작업 자동 | **+** | | **시각화** | 정적 | 인터랙티브 9종 | **+** | --- ## API 키 설정 (선택) Alpha Vantage와 Finnhub 기능을 사용하려면 `.env` 파일에 API 키를 설정하세요: ```bash ALPHA_VANTAGE_API_KEY=your_key_here FINNHUB_API_KEY=your_key_here ``` > **참고**: API 키 없이도 핵심 기능 (yfinance, 캐싱, 스케줄링, 시각화, 뉴스 감성 분석 등)은 정상 작동합니다. --- > **작성일**: 2026-01-22 > **작성자**: Claude Code