# 📊 MCP Market Statistics Server

한국 주식시장의 종합적인 통계 데이터와 시장 분석 정보를 제공하는 MCP(Model Context Protocol) 서버입니다.

[![CI/CD Pipeline](https://github.com/your-org/mcp-market-statistics/workflows/CI/CD%20Pipeline/badge.svg)](https://github.com/your-org/mcp-market-statistics/actions)
[![codecov](https://codecov.io/gh/your-org/mcp-market-statistics/branch/main/graph/badge.svg)](https://codecov.io/gh/your-org/mcp-market-statistics)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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 방법론** 적용으로 높은 코드 품질 보장