README.md•8.95 kB
# 📊 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 방법론** 적용으로 높은 코드 품질 보장