📊 MCP Market Statistics Server

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

✨ 주요 기능

🏢 시장 데이터

• 실시간 지수 현황: KOSPI, KOSDAQ, KOSPI200 등

• 시장 전체 통계: 시가총액, 거래대금, 상승/하락 종목 수

• 52주 신고가/신저가 통계 및 분석

📈 섹터별 분석

• 업종 로테이션 분석 및 추적

• 섹터별 밸류에이션 비교

• 리더/래거드 종목 식별

💰 투자자 동향

• 개인/기관/외국인 매매 동향

• 프로그램 매매 현황 분석

• 스마트머니 추종 지표

🌊 시장 심리 지표

• Fear & Greed Index (한국판)

• Put/Call Ratio 분석

• 변동성 지수 (VKOSPI)

• 뉴스 감성 분석

🔍 고급 분석

• 시장 이상 징후 탐지 - AI 기반 이상 패턴 감지

• 시장 국면 판단 - 불장/곰장/횡보장 구분

• 유동성 분석 - 시장 깊이 및 유동성 측정

• 상관관계 매트릭스 - 자산 간 상관관계 분석

• 패턴 인식 - 차트 패턴 및 기술적 지표 분석

• 다중 시간대 분석 - 여러 타임프레임 통합 분석

• 감정 분석 - 뉴스 및 소셜미디어 감정 분석

• 가격 예측 - 머신러닝 기반 가격 예측

• 리스크 평가 - 포트폴리오 리스크 분석

Related MCP server: MCP Stock Details Server

🚀 빠른 시작

사전 요구사항

• 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

🔧 설정

환경 변수

데이터베이스 스키마

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

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 방법론 적용으로 높은 코드 품질 보장