OpenCorpInsight DART MCP Server

OpenCorpInsight는 금융감독원 전자공시시스템(DART) API를 활용하여 기업의 재무정보를 분석하는 MCP(Model Context Protocol) 서버입니다.

🎯 주요 기능

Phase 1 (완료) ✅

• 기업 정보 조회: 회사명으로 기업의 기본 정보 조회
• 재무제표 조회: 현금흐름표, 손익계산서, 재무상태표 등 조회
• 재무비율 계산: ROE, ROA, 부채비율 등 주요 재무비율 자동 계산
• 기업간 비교: 여러 기업의 재무지표 비교 분석
• 공시 목록 조회: 특정 기간의 공시 보고서 목록 조회
• 캐싱 시스템: SQLite 기반 지능형 캐싱으로 성능 최적화

Phase 2 (완료) ✅

• 재무 건전성 분석: AI 기반 종합 재무 건전성 평가 (수익성, 안정성, 성장성, 활동성)
• 뉴스 수집 및 분석: Perplexity MCP 연동을 통한 기업 관련 뉴스 수집
• 감성 분석: 뉴스 기사의 감성 분석 및 투자 영향도 평가
• 이벤트 탐지: 주요 재무 이벤트 자동 탐지 (실적발표, 배당, M&A 등)
• 고급 캐싱: Phase 2 데이터에 최적화된 캐시 정책 적용

Phase 3 (완료) ✅

• 투자 신호 생성: 종합 분석 기반 Buy/Hold/Sell 투자 신호 생성
• 종합 리포트 생성: 전문적인 기업 분석 리포트 자동 생성
• PDF 내보내기: 분석 결과를 PDF 형태로 내보내기
• 고급 분석: 리스크 허용도 기반 맞춤형 투자 분석

Phase 4 (완료) ✅

• 포트폴리오 최적화: 다중 기업 포트폴리오 최적화 및 리밸런싱 제안
• 시계열 분석: 기업 성과의 시계열 트렌드 분석 및 미래 예측
• 벤치마크 비교: 업계 평균과의 상세 비교 분석 및 순위 평가
• 경쟁 분석: 경쟁사 대비 포지션 분석 및 SWOT 분석
• 업계 리포트: 특정 업계의 종합 분석 리포트 생성

🚀 빠른 시작

자동 설치 (권장)

# 저장소 클론
git clone https://github.com/your-username/OpenCorpInsight.git
cd OpenCorpInsight

# 자동 설치 스크립트 실행
chmod +x scripts/install.sh
./scripts/install.sh

수동 설치

# 1. Python 가상환경 생성
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 2. 의존성 설치
pip install -r requirements.txt

# 3. 환경변수 설정
cp env.example .env
# .env 파일에 DART_API_KEY 설정

# 4. 캐시 디렉토리 생성
mkdir -p cache logs

Claude Desktop 연동

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "opencorpinsight": {
      "command": "python3",
      "args": ["-m", "src.dart_mcp_server"],
      "cwd": "/path/to/OpenCorpInsight",
      "env": {
        "PYTHONPATH": "/path/to/OpenCorpInsight/src"
      }
    }
  }
}

Docker 실행

# Docker 이미지 빌드
docker build -t opencorpinsight .

# 컨테이너 실행
docker run -d --name opencorpinsight \
  -e DART_API_KEY=your_api_key \
  -v $(pwd)/cache:/app/cache \
  opencorpinsight

서버 실행

# 직접 실행
python3 -m src.dart_mcp_server

# 또는 스크립트 사용
./scripts/start_server.sh

🔧 사용법

Claude Desktop 연동

mcp_config.json을 Claude Desktop 설정에 추가:

{
  "mcpServers": {
    "dart-mcp-server": {
      "command": "python",
      "args": ["/path/to/OpenCorpInsight/src/dart_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/OpenCorpInsight/.venv/lib/python3.13/site-packages"
      }
    }
  }
}

📖 MCP 도구 사용 예시

Phase 1: 기본 재무 분석

#### 1. API 키 설정

{
  "tool": "set_dart_api_key",
  "arguments": {
    "api_key": "your_dart_api_key_here"
  }
}

