📊 MCP Market Statistics Server

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

✨ 주요 기능

🏢 시장 데이터

• 실시간 지수 현황: KOSPI, KOSDAQ, KOSPI200 등
• 시장 전체 통계: 시가총액, 거래대금, 상승/하락 종목 수
• 52주 신고가/신저가 통계 및 분석

📈 섹터별 분석

• 업종 로테이션 분석 및 추적
• 섹터별 밸류에이션 비교
• 리더/래거드 종목 식별

💰 투자자 동향

• 개인/기관/외국인 매매 동향
• 프로그램 매매 현황 분석
• 스마트머니 추종 지표

🌊 시장 심리 지표

• Fear & Greed Index (한국판)
• Put/Call Ratio 분석
• 변동성 지수 (VKOSPI)
• 뉴스 감성 분석

🔍 고급 분석

• 시장 이상 징후 탐지 - AI 기반 이상 패턴 감지
• 시장 국면 판단 - 불장/곰장/횡보장 구분
• 유동성 분석 - 시장 깊이 및 유동성 측정
• 상관관계 매트릭스 - 자산 간 상관관계 분석
• 패턴 인식 - 차트 패턴 및 기술적 지표 분석
• 다중 시간대 분석 - 여러 타임프레임 통합 분석
• 감정 분석 - 뉴스 및 소셜미디어 감정 분석
• 가격 예측 - 머신러닝 기반 가격 예측
• 리스크 평가 - 포트폴리오 리스크 분석

🚀 빠른 시작

사전 요구사항

• Python 3.11 이상
• TimescaleDB
• Redis
• Docker (선택사항)

설치

1. 저장소 클론

   git clone https://github.com/your-org/mcp-market-statistics.git
   cd mcp-market-statistics
   

2. 가상환경 생성 및 활성화

   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # 또는
   venv\Scripts\activate  # Windows
   

3. 의존성 설치

   make install
   # 또는
   pip install -r requirements.txt
   

4. 환경 변수 설정

   cp .env.example .env
   # .env 파일을 편집하여 데이터베이스 및 API 설정
   

Docker를 이용한 실행

# 이미지 빌드 및 실행
make docker-run

# 또는 직접 실행
docker-compose up -d

개발 모드 실행

# 개발 서버 시작
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) 방법론을 따릅니다.

# 모든 테스트 실행
make test

# 커버리지와 함께 테스트
make test-cov

# 통합 테스트 실행
make test-integration

코드 품질

# 린팅 실행
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 키	-

데이터베이스 스키마

데이터베이스 스키마를 초기화하려면:

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 - 시장 국면 판단

사용 예시

# 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"
})

🔍 모니터링

헬스체크

curl http://localhost:8000/health

메트릭

서버는 Prometheus 메트릭을 /metrics 엔드포인트에서 제공합니다.

로그

구조화된 JSON 로그를 사용하여 ELK 스택과 호환됩니다.

🤝 기여하기

1. 이슈를 생성하여 기능 요청이나 버그를 리포트해주세요
2. 포크하여 새로운 브랜치를 생성해주세요
3. 변경사항을 커밋해주세요
4. 테스트를 실행하고 통과하는지 확인해주세요
5. 풀 리퀘스트를 생성해주세요

개발 워크플로우

# 의존성 설치 및 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 파일을 참조하세요.

🙋‍♂️ 지원

• 문서: 프로젝트 위키
• 이슈: GitHub Issues
• 토론: GitHub 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 방법론 적용으로 높은 코드 품질 보장