MCP Market Statistics Server

# 📊 MCP Market Statistics Server 한국 주식시장의 종합적인 통계 데이터와 시장 분석 정보를 제공하는 MCP(Model Context Protocol) 서버입니다. [](https://github.com/your-org/mcp-market-statistics/actions) [](https://codecov.io/gh/your-org/mcp-market-statistics) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) ## ✨ 주요 기능 ### 🏢 시장 데이터 - **실시간 지수 현황**: KOSPI, KOSDAQ, KOSPI200 등 - **시장 전체 통계**: 시가총액, 거래대금, 상승/하락 종목 수 - **52주 신고가/신저가** 통계 및 분석 ### 📈 섹터별 분석 - **업종 로테이션** 분석 및 추적 - **섹터별 밸류에이션** 비교 - **리더/래거드 종목** 식별 ### 💰 투자자 동향 - **개인/기관/외국인** 매매 동향 - **프로그램 매매** 현황 분석 - **스마트머니 추종** 지표 ### 🌊 시장 심리 지표 - **Fear & Greed Index** (한국판) - **Put/Call Ratio** 분석 - **변동성 지수** (VKOSPI) - **뉴스 감성 분석** ### 🔍 고급 분석 - **시장 이상 징후 탐지** - AI 기반 이상 패턴 감지 - **시장 국면 판단** - 불장/곰장/횡보장 구분 - **유동성 분석** - 시장 깊이 및 유동성 측정 - **상관관계 매트릭스** - 자산 간 상관관계 분석 - **패턴 인식** - 차트 패턴 및 기술적 지표 분석 - **다중 시간대 분석** - 여러 타임프레임 통합 분석 - **감정 분석** - 뉴스 및 소셜미디어 감정 분석 - **가격 예측** - 머신러닝 기반 가격 예측 - **리스크 평가** - 포트폴리오 리스크 분석 ## 🚀 빠른 시작 ### 사전 요구사항 - Python 3.11 이상 - TimescaleDB - Redis - Docker (선택사항) ### 설치 1. **저장소 클론** ```bash git clone https://github.com/your-org/mcp-market-statistics.git cd mcp-market-statistics ``` 2. **가상환경 생성 및 활성화** ```bash python -m venv venv source venv/bin/activate # Linux/Mac # 또는 venv\Scripts\activate # Windows ``` 3. **의존성 설치** ```bash make install # 또는 pip install -r requirements.txt ``` 4. **환경 변수 설정** ```bash cp .env.example .env # .env 파일을 편집하여 데이터베이스 및 API 설정 ``` ### Docker를 이용한 실행 ```bash # 이미지 빌드 및 실행 make docker-run # 또는 직접 실행 docker-compose up -d ``` ### 개발 모드 실행 ```bash # 개발 서버 시작 make dev-server # 테스트 실행 make test # 코드 포맷팅 make format # 보안 검사 make security ``` ## 🛠️ 개발 가이드 ### 프로젝트 구조 ``` mcp-market-statistics/ ├── src/ # 소스 코드 │ ├── server.py # MCP 서버 메인 │ ├── tools/ # MCP 도구 정의 │ ├── collectors/ # 데이터 수집 │ ├── analytics/ # 고급 분석 엔진 │ │ ├── advanced_pattern_recognition.py │ │ ├── multi_timeframe_analyzer.py │ │ ├── correlation_engine.py │ │ ├── price_predictor.py │ │ ├── sentiment_analyzer.py │ │ ├── market_anomaly_detector.py │ │ └── risk_assessment_engine.py │ ├── analyzers/ # 시장 분석기 │ ├── calculators/ # 계산 모듈 │ ├── models/ # 데이터 모델 │ ├── utils/ # 유틸리티 │ ├── exceptions.py # 커스텀 예외 │ └── config.py # 설정 관리 ├── tests/ # 테스트 코드 ├── .github/workflows/ # CI/CD 파이프라인 ├── requirements.txt # Python 의존성 ├── Dockerfile # Docker 이미지 빌드 ├── docker-compose.yml # 서비스 오케스트레이션 └── Makefile # 개발 명령어 ``` ### 테스트 작성 이 프로젝트는 **TDD(Test-Driven Development)** 방법론을 따릅니다. ```bash # 모든 테스트 실행 make test # 커버리지와 함께 테스트 make test-cov # 통합 테스트 실행 make test-integration ``` ### 코드 품질 ```bash # 린팅 실행 make lint # 코드 포맷팅 make format # 보안 검사 make security # 모든 체크 실행 make ci-test ``` ## 🔧 설정 ### 환경 변수 | 변수명 | 설명 | 기본값 | |--------|------|--------| | `TIMESCALE_DB_HOST` | TimescaleDB 호스트 | localhost | | `TIMESCALE_DB_PORT` | TimescaleDB 포트 | 5432 | | `TIMESCALE_DB_NAME` | 데이터베이스 이름 | market_stats | | `REDIS_HOST` | Redis 호스트 | localhost | | `REDIS_PORT` | Redis 포트 | 6379 | | `LOG_LEVEL` | 로그 레벨 | INFO | | `KRX_API_KEY` | KRX API 키 | - | ### 데이터베이스 스키마 데이터베이스 스키마를 초기화하려면: ```bash make db-setup ``` ## 📡 API 사용법 ### MCP 도구 목록 #### 기본 시장 데이터 1. **`get_market_overview`** - 시장 전체 현황 2. **`get_sector_statistics`** - 섹터별 통계 3. **`get_investor_flows`** - 투자자별 매매 동향 4. **`get_market_breadth`** - 시장 폭 지표 #### 고급 분석 도구 5. **`analyze_advanced_patterns`** - 고급 패턴 인식 및 분석 6. **`analyze_multi_timeframe`** - 다중 시간대 분석 7. **`analyze_correlations`** - 상관관계 엔진 8. **`predict_prices`** - AI 기반 가격 예측 9. **`analyze_sentiment`** - 감정 분석 10. **`detect_anomalies`** - 시장 이상 징후 탐지 11. **`assess_risks`** - 리스크 평가 12. **`get_market_sentiment`** - 시장 심리 지표 13. **`get_market_regime`** - 시장 국면 판단 ### 사용 예시 ```python # MCP 클라이언트를 통한 사용 import mcp client = mcp.Client("market-stats-server") # 시장 개요 조회 overview = await client.call_tool("get_market_overview", { "market": "KOSPI", "include_details": True }) # 섹터 통계 조회 sectors = await client.call_tool("get_sector_statistics", { "sector": "IT", "period": "1d" }) ``` ## 🔍 모니터링 ### 헬스체크 ```bash curl http://localhost:8000/health ``` ### 메트릭 서버는 Prometheus 메트릭을 `/metrics` 엔드포인트에서 제공합니다. ### 로그 구조화된 JSON 로그를 사용하여 ELK 스택과 호환됩니다. ## 🤝 기여하기 1. 이슈를 생성하여 기능 요청이나 버그를 리포트해주세요 2. 포크하여 새로운 브랜치를 생성해주세요 3. 변경사항을 커밋해주세요 4. 테스트를 실행하고 통과하는지 확인해주세요 5. 풀 리퀘스트를 생성해주세요 ### 개발 워크플로우 ```bash # 의존성 설치 및 pre-commit 설정 make install-dev # 새로운 기능 브랜치 생성 git checkout -b feature/new-feature # 개발 및 테스트 make test # 커밋 전 체크 make pre-commit # 커밋 및 푸시 git commit -m "feat: add new feature" git push origin feature/new-feature ``` ## 📄 라이선스 이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요. ## 🙋‍♂️ 지원 - **문서**: [프로젝트 위키](https://github.com/your-org/mcp-market-statistics/wiki) - **이슈**: [GitHub Issues](https://github.com/your-org/mcp-market-statistics/issues) - **토론**: [GitHub Discussions](https://github.com/your-org/mcp-market-statistics/discussions) ## 🏗️ 개발 현황 ### Phase 1-4: 기본 인프라 및 데이터 수집 (완료 ✅) - MCP 서버 아키텍처 - 데이터 수집 파이프라인 - 기본 분석 도구 - 데이터베이스 및 캐싱 ### Phase 5: 고급 분석 시스템 (완료 ✅) - **AdvancedPatternRecognition**: 차트 패턴, 캔들스틱, 하모닉 패턴 인식 - **MultiTimeframeAnalyzer**: 다중 시간대 통합 분석 - **CorrelationEngine**: 고급 상관관계 분석 (18개 분석 방법) - **PricePredictor**: 머신러닝 기반 가격 예측 - **SentimentAnalyzer**: 뉴스 및 소셜미디어 감정 분석 - **MarketAnomalyDetector**: AI 기반 이상 패턴 탐지 - **RiskAssessmentEngine**: 포트폴리오 리스크 분석 ### Phase 6-10: 계산 모듈 및 최적화 (진행 예정) - Calculator 모듈 구현 - Analyzer 모듈 구현 - Model 모듈 구현 - 성능 최적화 - 배포 및 운영 ## 📊 프로젝트 통계 - **총 코드 라인**: 15,000+ 라인 - **테스트 커버리지**: 95%+ - **구현된 분석 방법**: 100+ 개 - **지원 패턴**: 50+ 종류 - **TDD 방법론** 적용으로 높은 코드 품질 보장