#### 2. 기업 정보 조회

{
  "tool": "get_company_info", 
  "arguments": {
    "corp_name": "삼성전자"
  }
}

#### 3. 재무제표 조회

{
  "tool": "get_financial_statements",
  "arguments": {
    "corp_name": "삼성전자",
    "year": "2023",
    "reprt_code": "11014",
    "fs_div": "CFS", 
    "statement_type": "현금흐름표"
  }
}

#### 4. 재무비율 계산

{
  "tool": "get_financial_ratios",
  "arguments": {
    "corp_name": "삼성전자",
    "year": "2023"
  }
}

#### 5. 기업간 비교 분석

{
  "tool": "compare_financials",
  "arguments": {
    "corp_names": ["삼성전자", "SK하이닉스", "LG전자"],
    "year": "2023",
    "metrics": ["ROE", "ROA", "부채비율", "영업이익률"]
  }
}

Phase 2: 고급 분석 및 뉴스

#### 6. 재무 건전성 종합 분석

{
  "tool": "analyze_company_health",
  "arguments": {
    "corp_name": "삼성전자",
    "analysis_period": 3,
    "weight_config": {
      "profitability": 0.3,
      "stability": 0.3,
      "growth": 0.2,
      "activity": 0.2
    }
  }
}

#### 7. 기업 뉴스 수집 및 분석 (Perplexity 연동)

{
  "tool": "get_company_news",
  "arguments": {
    "corp_name": "삼성전자",
    "search_period": "week",
    "news_categories": ["earnings", "business", "technology"],
    "include_sentiment": true
  }
}

#### 8. 뉴스 감성 분석

{
  "tool": "analyze_news_sentiment",
  "arguments": {
    "corp_name": "삼성전자",
    "search_period": "week",
    "analysis_depth": "detailed"
  }
}

#### 9. 재무 이벤트 탐지

{
  "tool": "detect_financial_events",
  "arguments": {
    "corp_name": "삼성전자",
    "monitoring_period": 30,
    "event_types": ["earnings", "dividend", "capital_increase", "major_contract"]
  }
}

Phase 3: 투자 신호 및 리포트

#### 10. 투자 신호 생성

{
  "tool": "generate_investment_signal",
  "arguments": {
    "corp_name": "삼성전자",
    "analysis_period": 3,
    "weight_config": {
      "financial_health": 0.4,
      "news_sentiment": 0.3,
      "event_impact": 0.2,
      "market_trend": 0.1
    },
    "risk_tolerance": "moderate"
  }
}

#### 11. 종합 분석 리포트 생성

{
  "tool": "generate_summary_report",
  "arguments": {
    "corp_name": "삼성전자",
    "report_type": "comprehensive",
    "include_charts": false,
    "analysis_depth": "detailed"
  }
}

#### 12. PDF 내보내기

{
  "tool": "export_to_pdf",
  "arguments": {
    "corp_name": "삼성전자",
    "report_content": "# 삼성전자 분석 리포트\n\n...",
    "include_metadata": true,
    "page_format": "A4"
  }
}

Phase 4: 포트폴리오 분석 및 벤치마킹

#### 13. 포트폴리오 최적화

{
  "tool": "optimize_portfolio",
  "arguments": {
    "companies": ["삼성전자", "LG전자", "SK하이닉스"],
    "investment_amount": 100000000,
    "risk_tolerance": "moderate",
    "optimization_method": "sharpe"
  }
}

#### 14. 시계열 분석

{
  "tool": "analyze_time_series",
  "arguments": {
    "corp_name": "삼성전자",
    "analysis_period": 5,
    "metrics": ["매출액", "영업이익", "순이익"],
    "forecast_periods": 8
  }
}

#### 15. 업계 벤치마크 비교

{
  "tool": "compare_with_industry",
  "arguments": {
    "corp_name": "삼성전자",
    "industry": "반도체",
    "comparison_metrics": ["ROE", "ROA", "부채비율"],
    "analysis_type": "detailed"
  }
}

#### 16. 경쟁 포지션 분석

