📊 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 (선택사항)

설치

저장소 클론

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

가상환경 생성 및 활성화

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

의존성 설치

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

환경 변수 설정

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 도구 목록

기본 시장 데이터

get_market_overview - 시장 전체 현황
get_sector_statistics - 섹터별 통계
get_investor_flows - 투자자별 매매 동향
get_market_breadth - 시장 폭 지표

고급 분석 도구

analyze_advanced_patterns - 고급 패턴 인식 및 분석
analyze_multi_timeframe - 다중 시간대 분석
analyze_correlations - 상관관계 엔진
predict_prices - AI 기반 가격 예측
analyze_sentiment - 감정 분석
detect_anomalies - 시장 이상 징후 탐지
assess_risks - 리스크 평가
get_market_sentiment - 시장 심리 지표
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 스택과 호환됩니다.

🤝 기여하기

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

개발 워크플로우

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

🙋‍♂️ 지원

🏗️ 개발 현황

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