{
  "tool": "analyze_competitive_position",
  "arguments": {
    "corp_name": "삼성전자",
    "competitors": ["SK하이닉스", "LG전자"],
    "analysis_metrics": ["ROE", "ROA", "매출액증가율"],
    "include_swot": true
  }
}

#### 17. 업계 분석 리포트

{
  "tool": "generate_industry_report",
  "arguments": {
    "industry": "반도체",
    "report_type": "comprehensive",
    "include_rankings": true
  }
}

🧪 테스트

자동 테스트 실행

# 테스트 스크립트 실행
./scripts/run_tests.sh

# 또는 수동으로 pytest 실행
python -m pytest tests/ -v

테스트 커버리지

# 커버리지 포함 테스트
pip install pytest-cov
python -m pytest tests/ --cov=src --cov-report=html

📦 배포

Docker 배포

# 이미지 빌드
docker build -t opencorpinsight-mcp .

# 컨테이너 실행
docker run -e DART_API_KEY=your_api_key opencorpinsight-mcp

Docker Compose 배포

# 환경변수 설정 후
docker-compose up -d

# Redis 캐시 포함 배포
docker-compose --profile redis up -d

🏗️ 아키텍처

┌─────────────────┐
│   AI Agent      │ ← Claude, GPT 등
├─────────────────┤
│   MCP Client    │ ← MCP 프로토콜
├─────────────────┤
│   MCP Tools     │ ← 5개 카테고리 도구
├─────────────────┤
│  Cache Layer    │ ← SQLite 캐싱
├─────────────────┤
│  DART API       │ ← 금융감독원 API
└─────────────────┘

도구 카테고리

• Company Tools: 기업 기본 정보
• Financial Tools: 재무 데이터 및 비율
• Analysis Tools: AI 기반 분석 (Phase 2)
• News Tools: 뉴스 수집 및 감성 분석 (Phase 2)
• Report Tools: 보고서 생성 (Phase 3)

🚄 성능 최적화

OpenCorpInsight는 SQLite 기반 지능형 캐싱 시스템으로 최적화되어 있습니다:

#### Phase 1 캐시 정책

• 기업 정보: 24시간 TTL, 최대 1,000개
• 재무제표: 24시간 TTL, 최대 5,000개
• 재무비율: 12시간 TTL, 최대 2,000개
• 공시 목록: 6시간 TTL, 최대 3,000개

#### Phase 2 캐시 정책

• 기업 뉴스: 2시간 TTL, 최대 1,000개 (실시간성 중요)
• 감성 분석: 4시간 TTL, 최대 800개
• 재무 이벤트: 6시간 TTL, 최대 500개
• 기업 건전성: 12시간 TTL, 최대 300개

#### Phase 3 캐시 정책

• 투자 신호: 8시간 TTL, 최대 200개
• 종합 리포트: 24시간 TTL, 최대 100개
• PDF 내보내기: 72시간 TTL, 최대 50개

#### Phase 4 캐시 정책

• 포트폴리오 최적화: 12시간 TTL, 최대 150개
• 시계열 분석: 24시간 TTL, 최대 200개
• 성과 예측: 48시간 TTL, 최대 100개
• 업계 벤치마크: 24시간 TTL, 최대 300개
• 경쟁 분석: 12시간 TTL, 최대 200개
• 업계 리포트: 72시간 TTL, 최대 50개

🔐 보안

• API 키 보호: 환경변수 기반 키 관리
• 데이터 프라이버시: 공개 정보만 수집
• 로그 관리: 민감 정보 로깅 방지

📝 개발 가이드

새로운 도구 추가

1. src/dart_mcp_server.py에 도구 정의 추가
2. handle_call_tool()에 핸들러 추가
3. 구현 함수 작성
4. tests/ 디렉터리에 테스트 추가

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

OpenCorpInsight로 기업 분석을 더 쉽고 정확하게! 🚀

⚙️ 환경 설정

1. API 키 설정

#### DART API 키 (필수)

1. DART 홈페이지에서 회원가입
2. API 신청 후 승인 (보통 1-2일 소요)
3. 발급받은 40자리 API 키를 환경변수로 설정:

export DART_API_KEY="your_40_character_api_key_here"

또는 .env 파일 생성:

DART_API_KEY=your_40_character_api_key_here